USING JSERV'S MANUAL MODE
by Alexei Kosut <akosut@apache.org>

This document explains how to compile and run JServ in manual
Normally, 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.

COMPILING THE MANUAL JSERV PROGRAM

In this directory (manual), there is a Makefile. Edit this to reflect
your system's setup (C compiler, options).  Note that you must have
the system libraries for sockets, and that the library flags included
work for Solaris.  Then type "make".  This will compile a program,
"jserv", which will be used to run JServ.

CONFIGURING APACHE

Add the ServletManual directive to Apache's configuration:

ServletManual On

Now, Apache will not automatically start and stop JServHandler. You must
activate it manually.

RUNNING JSERV MANUALLY

Use the jserv program in the following form:

jserv [-Jopt1 -Jopt2...] [-t] [-m propfile] port

NOTE:  You must set the environmental variable JAVA_BINARY, and either
set JSERV_PROPERTY_FILE, or use the -m propfile option.

This will run JServ manually. JAVA_BINARY should be the fully qualified
location of the java executable; "propfile" (or $JSERV_PROPERTY_FILE)
should point to the location of the servlet properties file (see above),
and "port" should be the port JServHandler should run on. This should be
the same as the ServletPort directive.

You can use the -J switch to send options to the Java executable. For
example, -J-debug will turn on remote debugging, and -J-ms16m sets the
minimum heap size to 16 MB.

The optional -t command-line switch will activate stack traces. If this is
present, and an exception or error is thrown by the servlet, JServ wil
print the stack trace to stderr.

The configuration file for JServ in manual mode must have 'jserv.hosts',
whose value should be the list (seperated by ':') of virtual hosts which
will be using this JServ.  For each host in this list, there should also
be jserv.${host}.properties and jserv.${host}.repository.  The first
is a configuration file for this virtual host; the second is a location
(directory or jar/zip file) to search for servlets.  The configuration
file is fairly standard (servlets.startup, servlet.broker.code,
servlet.broker.description, and servlet.broker.initArgs all work here,
eg.).  Here is a sample:

In $JSERV_PROPERTIES_FILE:
-----
...
jserv.hosts=foo.bar.com:foo.baz.com
jserv.foo.bar.com.properties=/usr/local/apache/conf/jserv/foo.bar.properities
jserv.foo.bar.com.repository=/usr/local/apache/htdocs/foo.bar/classes
jserv.foo.baz.com.properties=/usr/local/apache/conf/jserv/foo.baz.properities
jserv.foo.baz.com.repository=/usr/local/apache/htdocs/foo.baz/lib/classes.jar
...
-----

In /usr/local/apache/conf/jserv/foo.bar.properities:

-----
...
servlets.startup=Spaz
servlet.Spaz.code=com.bar.foo.servlet.Spaz
...
-----
etc.

Note that the ServletBinary, ServletClasspath, ServletLog and
ServletProperties directives are ignored when JServHandler is run
manually. Make sure the classpath is set correctly, including the JDK
libraries, the JSDK libraries, and the apache.jserv package.

Also, when run manually, JServ will not use authentication to confirm that
JServHandler is being invoked by its parent Apache. This means that anyone
on the machine can run Java servlets. It is not recommended you run
JServHandler manually on a machine that has logins not owned by the
administrator.

If you are running JServ in a secure environment, you can run JServ on
a separate machine from the webserver.  To do this, set
jserv.security.localhostonly=false in $JSERV_PROPERTIES_FILE. Then,
configure the JServ plugin to talk to the machine on which JServ is
running (in Apache, this is "ServletHost {hostname | hostip}", which
is currently a global setting -- you can't have separate hosts for
separate virtual hosts).  Note that this only works in manual mode. 

SHUTTING DOWN/RESTARTING JSERV

It is reccomend that you run jserv in the background (use the & shell
option), and shut it down by sending it a TERM signal. To do this, find
the process id (pid) of jserv using the ps command or by looking at the
PID file (see below), and type "kill -TERM <pid>".  This will gracefully
shut down JServ, allowing servlets to perform any neccessary cleanup.

jserv now records its pid as either "jserv.pid" in the current directory
relative to where it was started, or in $JSERV_LOCK_FILE, if that
variable is defined.

If you want to restart JServ, which will destroy all the servlets, you
can send a HUP signal to JServ, using "kill -HUP <pid>".  (Note that this
will not unload the Java VM, so classes will not be reloaded. If you have
made changes to a class, you will need to stop and start JServ. --
JServ now has a custom classloader, so this may not longer be accurate:
classes may actually be reloaded when they change or when the server
is restarted.)


