By Gal Shachor <email@example.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:
- <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 c:\jakarta-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 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.
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
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:
- 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).
- 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 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).
- 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 under the bin directory
Put jni_connect.dll inside
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.
- You should define a JNI worker.
Set the worker.list property to point on a worker named jni:
Announce that the worker named jni is of 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,
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 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:
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.
- You should specify the tomcat home location as a Java system
properties. 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.
- You can specify additional PATH, to be use when loading dlls (useful
when you are using native code). For example:
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
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:
You can find a sample server file (jni_server.xml) under jakarta-tomcat/conf.
- 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
<!-- JNI connector, make sure that you update the native_lib
Parameter to point to your jni_connect.dll
These lines add a JNI connector to Tomcat.
- 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>" />
Again, make sure that you update <tomcat_home> to your real Tomcat
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="jni"
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:
- 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
$Id: in-process-howto.html,v 220.127.116.11 2000/11/04 20:37:46 craigmcc Exp $