| |
Table of Contents
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
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)
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.
You will need
You can get the latest CVS version of JBoss Pre-2.1 from here. Grab both jboss-cvs.zip and contrib-cvs.zip 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.
Build JBoss from the CVS sources. This is generally accomplished by changing to the src/build directory and executing build.sh (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.
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 build.sh (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 build.sh 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.
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">
</MLET>
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.
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>
<mbean>
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
-->
<ContextInterceptor className="org.jboss.tomcat.naming.JbossWebXmlReader" />
<!-- JBoss, Set the request thread classloader. Add before the org.apache.tomcat.request.SessionInterceptor
RequestInterceptor
-->
<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="org.jboss.tomcat.security.JbossRealm" />
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 run.sh/run.bat to add tools.jar to CLASSPATH, or by copying tools.jar to the TOMCAT_HOME/lib directory.
If you start JBoss now by typing run.sh (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.
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:
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.
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();Notes:
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...
Package your application in an ear file.
An ear file is a jar archive which contains:
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"?>
<application>
<display-name>My application</display-name>
<module>
<web>
<web-uri>webmodule.war</web-uri>
<context-root>/servlets</context-root>
</web>
</module>
<module>
<ejb>beans.jar</ejb>
</module>
</application>
See also the DTD for application.xml on Javasoft's website.
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.
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
 | |