Servlet Express - Installation instructions

Abstract

Servlet Express is a server side application developed to enable existing servers to use Java. Servlet Express is based on SUN J.D.K 1.1 (or 1.1.1), the Servlet interfaces defined by sun and the server APIs in the hosting Web Server. Servlet Express is running as part of the server (in process) hence getting better performance.

Some of the features available by using ServletExpress are :

Available for many servers.
Mime based piping.
Servlet Side include support.
Jar class loader.
Automatically load a class when it changes.

This document describes the installation instructions of Servlet Express for the Netscape/IIS/ICS family of servers. Other server families have a different installation methods.

Before Starting

As mentioned above, you will need Sun's JDK 1.1 or above installed on the hosting machine. Furthermore you will need Sun's Servlet developer toolkit. To get these toolkits you should refer to :

http://www.javasoft.com/products/jdk/1.1/ - for the JDK.
http://jeeves.javasoft.com/products/java-server/sdk/ - for the servlet development toolkit.

After getting both packages from sun install them, and add the jdk's \bin directory to the path, under NT the best way to do it is by opening My Computer | Control panel | System, going to the Environment and adding the jdk\bin to the path variable in the System variables.

After this part of the installation you should restart the system (boot).

Installation

The Servlet Express package comes in one (small) zip file. In order to start the installation unzip the file with a program that knows how to handle long file names (winzip 6.1 is a good example of such a program). After unzipping you will see the following directories:

src - Sources of sample servelets.
lib - Java classes of Servlet Express run time.
bin - dlls for various web servers and platforms.
home - servlets home directory.
cfg - sample web server and Servlet Express configuration files.
doc - include documentation.

The src, lib, doc and home directories are the same for all servers and operating systems. The cfg is not needed for the operation of the servlet engine but only comes in order to ease configuration of the host servers. The bin directory needs special attention because it includes several dlls that are related to different servers.

General configuration issues

Property files

In the home directory you can find three files, servlets.prp, rules.prp and mimeservlets.prp. These files inform the Servlet Engine which servlet to invoke. The prp files try to follow the guidelines of the files in Sun's Java Server.

The structure of the rules.prp is :

# comment

vpath1=servlet-name1

vpath2=servlet-name2

vpath3=servlet-name3

for example the following few lines:

/=MFileServlet

/mail/=MailServlet

/mail/file=MFileServlet

instructs the Servlet engine to run MailServlet so serve requests to the virtual path /mail/, to run MFileServlet for vpath that begin with / and for the vpath /mail/file.

The structure of the servlets.prp is :

# comment
servlets.servlet-name1.parameter=value

For example

servlets.MFileServlet.code=MFileServlet

means that the code to execute MFileServlet is the class located in MFileServlet.class.

The structure of mimeservlets.prp is :
# comment
text/plain=CopyServlet

For example

text/plain=CopyServlet

means that if one of the servlets will create output of type text/plain the output will be piped into CopyServlet.

For more information look at the prp files in the home directory and change them according to your needs. You can also look at JavaServer documentation.

servlets.cfg

The servlets engine is taking initial parameters from a file called servlets.cfg. servlets.cfg looks like a windows .ini file with the following entries:
[SERVLETS] - provieds servlet engine related parameters.
[JAVAVM]    - provieds Java VM related parameters.
[ICS]              - provieds ICS specific parameters.
[IIS]               - provieds IIS specific parameters.

The parameters in the [SERVLETS] entry are:

logfile - A log file for the native part of the servlets engine.

example - logfile=e:\logfile.txt

logison - enable/disable the logging to the logfile.

example - logison=false/true

servlets.dir - provides the location of the servlets directory. This directory should be outside of the classpath.

homedir - provides the location of the servlet home directory. In the servlet home you will locate the *.prp files.

The parameters in the [JAVAVM] entry are:

javaoutfile - the location of the file to be used by the Java VM for stdout + stderr.

classpath - the classpath to be used by the Java VM. Must include the ServletExpress classes + jdk classes + sdk classes.

javahome - the location of the Java Home.

The parameters in the [ICS] entry are:

httpd.cnf.path - the path to the server httpd.cfg file.

The parameters in the [IIS] entry are:

extensionloc - the URI to the adpter filter.

Binary files location

Inside the bin directory you can see the following directories:

ics411_42_win32 - dlls for ICS servers version 411 + 42 under WindowsNT4.
ns201_win32 - dlls for Netscape servers version 201 under WindowsNT4.
ns30_win32 - dlls for Netscape servers version 30 under WindowsNT4 (currently beta 4).
iis_2_3_win32 - dlls for Microsoft IIS vesion 2 and 3 under WindowsNT4 x86.

Each directory has a file named adpter.dll and another file called ???native.dll, you should put the ???native.dll in a location where the server can load it, a good place will be c:\winnt\system32 (under WIndowsNT).

The adpter.dll file is a server side application to be used by the server, you should inform the server about it's existence. The exact location of the adpter.dll file is depending on the server.

IIS Related installation issues

The configuration of the IIS is the hardest (Microsoft isn't it ?).

First copy adpter.dll to a directory located under the doc-root where it will have execution permissions. A good place will be
/scripts/ibm/adpter.dll

To inform the IIS about the new SAF you should update the registry.

The changes are :
In the key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters
change the value of the "Filter DLLs" to include the dapter.dll SAF

as an example :
C:\WINNT\System32\inetsrv\sspifilt.dll,c:\inetpub\scripts\ibm\adpter.dll

After that you should create the following key:
HKEY_LOCAL_MACHINE\SOFTWARE\IBM\Servlet
and add a new string value with the name cfgfiletag and a value of the location of the servlets.cnf file.
If you do not supply this parameter the SAF will look for the file at %SystemRoot%\servlets.cfg.

ICS Related installation issues

To inform the ICS about the new SAF you should update the httpd.cnf file of your server. Samples for the httpd.cnf are located in the cfg directory.

The changes are :

In the Init ServerInit add:
ServerInit "location of adpter.dll":AdapterInit d:\servlets.cnf

as an example :
ServerInit e:\ServletExpress\bin\ics411_42_win32\adpter.dll:AdapterInit d:\servlets.cnf

Those lines instructs the server to load the server side extension in the init stage and initialize it from the file e:\\servlets.cnf. If you do not supply an init parameter or you are using ICS411 the SAF will look for the file at %SystemRoot%\servlets.cfg.

In the PreExit stage :
PreExit "location of adpter.dll":AdapterService
If you want the server to perform the Authentication NameTrans Authorization ObjectType and so forth, you should manually add "service" stages with the patterns of the urls that you wish to serve using servlets.

as an example :
PreExit e:\ServletExpress\bin\ics411_42_win32\adpter.dll:AdapterService

Those lines instructs the server to execute the server side extension to serve requests.

Netscape Server Related installation issues

To inform the Netscape servers about the new SAF you should update the obj.conf file of your server. Samples for the obj.conf are located in the cfg directory.

The changes are :

In the Init stage add:
Init fn="load-modules" funcs="InitAdapter,AdapterAction" shlib="full path to adpter.dll"
Init fn="InitAdapter" cfgfiletag="full path to servlets.cnf"

as an example :
Init fn="load-modules" funcs="InitAdapter,AdapterAction" shlib="e:/ServletExpress/bin/ns201_win32 /adpter.dll"
Init fn="InitAdapter" cfgfiletag="e:\\servlets.cnf"

Those lines instructs the server to load the server side extension in the init stage and initialize it from the file e:\\servlets.cnf. If you do not supply a cfgfiletag the SAF will look for the file at %SystemRoot%\servlets.cfg.

In the service stage :

Service fn=AdapterAction

Those lines instructs the server to execute the server side extension to serve requests.

Invocation

Assuming that the configuration files are OK all you need now is to restart the server, so shut the server down and after that restart it.

Mime based piping

Mime based piping enables a user to pipe the output stream of one servlet to the input stream of a servlet associated with a spcific mime type. All the user have to do to make servlet s1 process mime type m1 is to add the following line in mimeservlets.prp:
m1=s1
As soon as one of the servlets will create an output of type m1, the output stream with that mime type will be associated with the input stream of s1.
You should note that:

The mime type is known from the setContentType(type) method.
If the servlet generating the output stream started to write to the stream before setting the mime type the piping will not work.

Servlet Side Include and Invocation

With ServletExpress you get the tools to create your own servlet invoker and servlet side include services.
In the com.ibm.ServletExpress.core package you can find two basic servlets one of them is ServletInvoker and the other is SSinvServlet. In order to implement new servlet invokers and servlet side include services you should inherit the servlets and use the protected invoke methods available from them. An example is available in the servlets directory.

You should note that the Invoker and the Servlet Side APIs are not fully defined and may pass major changes, however since most of the programming stuff is in the parsing of the HTML file etc. using them can be useful.
As for now mime based piping is working also for servlets invoked by servlet side include.

TroubleShooting

What will I do if ?

The server can not find the Java dlls. See that the jdk\bin is in the system path. The server runs as a service which is belong to the system, so you should include the jdk\bin in your System path and restart.
The server can not find the extension dlls. See that the ???native.dll is located at the system32 directory. See that the path you given to the adpter.dll in configuration files is OK.
From the log file I can see that there are Errors and that the problem is with attaching to the classes/methods. You should check the classpath and servlet.dir that you provided in the cnf file.

Known problems

IIS

When using IIS with other WWW NT services such as gopher, ftp etc. you should shut them all down in order to shut down the IIS.

ICS

When you shut down the server it may take it a while longer than it used to ...