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 d:\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 was tested using JDK1.1.7b/IBM's JDK 1.1.7/JDK1.2.2/JDK 1.3.0/JDK 1.3.1

Installation

The in-process adapter is not part of the "official" build of Jakarta, You can obtain the code and binaries needed for it by accessing http://jakarta.apache.org/builds/tomcat/release/v3.3/bin/win32/i386/. The adapter related file is jni_connect.dll.

The Tomcat JNI adapter requires the following actions:

  1. Putting jni_connect.dll in 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.
  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 in the bin directory

Put jni_connect.dll inside <tomcat_home>\bin\native

Update worker.properties and add the JNI worker

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

  1. You should define a JNI worker.
    Set the worker.list property to point on a worker named inprocess: worker.list=inprocess
    Announce that the worker named jni is of type jni: worker.inprocess.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.inprocess.class_path=d:\tomcat\lib\tomcat.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 and up it is jvm.dll. For example:
    worker.inprocess.jvm_lib=d:\sdk\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.inprocess.cmd_line=start
  5. You can specify additional Java system properties. For example:
    worker.inprocess.sysprops=java.compiler=NONE
  6. You can specify files to by used by the JVM for stdout and stderr. For example:
    worker.inprocess.stdout=d:\tomcat\logs\inprocess.stdout
    worker.inprocess.stderr=d:\tomcat\logs\inprocess.stderr
  7. You can specify additional PATH, to be use when loading dlls (useful when you are using native code). For example:
    worker.inprocess.ld_path=d:\SQLLIB\bin
    worker.inprocess.ld_path=d:\my\native\code
You can find a preconfigured worker file (workers.properties) under tomcat/conf/jk. you should only need to change the variable workers.tomcat_home and workerks.java_home and modify the workers.list line adding the inprocess preconfigured worker to activate jni.

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 add the following line :

<JniConnector/>

This line adds a JNI connector to Tomcat.

The default server.xml under jakarta-tomcat/conf already contains the needed configurations, the JNI Connector will not be active if tomcat is not started by JNI.

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="inprocess"
    </Object>

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

/examples/*=inprocess

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?

Working in-process requires both the server redirector (IIS-Tomcat/Netscape-Tomcat) and the in-process connector. The server redirector can direct work to different workers based on their name; now that we added the JNI worker the server redirector can forward it work... The basic operation is this:
  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.