By Gal Shachor <firstname.lastname@example.org>
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:
- <tomcat_home>\conf - Where you can place various configuration files
- <tomcat_home>\webapps - Containing example applications
- <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.
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
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:
- 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).
- Update workers.properties and add the JNI worker - The JNI worker
needs several configuration items, you will need to add those to the worker
- Updating server.xml - You need to instruct Tomcat to use the JNI connection
- Directing context(s) to the in-process Tomcat - You need to instruct
the redirector to send work to the in-process Tomcat
- 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...
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.
- You should define a JNI worker.
Set the worker.list property to point on a worker named inprocess:
Announce that the worker named jni is of type jni: worker.inprocess.type=jni
- 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
Note: Do not forget to include the JDK's tools.jar in your classpath.
- 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:
- You should provide command line options for Tomcat; you must provide
a -config option to specify your JNI configured server.xml. For example:
- You can specify additional Java system properties. For example:
- You can specify files to by used by the JVM for stdout and stderr. For example:
- You can specify additional PATH, to be use when loading dlls (useful when
you are using native code). For example:
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 :
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
On Netscape you can do that by modifying the lines in the servlet
configuration object to reflect redirect work to the new JNI worker.
ObjectType fn=force-type type=text/plain
Service fn="jk_service" worker="inprocess"
On IIS you will have to modify your uriworkermap.propeties 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:
- Change directory to the JNI connector source directory.
- Make sure that the environment variable JAVA_HOME is set and
points to your JDK installation
- 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:
- During the initialization the server redirector starts the JNI worker.
- Upon startup the JNI worker creates a JVM inside the web server and
starts Tomcat in it.
- 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.
- The JNI worker attaches to the JVM and submits the request into the
Tomcat engine (using the JNIEndpointConnector). Tomcat will then execute
- The server redirector collects the response from the JNI worker and
returns it to the browser.
Please send feedback, bug report or any additional information to