Chapter 1. Installing and Building the JBoss Server

JBoss, a free J2EE 1.4 certified application server, is the most widely used open source application server on the market. The highly flexible and easy-to-use server architecture has made JBoss the ideal choice for users just starting out with J2EE, as well as senior architects looking for a customizable middleware platform. The server binary and source code distributions are available from the SourceForge repository. ( The ready availability of the source code allows you to debug the server, learn its inner workings and create customized versions for your personal or business use.

This chapter will show you how to download and install JBoss 4.0. You will learn about the directory structure and understand what the key services and configuration files are.

1.1. Getting Started

Before installing and running the server, you need to check your system to make sure you have a working Java 1.4 or 1.5 JDK installation. The simplest way to do this is to execute the java -version command to ensure that the java executable is in your path and that you are using Version 1.4 or higher. A 1.4.2 JDK, for example, would produce version number like the following:

[tmp]$ java -version
java version "1.4.2_05"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_05-b04)
Java HotSpot(TM) Client VM (build 1.4.2_05-b04, mixed mode)

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. There is no requirement for root access to run JBoss on UNIX/Linux systems because none of the default ports are within the 0-1023 privileged port range.

The most recent release of JBoss is available from the JBoss downloads page, After you have downloaded the version you want to install, use the JDK jar tool (or any other ZIP extraction tool) to extract the archive contents into a location of your choice. The jboss-4.0.2.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. The extraction process will create a jboss-4.0.2 directory. The following section explores the contents of this directory.

1.2. Directory Structure

Installing the JBoss distribution creates a jboss-4.0.2 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.1, “A view of the JBoss server installation directory structure with the default server configuration file set expanded and overridable locations identified” illustrates the installation directory of the JBoss server.

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

Throughout this book we refer to the top-level jboss-4.0.2 directory as the JBOSS_DIST directory. 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”, 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.1. The JBoss top-level directory structure

binAll the entry point JARs and start scripts included with the JBoss distribution are located in the bin directory.
clientThe JARs that are required for clients that run outside of JBoss are located in the client directory.
server The JBoss server configuration sets are located under the server directory. The default server configuration set is the server/default set. JBoss ships with minimal, default and all configuration sets. The subdirectories and key configuration files contained in the default configuration set are discussed in more detail in Section 1.3, “The Default Server Configuration File Set”
lib The lib directory contains startup JARs used by JBoss. Do not place your own libraries in this directory.

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

Table 1.2. The JBoss server configuration directory structure

conf The conf directory contains the jboss-service.xml bootstrap descriptor file for a given server configuration. This defines the core services that are fixed for the lifetime of the server.
data The data directory is available for use by services that want to store content in the file system.
deploy The deploy directory is the default location the hot deployment service looks to for dynamic deployment content. This may be overridden through the URLDeploymentScanner URLs attribute.
lib The lib directory is the default location for static Java libraries that should not be hot deployed. All JARs in this directory are loaded into the shared classpath at startup.
logThe log directory is the directory log files are written to. This may be overridden through the conf/log4j.xml configuration file.
tmpThe tmp directory is used by JBoss to store temporarily files such as unpacked deployments.

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

1.3. The Default Server Configuration File Set

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.2, “An expanded view of the default server configuration file set conf and deploy directories” below shows the contents of the default configuration file set.

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

Figure 1.2. 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.


This is a minimalist example of the jboss-service.xml configuration file. It is the jboss-service.xml file used in the minimal configuration file set.


jboss-service.xml defines the core services configurations. The complete DTD and syntax of this file is described, along with the details on integrating custom services, in Section 2.4.2, “JBoss MBean Services”.


This directory is used by Tomcat.

The file specifies the JNDI InitialContext properties that are used within the JBoss server when an InitialContext is created using the no-arg constructor.


This file configures the Apache log4j framework category priorities and appenders used by the JBoss server code.


This file contains sample server side authentication configurations that are applicable when using JAAS based security. See Chapter 8, Security on JBoss for additional details on the JBoss security framework and the format of this file.


The server.policy file is a place holder for Java2 security permissions. The default file simply grants all permissions to all codebases.


This file provides the default configuration for the legacy EJB 1.1 CMP engine.


This file provides the default container configurations. Use of this file is covered in Chapter 5, EJBs on JBoss


This file provides a default configuration file for the JBoss CMP engine. See Chapter 11, The CMP Engine for the details of this descriptor.


The xmdesc directory contains XMBean descriptors for several services configured in the jboss-service.xml file.

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


This file configures the bean shell deployer, which deploys bean shell scripts as JBoss services.


This is a service that allows for custom invalidation of the EJB caches via JMS notifications. It is disabled by default.


This is a service that provides support for J2EE application clients. It manages the java:comp/env enterprise naming context for client applications based on the application-client.xml descriptor.


The EAR deployer is the service responsible for deploying J2EE EAR files.


The EJB deployer is the service responsible for deploying J2EE EJB JAR files.


hsqldb-ds.xml configures the Hypersonic 1.7.1 embedded database service configuration file. It sets up the embedded database and related connection factories. The format of JCA datasource files is discussed in Section 7.3, “Configuring JDBC DataSources”.


http-invoker.sar contains the detached invoker that supports RMI over HTTP. It also contains the proxy bindings for accessing JNDI over HTTP. This will be discussed in Section, “The HttpInvoker - RMI/HTTP Transport”


jboss-aop.deployer configures the AspectManagerService and deploys JBoss AOP applications.


jboss-hibernate.deployer deploys Hibernate archives (HAR files).


jboss-local-jdbc.rar is a JCA resource adaptor that implements the JCA ManagedConnectionFactory interface for JDBC drivers that support the DataSource interface but not JCA.


jboss-ws4ee.sar provides J2EE web services support.


jboss-xa-jdbc.rar is a JCA resource adaptor that implements the JCA ManagedConnectionFactory interface for JDBC drivers that support the XADataSource interface.


jbossjca-service.sar is the application server implementation of the JCA specification. It provides the connection management facilities for integrating resource adaptors into the JBoss server. The JCA layer is discussed in Chapter 7, Connectors on JBoss.


The jbossweb-tomcat55.sar directory provides the Tomcat 5.5 servlet engine. The SAR is unpacked rather than deployed as a JAR archive so that the tomcat configuration files can be easily edited. This service is discussed in Chapter 9, Web Applications.


hsqldb-jdbc-state-service.xml provides JMS state management using Hypersonic.


hsqldb-jdbc2-service.xml configures JMS persistence and caching using Hypersonic. It also contains the DestinationManager MBean, which is the core service for the JMS implementation.


jbossmq-destinations-service.xml configures a number of JMS queues and topics used by the JMS unit tests. Configuration of JMS destinations is discussed in Chapter 6, Messaging on JBoss.


jbossmq-httpil.sar provides a JMS invocation layer that allows the use of JMS over HTTP.


The jbossmq-service.xml file configures the core JBossMQ JMS service. JMS services are discussed in Chapter 6, Messaging on JBoss.


The jms-ds.xml file configures the JBossMQ JMS provider for use with the jms-ra.rar JCA resource adaptor.


jms-ra.rar is a JCA resource adaptor that implements the JCA ManagedConnectionFactory interface for JMS connection factories.


jvm-il-service.xml configures the in-JVM JMS transport invocation layer.


uil2-service.xml configures the JMS version 2 unified invocation layer. Its a fast and reliable custom socket based transport that should be used for messaging between JVMs.


The jmx-console.war directory provides the JMX Console. The JMX Console provides a simple web interface for managing the the MBean server. The JMX Console is discussed in Section 2.3.1, “Inspecting the Server - the JMX Console Web Application”


jmx-invoker-service.sar is an unpacked MBean service archive that exposes a subset of the JMX MBeanServer interface methods as an RMI interface to enable remote access to the JMX core functionality. This is similar to the legacy jmx-rmi-adaptor.sar, with the difference that the transport is handled by the detached invoker architecture. This service is discussed in Section 2.3.4, “Connecting to JMX Using Any Protocol”.


mail-ra.rar is a resource adaptor that provides a JavaMail connector.


The mail-service.xml file is an MBean service descriptor that provides JavaMail sessions for use inside the JBoss server.

management/console-mgr.sar, web-console.war

console-mgr.sar and web-console.war provide the Web Console. It is a web application/applet that provide a richer view of the JMX server management data than the JMX console. You may view the console using the URL http://localhost:8080/web-console/.


The monitoring-service.xml file configures alert monitors like the console listener and email listener used by JMX notifications.


The properties-service.xml file is an MBean service descriptor that allows for customization of the JavaBeans PropertyEditors as well as the definition of system properties. This is discussed further in Section 10.1, “System Properties Management”.

scheduler-service.xml, schedule-manager-service.xml

The scheduler-service.xml and schedule-manager-service.xml files are MBean service descriptors that provide a scheduling type of service. This is discussed further in Section 10.4, “Scheduling Tasks”.


The sqlexception-service.xml file is an MBean service descriptor for the handling of vendor specific SQLExceptions. Its usage is discussed in Section 11.11, “Entity Commands and Primary Key Generation”.


The uuid-key-generator.sar service provides a UUID-based key generation facility.

1.4.  Basic Installation Testing

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 script, as appropriate for your operating system. Your output should look like the following and contain no error or exception messages:

[bin]$ sh

JBoss Bootstrap Environment
JBOSS_HOME: /tmp/jboss-4.0.2
JAVA: /System/Library/Frameworks/JavaVM.framework/Home//bin/java
JAVA_OPTS: -server -Xms128m -Xmx128m
CLASSPATH: /tmp/jboss-4.0.2/bin/run.jar:/System/Library/Frameworks/JavaVM.framework/Home//l
15:19:42,557 INFO  [Server] Starting JBoss (MX MicroKernel)...
15:19:42,564 INFO  [Server] Release ID: JBoss [Zion] 4.0.2RC1 (build: CVSTag=JBoss_4_0_2_RC
1 date=200503171447)15:19:42,567 INFO  [Server] Home Dir: /private/tmp/jboss-4.0.2
15:19:42,570 INFO  [Server] Home URL: file:/private/tmp/jboss-4.0.2/
15:19:42,573 INFO  [Server] Library URL: file:/private/tmp/jboss-4.0.2/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.2/server/default
15:19:42,629 INFO  [Server] Server Home URL: file:/private/tmp/jboss-4.0.2/server/default/
15:19:42,634 INFO  [Server] Server Data Dir: /private/tmp/jboss-4.0.2/server/default/data
15:19:42,636 INFO  [Server] Server Temp Dir: /private/tmp/jboss-4.0.2/server/default/tmp
15:19:42,638 INFO  [Server] Server Config URL: file:/private/tmp/jboss-4.0.2/server/default
15:19:42,640 INFO  [Server] Server Library URL: file:/private/tmp/jboss-4.0.2/server/defaul
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 Compute
r, 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.2RC1 (build: CVSTag=JBoss_4_0_2_RC1 
date=200503171447)] 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 command.

[bin]$ ./ -S

The shutdown script supports the following options:

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

usage: shutdown [options] <operation>

    -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

    -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 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]$ ./ -c minimal
15:37:04,558 INFO  [Server] JBoss (MX MicroKernel) [4.0.2RC1 (build: CVSTag=JBoss_4_0_2_RC1 
date=200503171447)] Started in 5s:524ms

The run script supports the following options:

usage: [options]

    -h, --help                    Show this help message
    -V, --version                 Show version information
    --                            Stop processing options
    -D<name>[=<value>]            Set a system property
    -p, --patchdir=<dir>          Set the patch directory; Must be absolute
    -n, --netboot=<url>           Boot from net with the given url as base
    -c, --configuration=<name>    Set the server configuration name
    -j, --jaxp=<type>             Set the JAXP impl type (ie. crimson)
    -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

1.5. Booting from a Network Server

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/chap1/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.2 -buildfile \

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

[bin]$ ./ -c netboot

  JBoss Bootstrap Environment

  JBOSS_HOME: /tmp/jboss-4.0.2

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

  JAVA_OPTS: -server -Xms128m -Xmx128m
  CLASSPATH: /tmp/jboss-4.0.2/bin/run.jar:/System/Library/Frameworks/JavaVM.framework/Home//l
18:01:08,244 INFO  [Server] Starting JBoss (MX MicroKernel)...            
18:01:30,771 INFO  [Server] JBoss (MX MicroKernel) [4.0.2RC1 (build: CVSTag=JBoss_4_0_2_RC1
date=200503171447)] Started in 21s:210ms

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

[bin]$ sh --netboot=
[orb@toki bin]$ sh -b localhost  --netboot=

  JBoss Bootstrap Environment

  JBOSS_HOME: /tmp/jboss-4.0.2

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

  JAVA_OPTS: -server -Xms128m -Xmx128m

  CLASSPATH: /tmp/jboss-4.0.2/bin/run.jar:/System/Library/Frameworks/JavaVM.framework/Home//l


18:10:29,473 INFO  [Server] Starting JBoss (MX MicroKernel)...
18:10:29,483 INFO  [Server] Release ID: JBoss [Zion] 4.0.2RC1 (build: CVSTag=JBoss_4_0_2_RC1 
date=200503171447)18:10:29,487 INFO  [Server] Home Dir: /private/tmp/jboss-4.0.2
18:10:29,488 INFO  [Server] Home URL:
18:10:29,491 INFO  [Server] Library URL:
18:10:29,496 INFO  [Server] Patch URL: null
18:10:29,598 INFO  [Server] Server Name: default
18:10:29,602 INFO  [Server] Server Home Dir: /private/tmp/jboss-4.0.2/server/default
18:10:29,606 INFO  [Server] Server Home URL:
18:10:29,609 INFO  [Server] Server Data Dir: /private/tmp/jboss-4.0.2/server/default/data
18:10:29,611 INFO  [Server] Server Temp Dir: /private/tmp/jboss-4.0.2/server/default/tmp
18:10:29,614 INFO  [Server] Server Config URL:
18:10:29,617 INFO  [Server] Server Library URL:
18:10:29,620 INFO  [Server] Root Deployment Filename: jboss-service.xml
18:10:29,630 INFO  [Server] Starting General Purpose Architecture (GPA)...

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.