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 :

  1. Available for many servers.
  2. Mime based piping.
  3. Servlet Side include support.
  4. Jar class loader.
  5. 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 : 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: 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:

The parameters in the [JAVAVM] entry are: The parameters in the [ICS] entry are: The parameters in the [IIS] entry are:

Binary files location

Inside the bin directory you can see the following directories: 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:

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.

TroubleShooting

What will I do if ?

Known problems

IIS

  1. 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

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