In-Process HowTo

By Gal Shachor <shachor@il.ibm.com>

This document explains how to set up Netscape/IIS web servers so that Tomcat will run inside the web server process. It assumes that you have already followed the instructions in the web server specific howto and configured it to use Tomcat as an out of process servlet container.

Normally Tomcat is running in one process and the web servers runs in another; this however requires the web server to communicate using some IPC mechanism such as TCP/IP.
When Tomcat is running inside the web server process, requests for servlet execution are passed using JNI (and performance improves).

Note: Running the JVM inside the web server is not always a good idea. Sure it gives the best performance, but is lacks the stability associated with the out of process mode of operation. When deciding to run in-process make sure that top speed is what you need.

Document Conventions and Assumptions

<tomcat_home> is the root directory of tomcat. Your Tomcat installation should have the following subdirectories:

1. <tomcat_home>\conf - Where you can place various configuration files
2. <tomcat_home>\webapps - Containing example applications
3. <tomcat_home>\bin - Where you place web server plugins

In all the examples in this document <tomcat_home> will be c:\jakarta-tomcat.

A worker is defined to be a Tomcat process that accepts work from the web server.

Supported Configuration

For in-process operation you will have to use the Netscape/IIS redirectors, look at their supported configuration sections.

The in-process adapter has been tested using JDK 1.1.7b, IBM's JDK 1.1.7, JDK 1.1.8, JDK 1.2.2., and JDK 1.3.

Installation

As of Tomcat 3.2, a pre-built version of the in-process adapter, jni_connect.dll, is available under the win32/i386 directory where you downloaded the Tomcat binary distribution. For those using Netscape as your browser, try downloading a zip version of the file, if available. There can be problems using Netscape to download DLL files.

The Tomcat JNI adapter requires the following actions:

1. Putting jni_connect.dll under the bin directory - jni_connect.dll is used to issue callbacks from Tomcat back to the web server, either obtain a pre-built DLL or build it yourself (see the build section).
2. Update workers.properties and add the JNI worker - The JNI worker needs several configuration items, you will need to add those to the worker properties file.
3. Updating server.xml - You need to instruct Tomcat to use the JNI connection handlers. You will also need to provide the home property for your ContextManager (later on the log files and work directories will be created under this home).
4. Directing context(s) to the in-process Tomcat - You need to instruct the redirector to send work to the in-process Tomcat
5. Restart your server (so changes will take effect)

Putting jni_connect.dll under the bin directory

Put jni_connect.dll inside <tomcat_home>\bin\win32\i386\.

Update workers.properties and add the JNI worker

You should provide the JNI worker with several settings, some are mandatory and some are an option...

Note: The following instructions assume Tomcat is installed at c:\jakarta-tomcat. Adjust them appropriately to your Tomcat installation directory.

1. You should define a JNI worker.
   Set the worker.list property to point on a worker named jni: worker.list=jni
   Announce that the worker named jni is of type jni: worker.jni.type=jni
2. You should set a classpath to be use by the in-process Tomcat.
   To set the classpath use the worker.name.class_path property, for example:
   worker.jni.class_path=c:\jakarta-tomcat\classes
   worker.jni.class_path=c:\jakarta-tomcat\lib\jaxp.jar
   worker.jni.class_path=c:\jakarta-tomcat\lib\parser.jar
   worker.jni.class_path=c:\jakarta-tomcat\lib\jasper.jar
   worker.jni.class_path=c:\jakarta-tomcat\lib\servlet.jar
   worker.jni.class_path=c:\jakarta-tomcat\lib\webserver.jar
   worker.jni.class_path=c:\jdk1.2.2\lib\tools.jar
   Note: Do not forget to include the JDK's tools.jar in your classpath.
3. You should provide a full path to the dll implementing the JVM. For JDK1.1.x it is javai.dll, for JDK1.2.x it is jvm.dll. For example:
   worker.jni.jvm_lib=c:\jdk1.2.2\jre\bin\classic\jvm.dll
4. You should provide command line options for Tomcat; you must provide a -config option to specify your JNI configured server.xml. For example:
   worker.jni.cmd_line=-config
   worker.jni.cmd_line=c:\jakarta-tomcat\conf\jni_server.xml
   Note: The cmd_line string doesn't support embedded spaces. If the path to the jni_server.xml file includes spaces, use the DOS 8.3 name for directories that would otherwise contain a space.
5. You should specify the tomcat home location as a Java system properties. For example:
   worker.jni.sysprops=tomcat.home=c:\jakarta-tomcat
6. You can specify additional Java system properties. For example:
   worker.jni.sysprops=java.compiler=NONE
7. You can specify files to by used by the JVM for stdout and stderr. For example:
   worker.jni.stdout=c:\jakarta-tomcat\logs\jvm.stdout
   worker.jni.stderr=c:\jakarta-tomcat\logs\jvm.stderr
8. You can specify additional PATH, to be use when loading dlls (useful when you are using native code). For example:
   worker.jni.ld_path=c:\SQLLIB\bin
   worker.jni.ld_path=c:\my\native\code

You can find a sample worker file (jni_workers.properties) under jakarta-tomcat/conf. The contents of this file assume that Tomcat is installed at c:\jakarta-tomcat. Modify as needed if Tomcat is installed at a different location.

Update server.xml

By default Tomcat reads the file <tomcat_home>\conf\server.xml. This file defines among other things the contexts and connectors used by Tomcat. In order to work in-process you will have to perform the following actions:

1. You should update the connectors list.
   Remove all the connectors from your server.xml and add the following lines (note that you will need to update the area marked with <tomcat_home>)

       <!-- JNI connector, make sure that you update the native_lib
                Parameter to point to your jni_connect.dll
        -->
       <Connector className="org.apache.tomcat.service.JNIEndpointConnector">
           <Parameter name="native_lib"
               value="<tomcat_home>/bin/win32/i386/jni_connect.dll"/>
       </Connector>
     

   These lines add a JNI connector to Tomcat.
2. You should update the home attribute used by the ContextManager so that the ContextManager will know where to place the log, work and webapps directories. For example:

       <ContextManager debug="0" workDir="work" home="<tomcat_home>" />
       .
       .
       .
       </ContextManager />
     

   Again, make sure that you update <tomcat_home> to your real Tomcat root.

Redirect contexts to the JNI workers

You will need to select the contexts that you wish to serve using your jni worker.

On Netscape you can do that by modifying the lines in the servlet configuration object to reflect redirect work to the new JNI worker. For example:

    <Object name=servlet>
    ObjectType fn=force-type type=text/plain
    Service fn="jk_service" worker="jni"
    </Object>

On IIS you will have to modify your worker mount file to mount contexts to the JNI worker. For example:

When you are done restart your server. That's all, you should now be able to execute Tomcat in-process.

Building the JNI connector dll

The JNI connector was developed using Visual C++ Ver.6.0, so having this environment is a prereq if you want to perform a custom build. You will also need a JDK installation (the jre is not good enough) in order to use the JDK's include files.

The steps that you need to take are:

1. Change directory to the JNI connector source directory.
2. Make sure that the environment variable JAVA_HOME is set and points to your JDK installation
3. Execute the following command:
   MSDEV jni_connect.dsp /MAKE ALL
   If msdev is not in your path, enter the full path to msdev.exe

This will build both release and debug versions of the JNI connector.

An alternative will be to open the jni_connect workspace file (jni_connect.dsw) in msdev and build it using the build menu.

How does it work?

1. During the initialization the server redirector starts the JNI worker.
2. Upon startup the JNI worker creates a JVM inside the web server and starts Tomcat in it.
3. For each in-coming request for a servlet, the server redirector will check which worker is responsible for the specific context. If this worker is the JNI worker then the request is assigned to it.
4. The JNI worker attaches to the JVM and submits the request into the Tomcat engine (using the JNIEndpointConnector). Tomcat will then execute the request.
5. The server redirector collects the response from the JNI worker and returns it to the browser.

Feedback

Please send feedback, bug report or any additional information to tomcat-dev@jakarta.apache.org.

$Id: in-process-howto.html,v 1.1.2.2 2000/11/04 20:37:46 craigmcc Exp $