JServ - An Apache module for using Java servlets
by Alexei Kosut <akosut@apache.org>

Release: 0.9.7
Date: September 4, 1997

This document explains how to install and use JServ. Note that this
software is currently not fully tested or complete, and will probably not
work.

IN THIS DOCUMENT:

- Requirements
- Installing the Module
- Configuring Apache
- Configuring Apache to use Servlets
- Accessing Servlets
- Running JServ Manually
- Notes


REQUIREMENTS:

* Apache 1.2.0 or later <http://www.apache.org>
* JDK 1.1 or later <http://www.javasoft.com>
* JSDK 1.0 or later <http://jserv.javasoft.com>
* JServ (this package) <http://java.apache.org>


INSTALLING THE MODULE:

Copy mod_jserv.c into your Apache src/ directory. Add a Module line to
your Configuration, as specified by the Apache documentation. Recompile
Apache.


CONFIGURING APACHE:

mod_jserv needs a number of configuration directives set in the Apache
configuration file before it will run. These are as follows. Note that
these must be present in the main server configuration; any of the
following directives placed in a virtual server config will be ignored:

* ServletBinary

This is the location of the java Executable. Give it the full filename to
the java binary, e.g. "ServletBinary /usr/local/jdk1.1.3/bin/java"

* ServletClassPath

This directive adds a component to java's classpath. At least three such
directives are required: The JDK classes, the JSDK classes, and the JServ
classes. e.g.:

ServletClassPath /usr/local/jdk1.1.3/lib/classes.zip
ServletClassPath /usr/local/JSDK1.0/lib/classes.zip
ServletClassPath /usr/local/httpd/jserv/classes

Note that the servlets themselves do not have to be in these class paths.
They will be added later with ServletAlias.

* ServletEnvironment

ServletEnvironment lets you pass environment variables from Apache's
environment to the Java process. Normally, only PATH and TZ are passed on
(also, a CLASSPATH which is generated by mod_servlet). For example, if you
were using JDBC with Oracle, you might need to use the following:

ServletEnvironment LD_LIBRARY_PATH ORACLE_HOME

* ServletErrorLog

This directive takes the name of a file (relative to the server root) that
will be used as a log file for the servlets. This does not log specific
errors, but simply captures anything that Java servlets print to
System.err. If this directive is not present, these messages will go to
Apache's standard error.

When ServletLog is on, stack traces from exceptions and errors thrown by
the servlet will also be logged to this file. If ServletLog is off, these
traces will not be printed anywhere.

* ServletPort

This indicates a TCP port for the Java servlet interpreter to run on. The
default is 8007 (8 for HTTP, 007 for the spy. Yes, it's silly). You might
want to change it if you'll be running more than one Apache with mod_jserv
(each needs to run on a different port), or if you already use port 8007
for something. Note that this number is never used by anything except
internally between mod_jserv and the JServ classes. It is never present in
URLs.

* ServletProperties

This is the location (relative to Apache's server root) of the JServ
properties file. The default is "ServletProperties conf/servlets.properties".
If this file is present (it silently ignores
it if cannot be found or read), it is examined for properties when
starting a servlet. It should contain lines of the following style:

Classname.initArgs=arg1=val1,arg2=val2,...

Note that "Classname" should be the full name of the class, including the
package.

Alternately, you can give a servlet an "alias", which you can use when
accessing the servlet (see below). To do this, use the following example:

servlet.servletname.code=Classname
servlet.servletname.initArgs=arg1=val1,arg2=val2,...

Each alias use has a different instance of the servlet's class, which are
all different from the instance used if the servlet is accessed directly
by class name.

You can also use the properties file to indicate servlets which will be
initialized when JServ is started. These should be placed in a
space-delimiated list in the servlets.startup property. For example:

servlets.startup=servlet1 servlet2 servlet3...

The names servlet1, etc... can be either servlet aliases or full class
names.

* ServletAuthExport

If ServletAuthExport is set to "On", then mod_jserv will put the port and
secret authentication string into the request notes, where they are
accessible by other modules. This could allow other modules, such as
mod_perl, to access Java servlets. Note that activating this is a security
risk, because it allows other modules access to the authentication data,
which allows them complete acess to the Java servlets. The default is
"ServletAuthExport Off".


CONFIGURING APACHE TO USE SERVLETS

The most important directive is ServletAlias. This can be in either the
main server or a virtual server, and identified the location (both URI and
filename) of servlet classes. It takes the following syntax:

ServletAlias <uri> <directory or filename>

It takes a URI as the first argument, and a filename as the second. This
filename can point to either a directory which contains classes, or a
zip/jar file containing classes. This latter argument will also be added
to the classpath. For example, to use the JSDK sample servlets:

ServletAlias /servlets /usr/local/JSDK1.0/servlets

Or to use servlets that are in a zipfile:

ServletAlias /myservlets /home/bob/myservlets.zip


ACCESSING SERVLETS

When Apache starts up with the above directives, it will launch a Java
process at startup, which will be used to run the Java servlets. Each
servlet is launched only once, and is passed every request made for it (so
the servlet should be thread-safe). The servlets are kept in the processes
until Apache is killed or restarted, in which case the Java process is
also killed or restarted.

To access a servlet, simply put its class name after the URI configured by
a ServletAlias. For example, assuming you had /servlets configured as
above, and you wanted to access the SnoopServlet, you would go to
http://servername:serverport/servlets/SnoopServlet. Note that the
serverport is the port that Apache runs on, *not* the ServletPort port.
Also note that ".class" should not be present at the end of the class
name.

If your class is part of a package, the full package name should be used.
If the corresponding ServletAlias directive points to a directory, a slash
(/) should be used to separate the package name from the classname. If it
points to a zip/jar file, a dot (.) should be used. For example, if your
class was foo.bar.Class, and you had it in a directory of classes, you
should refer to it as "/servlets/foo/bar/Class". If it was in a zipfile,
it would be referred to as "/servlets/foo.bar.Class".

If you wish to access a servlet by name as configured in jserv.properties,
instead of by class, you should simply provide the name you have provided
after the path specified by the ServletAlias directive. For example, if
you have given your servlet a name of "foo", you would access the servlet
with "/servlets/foo".


RUNNING JSERV MANUALLY

Normally (as assumed by the above instructions), Apache starts the
JServHandler process (JServHandler is the Java class that
acts as a servlet server) automatically when Apache starts up, and kills
it when Apache is stopped or restarted. However, you may wish to start
and stop JServHandler separately from Apache. JServ provides this
functionality if desired.

For more information, please see the manual/README file, included with
this distributon.

NOTES

This package has only been tested with a few servlets, and there are
probably some bugs. It was implemented to the JSDK API specification, and
I probably interpreted some of it slightly differently than others did,
so if there are differences in behavior between JServ and JWS, that's
probably why.

The source is contained in five files, and compiles into seven classes.
All twelve files come with the JServ pacakge, in the classes/apache/jserv
directory.

The protocol used by mod_jserv to talk to the JServ Java process is
documented in the protocol.txt file. This might be useful if someone
wanted to use the Java classes to talk to another type of server.

There are a couple points in the code where things aren't done quite
right. There are marked with "FIXME". Anyone who has any ideas on how to
fix those, please do so.

