Integrating Tomcat and JOnAS (for JOnAS version < JOnAS2.6)

This guide describes how to integrate JOnAS with Tomcat from Apache. JOnAS will be used to run your beans inside EJB containers while Tomcat will be used to run your servlets or JSPs. Inside these servlets or JSPs, you will be allowed to access remotely beans inside the JOnAS EJBServer.

For the cases when you need security, Tomcat will be used also for user authentication. Refer to the security guide for more information on how to use security with JOnAS and Tomcat.

Here after are described the following steps to configure JOnAS and Tomcat to make them working together.

There are two families of Tomcat products: Tomcat3.3.x and Tomcat 4.0.x that differ on several points. In the following we describe how to work with each Tomcat family.

  1. Installing Tomcat
  2. Configuring Tomcat for JOnAS
  3. Structuring your Web Application
  4. Writing a servlet accessing a bean
  5. Writing a JSP accessing a bean
  6. Compiling your Web Application
  7. Running your Web Application
  8. Troubleshooting

Installing Tomcat

  1. Download Tomcat at Apache site
  2. Install Tomcat by unzipping the download file and put it in a specific directory.
  3. On Windows, set the JAVA_HOME variable in your environment to your JDK installation directory.

Configuring Tomcat for JOnAS

Since JOnAS 2.4.4 a new JOnAS service tomcat is provided for launching a servlet container Tomcat inside the JOnAS JVM.
Since JOnAS 2.5 two implementations of this service are provided one for Tomcat 3.3.x another for Tomcat 4.0.x.
All you have to do is to add tomcat in the jonas.services property of jonas.properties file and to set the jonas.service.tomcat.class property of jonas.properties file to:

  1. org.objectweb.jonas.tomcat.EmbeddedTomcatImpl33 for Tomcat 3.3.x (this is the default value)
  2. org.objectweb.jonas.tomcat.EmbeddedTomcatImpl40 for Tomcat 4.0.x

Note that if you want to run the servlet container and the ejb container in separate JVM, you can run two instances of JOnAS server, one with only the tomcat service, and another with all other services but tomcat.

Structuring your Web Application

A Web Application is made of several parts:

The directory structure of your application should look like this:

etcthe web.xml file describing your web application
webhtml, images, JSPs that will be copied in TOMCAT directory
srcservlet sources, should mimic the package hierarchy
beansbeans sources, should mimic the package hierarchy

In case your beans comes from another application, you don't need the bean directory.

2 examples using Tomcat and JOnAS are provided with the JOnAS distribution. They can be found in the example directory:

Writing a servlet accessing a bean

You must write in your servlet code the same code you would write in a simple java application:

An example of java servlet can be found in the websample example.

Writing a JSP accessing a bean

Writing JSPs in place of java servlet allows you to easily create web content that has both static and dynamic components. JSP offers all the dynamic capabilities of Java Servlet but provides a more natural approach to creating static content. More details about using JSPs can be found on java.sun.com

It could be a good idea to hide all the mechanisms to access EJBs from JSPs by using a proxy java bean, refered in the JSP by the usebeanalarm example. Just look at one of the .jsp files. A proxy java bean ViewProxy.java has been used to contain the glue necessary to access EJB.

Compiling your Web Application

With ant you can compile the Web applications that you'll find under $JONAS_ROOT/examples.
You have to do build install for compilling examples and installing .war file in tomcat.

If you use the gnu make, you just have to do:
maketo compile the whole application
make installto install the .war file in tomcat

You can also run compilers manually via compile.sh or compile.bat.

Looking at the alarm example, the following steps are performed to rebuild all the web application:

  1. make install in the bean directory, to build the alarm.jar file and install it in $JONAS_ROOT/ejbjars
  2. create in output/webapps an alarm directory that will be used to build the alarm.war file that will be installed in $TOMCAT_HOME/webapps ($CATALINA_HOME/webapps)
  3. copy $JONAS_ROOT/ejbjars/alarm.jar in output/webapps/alarm/WEB-INF/lib. This is the way servlets or JSP will see bean classes. Another possibility would be to make this classes accessible by the classpath.
  4. copy etc/web.xml in output/webapps/alarm/WEB-INF
  5. copy all files under web directory in output/webapps/alarm
  6. make a .war file with all the directory hierarchy under output/webapps/alarm

Installing the application is copying alarm.war in $TOMCAT_HOME/webapps ($CATALINA_HOME/webapps) and copying apps-alarm.xml $TOMCAT_HOME/conf (for Tomcat 4.0.x apps-alarm.xml is not used).

Running your Web Application

You are now ready to run your web application:

  1. start the EJBServer with the tomcat service
  2. Use your brother to access the welcome page, usually index.html

Troubleshooting

Under certain circonstances with JOnAS (JEREMIE), you may have a java.lang.ClassCastException in a servlet that makes:
home = (XXHome)PortableRemoteObject.narrow(initialContext.lookup("XXHome"), XXHome.class);
The workaround with Tomcat 3.3.x is to make visible from the CLASSPATH the ejb-jar file in which the class XXHome is defined.
The workaround with Tomcat4.0.x is to remove the ejb-jar file from $TOMCAT_HOME/webapps/WEB-INF/lib and to make it visible from the CLASSPATH.