Tomcat Domino HowTo

By Andy Armstrong andy@tagish.com

Recent version of the Lotus Domino web server have had the ability to host Java servlets, but at the time of writing the Domino servlet container uses JDK 1.2.2 and it is not (apparently) possible to replace this with JDK 1.3. That means if you want to use JAAS or any other API that is JDK 1.3 only in your servlets you're stuck.

Supported Configuration

The Domino Tomcat redirector was developed and tested on:
  1. WinNT4.0-i386 SP6a (it should be able to work on other versions of the NT service pack.) and Windows 2000 Professional
  2. RedHat Linux 7
  3. Lotus Domino 5.0.6a
  4. Tomcat3.2
Other recent version of each of these should work fine. The redirector uses ajp12 or ajp13 to send requests to the Tomcat containers. It probably also works with Tomcat in process, but that hasn't been tested.

Doubtless you're anxious to get started, so jump directly to Building (NT, Linux) or Installing (NT, Linux).

Building (NT)

If you have the redirector source you'll need to build it before you can use it with a Domino server. If not you can skip directly to Installing. To compile it you'll need the Tomcat source and Microsoft Visual C++ 6.0. You will probably also want the Lotus Notes C API version 5.0.7 or later. You can build the DLL without the C API, in which case you'll need to define the macro NO_CAPI in config.h. If you do this Domino logging from the DLL will be disabled.

Firstly unpack the source archive and move the directory called "domino" into your Tomcat source tree as (e.g.)

    D:\Works\Tomcat\jakarta-tomcat\src\native\domino

In other words place domino in the same directory as the other native code elements such as "iis" and "netscape". Now open the project file "dsapi.dsw" in Visual C++. As distributed the project refers to a number of file paths on the system that were used during development which will likely be different on the system you're using. Unless these are set correctly the project will not build. To check these go to the project settings page (Alt-F7). Select "All Configurations" in the Settings For: picker and go to the "C/C++" tab. Select "Preprocessor" from the Category: picker.

Have a look in the Additional include directories: field. It contains a number of file paths separated by commas. You need to replace these file paths with the appropriate ones for your system. Specifically you need to replace "C:\JBuilder4\jdk1.3" with the path to your JDK1.3 directory and "C:\notesapi" with the path to your Lotus Notes C API installation.

When you've fixed those paths visit the "Link" tab. Under Category: "Input" check the Additional library path: field. Again this refers to the Lotes Notes C API installation and may need to be updated to reflect where you have it installed.

Once these paths are correctly set you should be able compile the project by hitting F7 or selecting the appropriate option from the Build menu. Assuming all goes well a new directory called Release will appear below the project directory and, when the build is complete, the file tomcat_redirector.dll will appear in this directory.

Installing (NT)

Let's assume you've already got a working Tomcat installation and that the NT system variables JAVA_HOME, TOMCAT_HOME and CLASSPATH are properly set. You can verify that this is the case by typing

    C:\> full path to tomcat\bin\tomcat run

If everything is set up correctly Tomcat should start and it should be possible to connect to your server on port 8080 using a browser. Try something like

    http://name of server:8080/

which, assuming Tomcat is still in its default state will produce the examples page. You need to make sure that you have a working Tomcat installation before continuing with these instructions. If you have problems with installing or configuring Tomcat, you'd better go here: http://jakarta.apache.org/tomcat/.

Once you've got a working Tomcat, copy the file tomcat_redirector.dll to the Domino program directory (this is the directory, which may be called something like C:\Lotus\Domino, that contains a file called nlnotes.exe). Shortly we will tell Domino where to find this file, but before we do that we need to make some registry entries. The simplest way is to edit the supplied file tomcat_redirector.reg, which initially will look like this 

    REGEDIT4

    [HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Dsapi Redirector\1.0]
    "log_file"="D:\\tomcat\\logs\\domino.log"
    "log_level"="debug"
    "worker_file"="D:\\tomcat\\conf\\workers.properties"
    "worker_mount_file"="D:\\tomcat\\conf\\uriworkermap.properties"
    "tomcat_start"="D:\\tomcat\\bin\\tomcat.bat start"
    "tomcat_stop"="D:\\tomcat\\bin\\tomcat.bat stop"
Edit this file to reflect the location where Tomcat has been installed, i.e. replace the instances of D:\\tomcat with the appropriate path remembering to retain the double backslashes. Once you've made the necessary changes save this file and double click on it to enter it into the registry.

Note that the files referred to by the worker_file and worker_mount_file keys need to exist and contain sane values. Default Tomcat installations will have these files. Note also that recent versions of Tomcat write a file called uriworkermap.properties-auto when they start up that can be renamed uriworkermap.properties to obtain default behaviour.

Note for Windows 2000 users

For some reason Windows 2000 seems to have a problem resolving the references to localhost in the default workers.properties. The easiest solution is to replace 'localhost' with '127.0.0.1' everywhere it appears.

Automatically Starting Tomcat

The last two registry entries above provide commands that the redirector DLL will use to start and stop Tomcat when the Domino http server starts and stops respectively. If you don't require this behaviour these two lines can be omitted (or deleted if you've already placed them in the registry).

Configuring Domino

Finally we need to configure Domino to use the DSAPI extension DLL. For those who are unfamiliar with Domino server configuration most of a server's configurable behavior is dictated by a document called the "server document" in a database called the "Public Name and Address Book" or "NAB" for short (N.B. Lotus have renamed the NAB to "Domino Directory" from Domino 5 onwards). Each Domino server will have a NAB (called names.nsf) and each NAB will have a number of server documents including one for the current server. If you have not previously configured a Domino server you may need to refer to the supplied documentation, or you may need to pass this document to your tame Domino administrator.

Assuming you know your way around a Domino server document what we're going to do is actually quite simple. Open the server document for this server, place it in Edit mode, then locate the DSAPIsection and the 'DSAPI filter file names' field on the Internet Protocols tab, HTTP sub-tab. Add "tomcat_redirector.dll" to the DSAPI field, then save and close the document.

Restart Domino

In order to get these settings to take effect and make sure that you haven't disrupted anything else you should now restart the Domino server. If the server is running as a service and you have changed any relevant system variables (JAVA_HOME, TOMCAT_HOME, CLASSPATH) since the last time you restarted the computer you should do a complete restart now because updates to system variables are not seen by services until after a reboot. If all goes well you should see something like this on the server console when the web server starts up. 
    29/05/2001 18:54:13   JVM: Java Virtual Machine initialized.
    29/05/2001 18:54:14   Attempting to start Tomcat: C:\tomcat\bin\tomcat.bat start
    Including all jars in C:\Tomcat\lib in your CLASSPATH.

    Using CLASSPATH: C:\Tomcat\classes;C:\Tomcat\lib\ant.jar;C:\Tomcat\lib\servlet.jar

    Starting Tomcat in new window
    29/05/2001 18:54:15   Apache Tomcat Interceptor (Jakarta/DSAPI/1.0) loaded
    29/05/2001 18:54:16   HTTP Web Server started
At about the same time Tomcat should open in a new window (assuming you enabled the autostart option in the registry settings). You should now be able to visit a URL that is handled by Tomcat. Something like

    http://name of server/servlet/SnoopServlet

may be available, depending on how Tomcat is configured. If that all works you're done ;-)

Building (Linux)

If you have the redirector source you'll need to build it before you can use it with a Domino server. If not you can skip directly to Installing. To compile it you'll need the Tomcat source. You will probably also want the Lotus Notes C API version 5.0.3 for Unix or later. You can build the redirector without the C API, in which case you'll need to define the macro NO_CAPI in config.h. If you do this Domino logging from the redirector will be disabled.

Firstly unpack the source archive and move the directory called "domino" into your Tomcat source tree as (e.g.)

    /usr/src/tomcat/jakarta-tomcat/src/native/domino

In other words place domino in the same directory as the other native code elements such as "iis" and "netscape".

Next edit the Makefile providing appropriate values for these variables: 

    # The root of your Domino installation. Mine's in /usr/local/lotus, but your's
    # may well be /opt/lotus
    NOTESROOT=/usr/local/lotus

    # The place where the Notes API is installed
    NOTESAPI=$(NOTESROOT)/notesapi

    # The Domino program directory.
    NOTESHOME=$(NOTESROOT)/notes/5061/linux

    # The Domino data directory (the directory containing names.nsf)
    NOTESDATA=$(NOTESROOT)/notes/data

    # The include path for the Notes C API headers
    NOTESINC=$(NOTESAPI)/include

    # Where tomcat is installed. This is where conf, lib, webapps et al normally are
    TOMCATHOME=/usr/local/apache/tomcat

    # Your JDK's include directory
    JAVAINC=$(JAVA_HOME)/include
Once that's done you should be able to type

    $ make

to build the redirector and, assuming that worked, type

    $ make install

to place the redirector (libtomcat.so) and its settings file (libtomcat.ini) in the appropriate places (the Domino program and data directories respectively).

Installing (Linux)

Let's assume you've already got a working Tomcat installation and that the system variables JAVA_HOME, TOMCAT_HOME and CLASSPATH are properly set. You can verify that this is the case by typing

    $ full path to tomcat/bin/tomcat.sh run

If everything is set up correctly Tomcat should start and it should be possible to connect to your server on port 8080 using a browser. Try something like

    http://name of server:8080/

which, assuming Tomcat is still in its default state will produce the examples page. You need to make sure that you have a working Tomcat installation before continuing with these instructions. If you have problems with installing or configuring Tomcat, you'd better go here: http://jakarta.apache.org/tomcat/.

Once you've got a working Tomcat, copy the file libtomcat.so to the Domino program directory (this is the directory, which may be called something like /opt/lotus/notes/5601/linux, that contains a file called libnotes.so) and libtomcat.ini to the Domino data directory. Note that if you're building the redirector from source these files should already have been copied to the appropriate locations. Before using the redirector you may like to review the settings in libtomcat.ini which, by default, will look something like this: 

    log_file=/usr/local/apache/tomcat/logs/domino.log
    log_level=debug
    worker_file=/usr/local/apache/tomcat/conf/workers.properties
    worker_mount_file=/usr/local/apache/tomcat/conf/uriworkermap.properties
    tomcat_start=/usr/local/apache/tomcat/bin/tomcat.sh start
    tomcat_stop=/usr/local/apache/tomcat/bin/tomcat.sh stop
If you're building the redirector from the source you may not need to make any changes, otherwise you may have to edit this file to reflect the location where Tomcat has been installed, i.e. replace the instances of /usr/local/apache/tomcat with the appropriate path.

Note that the files referred to by the worker_file and worker_mount_file keys need to exist and contain sane values. Default Tomcat installations will have these files. Note also that recent versions of Tomcat write a file called uriworkermap.properties-auto when they start up that can be renamed uriworkermap.properties to obtain default behaviour.

Automatically Starting Tomcat

The last two registry entries above provide commands that the redirector will use to start and stop Tomcat when the Domino http server starts and stops respectively. If you don't require this behaviour these two lines can be deleted.

Configuring Domino

Finally we need to configure Domino to use the DSAPI extension. For those who are unfamiliar with Domino server configuration most of a server's configurable behavior is dictated by a document called the "server document" in a database called the "Public Name and Address Book" or "NAB" for short (N.B. Lotus have renamed the NAB to "Domino Directory" from Domino 5 onwards). Each Domino server will have a NAB (called names.nsf) and each NAB will have a number of server documents including one for the current server. If you have not previously configured a Domino server you may need to refer to the supplied documentation, or you may need to pass this document to your tame Domino administrator.

Assuming you know your way around a Domino server document what we're going to do is actually quite simple. Open the server document for this server, place it in Edit mode, then locate the DSAPIsection and the 'DSAPI filter file names' field on the Internet Protocols tab, HTTP sub-tab. Add "libtomcat.so" to the DSAPI field, then save and close the document.

Restart Domino

In order to get these settings to take effect and make sure that you haven't disrupted anything else you should now restart the Domino HTTP server. At the Domino console type

    tell http quit

then

    load http

You should see the HTTP server reload along with messages that will confirm that the redirector has loaded and that Tomcat has (if you used Tomcat autostart) started. You should now be able to visit a URL that is handled by Tomcat. Something like

    http://name of server/servlet/SnoopServlet

may be available, depending on how Tomcat is configured.

Feedback

Please send feedback, bug reports or any additional information to Andy Armstrong, andy@tagish.com