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 customizable middleware platform. The server binary and source code distributions are available from the SourceForge repository. (http://sourceforge.net/projects/jboss). 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 is a step-by-step tutorial about how to install and configure JBoss 3.2. You will learn how to:
You will also learn about:
The most recent release of JBoss is available from the SourceForge JBoss project files page, http://sourceforge.net/projects/jboss. You will also find previous releases as well as beta and release candidate versions of upcoming releases.
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 with a 1.3.1 JDK would produce version number like the following.
[nr@toki tmp]$ java -version java version "1.3.1" Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1-root_1.3.1_031103-17:49) Java HotSpot(TM) Client VM (build 1.3.1_03-76, 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 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 within the 0-1023 privileged port range.
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.6.zip archive contents into a location of your choice. The jboss-3.2.6.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.6 directory. The following section explores the contents of this directory.
As mentioned above, installing the JBoss distribution creates a jboss-3.2.6 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. Figure 1.1, “The 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.
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.6 directory as the JBOSS_DIST directory. In Figure 1.1, “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 Table 1.1, “The JBoss directory structure”. 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 Figure 1.1, “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
Table 1.1. The JBoss directory structure
|bin||All the entry point JARs and start scripts included with the JBoss distribution are located in the bin directory.|
|client||JARs required for clients are located in
the client directory. A
typical client requires the following:
|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.1.3, “The Default Server Configuration File Set”||SERVER_BASE_DIR ="jboss.server.base.dir"SERVER_BASE_URL ="jboss.server.base.url"|
|lib||The lib directory contains startup JARs used by JBoss. Do not place your own libraries in this directory.||LIBRARY_URL ="jboss.lib.url"|
|conf||The conf directory contains the bootstrap descriptor, jboss-service.xml by default, file for a given server configuration. This defines the core services that are fixed for the lifetime of the server.||SERVER_CONFIG_URL ="jboss.server.config.url"|
|data||The data directory is a location available for use by services that want to store content in the file system.||SERVER_DATA_DIR ="jboss.server.data.dir"|
|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 referred to the by bootstrap descriptor. All JARs in this directory are loaded into the shared classpath.||SERVER_LIBRARY_URL ="jboss.server.lib.url"|
|log||The log directory is the default directory into which the bootstrap logging service places its logs. This may be overridden through the conf/log4j.xml configuration file.||none|
|tmp||The tmp directory is the location to which deployments are copied for local use.||SERVER_TEMP_DIR="jboss.server.temp.dir"|
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.
Figure 1.2. An expanded view of the default server configuration file set conf and deploy directories
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:
[orb@toki bin]$ sh run.sh ========================================================================= JBoss Bootstrap Environment JBOSS_HOME: /tmp/jboss-3.2.6 JAVA: /System/Library/Frameworks/JavaVM.framework/Home//bin/java JAVA_OPTS: -Dprogram.name=run.sh CLASSPATH: /tmp/jboss-3.2.6/bin/run.jar:/System/Library/Frameworks/JavaVM.framework/Home //lib/tools.jar ========================================================================= 11:41:32,879 INFO [Server] Starting JBoss (MX MicroKernel)... 11:41:32,898 INFO [Server] Release ID: JBoss [WonderLand] 3.2.6 (build: CVSTag=JBoss_3_2_ 6 date=200410140106) 11:41:32,902 INFO [Server] Home Dir: /private/tmp/jboss-3.2.6 11:41:33,039 INFO [Server] Home URL: file:/private/tmp/jboss-3.2.6/ 11:41:33,043 INFO [Server] Library URL: file:/private/tmp/jboss-3.2.6/lib/ 11:41:33,140 INFO [Server] Patch URL: null 11:41:33,147 INFO [Server] Server Name: default 11:41:33,237 INFO [Server] Server Home Dir: /private/tmp/jboss-3.2.6/server/default 11:41:33,250 INFO [Server] Server Home URL: file:/private/tmp/jboss-3.2.6/server/default/ 11:41:33,256 INFO [Server] Server Data Dir: /private/tmp/jboss-3.2.6/server/default/data 11:41:33,260 INFO [Server] Server Temp Dir: /private/tmp/jboss-3.2.6/server/default/tmp 11:41:33,266 INFO [Server] Server Config URL: file:/private/tmp/jboss-3.2.6/server/defaul t/conf/ 11:41:33,270 INFO [Server] Server Library URL: file:/private/tmp/jboss-3.2.6/server/defau lt/lib/ 11:41:33,276 INFO [Server] Root Deployment Filename: jboss-service.xml 11:41:33,342 INFO [Server] Starting General Purpose Architecture (GPA)... 11:41:35,176 INFO [ServerInfo] Java version: 1.4.2_05,Apple Computer, Inc. 11:41:35,180 INFO [ServerInfo] Java VM: Java HotSpot(TM) Client VM 1.4.2-38,"Apple Comput er, Inc." 11:41:35,190 INFO [ServerInfo] OS-System: Mac OS X 10.3.5,ppc 11:41:37,259 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:
[nr@toki bin]$ ./shutdown.sh A JMX client to shutdown (exit or halt) a remote JBoss server. usage: shutdown [options] <operation> options: -h, --help Show this help message -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 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] operations: -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 ... 22:26:49,566 INFO [Server] JBoss (MX MicroKernel) [3.2.6RC2 (build: CVSTag=Branch_3_2 dat e=200409270100)] Started in 11s:744ms
To view all of the supported command line options for the JBoss server bootstrap class issue run -h command, and the output will be:
usage: run.sh [options] 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
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.6 -buildfile src/main/org/jboss/chap1/ build-netboot.xml Buildfile: src/main/org/jboss/chap1/build-netboot.xml netboot: [mkdir] Created dir: /tmp/jboss-3.2.6/server/netboot [copy] Copying 44 files to /tmp/jboss-3.2.6/server/netboot [unzip] Expanding: /tmp/jboss-3.2.6/docs/examples/netboot/netboot.war into /tmp/jboss- 3.2.6/server/netboot/deploy/netboot.war [copy] Copying 14 files to /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war [copy] Copying 211 files to /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server /default [copy] Copied 1 empty directory to /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war /server/default [copy] Copying 1 file to /tmp/jboss-3.2.6/server/netboot/deploy/jbossweb-tomcat50.sar /META-INF zipdir: [move] Moving 10 files to /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/d efault/deploy/http-invoker.sarx [zip] Building zip: /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/defaul t/deploy/http-invoker.sar [delete] Deleting directory /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/d efault/deploy/http-invoker.sarx zipdir: [move] Moving 6 files to /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/de fault/deploy/jms/jbossmq-httpil.sarx [zip] Building zip: /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/defaul t/deploy/jms/jbossmq-httpil.sar [delete] Deleting directory /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/d efault/deploy/jms/jbossmq-httpil.sarx zipdir: [move] Moving 35 files to /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/d efault/deploy/jbossweb-tomcat50.sarx [zip] Building zip: /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/defaul t/deploy/jbossweb-tomcat50.sar [delete] Deleting directory /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/d efault/deploy/jbossweb-tomcat50.sarx zipdir: [move] Moving 22 files to /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/d efault/deploy/jmx-console.warx [zip] Building zip: /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/defaul t/deploy/jmx-console.war [delete] Deleting directory /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/d efault/deploy/jmx-console.warx zipdir: [move] Moving 5 files to /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/de fault/deploy/management/console-mgr.sarx [zip] Building zip: /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/defaul t/deploy/management/console-mgr.sar [delete] Deleting directory /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/d efault/deploy/management/console-mgr.sarx zipdir: [move] Moving 53 files to /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/d efault/deploy/management/web-console.warx [zip] Building zip: /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/defaul t/deploy/management/web-console.war [delete] Deleting directory /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/d efault/deploy/management/web-console.warx zipdir: [move] Moving 2 files to /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/de fault/deploy/jmx-invoker-adaptor-server.sarx [zip] Building zip: /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/defaul t/deploy/jmx-invoker-adaptor-server.sar [delete] Deleting directory /tmp/jboss-3.2.6/server/netboot/deploy/netboot.war/server/d efault/deploy/jmx-invoker-adaptor-server.sarx BUILD SUCCESSFUL
You then startup the netboot server by specifying the netboot configuration as follows:
[nr@toki bin]$ ./run.sh -c netboot ========================================================================= JBoss Bootstrap Environment JBOSS_HOME: /tmp/jboss-3.2.6 JAVA: /System/Library/Frameworks/JavaVM.framework/Home//bin/java JAVA_OPTS: -Dprogram.name=run.sh CLASSPATH: /tmp/jboss-3.2.6/bin/run.jar:/System/Library/Frameworks/JavaVM.framework/Home //lib/tools.jar ========================================================================= 13:53:38,479 INFO [Server] Starting JBoss (MX MicroKernel)... 13:53:38,488 INFO [Server] Release ID: JBoss [WonderLand] 3.2.6RC2 (build: CVSTag=Branch_ 3_2 date=200409270100) 13:53:38,503 INFO [Server] Home Dir: /private/tmp/jboss-3.2.6 13:53:38,552 INFO [Server] Home URL: file:/private/tmp/jboss-3.2.6/ 13:53:38,555 INFO [Server] Library URL: file:/private/tmp/jboss-3.2.6/lib/ 13:53:38,563 INFO [Server] Patch URL: null 13:53:38,568 INFO [Server] Server Name: netboot 13:53:38,598 INFO [Server] Server Home Dir: /private/tmp/jboss-3.2.6/server/netboot 13:53:38,644 INFO [Server] Server Home URL: file:/private/tmp/jboss-3.2.6/server/netboot/ 13:53:38,648 INFO [Server] Server Data Dir: /private/tmp/jboss-3.2.6/server/netboot/data 13:53:38,653 INFO [Server] Server Temp Dir: /private/tmp/jboss-3.2.6/server/netboot/tmp 13:53:38,656 INFO [Server] Server Config URL: file:/private/tmp/jboss-3.2.6/server/netboo t/conf/ 13:53:38,660 INFO [Server] Server Library URL: file:/private/tmp/jboss-3.2.6/server/netbo ot/lib/ 13:53:38,663 INFO [Server] Root Deployment Filename: jboss-service.xml 13:53:38,679 INFO [Server] Starting General Purpose Architecture (GPA)... 13:53:40,057 INFO [ServerInfo] Java version: 1.4.2_05,Apple Computer, Inc. 13:53:40,060 INFO [ServerInfo] Java VM: Java HotSpot(TM) Client VM 1.4.2-38,"Apple Comput er, Inc." 13:53:40,131 INFO [ServerInfo] OS-System: Mac OS X 10.3.5,ppc 13:53:41,883 INFO [Server] Core system initialized 13:53:45,468 INFO [Log4jService$URLWatchTimerTask] Configuring from URL: resource:log4j.x ml 13:53:47,754 INFO [NamingService] Started jnpPort=1099, rmiPort=1098, backlog=50, bindAdd ress=/192.168.168.110, Client SocketFactory=null, Server SocketFactory=org.jboss.net.socke ts.DefaultSocketFactory@ad093076 13:53:53,702 INFO [Embedded] Catalina naming disabled 13:53:57,796 INFO [Http11Protocol] Initializing Coyote HTTP/1.1 on http-192.168.168.110-8 080 13:53:58,102 INFO [Catalina] Initialization processed in 3578 ms 13:53:58,108 INFO [StandardService] Starting service jboss.web 13:53:58,185 INFO [StandardEngine] Starting Servlet Engine: Apache Tomcat/5.0.28 13:53:58,360 INFO [StandardHost] XML validation disabled 13:53:58,575 INFO [Catalina] Server startup in 469 ms 13:53:59,277 INFO [TomcatDeployer] deploy, ctxPath=/, warUrl=file:/private/tmp/jboss-3.2. 6/server/netboot/deploy/jbossweb-tomcat50.sar/ROOT.war/ 13:54:03,106 INFO [TomcatDeployer] deploy, ctxPath=/netboot, warUrl=file:/private/tmp/jbo ss-3.2.6/server/netboot/deploy/netboot.war/ 13:54:04,111 INFO [Http11Protocol] Starting Coyote HTTP/1.1 on http-192.168.168.110-8080 13:54:04,797 INFO [ChannelSocket] JK2: ajp13 listening on /192.168.168.110:8009 13:54:04,883 INFO [JkMain] Jk running ID=0 time=1/303 config=null 13:54:04,898 INFO [Server] JBoss (MX MicroKernel) [3.2.6RC2 (build: CVSTag=Branch_3_2 dat e=200409270100)] Started in 25s:64ms
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:
[orb@rubik bin]$ sh run.sh --netboot=http://192.168.168.110:8080/netboot/ ========================================================================= JBoss Bootstrap Environment JBOSS_HOME: /tmp/jboss-3.2.6 JAVA: /System/Library/Frameworks/JavaVM.framework/Home//bin/java JAVA_OPTS: -Dprogram.name=run.sh CLASSPATH: /tmp/jboss-3.2.6/bin/run.jar:/System/Library/Frameworks/JavaVM.framework/Home //lib/tools.jar ========================================================================= 13:55:40,847 INFO [Server] Starting JBoss (MX MicroKernel)... 13:55:40,867 INFO [Server] Release ID: JBoss [WonderLand] 3.2.6RC2 (build: CVSTag=Branch_ 3_2 date=200409270100) 13:55:40,874 INFO [Server] Home Dir: /private/tmp/jboss-3.2.6 13:55:40,877 INFO [Server] Home URL: http://192.168.168.110:8080/netboot/ 13:55:40,880 INFO [Server] Library URL: http://192.168.168.110:8080/netboot/lib/ 13:55:40,928 INFO [Server] Patch URL: null 13:55:40,931 INFO [Server] Server Name: default 13:55:40,934 INFO [Server] Server Home Dir: /private/tmp/jboss-3.2.6/server/default 13:55:40,940 INFO [Server] Server Home URL: http://192.168.168.110:8080/netboot/server/de fault/ 13:55:40,943 INFO [Server] Server Data Dir: /private/tmp/jboss-3.2.6/server/default/data 13:55:40,946 INFO [Server] Server Temp Dir: /private/tmp/jboss-3.2.6/server/default/tmp 13:55:40,950 INFO [Server] Server Config URL: http://192.168.168.110:8080/netboot/server/ default/conf/ 13:55:40,954 INFO [Server] Server Library URL: http://192.168.168.110:8080/netboot/server /default/lib/ 13:55:40,957 INFO [Server] Root Deployment Filename: jboss-service.xml 13:55:41,014 INFO [Server] Starting General Purpose Architecture (GPA)... ...
The custom netboot configuration fileset consists simply of the files needed to run the bossweb-tomcat50.sar web server and a netboot.war whose content is the JBOSS_DIST/lib and JBOSS_DIST/server/default files.
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.
The JBoss source is hosted at SourceForge, a great Open Source community service provided by VA Linux Systems. With over 88,000 Open Source projects and nearly 950,000 registered users, SourceForge.net is the largest Open Source hosting service available. Many of tche top Open Source projects have moved their development to the sourcesorge.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/).
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.
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:email@example.com:/cvsroot/jboss login cvs -z3 -d:pserver:firstname.lastname@example.org:/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:email@example.com:/cvsroot/jboss and then use the following abbreviated versions of the previous commands:
cvs login cvs -z3 co modulename
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 is the major version, Y is the minor version and Z is the 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_6 jboss-3.2 # Checkout the 3.2.6 release version code cvs co jboss-head # Checkout the curent HEAD branch code
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/.
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.
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.6 directory on a Linux system. Next, obtain the 3.2.6 version of the source code as shown here:
[nr@toki tmp]$ mkdir 3.2.6 [nr@toki tmp]$ cd 3.2.6 [nrrrr@toki 3.2.6]$ export CVSROOT=:pserver:firstname.lastname@example.org:/cvsroot/jboss [nr@toki 3.2.6]$ cvs co -r JBoss_3_2_6 jboss-3.2 cvs server: Updating tools U tools/.classpath U tools/.donotremove U tools/.project 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.
[nr@toki 3.2.6]$ cd jboss-3.2/build/ [nr@toki build]$ export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Home/ [nr@toki build]$ PATH=$JAVA_HOME/bin:$PATH [nr@toki build]$ ./build.sh Searching for build.xml ... Buildfile: /tmp/3.2.6/jboss-3.2/build/build.xml ... BUILD SUCCESSFUL Total time: 2 minutes 41 seconds
Note that if you see an "Failed to launch JJTree" error do not have the JAVA_HOME/bin directory in your PATH required for the JavaCC JJTree Ant task.
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.
The top-level directory structure under the jboss-3.2 source tree is illustrated in Figure 1.3, “The testsuite CVS module directory structure”, the CVS source tree top-level directories. Table 1.2, “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.2. Descriptions of the top-level directories of the JBoss CVS source tree.
|build||The main build directory from which the release builds are initiated|
|cache||The JBoss TreeCache module|
|cluster||The clustering support services source module.|
|common||A source module of common utility type code used by many of the other source modules.|
|compatible||A backward compatibility module currently under development|
|connector||The JCA support and application server integration source module.|
|console||Admin apps for viewing the JMX MBeans|
|hibernate||The hibernate deployer service.|
|iiop||The RMI/IIOP transport service source module.|
|j2ee||The core J2EE interfaces and classes.|
|jaxrpc||The J2EE web services module.|
|jboss.net||A web services support source module that provides support for using SOAP to invoke operations on EJBs and MBeans.|
|jmx||The JBoss JMX implementation source module.|
|management||The JBoss JSR-77 source module.|
|messaging||The JBoss JMS implementation source module.|
|naming||The JBoss JNDI implementation source module.|
|security||The JBoss standard J2EE declarative security implementation based on JAAS.|
|server||The EJB 2.0 container implementation related source.|
|system||The JMX micro kernel based bootstrap services and standard deployment services source module.|
|testsuite||The JUnit unit test source module.|
|thirdparty||A module containing the third-party binary jars used by the JBoss modules.|
|tomcat||The Tomcat-5.0.x embedded service source module|
|tools||The jars used by the JBoss build process.|
|transaction||The JTA transaction manager|
|varia||Various utility services that have not or will not been integrated into one of the higher-level modules.|
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 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 manifest, 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 testsuite directory. The key targets in the build.xml file include:
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. Figure 1.4, “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.6 release.
You can find the results of the testsuite in the JBoss distribution in under the JBOSS_DIST/docs/tests directory.
Note that many tests require a running JBoss instance to deploy to. The build script does not start the JBoss instance. You will need to manually start the JBoss server in the all configuration before running the tests.
 There was a change in the module aliases used to obtain the complete JBoss source tree just prior to the 3.0.4 release. Now, instead of using jboss-all as the module alias for every branch, a branch specific module alias is defined. For the 3.0 branch this is jboss-3.0, for the 3.2 branch it is jboss-3.2, etc. To checkout the HEAD revision of jboss to obtain the latest code on the main branch you would use jboss-head as the module alias.