CHAPTER 1 Installing and Building the JBoss Server
JBoss, a free J2EE based 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 customizes middleware platform. The server is available as a binary distribution with either Tomcat or Jetty bundled as the servlet container. The source code for each binary distribution is also available from the server source repository located at SourceForge ( http://sourceforge.net/projects/jboss ). The readily 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 is a step-by-step tutorial about how to install and configure JBoss 3.2.x. You will learn how to:
- Obtain updated binaries from the JBoss SourceForge project site
- Install the binary
- Test the installation
- The installation directory structure
- Key configuration files an administrator may want to use to customize the JBoss installation
- How to obtain the source code for the 3.2.x release from the SourceForge CVS repository
- How to build the server distribution.
Getting the Binary Files
The most recent release of JBoss is available from the SourceForge JBoss project files page, which is located at the following URL:
http://sourceforge.net/projects/jboss .
Here, you will also find previous releases as well as beta and release candidate versions of upcoming releases.
Prerequisites
Before installing and running the server, check your system to make sure you have a working JDK 1.3+ 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.3 or higher. For example, running this command on a Linux system with the Sun 1.3.1 JDK produces the following:
Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1_03-b03)
Java HotSpot(TM) Client VM (build 1.3.1_03-b03, mixed mode)
It does not matter where you install JBoss. Note, however, that installing JBoss into a directory that has a name containing 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 below the 0-1023 privileged port range.
Installing the Binary Package
After you have the binary archive you want to install, use the JDK jar tool (or any other zip extraction tool) to extract the jboss-3.2.3.zip archive contents into a location of your choice. The jboss-3.2.3.tgz archive is a gzipped tar file that requires a gnutar compatible tar which can handle the long pathnames in the archive. The default tar binaries on Solaris and OSX do not currently support the long pathnames. The extraction process will create a jboss-3.2.3 directory. The following section explores the contents of this directory.
Directory Structure
As mentioned above, installing the JBoss distribution creates a jboss-3.2.3 directory which contains server start scripts, jars, server configuration sets and working directories. You do need to know your way around the distribution layout to locate jars for compilation, updating configurations, deploying your code, etc. See The view of the JBoss server installation directory structure with the default server configuration file set expanded and overridable locations identified. below illustrates the installation directory of the JBoss server.
FIGURE 1-1. The view of the JBoss server installation directory structure with the default server configuration file set expanded and overridable locations identified
Throughout the book we will refer to the top-level jboss-3.2.3 directory as the JBOSS_DIST directory. In See The 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. The purpose of each of these directories are discussed in See Descriptions of the top-level directories of the JBoss CVS source tree... In this table, the "ServerConfig Property" column refers to the org.jboss.system.server.ServerConfig interface constant and its corresponding system property string. The ServerConfig constant names and corresponding system property name are displayed in the blue text in See The view of the JBoss server installation directory structure with the default server configuration file set expanded and overridable locations identified.. The XXX_URL names correspond to locations that can be specified using a URL to access remote locations, for example, http URLs against a web server. You can use the properties listed in the following table to override the layout of a JBoss distribution
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 below shows the contents of the default configuration file set.
FIGURE 1-2. An expanded view of the default server configuration file set conf and deploy directories
conf/jboss-minimal.xml
This is a minimalist example of the jboss-server.xml configuration file. It is the jboss-server.xml file used in the minimal configuration file set.
conf/jboss-service.xml
The 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 JBoss MBean Services.
conf/jbossmq-state.xml
The jbossmq-state.xml is the JBossMQ configuration file that specifies the user to password mappings file, and the user to durable subscription. The format of this file is described in org.jboss.mq.sm.file.DynamicStateManager.
conf/jndi.properties
The jndi.properties file specifies the JNDI InitialContext properties that are used within the JBoss server when an InitialContext is created using the no-arg constructor.
conf/log4j.xml
The log4j.xml file configures the Apache log4j framework category priorities and appenders used by the JBoss server code. See the JBoss/Log4j book for details on configuring and using log4j with JBoss.
conf/login-config.xml
The login-config.xml file contains sample server side authentication configurations that are applicable when using JAAS based security. See the Chapter 8, "See Security on JBoss - J2EE Security Configuration and Architecture." for additional details on the JBoss security framework and the format of this file.
conf/server.policy
The server.policy file is a place holder for Java2 security permissions. The default file simply grants all permissions to all codebases.
conf/standardjaws.xml
The standardjaws.xml provides a default configuration file for the legacy EJB 1.1 JBossCMP engine. The cmp layer was rewritten in JBoss 3.0 to support EJB 2.0 and is fully documented for the 3.2 version in the chapter entitled The CMP Engine.
conf/standardjbosscmp-jdbc.xml
The standardjbosscmp-jdbc.xml provides a default configuration file for the JBoss 3.2 EJB 2.0 JBossCMP engine. See The CMP Engine for the details of this descriptor.
conf/standardjboss.xml
The standardjboss.xml file provides the default container configurations. Use of this file is covered in Chapter 5, "See EJBs on JBoss - The EJB Container Configuration and Architecture."
deploy/cache-invalidation-service.xml
The cache-invalidation-service.xml is a service that allows for custom invalidation of the EJB caches via JMS notifications. It is disabled by default.
deploy/client-deployer-service.xml
The client-deployer-service.xml is a service that provides suppport for J2EE application clients. It manages the "java:comp/env" enterprise naming context for client applications based on the application-client.xml descriptor.
deploy/hsqldb-ds.xml
The hsqldb-ds.xml 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 Configuring JDBC DataSources.
deploy/http-invoker.sar
The http-invoker.sar contains the detached invoker that supports RMI/HTTP. It also setups bindings of RMI/HTTP proxies for the JNDI naming service that allow the JBoss JNDI service to be accessed over http. This will be discussed in The HttpInvoker - RMI/HTTP Transport.
deploy/jboss-jca.sar
The jboss-jca.sar is the application server implementation of the 1.0 JCA specification. It provides the connection management facilities for integrating resource adaptors into the JBoss server. The JCA layer is discussed in Connectors on JBoss - The JCA Configuration and Architecture.
deploy/jboss-local-jdbc.rar
The 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.
deploy/jboss-xa.rar
The jboss-xa.rar is a JCA resource adaptor that implements the JCA ManagedConnectionFactory interface for JDBC drivers that support the XADataSource interface, but do not provide JCA adaptor.
deploy/jbossweb-tomcat41.sar
The jbossweb-tomcat41.sar directory is an unpacked MBean service archive for the configuration of the Tomcat 4.1.27 servlet engine. The SAR is unpacked rather than deployed as a jar archive so that the jbossweb-tomcat41.sar/META-INF/jboss-service.xml descriptor can be easily edited. This service is discussed in Integrating Servlet Containers
deploy/jms/jbossmq-destinations-service.xml
The jbossmq-destinations-service.xml file configures a number of JMS queues and topics used by the JMS unit tests. Configuration of JMS destinations is discussed in Messaging on JBoss - JMS Configuration and Architecture.
deploy/jms/jbossmq-httpil.sar
The jbossmq-httpil.sar provides a JMS invocation layer that allows the use of JMS over http.
deploy/jms/jbossmq-service.xml
The jbossmq-service.xml file configures the core JBossMQ JMS service. These JMS services are discussed in Messaging on JBoss - JMS Configuration and Architecture.
deploy/jms/jms-ra.rar
The jms-ra.rar is a JCA resource adaptor that implements the JCA ManagedConnectionFactory interface for JMS ConnectionFactories.
deploy/jms/jms-ds.xml
The jms-ds.xml file configures the JBossMQ JMS provider for use with the jms-ra.rar JCA resource adaptor.
deploy/jms/jvm-il-service.xml
The jvm-il-service.xml configures the inter-vm JMS transport invocation layer. This transport layer is described in org.jboss.mq.il.jvm.JVMServerILService.
deploy/jms/oil-service.xml
The oil-service.xml configures the JMS optimized invocation layer. This transport layer is described in org.jboss.mq.il.oil.OILServerILService (deprecated).
deploy/jms/oil2-service.xml
The oil2-service.xml configures the JMS version 2 optimized invocation layer. It is an experimental work that should not be used and will be dropped in the future.
deploy/jms/rmi-il-service.xml
The rmi-il-service.xml configures the JMS RMI based invocation layer. This is a slow transport layer that should not be used and will be dropped in the future.
deploy/jms/uil2-service.xml
The uil2-service.xml configures the JMS version 2 unified invocation layer. Its a custom socket based transport that is the fastest and most reliable and should be used for inter-vm messaging. This transport layer is described in org.jboss.mq.il.uil2.UILServerILService.
deploy/jmx-console.war
The jmx-console.war directory is an unpackaged web application archive that provides an HTML adaptor for the JMX MBeanServer. The war is unpackaged rather than deployed as a jar archive so that the jmx-console.war/WEB-INF/*.xml descriptors may be edited to configure role based security easily. The jmx-console is discussed in Inspecting the Server - the JMX Console Web Application.
deploy/jmx-invoker-adaptor-server.sar
The jmx-invoker-adaptor-server.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 Connecting to JMX Using Any Protocol.
deploy/mail-service.xml
The mail-service.xml file is an MBean service descriptor that provides JavaMail sessions for use inside of the JBoss server..
deploy/management/console-mgr.sar, web-console.war
The console-mgr.sar and web-console.war are an experimental web application/applet that provide a richer view of the JMX server management data than the jmx-console war. At this time they are still under development. You may view the console using the URL http://localhost:8080/web-console/ .
deploy/properties-service.xml
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 System Properties Management.
deploy/scheduler-service.xml, schedule-manager-service.xml
The scheduler-service.xml, schedule-manager-service.xml files are MBean service descriptors that provides a scheduling type of service. This is discussed further in Scheduling Tasks.
deploy/snmp-adaptor.sar
The snmp-adaptor.sar is a JMX to SNMP adaptor. It allows for the mapping of JMX notifications onto SNMP traps.
deploy/sqlexception-service.xml
The sqlexception-service.xml file is an MBean service descriptor for handling vendor specific handling of java.sql.SQLException s. Its usage is discussed in Entity Commands and Primary Key Generation.
deploy/transaction-service.xml
The transaction-service.xml service descriptor sets up the JBoss JTA transaction manager related services. This and related services are discussed in more detail in Transactions on JBoss - The JTA Transaction Service.
deploy/user-service.xml
The user-service.xml file is a template MBean service descriptor to which you may add your own custom MBean services. Its not necessary to use this file for this purpose however. Writing MBean services is discussed in Writing JBoss MBean Services.
Basic Installation Testing
Once 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 be similar to that shown below and contain no error or exception messages:
[nr@toki bin]$ ./run.sh ================================================================================
JAVA: /System/Library/Frameworks/JavaVM.framework/Home//bin/java
JAVA_OPTS: -Dprogram.name=run.sh
CLASSPATH: /tmp/jboss-3.2.3/bin/run.jar:/System/Library/Frameworks/JavaVM.framework/Home//lib/tools.jar
================================================================================
11:53:32,324 INFO [Server] Starting JBoss (MX MicroKernel)...
11:53:32,407 INFO [Server] Release ID: JBoss [WonderLand] 3.2.3 (build: CVSTag=JBoss_3_2_3 date=200311301445)
11:53:32,415 INFO [Server] Home Dir: /private/tmp/jboss-3.2.3
11:53:32,417 INFO [Server] Home URL: file:/private/tmp/jboss-3.2.3/
11:53:32,417 INFO [Server] Library URL: file:/private/tmp/jboss-3.2.3/lib/
11:53:32,421 INFO [Server] Patch URL: null
11:53:32,424 INFO [Server] Server Name: default
11:53:32,458 INFO [Server] Server Home Dir: /private/tmp/jboss-3.2.3/server/default
11:53:32,499 INFO [Server] Server Home URL: file:/private/tmp/jboss-3.2.3/server/default/
11:53:32,500 INFO [Server] Server Data Dir: /private/tmp/jboss-3.2.3/server/default/data
11:53:32,501 INFO [Server] Server Temp Dir: /private/tmp/jboss-3.2.3/server/default/tmp
11:53:32,501 INFO [Server] Server Config URL: file:/private/tmp/jboss-3.2.3/server/default/conf/
11:53:32,503 INFO [Server] Server Library URL: file:/private/tmp/jboss-3.2.3/server/default/lib/
11:53:32,504 INFO [Server] Root Deployment Filename: jboss-service.xml
11:53:32,518 INFO [Server] Starting General Purpose Architecture (GPA)...
11:53:33,511 INFO [ServerInfo] Java version: 1.4.2_03,Apple Computer, Inc.
11:53:33,512 INFO [ServerInfo] Java VM: Java HotSpot(TM) Client VM 1.4.2-34,"Apple Computer, Inc."
11:53:33,512 INFO [ServerInfo] OS-System: Mac OS X 10.3.3,ppc
11:53:33,648 INFO [ServiceController] Controller MBean online
11:53:33,963 INFO [MainDeployer] Started jboss.system:service=MainDeployer
11:53:34,263 INFO [MainDeployer] Adding deployer: org.jboss.deployment.JARDeployer@1a700a
11:53:34,264 INFO [JARDeployer] Started jboss.system:service=JARDeployer
11:53:34,328 INFO [MainDeployer] Adding deployer: org.jboss.deployment.SARDeployer@b68d78
11:53:34,386 INFO [SARDeployer] Started jboss.system:service=ServiceDeployer
11:53:34,387 INFO [Server] Core system initialized
If your output is similar to this (accounting for installation directory differences), you should now be ready to use JBoss. To shutdown the server, simply issue a Ctrl-C sequence in the console in which JBoss was started. Alternatively, you can use the shutdown.sh command:
A JMX client to shutdown (exit or halt) a remote JBoss server.
usage: shutdown [options] <operation>
-h, --help Show this help message
-D<name>[=<value>] Set a system property
-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 RMI adapter to use
-u, --user=<name> Specify the username for authentication[not implemented yet]
-p, --password=<name> Specify the password for authentication[not implemented yet]
-S, --shutdown Shutdown the server (default)
-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 pass in the name of the directory under JBOSS_DIST/server you wish to use as the value to the -c command line option. For example, to start with the minimal configuration file set you would specify:
[nr@toki bin]$ ./run.sh -c minimal
12:00:26,983 INFO [Server] JBoss (MX MicroKernel) [3.2.3 (build: CVSTag=JBoss_3_2_3 date=200311301445)] Started in 3s:343ms
To view all of the supported command line options for the JBoss server bootstrap class issue run -h command, and the output will be:
-h, --help Show this help message
-V, --version Show version information
-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 (i.e. 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
Booting from a Network Server
One very useful command line option is the --netboot=url 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 the ServerConfig.HOME_URL to the netboot option url argument value. In the absence of any other overrides, all of 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 a 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 book examples/src/main/org/jboss/chap1/build-netboot.xml file. To test the netboot feature, run the build-netboot.xml script specifying the location of the JBOSS_DIST you want to use as the netboot webserver as shown here:
[nr@toki examples]$ ant -Djboss.dist=/tmp/jboss-3.2.3 -buildfile src/main/org/jboss/chap1/build-netboot.xml
Buildfile: src/main/org/jboss/chap1/build-netboot.xml
[mkdir] Created dir: /tmp/jboss-3.2.3/server/netboot
[copy] Copying 32 files to /tmp/jboss-3.2.3/server/netboot
[unzip] Expanding: /tmp/jboss-3.2.3/docs/examples/netboot/netboot.war into /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war
[copy] Copying 14 files to /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war
[copy] Copying 148 files to /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default
[copy] Copying 1 file to /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/jmx-console.war/WEB-INF/lib
[move] Moving 10 files to /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/http-invoker.sarx
[zip] Building zip: /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/http-invoker.sar
[delete] Deleting directory /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/http-invoker.sarx
[move] Moving 8 files to /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/jms/jbossmq-httpil.sarx
[zip] Building zip: /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/jms/jbossmq-httpil.sar
[delete] Deleting directory /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/jms/jbossmq-httpil.sarx
[move] Moving 24 files to /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/jbossweb-tomcat41.sarx
[zip] Building zip: /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/jbossweb-tomcat41.sar
[delete] Deleting directory /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/jbossweb-tomcat41.sarx
[move] Moving 23 files to /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/jmx-console.warx
[zip] Building zip: /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/jmx-console.war
[delete] Deleting directory /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/jmx-console.warx
[move] Moving 2 files to /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/jmx-invoker-adaptor-server.sarx
[zip] Building zip: /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/jmx-invoker-adaptor-server.sar
[delete] Deleting directory /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/jmx-invoker-adaptor-server.sarx
[move] Moving 6 files to /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/snmp-adaptor.sarx
[zip] Building zip: /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/snmp-adaptor.sar
[delete] Deleting directory /tmp/jboss-3.2.3/server/netboot/deploy/netboot.war/server/default/deploy/snmp-adaptor.sarx
You then startup the netboot server by specifying the netboot configuration as follows:
[nr@toki bin]$ ./run.sh -c netboot
=================================================================================
JAVA: /System/Library/Frameworks/JavaVM.framework/Home//bin/java
JAVA_OPTS: -Dprogram.name=run.sh
CLASSPATH: /tmp/jboss-3.2.3/bin/run.jar:/System/Library/Frameworks/JavaVM.framework/Home//lib/tools.jar
================================================================================
11:16:49,563 INFO [Server] Starting JBoss (MX MicroKernel)...
11:16:49,569 INFO [Server] Release ID: JBoss [WonderLand] 3.2.3 (build: CVSTag=JBoss_3_2_3 date=200311301445)
11:16:49,629 INFO [Server] Home Dir: /private/tmp/jboss-3.2.3
11:16:49,632 INFO [Server] Home URL: file:/private/tmp/jboss-3.2.3/
11:16:49,635 INFO [Server] Library URL: file:/private/tmp/jboss-3.2.3/lib/
11:16:49,642 INFO [Server] Patch URL: null
11:16:49,647 INFO [Server] Server Name: netboot
11:16:49,670 INFO [Server] Server Home Dir: /private/tmp/jboss-3.2.3/server/netboot
11:16:49,673 INFO [Server] Server Home URL: file:/private/tmp/jboss-3.2.3/server/netboot/
11:16:49,723 INFO [Server] Server Data Dir: /private/tmp/jboss-3.2.3/server/netboot/data
11:16:49,728 INFO [Server] Server Temp Dir: /private/tmp/jboss-3.2.3/server/netboot/tmp
11:16:49,731 INFO [Server] Server Config URL: file:/private/tmp/jboss-3.2.3/server/netboot/conf/
11:16:49,734 INFO [Server] Server Library URL: file:/private/tmp/jboss-3.2.3/server/netboot/lib/
11:16:49,737 INFO [Server] Root Deployment Filename: jboss-service.xml
11:16:49,749 INFO [Server] Starting General Purpose Architecture (GPA)...
11:16:50,519 INFO [ServerInfo] Java version: 1.4.2_03,Apple Computer, Inc.
11:16:50,526 INFO [ServerInfo] Java VM: Java HotSpot(TM) Client VM 1.4.2-34,"Apple Computer, Inc."
11:16:50,529 INFO [ServerInfo] OS-System: Mac OS X 10.3.3,ppc
11:17:05,413 INFO [MainDeployer] Deployed package: file:/private/tmp/jboss-3.2.3/server/netboot/conf/jboss-service.xml
11:17:05,533 INFO [Server] JBoss (MX MicroKernel) [3.2.3 (build: CVSTag=JBoss_3_2_3 date=200311301445)] Started in 15s:783ms
You can now startup any other instance of JBoss using just the run script and run.jar from the JBOSS_DIST/bin directory. For example:
================================================================================
JAVA_OPTS: -Dprogram.name=run.sh
CLASSPATH: /tmp/jboss-3.2.3/bin/run.jar:/lib/tools.jar
================================================================================
11:15:16,810 INFO [Server] Starting JBoss (MX MicroKernel)...
11:15:16,814 INFO [Server] Release ID: JBoss [WonderLand] 3.2.3 (build: CVSTag=JBoss_3_2_3 date=200311301445)
11:15:16,815 INFO [Server] Home Dir: /private/tmp/jboss-3.2.3
11:15:16,816 INFO [Server] Home URL: http://toki.local.:8080/netboot/
11:15:16,817 INFO [Server] Library URL: http://toki.local.:8080/netboot/lib/
11:15:16,821 INFO [Server] Patch URL: null
11:15:16,822 INFO [Server] Server Name: default
11:15:16,823 INFO [Server] Server Home Dir: /private/tmp/jboss-3.2.3/server/default
11:15:16,824 INFO [Server] Server Home URL: http://toki.local.:8080/netboot/server/default/
11:15:16,825 INFO [Server] Server Data Dir: /private/tmp/jboss-3.2.3/server/default/data
11:15:16,825 INFO [Server] Server Temp Dir: /private/tmp/jboss-3.2.3/server/default/tmp
11:15:16,826 INFO [Server] Server Config URL: http://toki.local.:8080/netboot/server/default/conf/
11:15:16,827 INFO [Server] Server Library URL: http://toki.local.:8080/netboot/server/default/lib/
11:15:16,828 INFO [Server] Root Deployment Filename: jboss-service.xml
11:15:16,839 INFO [Server] Starting General Purpose Architecture (GPA)...
11:15:17,676 INFO [ServerInfo] Java version: 1.4.2_03,Apple Computer, Inc.
11:15:17,679 INFO [ServerInfo] Java VM: Java HotSpot(TM) Client VM 1.4.2-34,"Apple Computer, Inc."
11:15:17,679 INFO [ServerInfo] OS-System: Mac OS X 10.3.3,ppc
11:16:53,266 INFO [MainDeployer] Deployed package: http://toki.local.:8080/netboot/server/default/conf/jboss-service.xml
11:16:53,272 INFO [Server] JBoss (MX MicroKernel) [3.2.3 (build: CVSTag=JBoss_3_2_3 date=200311301445)] Started in 1m:36s:432ms
The custom netboot configuration fileset consists simply of the files needed to run the jbossweb-jbossweb-tomcat41.sar web server and a netboot.war whose content is the JBOSS_DIST/lib and JBOSS_DIST/server/default files.
Building the Server from Source Code
Source code is available for every JBoss module, and you can build any version of JBoss from source by downloading the appropriate version of the code from SourceForge.
Accessing the JBoss CVS Repositories at SourceForge
The JBoss source is hosted at SourceForge, a great Open Source community service provided by VA Linux Systems. With over 80,000 Open Source projects and nearly 850,000 registered users, SourceForge.net is the largest Open Source hosting service available. Many of the top Open Source projects have moved their development to the SourceForge.net site. The services offered by SourceForge include hosting of project CVS repositories and a web interface for project management that includes bug tracking, release management, mailing lists and more. Best of all, these services are free to all Open Source developers. For additional details and to browse the plethora of projects, see the SourceForge home page: ( http://sourceforge.net/ ).
Understanding CVS
CVS (Concurrent Versions System) is an Open Source version control system that is used pervasively throughout the Open Source community. CVS is a Source Control or Revision Control tool designed to keep track of source changes made by groups of developers who are working on the same files. CVS enables developers to stay in sync with each other as each individual chooses.
Anonymous CVS Access
The JBoss project's SourceForge CVS repository can be accessed through anonymous (pserver) CVS with the following instruction set. The module you want to check out must be specified as the modulename. When prompted for a password for anonymous, simply press the Enter key. The general syntax of the command line version of CVS for anonymous access to the JBoss repositories is:
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/jboss login
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/jboss co modulename
The first command logs into JBoss CVS repository as an anonymous user. This command only needs to be performed once for each machine on which you use CVS because the login information will be saved in your HOME/.cvspass file or equivalent for your system. The second command checks out a copy of the modulename source code into the directory from which you run the cvs command. To avoid having to type the long cvs command line each time, you can set up a CVSROOT environment variable with the value ":pserver:anonymous@cvs.jboss.sourceforge.net:/cvsroot/jboss" and then use the following abbreviated versions of the previous commands:
The name of the JBoss module alias you use depends on the version of JBoss you want. For the 3.0 branch the module name is jboss-3.0, for the 3.2 branch it is jboss-3.2, and in general, for branch x.y the module name is jboss-x.y. To checkout the HEAD revision of jboss to obtain the latest code on the main branch you would use jboss-head as the module name. Releases of JBoss are tagged with the pattern JBoss_X_Y_Z where X=major version, Y=minor version and Z=patch version. Release branches of JBoss are tagged with the pattern Branch_X_Y. Some checkout examples are:
cvs co -r Branch_3_0 jboss-3.0 # Checkout the current 3.0 branch code
cvs co -r JBoss_3_0_6 jboss-3.0 # Checkout the 3.0.6 release version code
cvs co -r Branch_3_2 jboss-3.2 # Checkout the current 3.2 branch code
cvs co -r JBoss_3_2_3 jboss-3.2 # Checkout the 3.2.3 release version code
Obtaining a CVS Client
The command line version of the CVS program is freely available for nearly every platform, and is included by default on most Linux and Unix distributions. A good port of CVS as well as numerous other Unix programs for Win32 platforms is available from Cygwin at http://sources.redhat.com/cygwin/ . The syntax of the command line version of CVS will be examined because this is common across all platforms.
For complete documentation on CVS, check out the CVS home page at http://www.cvshome.org/ .
Building the JBoss-3.2.3 Distribution Using the Source Code
Every JBoss release includes a source archive that contains everything needed to build the release and is available from the files section of the JBoss project site here: http://sourceforge.net/projects/jboss/ . The source directory structure matches that of the cvs source tree described below so once you have the source distribution you can build the release by following the instructions given in the next section, beginning with the instructions after the step to obtain the jboss-3.2 source tree.
Building the JBoss-3.2.3 Distribution Using the CVS Source Code
This section will guide you through the task of building a JBoss distribution from the CVS source code. To start, create a directory into which you want to download the CVS source tree, and move into the newly created directory. This directory is referred to as the CVS_WD directory for CVS working directory. The example build in this book will check out code into a /tmp/3.2.3 directory on a Linux system. Next, obtain the 3.2.3 version of the source code as shown here1:
[nrrrr@toki 3.2.3]$ export CVSROOT=:pserver:anonymous@cvs.sourceforge.net:/cvsroot/jboss
[nr@toki 3.2.3]$ cvs co -r JBoss_3_2_3 jboss-3.2
cvs server: Updating tools/apache
The resulting jboss-3.2 directory structure contains all of the cvs modules required to build the server. To perform the build, cd to the jboss-all/build directory and execute the build.sh or build.bat file as appropriate for you OS. You will need to set the JAVA_HOME environment variable to the location of the JDK you wish to use for compilation. For this example build, JAVA_HOME is set to a Sun JDK 1.4.1 installation located under /home/starksm/Java/j2sdk1.4.1_02.
Listing 1-1, the JBoss 3.2.x branch build process
[orb@toki 3.2.3]$ cd jboss-3.2/build/
[orb@toki build]$ export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Home/[orb@toki build]$ PATH=$JAVA_HOME/bin:$PATH
Buildfile: /tmp/3.2.3/jboss-3.2/build/build.xml
Total time: 2 minutes 41 seconds
Note that if you see an error like the following:
file:/tmp/3.2.3/jboss-3.2/server/build.xml:233: Failed to launch JJTree
you do not have the JAVA_HOME/bin directory in your PATH. The JavaCC JJTree Ant task needs this for some reason currently.
The build process is driven by an Ant based configuration. The main Ant build script is the build.xml file located in the jboss-3.2/build directory. This script uses a number of custom Ant tasks masked as buildmagic constructs. The purpose of the main build.xml file is to compile the various module directories under jboss-3.2 and then to integrate their output to produce the binary release. The binary release structure is found under the jboss-3.2/build/output directory. The example above used the build.sh script to kickoff the build process. This is just a wrapper the launches the ant binary included in the distribution. You can simply use ant if you have your environment setup to run Ant from the command line.
An Overview of the JBoss CVS Source Tree
The top-level directory structure under the jboss-3.2 source tree is illustrated in Figure 1-3, the CVS source tree top-level directories.See Descriptions of the top-level directories of the JBoss CVS source tree.. gives the primary purpose of each of the top-level directories.
TABLE 1-1. Descriptions of the top-level directories of the JBoss CVS source tree.
Using the JBossTest unit testsuite
More advanced testing of the JBoss installation and builds can be done using the JBoss testsuite. The JBossTest suite is a collection of client oriented unit tests of the JBoss server application. It is an Ant based package that uses the JUnit ( http://www.junit.org ) unit test framework. The JBossTest suite is used as a QA benchmark by the development team to help test new functionality and prevent introduction of bugs. It is run on a nightly basis and the results are posted to the development mailing list for all to see.
The unit tests are run using Ant and the source for the tests are contained in the jboss-3.2/testsuite directory of the source tree. The structure of the testsuite CVS module is illustrated in See The unit tests are run using Ant and the source for the tests are contained in the jboss-3.2/testsuite directory of the source tree. The structure of the testsuite CVS module is illustrated in Figure ...
FIGURE 1-3. The testsuite CVS module directory structure
The two main source branches are src/main and src/resources. The src/main tree contains the Java source code for the unit tests. The src/resources tree contains resource files like deployment descriptors, jar manifests, web content, etc. The root package of every unit test is org.jboss.test. The typical structure below each specific unit test subpackage (for example, security) consists of a test package that contains the unit test classes. The test subpackage is a required naming convention as this is the only directory searched for unit tests by the Ant build scripts. If the tests involves EJBs then the convention is to include an interfaces, and ejb subpackage for these components. The unit tests themselves need to follow a naming convention for the class file. The unit test class must be named XXXUnitTest.java, where XXX is either the class being tested or the name of the functionality being tested.
To run the unit tests use the build scripts located in the jboss-all/testsuite directory. The key targets in the build.xml file include:
- tests: this target builds and runs all unit tests and generates HTML and text reports of the tests into the testsuite/output/reports/html and testsuite/output/reports/text directories respectively.
- tests-standard-unit: builds all unit tests and runs a subset of the key unit tests. This is useful for quick check of the server to test for gross problems.
-
test: this target allows one to run all tests within a particular package. To run this target you need to specify a test property that specifies a package name using -Dtest=package command line. The package value is the name of the package below org.jboss.test you want to run unit tests for. So, for example, to run all unit tests in the org.jboss.test.naming package, you would use:
build.sh -Dtest=naming test -
one-test: this target allows you to run a single unit test. To run this target you need to specify a test property that specifies the classname of the unit test using -Dtest=classname on the command line. So, for example, to run the org.jboss.test.naming.test.ENCUnitTestCase, you would use:
build.sh -Dtest=org.jboss.test.naming.test.ENCUnitTestCase one-test - tests-report: this target generates html and text reports of the tests into the testsuite/output/reports/html and testsuite/output/reports/text directories respectively using the current JUnit xml results in the testsuite/output/reports directory. This is useful for generating the nice html reports when you have run a subset of the tests by hand and want to generate a summary.
On completion of a test the testsuite/output/reports directory will contain one or more XML files that represent the individual JUnit test runs. The tests-report target collates these into an html report located in the html subdirectory along with a text report located in the text subdirectory. See An example testsuite run report status html view as generated by the testsuite. shows an example of the html report for a run of the test suite against the JBoss-3.2.3 release.
You can find the results of the testsuite in the jboss distribution in under the JBOSS_DIST/docs/tests directory.
