# 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.
   - for Tomcat 3.3.x: This directory will be referred as $TOMCAT_HOME.
     Set the TOMCAT_HOME variable in your environment and export it.
   - for Tomcat 4.0.x: This directory will be referred as $CATALINA_HOME.
     If you want to share a single copy of Tomcat 4 among multiple users on the same server, you must configure a CATALINA_BASE environment variable (in addition to CATALINA_HOME) that points to a directory that is unique to your instance. Set both variables in your environment and export them.
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:

- An EJBServer running the different JOnAS services and possibly the registry
- A Tomcat server running servlets and JSPs
- Your brother accessing remotely html pages, servlets and JSPs.

The directory structure of your application should look like this:

etc | the web.xml file describing your web application
web | html, images, JSPs that will be copied in TOMCAT directory
src | servlet sources, should mimic the package hierarchy
beans | beans 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:

- The Alarm demo
- The WebSample example

## Writing a servlet accessing a bean

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

- create an initial context.
- lookup the bean home
- find or create a bean and access it

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 `usebean`alarm 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:

make | to compile the whole application
make install | to 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.