head	1.2;
access;
symbols
	JSERV_00_09_09:1.2
	JSERV_0_9_8:1.1.1.1
	JSERV:1.1.1;
locks; strict;
comment	@# @;


1.2
date	98.01.12.15.08.00;	author ed;	state Exp;
branches;
next	1.1;

1.1
date	97.12.05.00.39.50;	author jon;	state Exp;
branches
	1.1.1.1;
next	;

1.1.1.1
date	97.12.05.00.39.50;	author jon;	state Exp;
branches;
next	;


desc
@@


1.2
log
@Changes to use socket based restart notification (lots of changes in signal
handlers), to allow JServ to run on a different machine, to improve
efficiency of hex characters, conversions, documentation for the README
for manual jserv, and catching one more possible exception.

Not all the files listed as having been changed were actually.
@
text
@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.)


@


1.1
log
@Initial revision
@
text
@d14 4
a17 2
your system's setup (C compiler, options). Then type "make". This will
compile a program, "jserv", which will be used to run JServ.
d32 1
a32 1
jserv javabin [-Jopt1 -Jopt2...] [-t] propfile port
d34 8
a41 5
This will run JServ manually. "javabin" should be the full path name of
your java runtime binary. "propfile" 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.
d44 2
a45 1
example, -J-debug will turn on remote debugging.
d51 31
d85 1
a85 2
libraries, the JSDK libraries, the apache.jserv package, and the locations
of your servlets.
d93 8
d105 7
a111 3
the process id (pid) of jserv using the ps command, and type "kill <pid>".
This will gracefully shut down JServ, allowing servlets to perform any
neccessary cleanup.
d114 1
a114 1
can send a HUP signal to JServ, using "kill -HUP <pid>". Note that this
d116 4
a119 1
made changes to a class, you will need to stop and start JServ.
@


1.1.1.1
log
@JServ 0.9.8
@
text
@@
