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.
example - servlets.dir=e:\servlet-dir
-
homedir - provides the location of the servlet home directory. In the servlet
home you will locate the *.prp files.
example - homedir=e:\ServletExpress\home\
The parameters in the [JAVAVM] entry are:
-
javaoutfile - the location of the file to be used by the Java VM for stdout
+ stderr.
example - javaoutfile=e:\javalog.txt
-
classpath - the classpath to be used by the Java VM. Must include the ServletExpress
classes + jdk classes + sdk classes.
example - classpath=e:\ServletExpress\lib;e:\jdk1.1\lib\classes.zip;
e:\sdk\lib\classes.zip
-
javahome - the location of the Java Home.
example - javahome=e:\jdk1.1
The parameters in the [ICS] entry are:
-
httpd.cnf.path - the path to the server httpd.cfg file.
example - httpd.cnf.path=c:\winnt\httpd.cnf
The parameters in the [IIS] entry are:
-
extensionloc - the URI to the adpter filter.
example - extensionloc=/scripts/ibm/adpter.dll
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 ...