Introduction

Tomcat is a popular open source Java Server Pages and Java Servlet engine, provided through the Apache Software Foundation.  Tomcat is part of the Apache Jakarta Project.  Tomcat is a basic HTTP server, but not very efficient at processing files other than the JSP and servlets.  That is the primary reason to link Tomcat to a server such as Apache 2 or the Microsoft Information Server (IIS).  Tomcat can handle the JSP and servlets, and the the industrial-strength HTTP server can handle the balance of the pages.  The marriage allows for a mixture of Java and Perl, PHP, ASP and other technologies that the Tomcat server cannot offer by itself.

The Tomcat server must run parallel to Apache or IIS.  These HTTP servers are linked to Tomcat by use of a connector.  The job of the connector is to identify requests for a URL that is actually a JSP or servlet, and then forward those requests to the Tomcat server for processing.  The connector is actually a filter that is positioned to examine every request reaching the HTTP server.  Those which are not Java related it ignores.  The Java related requests are passed to the Tomcat server.

There have been several connectors constructed to perform this task, but the current supported connector under the Tomcat project is the Coyote JK2 connector.  The source code is downloadable from the Jakarta Web site.

Downloads

Downloads are available from the Jakarta Web site, and the last compiled versions for Apache 2 are located here.  There is some support for Apache 1.3 with a modified compilation, but that is outside the scope of our interest.  The Java Native Interface (JNI) is may be used by experienced developers to integrate programs written in another language such as C++ into the Java environment.

Linux
mod_jk2-2.0.43.so	The filter module for the Apache HTTP 2.0.42 & 2.0.43 servers
jkjni-2.0.so	The JNI callback module for the Apache HTTP 2.0.43 server
Solaris
mod_jk2-2.0.43.so	The filter module for the Apache HTTP 2.0.42 & 2.0.43 servers
jkjni.so	The JNI callback module for the Apache HTTP 2.0.43 server
Windows
mod_jk2-2.0.43.dll	The filter module for the Apache HTTP 2.0.43 server
isapi_redirector2.dll	The filter module for Microsoft Internet Information Services 4.0 & 5.0

You will also need the workers2.properties file which is almost identical for all platforms.

Configuring Coyote JK2 for Apache 2

The Apache 2 configuration is very straightforward.

1. Determine the root of the Apache 2 directory structure.
2. Copy the filter module for your platform (mod_jk2-2.0.43.so, or mod_jk2.0.43.dll) to the Apache2/modules directory.
3. If JNI is also being supported in Linux or Solaris, copy that module as well.
4. Copy the workers2.properties file to the Apache2/conf directory.
5. Edit the workers2.properties file and change the ${serverroot} entries to the Apache2 directory.  For Windows systems forward or backward slashes are both acceptable.  We normally choose forward slashes to remain consistent with the prototype entries.
6. Edit the httpd.conf file in the Apache2/conf directory.
7. Locate where the modules are loaded, and add an entry to load the Coyote module (the extension is .so for Linux or Solaris, and .dll for Windows).

LoadModule jk2_module modules/mod_jk2-2.0.43.so, or
LoadModule jk2_module modules/mod_jk2-2.0.43.dll

8. Restart the HTTP service.  In Linux or Solaris use "apachectl stop" and "apachectl start".  In Windows locate the Apache2 service in the Services Management Console (Administrative Tools -> Services), and restart it.
9. Check the jsp and servlet engine by using the URLs http://localhost/examples/jsp/index.html, and http://localhost/examples/servlets/index.html.
10. Make sure regular pages are still working.

Configuring Coyote J2K for Microsoft Internet Information Services

1. Locate the top of the Tomcat 4 installation, by default this should be c:\program files\apache group\tomcat 4.1.
2. Copy the isapi_redirector2.dll to the top of the Tomcat 4 installation.
3. Copy the worker2.properties file to the conf directory at the top of the Tomcat insallation.
4. Edit the worker2.properties file, specifically looking for the two lines containing ${serverroot}.  Replace that ${serverroot} with the path to the Tomcat directory.  Forward or backwards slashes are OK, we normally choose forward slashes to remain consistent with the prototype entries.
5. Edit the registry, and make sure the key “HKEY_LOCAL_MACHINE\Software\Apache Software Foundation\Jakarta Isapi Redirector\2.0” exists.  Create the key if it does not exist.
6. In the key, create the following strings.  Replace ${serverroot} with the path to the Tomcat directory (as in step 4), but use a Windows path with backslashes:
    

The logging level should be set to error unless there is a problem that needs troubleshooting.  Log messages go to the Windows application event log, not into a file.

7. Close the registry editor.
8. Open the Internet Information Services management console from Administrative Tools.
9. In the appropriate Web site (probably the “Default Web Site”), create a virtual directory named “jakarta”.  This needs to be connected to the Tomcat directory where the isapi_redirector2.dll file is located.  Assign execute permission to the new entry.
10. Open the properties of the Web site, and click on the “ISAPI Filters” tab.
11. Click on the add button to add a new filter entry.
12. Name the filter “Jakarta”.
13. Set the location of the filter to the path of the isapi_redirector2.dll file.
14. Click OK to add the filter, and OK again to save the changes.
15. Open the properties dialog for the Web site again and check the ISAPI Filters page to make sure the filter loaded correctly (it should have a green arrow pointing upwards).  If it did not load correctly, then check the registry and the workers2.properties file for errors.
16. Close the properties page if it is open, and close the Internet Information Services management console.
17. Check the jsp and servlet engine by using the URLs http://localhost/examples/jsp/index.html, and http://localhost/examples/servlets/index.html.
18. Make sure regular pages are still working.