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

Release: 0.9.1
Date: 7/30/97

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.

REQUIREMENTS:

* Apache 1.2.0 or later
* JDK 1.1 or later
* JSDK 1.0
* JServ (this package)

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

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

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/jserv.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. JServ does not support JWS-style servlet names.

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 seperate 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".

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 interepreted some of it slightly differently than others did,
so if there are differences in behavior between JServ and JWS, that's
probably why.

There is only one source file, JServHandler.java. There are four
classes, apache.jserv.JServConnection, apache.jserv.JServHandler,
apache.jserv.JServInputStream and apache.jserv.JServOutputStream. All five
files come with this package, in apache/jserv (the package path).

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.
