Integrating Domino with JSP Engines

tieplantlimabeansSoftware and s/w Development

Oct 28, 2013 (4 years and 8 months ago)


Integrating Domino with JSP Engines
An Integrator’s Handbook

Jurgen Van de Moere –
February 2002

Please note !

All the information in this whitepaper has been written to help other people integrate JSP engines with Domino.
The writer of this handbook will not be held responsible for possible damage to your existing infrastructure when
trying the procedures outlined in this manual. Use all information at your own risk !
Table of Contents

As you have read in the note above, this handbook is merely a guidline in helping you integrate
Domino with external JSP Engines. The writer, which is me, will not be held responsible if these
procedures don’t work in your situation nor will I be held responsible for any support
whatsoever. Also please note that English is not my native tongue but I will try my best to
explain everything as clear as possible. Enjoy this handbook !

Why this whitepaper ?

After the removal of Garnet in the Pre-Release 1 version of Domino 6, the need for integration
with external JSP engines, aka JSP containers, was high due to the fact that a lot of Domino
developers had tasted the power of JSP in combination with Domino. Lotus removed the
internal JSP facilities with the objective of becoming compatible with external J2EE systems
instead of incorporating a J2SE system themselves. This makes it easier for Lotus to support
Domino and gives us, developers, a broader range of JSP engines to choose from. Eventhough
there was a lot of commotion at the moment, this decission was right in my opinion if and only if
Lotus will keep supporting and putting effort in seamless connections with external JSP
engines. That’s why I wrote this whitepaper. After testing Domino with multiple JSP engines, it
is time that more people should do so to get a better picture of how well it is working and what
should be improved. You are welcome to send me your feedback at

I hope you benefit from reading this handbook and I’m sure you’ll be up and running before Pre-
release 2 comes out ;-)

Best regards,
Jurgen Van de Moere
N.V. Eurodaq S.A.


This handbook is written for Windows 2000 servers only. If you need to enable external JSP
engines with Domino on Linux, you are free to read the guidelines and try to apply them on your
Linux box. If you succeed, please send me a note at
so I
can complete this handbook with Linux guidelines.

So the requirements are:

Windows 2000 server or advanced server
IIS 5.0
Lotus Domino Rnext

Integration has been tested on the following JSP engines:

Apache Tomcat 4.0.2 (aka Catalina) (Successful)
Orionserver 1.5.2 (Successful)
Jrun 3.0 (Unsuccessful but working on it with Allaire/Macromedia)
Oracle (Unsuccessful due to insufficient testing)

Thus, for now, we will discuss 2 external JSP engines: Apache Tomcat 4.0.2 and Orionserver
1.5.2. Note that Apache Tomcat was the initial garnet JSP container incorporated in previous
beta’s and above all it is completely FREE for use, so this will give you an excellent garnet

Integrating Domino with Apache Tomcat 4.0.2

The first part of this handbook will be devoted to the integration of Domino and Apache Tomcat
4.0.2. Apache Tomcat is a FREE open-source JSP container (it is not a full J2EE server) that
can serve JSP’s and servlets just like garnet did. This servlet and jsp container is an excellent
alternative to garnet. You can download Apache Tomcat 4.0.2 at


Integrating Domino with Apache is fairly easy and you’ll be surprised how easy it is to set things
up. So let’s have a look at how we’re going to do it:

In order for a JSP container and Domino to work together, they must connect to each other. If a
jsp container needs to show Domino data, it connects to the Domino server, gets the data and
shows it. That’s easy to understand.

But there is a problem and it’s not with the data. As long as you use jsp’s and get the data from
Domino, you’re ok, but what if a user enters
in his/her
browser ? The jsp engines will not know what a .nsf file is and it will certainly not find it in it’s
application directory. Therefore, there needs to be a connector between the 2 servers that
makes it clear which one handles what.

In normal circumstances, this connector is a DSAPI connector. A DSAPI connector is a .dll file
that is loaded when Domino starts and it tells Domino to pass .jsp request to another JSP
container instead of the Domino http task when such a request comes in since the Domino http
task does not know how to handle .jsp requests.

This is a beautiful concept but unfortunately not all JSP engines provide a DSAPI connector for
Domino. Luckily for us, Tomcat 4.0.2 does ! So what we’ll do in the next steps is integrate this
DSAPI in Domino. Domino will then automatically start the Tomcat container when the http task
loads en shut it down when it quits. Also, Domino will automatically pass JSP and servlet
requests to Tomcat seemlessly without the end-user noticing anything. See the garnet concept
appearing again ? ;-)

So what’s the difference with garnet ? The way that Domino will serve pages using this concept
is exactly the same as it was with garnet. The only difference is the method of development.
You will no longer use the Domino Designer as a development tool for JSP’s and servlets since
this feature was removed. You, as a developer, will now have to create JSP’s and servlets
using external tools (e.g. jEdit) and place them in the right directory on the server manually.
This is not a heavy pay-off for JSP and servlet functionality…

I will provide some links to good, solid tools in appendix A of this whitepaper.

So let’s get started !

Installing Apache Tomcat 4.0.2

First of all you need to download Apache Tomcat 4.0.2 at
and extract the contents
of the cabinet to a directory on your harddrive.

During the following steps I will assume that you extract it to c:\jakarta-tomcat-4.0.2 which is the
default folder and that your Domino server is installed in c:\lotus\domino.

After extracting Tomcat in this directory, you need to create 2 files in the c:\jakarta-tomcat-
4.0.2\conf directory. The files are called and You
can use a simple text editor like notepad to create both files. Normally these files should be
included in Tomcat but for some reason they are not, so you will have to create them manually.
The next page shows the content of the files.

# *********** Begin ***
# Simple worker configuration file

# Mount the Servlet context to the ajp13 worker

# Mount the examples context to the ajp13 worker

# Advanced mount of the examples context
# /examples/servlet/*=ajp13
# ************* End ****

# ************ Begin **************

# Specifies the load balance factor when used with
# a load balancing worker.
# Note:
# ----> lbfactor must be > 0
# ----> Low lbfactor means less work done by the worker.

# Specify the size of the open connection cache.

#------ DEFAULT LOAD BALANCER WORKER DEFINITION ----------------------

# The loadbalancer (type lb) worker perform weighted round-robin
# load balancing with sticky sessions.
# Note:
# ----> If a worker dies, the load balancer will check its state
# once in a while. Until then all work is redirected to peer
# worker.

# worker.tomcat_home should point to the location where you
# installed tomcat. This is where you have your conf, webapps and lib
# directories.

# worker.java_home should point to your Java installation. Normally
# you should have a bin and lib directories beneath it.

# You should configure your environment slash... ps=\ on NT and / on UNIX
# and maybe something different elsewhere.

#------ ADVANCED MODE ------------------------------------------------

#------ DEFAULT worker list ------------------------------------------
# The worker that your plugins should create and work with

#------ DEFAULT ajp13 WORKER DEFINITION ------------------------------

# Defining a worker named ajp13 and of type ajp13
# Note that the name and the type do not have to match.

# ************ End **************

Special Notice

Notice that contains a line “worker.java_home=C:\jdk1.3.1_01”. This line
depends on where you installed your jdk. As of this writing, jdk 1.4 was just released (I was
unable to test it with jdk 1.4 due to time-restrictions but the Sun reports show immense
performance gains using jdk 1.4) and can be downloaded at

First Tryout

Now that Apache Tomcat has been installed, it’s time for a first tryout. Try launching c:\jakarta-
tomcat-4.0.2\bin\startup.bat and when the server has started, open your browser and enter the
following url: http://your_machine_name:8080

If Tomcat doesn’t start, make sure you have the following envorinmont variables set:

CATALINA_HOME = c:\jakarta-tomcat-4.0.2
JAVA_HOME = c:\jdk1.3.1_01
TOMCAT_HOME = c:\jakarta-tomcat-4.0.2

(In Windows 2K, you can edit these in control panel > system > advanced > environment

This should show the Tomcat opening screen. We are now ready to integrate with domino. Shut
down the server by running c:\jakarta-tomcat-4.0.2\bin\shutdown.bat.

Let’s Integrate !

Now it’s time to start integrating Domino and Apache Tomcat. You will need 2 files to perform
the integration:

- tomcat_redirector.dll

Both files can be downloaded at

After you downloaded them, you must copy tomcat_redirector.dll to your domino program
directory e.g. c:\lotus\domino.

Now you must edit tomcat_redirector.reg with a text editor (e.g. notepad) because the included
.reg file is the .reg file for previous versions of Tomcat. The new version must look like this:


[HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Dsapi

After editing and saving tomcat_redirector.reg, just double click it and Windows will add the
lines to your registry.

Domino Settings

Now it’s time to complete the final step of the integration part. Open the public names and
address book on the Domino server and edit the server document of the server you are

Go to Internet Protocols > DSAPI

Enter “tomcat_redirector.dll” (without quotes) in the field.

Save and close the server document.

Shutdown the domino server and make sure the apache server isn’t running.

Now start the domino server and you will notice that the apache server will automatically start
when the http task is loaded.

Open your browser and go to http://your_machine_name/examples/jsp/index.html

Notice that we do not specify the “:8080” here, so domino will accept the request and forward it
to Tomcat.

If all goes well, Domino has now been successfully integrated with Tomcat and you can now
start deploying your own JSP and servlet applications using Tomcat.
A Simple Application Example

Let’s create a simple JSP application in Tomcat that accesses a notes database using the
custom tag library provided by Lotus (domtags, domutil, dolstags). In order for the custom tags
to work properly, a few steps must be made:

- make sure your PATH environment variable contains c:\lotus\domino. This is essential
since the JSP’s will access the databases on this server. E.g. if you open “test.nsf” from a
JSP within Tomcat, it will open it in the data directory of the server running in
c:\lotus\domino since it is that server that is specified in the PATH.
- copy notes.jar and domtags.jar to c:\jakarta-tomcat-4.0.2\common\lib. Both files can be
found in the domino folders.

After completing these steps, you will be able to use the custom tag library. This only needs to
be done once. Now restart your Domino server and if all goes well, this should also restart your
Tomcat server automatically.

Now it’s time to create our first application, let’s call it “simple”:

- create an application directory in the Tomcat webapps folder where we can store our
application files: create c:\jakarta-tomcat-4.0.2\webapps\simple folder
- create c:\jakarta-tomcat-4.0.2\webapps\simple\WEB-INF folder
- create c:\jakarta-tomcat-4.0.2\webapps\simple\WEB-INF\tlds folder
- copy domtags.tld, domutil.tld and dolstags.tld to c:\jakarta-tomcat-
4.0.2\webapps\simple\WEB-INF\tlds (all files can be found in the Domino directories)
- create c:\jakarta-tomcat-4.0.2\webapps\simple\WEB-INF\web.xml file:

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"

These are the basic elements we need to create an application using Tomcat. You must repeat
these steps for every application you create. Don’t panic, it’s really simple and straightforward.
A simple trick is to create a model folder that contain all files as mentioned above and then
copy/paste this folder, rename it to your application name and you’re up and running. Just don’t
forget to edit the web.xml file and adjust the default database name, that’s all.

Last but not least we must add a line to the file in the c:\jakarta-tomcat-
4.0.2\conf folder that says:


This line makes sure that all requests that begin with /simple/ are treated properly. You must
add a line like this for every application you create.
Our First JSP Page

Now let’s create our first .jsp file. Let’s call it index.jsp. So open a JSP editor (as mentioned
previously, jEdit is awesome, but you can also use notepad if you want):

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<%@ page contentType="text/html; charset=UTF-8" import="lotus.domino.*,java.util.*" %>
<%@ taglib uri="domtags.tld" prefix="domino" %>
<%@ taglib uri="domutil.tld" prefix="util" %>

<table cellspacing="0" cellpadding="2">

<tr><td width="150"><h4>First Name</h4></td><td width="150"><h4>Last

<domino:view viewname="Persons">

<domino:viewloop start="1" count="3">
<td width="150">
<domino:viewitem col="1"/>
<td width="150">
<domino:viewitem col="2"/>

<domino:novalues>No items</domino:novalues>



Since simple.nsf is the default database name (in web.xml) this database will be opened and
the “Persons” view will be used to create a table. So to test this example page, you must create
a database called simple.nsf under c:\lotus\domino\data (or whatever server that is specified in
the PATH environment variable) and create a view called “Persons” that contains a value in the
first column and second column. Then create some documents so the view gets filled and then
run http://your_machine_name/simple/index.jsp

Notice that Domino forwards the request to Tomcat and Tomcat reads it’s data from Domino.

Also note that if you specify a database name in the tags (e.g. in the view tag) the default
database name will be overridden. So the easiest thing to do is just specify a default database
name in web.xml, don’t use db names in the tags unless it’s a different one…

Well, there’s nothing more to say then:

Mission accomplished ! ;-)

I hope you all benefited from reading these notes and I’ll be working hard to provide you with
more details about how to set Domino up with orionserver. I already got it running on my server
but I haven’t had the time to write the installation notes yet.

I am very busy with my daily work so please give me some slack ;-)

Also, if you find any typo’s or misspelled words, please let me know so I can correct them so
that other people can better understand my words. Thanks for reading.

Best regards,
Jurgen Van de Moere
N.V. Eurodaq S.A.