The most recent release of JBoss is available from the JBoss downloads page, http://www.jboss.org/products/jbossas/downloads. After you have downloaded the version you want to install, use the JDK jar tool (or any other ZIP extraction tool) to extract the jboss-4.0.3.zip archive contents into a location of your choice. It does not matter where on your system you install JBoss. Note, however, that installing JBoss into a directory that has a name that contains spaces causes problems in some situations with Sun-based VMs. This is caused by bugs with file URLs not correctly escaping the spaces in the resulting URL. The jboss-4.0.3.tgz archive is a gzipped tar file that requires a gnutar-compatible tar program that can handle the long pathnames in the archive. The default tar binaries on Solaris and OS X do not currently support the long pathnames.

As of JBoss 4.0.3, JBoss also provides a GUI installer that can simplify the installation process. In addition to the basic installation, the installer allows you to select the which services are installed secure the JBoss management applications. Using a custom JBoss install created by the installer can greatly simplify the installation and configuration of JBoss.

The installer can be run directly from a web browser using Java Web Start or can be downloaded as an executable JAR file named jboss-4.0.3-installer.jar. On many operating system, you can run executable JARs by double-clicking them. If your system doesn't support that, you can run the installer directly from the command line:

[tmp]$ java -jar jboss-4.0.3-installer.jar

When you launch the installer, you will be able to select the starting server configuration and then be given the option to further customize the services installed as shown in Figure 1.1, “A view of the JBoss server installation directory structure with the default server configuration file set expanded and overridable locations identified”.

Figure 1.1. A view of the JBoss server installation directory structure with the default server configuration file set expanded and overridable locations identified

The installer will install all the services requested into the default server configuration. This will leave you with a smaller install image and a directory structure that is slightly different than the one we will use in the examples. It is recommended for the purporses of the examples in the book that you use the complete installation download and not the smaller install image

Installing the JBoss distribution creates a jboss-4.0.3 directory that contains server start scripts, JARs, server configuration sets and working directories. You need to know your way around the distribution layout to locate JARs for compiling code, updating configurations, deploying your code, etc. Figure 1.2, “The JBoss installer package selection screen” illustrates the installation directory of the JBoss server.

Figure 1.2. The JBoss installer package selection screen

Throughout this book we refer to the top-level jboss-4.0.3 directory as the JBOSS_DIST directory. In Figure 1.2, “The JBoss installer package selection screen”, the default server configuration file set is shown expanded. It contains a number of subdirectories: conf, data, deploy, lib, log, and tmp. In a clean installation, only the conf, deploy, and lib directories will exist. Several of the locations may be overridden. For these locations, the org.jboss.system.server.ServerConfig interface constant and its corresponding system property string are shown. The names ending in URL correspond to locations that can be specified using a URL to access remote locations, for example, HTTP URLs against a web server. Table 1.1, “The JBoss top-level directory structure” shows the the top-level directories and their function.

Table 1.2, “The JBoss server configuration directory structure” shows the the directories inside of the server configuration directory and their function.

The contents of the conf and deploy directories will be shown in the following section.

The JBOSS_DIST/server directory contains one or more configuration file sets. The default JBoss configuration file set is located in the JBOSS_DIST/server/default directory. JBoss allows you to add more than one configuration set so a server can easily be run using alternate configurations. Creating a new configuration file set typically starts with copying the default file set into a new directory name and then modifying the configuration files as desired. Figure 1.3, “An expanded view of the default server configuration file set conf and deploy directories” below shows the contents of the default configuration file set.

Figure 1.3. An expanded view of the default server configuration file set conf and deploy directories

The files in the conf directory are explained in the following section.

The following are the files in the deploy directory and their function.

After you have installed the JBoss distribution, it is wise to perform a simple startup test to validate that there are no major problems with your Java VM/operating system combination. To test your installation, move to the JBOSS_DIST/bin directory and execute the run.bat or run.sh script, as appropriate for your operating system. Your output should look like the following and contain no error or exception messages:

[bin]$ sh run.sh

=========================================================================
            
JBoss Bootstrap Environment
            
JBOSS_HOME: /tmp/jboss-4.0.3
            
JAVA: /System/Library/Frameworks/JavaVM.framework/Home//bin/java
            
JAVA_OPTS: -server -Xms128m -Xmx128m -Dprogram.name=run.sh
            
CLASSPATH: /tmp/jboss-4.0.3/bin/run.jar:/System/Library/Frameworks/JavaVM.framework/Home
/lib/tools.jar
            
=========================================================================
            
15:19:42,557 INFO  [Server] Starting JBoss (MX MicroKernel)...
15:19:42,564 INFO  [Server] Release ID: JBoss 4.0.3RC2 (build: CVSTag=Branch_4_0 
date=200508131954)
15:19:42,570 INFO  [Server] Home URL: file:/private/tmp/jboss-4.0.3/
15:19:42,573 INFO  [Server] Library URL: file:/private/tmp/jboss-4.0.3/lib/
15:19:42,604 INFO  [Server] Patch URL: null
15:19:42,608 INFO  [Server] Server Name: default
15:19:42,627 INFO  [Server] Server Home Dir: /private/tmp/jboss-4.0.3/server/default
15:19:42,629 INFO  [Server] Server Home URL: file:/private/tmp/jboss-4.0.3/server/default/
15:19:42,634 INFO  [Server] Server Data Dir: /private/tmp/jboss-4.0.3/server/default/data
15:19:42,636 INFO  [Server] Server Temp Dir: /private/tmp/jboss-4.0.3/server/default/tmp
15:19:42,638 INFO  [Server] Server Config URL: 
file:/private/tmp/jboss-4.0.3/server/default/conf/
15:19:42,640 INFO  [Server] Server Library URL: 
file:/private/tmp/jboss-4.0.3/server/default/lib/
15:19:42,642 INFO  [Server] Root Deployment Filename: jboss-service.xml
15:19:42,657 INFO  [Server] Starting General Purpose Architecture (GPA)...
15:19:43,960 INFO  [ServerInfo] Java version: 1.4.2_05,Apple Computer, Inc.
15:19:43,963 INFO  [ServerInfo] Java VM: Java HotSpot(TM) Client VM 1.4.2-38,"Apple 
Computer, Inc."
15:19:43,970 INFO  [ServerInfo] OS-System: Mac OS X 10.3.8,ppc
15:19:45,243 INFO  [Server] Core system initialized
...
15:20:42,584 INFO  [Server] JBoss (MX MicroKernel) [4.0.3RC2 (build: CVSTag=Branch_4_0 
date=200508131954)] Started in 58s:659ms

If your output is similar to this (accounting for installation directory differences), you are now be ready to use JBoss. To shutdown the server, you simply issue a Ctrl-C sequence in the console in which JBoss was started. Alternatively, you can use the shutdown.sh command.

[bin]$ ./shutdown.sh -S

The shutdown script supports the following options:

A JMX client to shutdown (exit or halt) a remote JBoss server.

usage: shutdown [options] <operation>

options:
    -h, --help                Show this help message (default)
    -D<name>[=<value>]        Set a system property
    --                        Stop processing options
    -s, --server=<url>        Specify the JNDI URL of the remote server
    -n, --serverName=<url>    Specify the JMX name of the ServerImpl
    -a, --adapter=<name>      Specify JNDI name of the MBeanServerConnection to use
    -u, --user=<name>         Specify the username for authentication
    -p, --password=<name>     Specify the password for authentication

operations:
    -S, --shutdown            Shutdown the server
    -e, --exit=<code>         Force the VM to exit with a status code
    -H, --halt=<code>         Force the VM to halt with a status code

Using run.sh without any arguments starts the server using the default server configuration file set. To start with an alternate configuration file set, you pass in the name of the directory under JBOSS_DIST/server that you want to use as the value to the -c command line option. For example, to start with the minimal configuration file set you would specify:

[bin]$ ./run.sh -c minimal
...
15:02:02,939 INFO  [Server] JBoss (MX MicroKernel) [4.0.3RC2 (build: CVSTag=Branch_4_0 
date=200508311658)] Started in 6s:809ms

The run script supports the following options:

usage: run.sh [options]
    -h, --help                    Show this help message
    -V, --version                 Show version information
    --                            Stop processing options
    -D<name>[=<value>]            Set a system property
    -d, --bootdir=<dir>           Set the boot patch directory; Must be absolute or url
    -p, --patchdir=<dir>          Set the patch directory; Must be absolute or url
    -n, --netboot=<url>           Boot from net with the given url as base
    -c, --configuration=<name>    Set the server configuration name
    -B, --bootlib=<filename>      Add an extra library to the front bootclasspath
    -L, --library=<filename>      Add an extra library to the loaders classpath
    -C, --classpath=<url>         Add an extra url to the loaders classpath
    -P, --properties=<url>        Load system properties from the given url
    -b, --host=<host or ip>       Bind address for all JBoss services
    -g, --partition=<name>        HA Partition name (default=DefaultDomain)
    -u, --udp=<ip>                UDP multicast address

One very useful command-line option is the --netboot option, which causes JBoss to startup using the given URL as the base URL from which all libraries and configurations are loaded. Specifying the netboot option sets ServerConfig.HOME_URL to the netboot option URL argument value. In the absence of any other overrides, all the locations found in the standard JBOSS_DIST structure of will be resolved relative to the HOME_URL value. This means that if you make a JBoss distribution available from a web server you can boot JBoss using only the run scripts and run.jar file from the JBOSS_DIST/bin directory. Note that the web server must support the PROPFIND WebDAV command. JBoss includes a simple servlet filter that provides minimal support for the PROPFIND command so that JBoss itself may be used as the netboot web server.

An example Ant build script that creates a custom netboot configuration fileset for booting the default configuration is available in the examples/src/main/org/jboss/netboot/build-netboot.xml file. To test the netboot feature, you run the build-netboot.xml script specifying the location of the JBOSS_DIST you want to use as the netboot webserver, as shown here:

[examples]$ ant -Djboss.dist=/tmp/jboss-4.0.3 -buildfile \
src/main/org/jboss/netboot/build-netboot.xml

You then startup the netboot server by specifying the netboot configuration as follows:

[bin]$ ./run.sh -c netboot
=========================================================================

  JBoss Bootstrap Environment

  JBOSS_HOME: /tmp/jboss-4.0.3

  JAVA: /System/Library/Frameworks/JavaVM.framework/Home//bin/java

  JAVA_OPTS: -server -Xms128m -Xmx128m -Dprogram.name=run.sh
            
  CLASSPATH: /tmp/jboss-4.0.3/bin/run.jar:/System/Library/Frameworks/JavaVM.framework/Home//l
ib/tools.jar
            
=========================================================================
18:01:08,244 INFO  [Server] Starting JBoss (MX MicroKernel)...            
...
18:01:30,771 INFO  [Server] JBoss (MX MicroKernel) [4.0.3RC2 (build: CVSTag=Branch_4_0 
date=200508311658)] Started in 12s:572ms

You can now startup any other instance of J Boss using just the run script and run.jar from the JBOSS_DIST/bin directory. Here's an example:

[bin]$ sh run.sh --netboot=http://192.168.0.101:8080/netboot/

The custom netboot configuration fileset consists simply of the files needed to run the jbossweb-tomcat55.sar web server and a netboot.war whose content is the JBOSS_DIST/lib and JBOSS_DIST/server/default files.

Netboot does have some important limitations that need to be considered before considering deploying JBoss in this manner. First, due to a limitation the JSP compilation, web applications using JSPs need to be distributed in a pre-compiled state. Additionally, since JBoss loads classes dynamically from the netboot server as needed, you should carefully consider the architecture of the machine acting as the netboot server to insure that you don't introduce a single point of failure.