This document briefly explains how to install JServ, for both
automatic and manual mode.  It does not provide in depth information
(README provides that in release 0.9.11), just enough information
(and references) to get you started.

-
 * Authors: 	Ed Korthof
 * Revision:	$Revision: 1.1.2.1 $ 
 * Date:		$Date: 1998/05/19 12:01:37 $
-


Table Of Contents

	Road Map
	Making JServ Classes
	Installing the JServ Module
	Automatic Mode
	Manual Mode
	Available Apache Directives
	General Properties File
	Servlets Properties Files


---------------------------------------------------------------------------
		Road Map
You should follow one of the two paths shown below:

For Automatic Mode:
  1.) Make the JServ Classes (Making JServ Classes)
  2.) Recompile Apache (Installing the JServ Module)
  3.) Set up the Apache Configuration file(s) for Automatic Mode
      (Automatic Mode)

For Manual Mode:
  1.) Make the JServ Classes (Making JServ Classes)
  2.) Recompile Apache (Installing the JServ Module)
  3.) Set up Manual Mode (Manual Mode)
  4.) Set up the Apache Configuration file(s) for Manual Mode
      (Manual Mode)

Note that in the text which follows, it has been assumed that JServ
was placed in /local/jserv.  That string should generally be replaced
with the directory in which you wish to place jserv.  You should start by
untarring the distribution, and copying it into that directory.

---------------------------------------------------------------------------
		Making JServ Classes

On some systems, you can go to /local/jserv and run make.  This
may work -- or it may not.

If it fails, you can set your class path to an appropriate value.
Assuming you installed jserv in /local/jserv and java in /usr/local/java,
that could be (in csh, then sh):
setenv CLASSPATH /usr/local/java/lib/classes.zip:/local/jserv/servclasses.zip:/local/jserv/src
    or
CLASSPATH=/usr/local/java/lib/classes.zip:/local/jserv/servclasses.zip:/local/jserv/src; export CLASSPATH

Then compile all the java files (assuming you're in /local/jserv):

javac src/org/apache/*/*.java src/org/apache/util/*/*.java

Note that the directory for the JServ classes is now:
/local/jserv/src

The file for the JSDK classes is
/local/jserv/servclasses.zip

These will be needed later.


---------------------------------------------------------------------------
		Installing the JServ Module

You may need to recompile Apache in order to use JServ.  If this is
the case, follow the directions in the README file (basically, copy
mod_jserv.c to the appropriate source directory in Apache, edit the
Configuration file and the Makefile, run Configure, and then use make).


---------------------------------------------------------------------------
		Automatic Mode

In this mode, JServ is started and stopped by Apache.

You need to set the following Apache directives to use this mode:

ServletPort, ServletAlias, ServletClassPath, ServletBinary,
ServletProperties

It is strongly recommended that you use the following directive:

ServletErrorLog

The meanings of these directives are shown below, in the section
"Available Apache Directives"; a sample set of them is shown below:
	ServletPort 8008
	ServletAlias /servlets /local/jserv/servlets
	ServletClassPath /usr/local/java/lib/classes.zip:/local/jserv/servclasses.zip:/local/jserv/src
	ServletBinary /usr/local/java/bin/java
	ServletProperties /local/jserv/conf/jserv.properties
	ServletErrorLog logs/jserv_errors.log


---------------------------------------------------------------------------
		Manual Mode

In this mode, JServ runs as a separate process, requiring its own
initialization and shutdown at system startup and shutdown.  There are
scripts in the manual directory which may be helpful for this.

To use this mode, compile jserv.c (in the manual directory).  You may
need to edit the Makefile options for your system (Linux and Solaris
are shown; options for other systems would be welcome).

You will need to write a configuration file at this point -- this file
will be refered to as jserv.properties.  It needs to have at least three
entries: first, it needs to have a "jserv.hosts" line, indicating which
virtual hosts will be using the JServ.  For each of those hosts, there
should be two directives: "jserv.${host}.repository" and
"jserv.${host}.properties".  The following is a sample jserv.properties
file:
	jserv.hosts=_default_:foo.bar.com
	jserv.foo.bar.com.repository=/home/foo/lib/classes:/www/foo/lib/classes
	jserv.foo.bar.com.properties=/home/foo/conf/servlet.properties
	jserv._default_.repository=/local/apache/lib/classes
	jserv._default_.repository=/local/jserv/conf/jserv.properties._default_
(_default_ is a special value documented in manual/README.)

Then edit the scripts start-jserv and stop-jserv (or, if you'd rather
use a single script, jserv.init), setting the appropriate values for
several paths, the jserv.properties file, the port, and any other
available options.

The format of the properties files for each of the hosts is documented
below, in the section "Servlet Properties Files".

The last thing you need to do is to reconfigure Apache -- the following
directives (which can be in any of the conf files other than .htaccess
files) are needed:

ServletManual On
ServletPort {port}
ServletAlias /servlets /local/jserv/servlets

The meaning of these directives, as well as a list of all available
directives can be found below, in the section "Available Apache Directives".

After you've added these directives, restart Apache.


---------------------------------------------------------------------------
		Available Apache Directives

Unless otherwise stated, all directives are optional.

name:			value:			Manual/Automatic/Both

ServletAlias		(alias) (dir)		B

	the alias is used to map requests to mod_jserv; any URI which begins
	with this string will be handled by mod_jserv.  dir is actually a
	directory, zip, or jar file; it (as well as possibly other paths
	or files) will be searched for servlets when a request matches
	the alias.  ServletAlias is required.

ServletAuthExport	(on|off)		A

	whether or not to allow other modules to have access to JServ's
	authorization information.  not relevant in Manual mode because
	in Manual mode, there is currently no authorization information
	required to talk to the JServ process.

ServletBinary		(executable file)	A

	the full path for the executabe file to use to start the JVM
	when in automatic mode.  ServletBinary is required in
	automatic mode.

ServletClassPath	(path specification)	A

	the classpath for JServ, which the webservers initiates in
	automatic mode.  This is a colon separated list of files,
	directories, zip files, and jar files; it should contain
	the general Java libraries, the 'servclasses.zip' file which
	comes with the JServ distribution, and the JServ class
	files.  For example, it might be the following:
	ServletClassPath /usr/local/java/lib/classes.zip:/local/jserv/servclasses.zip:/local/jserv/src
	ServletClassPath is required in automatic mode.

ServletEnvironment	(list of variables)	A

	a space separated list of variable names; these environmental
	variables will be passed on to the JServ processes created in
	automatic mode.  If you use Oracle, eg., you will need to pass
	along ORACLE_HOME and LD_LIBRARY_PATH (which will also need to
	be set in the script whichs starts the webserver).

ServletGeneralProperties(filename)		A

	this is the general properties file given to JServ during
	initialization in automatic mode.

ServletBinaryArgument	(raw arguments)		A

	the arguments to be passed along to the ServletBinary (which
	starts the JVM), when it is launched in automatic mode.
	Here are two examples: -J-mx64m (which sets the maximum heap
	size to 64 MB) and -J-ms16m (which sets the minimum heap
	size to 16 MB).  These numbers are only examples; you should
	use numbers appropriate to your applications, if necessary.

ServletArgument		(raw arguments)		A

	the arguments to be passed to the JServ process, when it is
	launched during the automatic startup process.

ServletErrorLog		(abs or rel file)	A

	the absolute or relative (to the httpd ServerRoot) file will
	be used for logging in Automatic mode.

ServletManual		(on|off)		B

	this directive determines whether manual mode will be on or
	off; it defaults to off.

ServletPort		(number)		B

	the port is used to connect to JServ.  in manual mode, it
	should correspond to the port used in the script which starts
	JServ.  this directive is required.

ServletVMHost		(host name or ip)	M

	the name (which the server will attempt to resolve to an ip)
	or ip will be used to connect to JServ (the JServ process
	should be running on that machine).

ServletManagerHostName	(arbitrary string)	M

	the string will be used to identify this host when talking to
	JServ; it should correspond to one entry in the jserv.hosts line.


---------------------------------------------------------------------------
		General Properties File

This file is the general properties is optional in automatic mode, but
required in manual mode.  The directives are as follows:

name:			value:			Automatic/Manual/Both

jserv.hosts		host1[:host2:...:hostn]	M

	this directive sets up the virtual hosts which will be handled
	by this JServ.  note that "_default_" is a special value which
	will match any otherwise unmatched request.  also note that
	the name a request gives (which is ordinarily the virtual host
	name) can be overriden with the Apache directive
	ServletManagerHostName.  if there is no host named "_default_"
	then requests whose hostname doesn't match a configured host
	will be rejected.  this directive is required; and for
	each host, jserv.{host}.repository and jserv.{host}.properties
	are required.

jserv.hostX.repository	(classpath spec)	M

	the classpath spec is a colon separated list consisting of
	directories, zip files, and jars.  it will be used to
	extend the classpath of this host.  hostX represents one of
	the hosts configured in the jserv.hosts line.  this directive
	is required in manual mode.  furthermore, each of the listed
	resources *must* exist, or JServ will not work.  the
	value may be empty.

jserv.hostX.properties	(properties file)	M

	the properties file will be the Servlet Properties File,
	documented below.  this directive is required, but the file
	does not need to exist.

jserv.security.localhostonly	(true|false)	M

	this should be set to true if webservers on other machines
	will be talking to this JServ.  otherwise, it should be
	false for security reasons.

jserv.tracing		(list of numbers)	B

	this directive sets tracing true for each of the specified
	numbers (which may be a bit-wise-OR combination of other
	values).  the list is colon separated.
	this (and the following tracing directives) are valid in
	either mode.

jserv.tracing.Init		(true|false)	B
jserv.tracing.ServiceRequest	(true|false)	B
jserv.tracing.RequestData	(true|false)	B
jserv.tracing.ResponseHeaders	(true|false)	B
jserv.tracing.Signal		(true|false)	B
jserv.tracing.ExceptionTracing	(true|false)	B
jserv.tracing.ServletManager	(true|false)	B
jserv.tracing.Classloader	(true|false)	B
jserv.tracing.ClassloaderVerbose (true|false)	B

	each of these directives turns on (or off -- this will override
	the jserv.tracing line) tracing for the specified type of
	tracing.


---------------------------------------------------------------------------
		Servlets Properties Files

There is one servlets properties file for each host or virtual host,
as configured.  That file may contain any of the following directives,
all of which are relevant in either mode:

name:				value:

servlets.startup		(servlets list)

	comma/space separated list of servlets to started when this
	host/virtual host is initialized.  each can be either an
	absolute name or an alias

servlets.default.initArgs	(raw string)

	this, if present and not empty, will be used as the
	initialization argument to any servlets which don't have their
	own configured initArgs.  when used, it is passed to the init
	function.

servlet.(name).code		(fully qualifed classname)

	this resolves an alias (name) to a class (the value).  if
	aliases are used, you should refer to the servlets by their
	aliases throughout.

servlet.(name).initArgs		(raw string)

	this is the initialization arguments for the class or
	alias "name".  it will be passed in to the init funciton.

jserv.init.timeout		(integer timeout in milliseconds)

	this, if present, is the time a servlet which has been
	told to initalize itself will be allowed to work before
	being considered a failure.

jserv.destroy.timeout		(integer timeout in milliseconds)

	this, if present, is the time a servlet which has been
	told to destroy itself will be allowed to work before
	being considered a failure.

jserv.autoreload.file		(true|false)

	if true, this will cause the host/virtual host to be
	reloaded (including class files) if the servlets property
	file for that host changes.

jserv.autoreload.classes	(true|false)

	if true, this will cause the host/virtual host to be
	reloaded if any of the class files change).

