Posted: 18 May 2005

Abstract

The JBoss Application Server (JBoss AS) which ships with SUSE Linux Enterprise Server 9 (SLES9) is a J2EE 1.4 certified, scalable, open source, enterprise class Java Application Server. With its superior performance, and strict standards compliance it is taking the Application Server market place by storm.

In this paper we familiarize the reader with JBoss on SLES9, covering installation, configuration and basic use while highlighting some special SLES nuances.

1. Java Application Servers, J2EE and JBoss
2. Installing
3. Setting JBoss to Run as a Service
4. JBoss Directory Structure
5. Server Configurations
6. Hello World! and Deployment

Java Application Servers, J2EE and JBoss

JBoss is a Java Application Server ? an software tool that provides an execution environment for Java 2 Enterprise Edition (J2EE) component based services. J2EE components incorporate several differing technologies such as Java Servlets, Java Server Pages (JSP), XML and Enterprise Java Beans (EJB). Java Application Servers provide the supporting framework for these J2EE components, supplying much of the low-level prosaic services such as security, scalability, protocol support etc... freeing the developer to concentrate on the business logic.

JBoss began in 1999 as a pure EJB environment under the development of Marc Fleury, the founding father of JBoss Inc. From these humble beginnings JBoss AS has rapidly evolved into a full enterprise capable product, and is self declared the most popular application server available.

Installing

Installation couldn't be easier, simply open up YaST search for "JBoss", select and install. Since the application server is in essence a Java application, the installer will require a Java Runtime Environment (JRE) to be installed if one does not already exist. If you are planning to develop to JBoss, a Java Development Environment (commonly know as a JDK) will also be required. These packages may be found on the distribution via searching for "java" in YaST.

Once a JRE or JDK is installed, the Java management scripts on SLES9 will automatically set the JAVA_HOME variable and are capable of maintaining multiple Java environments on a single SLES9 machine. JAVA_HOME is important as a prerequisite for running JBoss.

Setting JBoss to Run as a Service

After installation we can easily set JBoss up to run as a service via YaST, System -> Runlevel Editor as shown.

Check JBoss is running via surfing to http://localhost:8080/jmx-console

JBoss Directory Structure

Having verified the installation, now is a good time to look at what's been placed where.

The majority of the installation is located under a single directory, referenced in the startup scripts as the JBOSS_HOME. On SLES9 this is /usr/share/jboss, under which you will find a hierarchy common to all JBoss installations:

• bin/
  Scripts to control JBoss.
  
• client/
  Libraries for use by remote clients.
  
• docs/ (symlink to /usr/share/doc/packages/jboss/docs)
  Guess what, it's documentation!
  
• lib/
  Core libraries.
  
• server/ (symlink to /src/www/jboss)
  Services hosted and served.

On SLES, JBoss is installed as a Linux Standards Base (LSB) compliant application, that is to say that all the components of the installation are located in well defined directories according to the LSB standard. This differs slightly to a "normal" JBoss installation detailed in the JBoss documentation. To support both directory layouts with minimal fuss, some of the directories in the standard JBoss hierarchy on SLES9 are symlinks to the correct locations according to the LSB, thus providing LSB compliance almost transparently.

Server Configurations

Of the above top level directories, probably most important is server/. This directory is the home for the differing configurations of services hosted by JBoss. With a vanilla installation there are three sample configurations: default, minimal and all, each of which exists as a subdirectory under server/.

These three standard configurations all provide to various degrees, the set of core services available from JBoss.

• Minimal ? just the bare bones such as logging and hot-deployment.
  
• Default ? not surprisingly the default configuration if no other is specified. This provides everything in minimal plus security, transaction services and RMI amongst others.
  
• All ? the whole kitten caboodle! Everything in default plus clustering, webservices and more.
  

Drilling down further into each configuration we see yet another common hierarchy below.

• conf/ (symlink to /etc/jboss/<config-name>)
  Meta-information for the configuration.
  
• data/
  Data store for JBoss. This directory is created by JBoss when the configuration is started for the first time.
  
• deploy/
  Location for the deployed components - dynamically scanned do detect any additions or changes made while JBoss is running (hot-deployment).
  
• lib/
  Libraries (in addition to the core ones) required by this configuration.
  
• log/ (symlink to /var/log/jboss/<config-name>)
  Service specific logs. Like data/ this directory is created by JBoss on first instantiation.
  
• tmp/
  Used as temporary store by JBoss. Similarly to log/ and data/ this directory is created by JBoss.
  
• work/ (symlink to /var/cache/jboss/<config-name>)
  Used for JSP caching.
  

In addition to the predefined configurations, we may can create new ones with our own bespoke set of services. The easiest way to do this and maintain the correct directory structure is to copy one of the standard ones such as default. Once copied you may notice that the other configurations have owner and group set to jboss, while the new configuration will be root. This can be safely ignored since the ownership of the directory will be set to jboss when the application server loads this configuration.

# cp -R default simon
# ll
drwxr-xr-x  6  jboss jboss 216 2005-04-24 13:35 all
drwxr-xr-x  6  jboss jboss 216 2005-04-24 13:43 default
drwxr-xr-x  5  jboss jboss 192 2005-04-24 13:35 minimal
drwxr-xr-x  6  root  root  216 2005-04-25 13:35 simon

To get JBoss to use this customized configuration instead of the default one we must edit /etc/sysconfig/j2ee on our SLES9 box and change the JBOSS_CONFIG variable from "default" to our new configuration name. You may also noticed that the JBOSS_HOME environment variable is also specified in this file.

...
JBOSS_CONFIG="simon"

Now that JBOSS_CONFIG has been updated, it's time to restart JBoss. This can either be done via YaST -> System -> Runlevel Editor which we saw previously, or as always for system services we can do this on the command line as follows:

# cd /etc/init.d
# ./jboss restart
Shutting down jboss			done
Starting up jboss(simon)			done
#

Hello World! and Deployment

With our new server configuration up and running, let's deploy an application to it. Applications tend to be contained within a single archive file which is deployed by simply dropping it into the deploy/ directory under the server configuration. The hot-deploy service mentioned earlier is one of the core services and will automatically load this application ready for use. Likewise applications may be undeployed via removal from this directory.

Before we can do this we need something to deploy, for this we'll use our old friend the "Hello World!" program. In this instance we're going to create a Hello World Java Server Page (JSP), packaging it up in a Web Application Archive (WAR) and then copy this to deploy directory of the server configuration discussed above.

Step 1 ? Create a directory for our code

This should be done outside of the JBoss environment since we'll be deploying it there when it's complete and "packaged up". Probably the best place for this would be your home directory.

$ mkdir HelloWorld
$ cd HelloWorld

Step 2- Create index.jsp

This is the JSP which does the work. In our case this will output "Hello World!" and the current date to the browser. Don't worry about the details, they're beyond the scope of this document. For further information see Java 2 Platform, Enterprise Edition (J2EE) in the References section at the end of this paper.

<%@ page import="java.util.*" %>
<html>
     <head><title>Hello World</title></head>	
     <body>
          <%! String message = "Hello, World!"; %> 
          <h1><%= message%> </h1>
          Today's date: <%= new Date() %>
     </body>
</html>

Step 3 ? Create the WEB-INF directory

WAR archives have there own standard directory structure where the web-container (a service JBoss provides to serve JSPs and servlets) will expect to find certain files. One of these well known directories is WEB-INF, which is required to contain web.xml which we'll create next.

$ mkdir WEB-INF
$ cd WEB-INF

Step 4 ? Create web.xml in the WEB-INF directory

With WEB-INF created we now create a minimal web.xml file. This describes the Web Application to JBoss and allows it to hook into many of the core services. We're keeping it small and simple here. Again don't worry about the details.

<web-app>
     <display-name>Hello World</display-name>
</web-app> 

Step 5 ? Check the $JAVA_HOME environment variable

What Java environment are we using? By default this will be a Java Runtime Environment (JRE) ? i.e. all the binaries and libraries required to run Java applications. But we want the development environment which includes much more, including the Java Archive program.

$ cd ../
$ echo $JAVA_HOME
/usr/lib/java/jre

Step 6 ? Change to a development Java environment

Providing we've installed a JDK from the SLES9 distribution media, then we can simply change the current environment with the setJava script (see "How To Port Java Applications To SUSE Linux" for more details concerning Java on SUSE).

$ source setJava ?-devel
$ echo $JAVA_HOME
/usr/lib/SunJava2-1.4

Step 7 ? Create the WAR archive

Almost there! Now we've got JAVA_HOME pointing to a development environment we can use the environment variable to get hold of the jar tool and create the WAR file. We specify we want to package our JSP and web.xml keeping the directory structure we so diligently created.

$ $JAVA_HOME/bin/jar -cvf HelloWorld.war *.jsp WEB-INF/

With the newly created HelloWorld.war we now deploy this to JBoss, which will then be picked up automatically.

$ cd /usr/share/jboss/server/simon/deploy
# cp ~/snattrass/HelloWorld/HelloWorld.war .

Finally we want to test our application via navigating to http://localhost:8080/HelloWorld. Since we named the file index.jsp the web-container recognizes this an an index page and loads it automatically without the need to specify it explicitly in the URL address bar.

So there we have it, the famous "Hello World!", written and deployed to JBoss on SUSE Linux Enterprise Server 9!

Summary

As we've seen it's easy to get off the ground with JBoss and not only is it packaged with SUSE Linux Enterprise Server 9, but it's Linux Standard Base compliant too!. Together JBoss and SLES9 let you concentrate on the business logic while taking the burden out of enterprise application development.

References

• JBoss Application Server
  http://www.jboss.org/products/jbossas
  
• Java 2 Platform, Enterprise Edition (J2EE)
  http://java.sun.com/j2ee
  
• How To Port Java Applications To SUSE Linux
  http://www.novell.com/coolsolutions/feature/11231.html
  
• Linux Standard Base Project
  http://www.linuxbase.org/
  
• Manually Creating a Simple Web ARchive (WAR) File
  http://access1.sun.com/techarticles/simple.WAR.html