Section 1.5. Installing JBoss

1.5. Installing JBoss

Now that we have all prerequisites in place, we can get to the reason why you are here: installing and running JBoss.

Download the JBoss Application Server Version 4.0.2 from Since it is written in Java, the same installation files will work on Windows, Linux, Unix, or Mac OS X. Any platform that has a JVM can run JBoss.

To install JBoss, simply unzip the downloaded file to the directory of your choice. Next, create an environment variable called JBOSS_HOME that points to the JBoss installation directory. Finally, add $JBOSS_HOME/bin to the system path so you can run JBoss from the command line.

To verify your JBoss installation, type run at a command prompt (run.bat for Windows users, for Linux/Unix/Mac users). You should see something like this in your terminal window:

     rosencrantz:/Library/jboss/bin sdavis$ ./     ===========================================     ==============================       JBoss Bootstrap Environment       JBOSS_HOME: /Library/jboss       JAVA: /System/Library/Frameworks/JavaVM.framework/home/bin/java       JAVA_OPTS: -server -Xms128m -Xmx128m       CLASSPATH: /Library/jboss/bin/run.jar:/System/Library/Frameworks/       JavaVM.framework/home/lib/tools.jar     ===========================================     ==============================     22:14:03,159 INFO  [Server] Starting JBoss (MX MicroKernel)...     22:14:03,177 INFO  [Server] Release ID: JBoss [Zion] 4.0.2     (build: CVSTag=JBoss_4_0_2 date=200505022023)     22:14:03,181 INFO  [Server] Home Dir: /Library/jboss-4.0.2     [many lines deleted for clarity...]     22:14:55,890 INFO  [Http11Protocol] Starting Coyote     HTTP/1.1 on http-     22:14:56,396 INFO  [ChannelSocket] JK: ajp13 listening on /     22:14:56,519 INFO  [JkMain] Jk running ID=0 time=0/240  config=null     22:14:56,530 INFO  [Server] JBoss (MX MicroKernel)      [4.0.2 (build: CVSTag=JBoss_4_0_2 date=200505022023)]     Started in 53s:238ms 

If you don't see any exceptions scroll by, JBoss is up and running when you see the final line: Started in xx ms. To stop JBoss, press ctrl+C.

Now that we're sure that everything runs, let's explore JBoss a bit more closely.

1.5.1. Touring the JBoss Directory Structure

JBoss has directory structure that resembles most open source projects (as shown in Figure 1-1). We're going to briefly point out what each directory holds, and then quickly move along. You'll rarely need to make changes to them. JBoss is configured and ready to run out of the box. You'll spend most of your time messing around with the server/ directory. This is where you deploy your application.

Figure 1-1 shows a brief overview of each directory:


Start up and shut down scripts.


JAR files used by external client applications that remotely access JNDI resources.


Strangely, the JBoss documentation is not found here. (It can be downloaded from Instead, you'll find various subdirectories:


XML DTDs describing the structure of J2EE standard and JBoss-specific deployment descriptors. In J2EE 1.4, DTDs have been deprecated in favor of Schemas. The DTDs are preserved here to support previous versions of the J2EE. JBoss still uses DTDs for JBoss-specific descriptors.


Subdirectories with sample JBoss descriptors. The most notable among them is the jca subdirectory that holds sample DataSource configuration files (*-ds.xml) for most of the major relational databases. We'll discuss this directory in more detail in the JDBC chapter.


Licenses for all the different services.


XML Schemas (XSDs) describing the structure of J2EE 1.4 standard deployment descriptors.


Unit and functional tests for JBoss.

Figure 1-1. JBoss directory structure


JAR files that make up JBoss.


Sub-directories for the various server configurations. This is where you deploy your applications.

1.5.2. Server Configurations

The server/ directory is the most interesting one of the bunch to us as J2EE developers. It is where we configure JBoss services and deploy our applications.

Earlier in the chapter we said that JBoss was a family of interrelated services. This family of services is called a Server Configuration. Three named server configurations are in the server/ directory: minimal, default, and all. The only difference among the three are the specific services that run at startup.


Includes only JNDI and logging services. As the name implies, it does not include any of the other standard J2EE services (EJBs, JMS, or a web container).


This is the base J2EE 1.4 configuration. It is what runs if you do not specify a server configuration .


This is the "kitchen sink" server configuration. It includes everything in the default configuration plus services like clustering.

You can easily create your own Server Configuration by simply copying one of these directories, giving it a unique name, and adding or removing services as you wish. We'll stick with the default ones for this book, but feel free to experiment on your own.

When we started JBoss previously, it ran using the default configuration. Try starting JBoss with the minimal configuration. At a command prompt, type run -c minimal. JBoss should start up in a fraction of the time it took last time. You also should see far fewer lines in the console output than you did last time.

Type ctrl+C at a command prompt to stop JBoss, and then run -c default to run the default server configuration again. Notice all of the additional services that start up in the default configuration.

JBoss is really just a thin JMX (Java Management Extenstions) microkernel. JMX is a framework that allows you to interact with live, running code. You can start and stop services, gather metrics, and even change parameters on the fly. Services that implement the JMX interface are called "managed beans," or MBeans.

Each of the J2EE services that run inside JBoss is an MBean. Log4j, Tomcat, and Hibernate are all MBeans. We'll talk about how to selectively turn them on and off in the next section.

You don't need to know anything about JMX to deploy an application to JBoss. You really don't need to know it to configure JBoss, eitheryou'll just see the terminology come up from time to time. JBoss is a great example of the power of JMX. (For more information on JMX, see Java Management Extensions by J. Steven Perry.)

1.5.3. Touring the Server Configuration Directory Structure

A server configuration has three core subdirectories: conf/, deploy/, and lib/. Like the main JBoss directories, you'll make changes to them only on rare occasions. Generally, you'll simply drop your EAR or WAR file in the deploy/ directory and let JBoss handle the rest.


Includes configuration files for core services such as Log4J and JAAS


Deployment directory for both dynamic JBoss services (MBeans) and your custom applications (EARs and WARs)


JAR files to support the dynamic JBoss services (MBeans).

Look around the default/conf/ directory. The main Server Configuration file is jboss-service.xml. The only reason why you might edit this file is to change a port that a specific service runs on. Edit these values with carethe ports assigned to these services are well known. Changing them could cause downstream services to fail.

Change to the default/lib/ directory. These JAR files make up the J2EE services. You might drop an occasional database driver in here, but all the JARs that your application uses should be included in the WAR or EAR lib/ directory.

Now change to the default/deploy/ directory. This is where we'll deploy the JAW application in just a bit. For now, let's play around with the JBoss MBeans.

Make sure that you have JBoss open in one console window and the default/deploy/ directory open in another. While JBoss runs, it constantly polls this directory looking for changes to the configuration. Let's dynamically undeploy an MBean to see this process in action.

The easiest way to see the process is to create a $JBOSS_HOME/server/default/undeploy/ directory. (It can be named anything you like, but "undeploy" is a common choice.) Move the hsqldb-ds.xml file to the undeploy/ directory and watch the JBoss console. You should see the Hypersonic database service shut down and all of the related services reconfigure themselves. Now move the file back from the undeploy/ directory to the deploy/ directory. Once again, JBoss recognizes the change in configuration and adjusts itself accordingly.

Adding and removing services while JBoss is running is called "hot deployment." As you'll see in the next section, you can hot deploy EARs and WARs as well.

Now that we've played around with JBoss a bit, let's deploy our first application.

Temporary Directories and Hot Deployment

The conf/, deploy/, and lib/ directories are always present in every Server Configuration. You may, however, have noticed some additional ones as you were exploring.

Once you've run a Server Configuration, several temporary directories are created. Data/, log/, tmp/, and work/ are all directories used by the running application. If JBoss is not running, you can safely delete these directories. They will be recreated the next time you run the Server Configuration.

In later chapters, you will see that our Ant scripts delete these directories as part of our deploy process. Our scripts are intended for "cold deployment"in other words, we expect you to bring down JBoss, deploy your application, and then restart the application server.

This conservative approach guarantees a clean deployment every time. We've seen far too many failed hot deployments (in this application server and others) to recommend them as a standard practice.

Symptoms of a failed hot deploy may include strange classloader exceptions, new, unrecognized configuration settings, and lost application- and session-scoped variables. If you patch your application to apply a critical bug-fix, we cannot in good conscience recommend anything but a cold deploy.

We have had limited success with hot patches that simply update JSPs and, to a lesser extent, patches that update class implementations without changing their interfaces (especially if RMI is not involved). Your mileage may vary with hot deployments, but our experience has shown that gambling is best saved for weekend trips to Las Vegas.

JBoss at Work. A Practical Guide
JBoss at Work: A Practical Guide
ISBN: 0596007345
EAN: 2147483647
Year: 2004
Pages: 197

Similar book on Amazon © 2008-2017.
If you may any questions please contact us: