Chapter 11. Howto

Table of Contents

Tomcat and JBoss - A Full J2EE Stack
Using JBoss-Jetty (under construction)
Using MS SQL Server with JBoss
Running the Examples from Enterprise JavaBeans, by Richard Monson-Haefel (Unix)
How to Integrate Custom Services via MBeans
JMX Connector Description and HowTo
How To us the Timer MBean
Deployment on JBoss
JAAS Based Security in JBoss
Using JavaMail in JBoss
Integrating JBuilder 4.0 Foundation with JBoss for source level debugging
How to Run and Debug EJBs using jBoss 2.0 inside of Visual Age for Java version 3.5
Integrating NetBeans/Forte for Java Community Edition with JBoss for source level debugging
EJX/AWT Development HowTo
JBossCX Configuration
External JNDI Configuration and JNDI Viewing
Customizing the JRMPContainerInvoker Socket Factories
Configuring and Using JAXP 1.1 In JBoss
Using Verifier in Ant
Deploying the Pet Store 1.1.1 Demo in JBoss
How to Integrate a Web Container into JBoss

Tomcat and JBoss - A Full J2EE Stack

The JBoss organization wants to deliver a complete J2EE based product to the market. The JBoss organization decided to integrate the Tomcat engine stack with a running version of JBoss in a single VM. Now you can serve all your servlet and JSP needs with 2 simple downloads and a couple of configuration files. Check out the Tomcat homepage for information related to Tomcat.

The goal of this page is to explain how to make JBoss automatically start Tomcat, so that it runs in the same VM.

We now run optimized stacks the JSP/Servlet engine talks natively with the EJB engine resulting in dramatic speed increases. Without the optimization the invocation is through the network layer. With the optimized layers the invocation is native, inVM, within the same stack of APIs


  • Parsing of server.xml for full Tomcat configuration support

  • Support for Tomcat 3.2 and up

  • Coming support for Catalina

  • Full j2ee integration in JMX

  • single startup/shutdown script

  • Separated stacks inVM

  • Integrated stacks inVM

  • J2EE deployer for JBoss/Tomcat

  • Full EAR support

  • JBoss Auto-Deploy for EAR

  • JNDI shared visibility

  • Integrated Security Model

Mailing lists

Refer to Tomcat's homepage for questions specific to Tomcat deployment.

Questions about the J2EE deployer and the integration should be posted to our lists (JBoss)

Distribution and CVS

JBoss Tomcat is shipped as part of the standard JBoss/Server package. However, the current distribution is based on an earlier version of EmbeddedTomcat that does not parse Tomcat's server.xml. If you don't need server.xml parsed (ie, you're not trying to integrate with Apache), then the current version may be the easiest route for you.

The Pre-2.1 CVS source contains a new version of EmbeddedTomcat (plus other enhancements) that does parse Tomcat's server.xml. It is recommended that you use the information provided below. This new version of EmbeddedTomcat will be rolled in to the official 2.1 release.

How-to build and install EmbeddedTomcat

You will need

You can get the latest CVS version of JBoss Pre-2.1 from here. Grab both and to build JBoss and EmbeddedTomcat.

You can get the latest release of tomcat from the jakarta website. NOTE: This has been tested with tomcat 3.2.1 However it won't run on tomcat 3.1, and tomcat 3.3 is not suppported yet.

  1. Build JBoss from src

    Build JBoss from the CVS sources. This is generally accomplished by changing to the src/build directory and executing (or build.bat on NT). The build creates a dist directory under the src root. This dist directory will be referred to as the JBOSS_HOME for the EmbeddedTomcat build.

  2. Build EmbeddedTomcat(optional)

    Build the EmbeddedTomcat service from the contrib CVS sources if you want. This is optional as the current JBoss cvs src includes a prebuilt version of the tomcat-service.jar. To build the EmbeddedTomcat service, change to the contrib/tomcat/src/build directory and execute (or build.bat on NT). NOTE: You need to define environment values for JBOSS_HOME and TOMCAT_HOME to fit your environment. JBOSS_HOME needs to point to the dist directory of the JBoss build step and TOMCAT_HOME is the dist directory of the jakarta-tomcat-3.2.x release.

    Once this build completes, execute client. This will create a new tomcat-test.ear.

    Once you've built EmbeddedTomcat, copy contrib/tomcat/tomcat-service.jar to $JBOSS_HOME/lib/ext. Finally, copy contrib/tomcat/tomcat-test.ear to $JBOSS_HOME/deploy.

  3. Add the tomcat libs to the server classpath

    In JBOSS_HOME/conf/default/ edit jboss.conf file to uncomment the ClassPathExtension mbean for the tomcat lib directory to:

    Figure 11.1. Adding tomcat classes to classpath

           <!--Uncomment to add Tomcat classes to classpath -->
           <MLET CODE = "org.jboss.util.ClassPathExtension" ARCHIVE="jboss.jar" CODEBASE="../../lib/ext/">
             <ARG TYPE="java.lang.String" VALUE="TOMCAT_HOME/lib/">
             <ARG TYPE="java.lang.String" VALUE="Tomcat">

    where TOMCAT_HOME value must be set to the full path described above in the build of the EmbeddedTomcat service. Note that there must be a trailing slash(/) in order for the jars in the lib directory to be added to the classpath.

  4. Edit jboss.jcml

    In JBOSS_HOME/conf/default/ edit the jboss.jcml file to uncomment the EmbeddedTomcatService mbean. Locate:

    Figure 11.2. EmbeddedTomcat MBean inclusion before

             Uncomment to add embedded tomcat service
             <mbean code="org.jboss.tomcat.EmbeddedTomcatService" name="DefaultDomain:service=EmbeddedTomcat" />

    and uncomment the mbean line so it reads as follows:

    Figure 11.3. EmbeddedTomcat MBean inclusion after

             Uncomment to add embedded tomcat service
             <mbean code="org.jboss.tomcat.EmbeddedTomcatService" name="DefaultDomain:service=EmbeddedTomcat" />

    Further down in the jboss.jcml file, make sure your J2eeDeployer is set as:

    Figure 11.4. J2eeDeployer setting

             <mbean code="org.jboss.deployment.J2eeDeployer" name="J2EE:service=J2eeDeployer">
               <attribute name="DeployerName">Default</attribute>
               <attribute name="JarDeployerName">:service=ContainerFactory</attribute>
               <attribute name="WarDeployerName">:service=EmbeddedTomcat</attribute>
  5. Edit Tomcat's server.xml

    Add the following lines to server.xml in TOMCAT_HOME/conf/

    Figure 11.5. Change in server.xml

           <!-- JBoss, Setup the class loader heirarchy to enable in VM call optimization.
                   Add after the org.apache.tomcat.context.WorkDirInterceptor ContextInterceptor
                   <ContextInterceptor className="org.jboss.tomcat.ContextClassLoaderInterceptor" />
           <!-- JBoss, Add the jboss-web.xml parser. Add after the org.jboss.tomcat.ContextClassLoaderInterceptor
                   <ContextInterceptor className="org.jboss.tomcat.naming.JbossWebXmlReader" />
           <!-- JBoss, Set the request thread classloader. Add before the org.apache.tomcat.request.SessionInterceptor
                   <RequestInterceptor className="org.apache.tomcat.request.Jdk12Interceptor" />
           <!-- JBoss, Map the current web user to the SecurityAssociation principal. Add
                           after the org.apache.tomcat.request.SimpleRealm RequestInterceptor
                   <RequestInterceptor className="" />
  6. Adding javac to the server classpath

    If you are going to be using JSP files with tomcat, you need to add the JDK lib/tools.jar file to the classpath to pickup the javac compiler. You can do this by either setting your CLASSPATH env variable, by editing to add tools.jar to CLASSPATH, or by copying tools.jar to the TOMCAT_HOME/lib directory.

  7. Start JBoss

    If you start JBoss now by typing (or run.bat for Windows) you should see the following Tomcat related output in your log messages:

    Figure 11.6. Embedded Tomcat started properly

           Using configuration "default"
           [Info] Java version: 1.3.0_01,Sun Microsystems Inc.
           [Info] Java VM: Java HotSpot(TM) Server VM 1.3.0_01,Sun Microsystems Inc.
           [Info] System: Linux 2.2.16-22,i386
           [EmbeddedTomcat] Starting
           [EmbeddedTomcat] Starting EmbeddedTomcat....
           2001-02-20 05:01:23 - ContextManager: Adding context Ctx( /examples )
           2001-02-20 05:01:23 - ContextManager: Adding context Ctx( /admin )
           [EmbeddedTomcat] Starting tomcat. Check logs/tomcat.log for error messages 
           2001-02-20 05:01:23 - ContextManager: Adding context Ctx(  )
           2001-02-20 05:01:23 - ContextManager: Adding context Ctx( /test )
           2001-02-20 05:01:25 - PoolTcpConnector: Starting HttpConnectionHandler on 8080
           2001-02-20 05:01:25 - PoolTcpConnector: Starting Ajp12ConnectionHandler on 8007
           [EmbeddedTomcat] OK
           [EmbeddedTomcat] Started
           [Default] JBoss PRE-2.1 Started in 0m:14s

That's it !! Note that the connection handlers are configured from Tomcat's server.xml file.

How-to package and deploy an EAR file on JBoss/Tomcat

In order to benefit from the classloader integration, you have to deploy your application in an EAR file as recommended by the J2EE specification.

In case you don't want to read all the J2EE spec, here is a brief summary of what you have to do:

  1. Write your beans and package them in an ejb-jar file.

    You don't have to do anything special here. See the manual for details on how to package beans for JBoss.

  2. Write your servlets/JSPs and package them in a war file.

    Add a Class-Path attribute to your war files MANIFEST.MF file to reference your beans package. for detailed information on that see: J2eeDeployment Howto.

    Assuming you have a bean deployed under the jndi name "myBean", the calls to this bean from your servlets will look like that:

           MyBeanHome home = (MyBeanHome)new InitialContext().lookup("myBean");
           MyBean bean = home.create();


    Since JBoss takes care of the classloader stuff, you don't have to include much in the WEB-INF/lib directory: you don't need any of your beans interfaces, and you don't need the old jboss-client.jar, jnp-client.jar...

  3. Package your application in an ear file.

    An ear file is a jar archive which contains:

    • Your jar files

    • Your war files

    • A deployment descriptor for your application.

      This file must be named "application.xml", and must be located in the META-INF directory in the ear archive. This file tells JBoss which modules are EJBs, which ones are web modules, and the context paths for the web-modules. Here is a sample application.xml file:

      Figure 11.7. Example application.xml

                  <?xml version="1.0" encoding="ISO-8859-1"?>
                      <display-name>My application</display-name>

      See also the DTD for application.xml on Javasoft's website.

  4. Deploy your ear file.

    Option 1: Copy your ear file to JBOSS_HOME/deploy (wow!)

    Option 2: Surf to http://yourhost:8082, and find the J2eeDeployer service. Give it the URL of your ear file (don't forget the protocol, be it http: or file:), and click on the deploy button.

  5. That's it!

    The server console should show your application being deployed on Tomcat and JBoss, and your web module should be available on http://yourhost:8080/servlets (assuming the context-root was "/servlets").

    Note: Even though JBoss and Tomcat are cooperating to dynamically deploy your application, Apache must be configured manually. This means that for your application to be visible through Apache, you must setup the appropriate JkMount statements in mod_jk.conf.

For a full example including a servlet and an EJB, see the tomcat-test.ear in the contrib/tomcat module

[1] The MANIFEST.MF referred to is the one inside the ejb or war archive and NOT the one directly in the ear archive.

[2] There is a "feature" of the jdk jarfile reader that means that you need to have a carriage return after the Class-Path entry in the manifest file - otherwise it is not found.