Server-Side Java with Jakarta-Tomcat

Simple ways to build web applications using servlets.

We could continue to use Tomcat as our main HTTP server. However, it is neither as fast nor as configurable as Apache or most other servers. For this reason, it's typical to use Apache for most HTTP requests and to forward servlet- or JSP-related requests to Tomcat.

In order for Apache to communicate with Tomcat, we must compile a module into our Apache server. The traditional way was with mod_jserv, based on a project called JServ. A new module, known as mod_jk, compiles into your Apache server similarly to mod_jserv but uses a more efficient and flexible protocol to communicate with Tomcat.

The easiest way to install mod_jk is to download the source code for Tomcat from the Jakarta web site. Even if you have downloaded the binary version of Tomcat for general use, you will need to retrieve the source code in order to compile and install mod_jk. After you unpack the source distribution, change to src/native/apache1.3. If you are using an early version of Apache 2.0, you should go to src/native/apache2.0 for the mod_jk source code.

The following instructions assume you have built your Apache server with the ability to handle DSO, dynamically loaded modules that were not originally compiled into the server. DSO is a wonderfully flexible mechanism for adding new modules; not all modules can always handle this flexibility, and you might find yourself compiling some or all of your Apache server statically. While mod_jk can certainly be compiled statically, the on-line documentation encourages users to install it as a DSO, both because it is easier to do so and because it means that you can update mod_jk without having to recompile Apache.

Compiling a module as a DSO means it must link against the Apache server using the names and addresses that were specified at the server's time of compilation. In order for us to compile modules with the same environment and information as the server, Apache provides apxs, a Perl program that ensures our modules are compiled correctly. apxs takes the same arguments as cc, as well as several of its own that allow us to install the module automatically.

From inside the apache1.3 directory, we can compile mod_jk in httpd.conf with the following command:

/usr/local/apache/bin/apxs -i -o -I../jk \
   -I$JAVA_HOME/include \
   -I$JAVA_HOME/include/linux -c *.c ../jk/*.c

If you enter the above command in three lines, rather than one, remember to include the backslashes (\) as the final character on each of the first two lines. Also note that we did not include the -a option, which activates the module in the Apache configuration file, because (as we shall soon see) that is done from within another, automatically generated, configuration file.

Now that mod_jk is installed, we must get Tomcat and mod_jk to speak to each other. Normally, Tomcat expects to receive requests from Apache with the Ajpv12 protocol. However, mod_jk and Tomcat both understand the Ajpv13 protocol, which is more advanced in a number of ways. We will thus need to modify our Tomcat configuration so that it supports Ajpv13, and then configure Apache to use that protocol to communicate with Tomcat.

Tomcat has two configuration files, one for the HTTP server (web.xml) and one for the Java servlet container (server.xml) files. Even if you have never worked with XML, you should not have to worry very much; not only is XML easy to learn, but the Tomcat configuration files are heavily commented. Both configuration files are in the $TOMCAT_HOME/conf directory.

In order to tell Tomcat to use Ajpv13, we must find the section of server.xml that defines the Ajp12 connector. The section normally looks like this when you install Tomcat:


    <Parameter name="handler"

    <Parameter name="port" value="8007"/>

As you can see, this defines the TCP/IP connector handler and indicates that Tomcat should use the Ajp12ConnectionHandler object in the org.apache.tomcat.service.connector package. We will add a similar block immediately following the one shown above:

<Connector className="org.apache.tomcat.service.

   <Parameter name="handler"

   <Parameter name="port" value="8009"/>
Aside from changing the name of the handler object, you can see that we have modified the port number to be 8009.

The mod_jk instructions make it clear that we should add the new Ajp13 handler to server.xml, leaving the Ajp12 handler in place. Otherwise, there may be problems when you try to shut down Tomcat.

Shut down Tomcat with $TOMCAT_HOME/bin/, and start it up again with $TOMCAT_HOME/bin/, just to make sure that the configuration changes did not break anything. If all is fine, you should see messages indicating that the HttpConnectionHandler is running on port 8080, the Ajp12ConnectionHandler is running on port 8007 and the Ajp13ConnectionHandler is running on port 8009.

The easiest and fastest way to tell Apache how to connect to Tomcat is to use mod_jk.conf-auto, a file that Tomcat generates each time it is restarted. This file, which is located in $TOMCAT_HOME/conf, contains all of the Apache directives necessary to load and use Tomcat. You simply need to include this set of definitions from within your Apache configuration:

Include /usr/java/jakarta-tomcat-3.2.1/conf/mod_jk.conf-auto

mod_jk.conf-auto is not only useful and automatic, it also provides a good sense of how to configure mod_jk and how to create sophisticated interactions between Apache and Tomcat. One thing to remember when working with Apache and Tomcat is that Apache must always start up after Tomcat is running so it can connect to the appropriate socket.



Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Where is it?

Andy Canfield's picture

servlet.jar is now named servlet-api.jar. Use 'locate' to find it on your particular system.