head	1.29;
access;
symbols
	JSERV_0_10_PREVIEW:1.24.0.2
	JSERV_0_9_11:1.23.0.2
	JSERV_0_9_12:1.22.0.2
	JSERV0_9_10:1.12
	JSERV0_9_10_DEV_199802091315:1.7
	JSERV_00_09_09:1.6
	JSERV_0_9_8:1.1.1.1
	JSERV:1.1.1;
locks; strict;
comment	@# @;


1.29
date	98.12.21.14.48.23;	author ed;	state Exp;
branches;
next	1.28;

1.28
date	98.12.21.14.45.36;	author ed;	state Exp;
branches;
next	1.27;

1.27
date	98.07.07.10.54.40;	author ed;	state Exp;
branches;
next	1.26;

1.26
date	98.06.18.20.14.40;	author ed;	state Exp;
branches;
next	1.25;

1.25
date	98.06.02.19.23.57;	author tim;	state Exp;
branches;
next	1.24;

1.24
date	98.05.10.18.59.21;	author ed;	state Exp;
branches;
next	1.23;

1.23
date	98.05.10.03.06.03;	author ed;	state Exp;
branches
	1.23.2.1;
next	1.22;

1.22
date	98.03.02.23.58.48;	author ed;	state Exp;
branches
	1.22.2.1;
next	1.21;

1.21
date	98.03.02.23.24.19;	author tim;	state Exp;
branches;
next	1.20;

1.20
date	98.02.26.20.06.46;	author jonbolt;	state Exp;
branches;
next	1.19;

1.19
date	98.02.24.18.41.13;	author ian;	state Exp;
branches;
next	1.18;

1.18
date	98.02.24.07.41.44;	author ian;	state Exp;
branches;
next	1.17;

1.17
date	98.02.23.08.20.08;	author ian;	state Exp;
branches;
next	1.16;

1.16
date	98.02.20.19.20.50;	author vincent;	state Exp;
branches;
next	1.15;

1.15
date	98.02.18.02.54.58;	author ian;	state Exp;
branches;
next	1.14;

1.14
date	98.02.17.12.20.05;	author ian;	state Exp;
branches;
next	1.13;

1.13
date	98.02.14.09.59.01;	author ian;	state Exp;
branches;
next	1.12;

1.12
date	98.02.14.06.52.00;	author ian;	state Exp;
branches;
next	1.11;

1.11
date	98.02.13.12.15.32;	author ian;	state Exp;
branches;
next	1.10;

1.10
date	98.02.11.23.46.03;	author francis;	state Exp;
branches;
next	1.9;

1.9
date	98.02.10.22.11.10;	author jonbolt;	state Exp;
branches;
next	1.8;

1.8
date	98.02.10.00.34.33;	author francis;	state Exp;
branches;
next	1.7;

1.7
date	98.01.23.23.31.50;	author zeng;	state Exp;
branches;
next	1.6;

1.6
date	98.01.20.08.28.47;	author ian;	state Exp;
branches;
next	1.5;

1.5
date	98.01.19.01.25.02;	author ian;	state Exp;
branches;
next	1.4;

1.4
date	98.01.19.01.21.42;	author ian;	state Exp;
branches;
next	1.3;

1.3
date	98.01.18.20.10.11;	author francis;	state Exp;
branches;
next	1.2;

1.2
date	98.01.17.23.54.51;	author francis;	state Exp;
branches;
next	1.1;

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

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

1.22.2.1
date	98.05.10.03.11.18;	author ed;	state Exp;
branches;
next	;

1.23.2.1
date	98.05.19.12.01.38;	author ed;	state Exp;
branches;
next	;


desc
@@


1.29
log
@correctly identify this as 0.9.12-dev (pending final release)
@
text
@Apache JServ - An Apache module for using Java servlets
by the Java-Apache group <java-apache@@list.working-dogs.com>
  
Release: 0.9.12-dev
Date: December 21, 1998

REQUIREMENTS:

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

DESCRIPTION OF FILES:

  README    - This file
  INSTALL   - Installation instructions
  CHANGES   - Change history
  LICENSE   - Apache JServ License
  TODO      - Unfinished/Incomplete items
  conf/     - Contains an example Servlet Properties file
  apache/   - Contains mod_jserv.c source to be compiled into Apache
  manual/   - Files need to run JServ in Manual mode (where an external
              process from Apache starts the JVM)
  docs/     - Additional supporting documentation
  servclasses.zip  - Java Servlet Development Kit (JSDK) 1.1 from Javasoft
  jserv-0.9.12.jar - Classes and source code to JServ
  jserv-0.9.12-tracing.jar - Same as jserv-0.9.12.jar, but with debugging
                             code compiled in.

WHAT TO DO NOW:

Read the INSTALL file and follow the directions.
Read the docs/howto.html for additional help.

Join the java-apache-users mailing list. 
http://java.apache.org/mail-list.html has instructions on how to do this.




@


1.28
log
@much simpler README.  installation docs are now in INSTALL; further
docs will go on the website.
@
text
@d4 2
a5 2
Release: 0.9.12
Date: December 15, 1998
@


1.27
log
@clarify which "Configuration" file we mean, with a bit more description
of the installation procedure and a pointer to the Apache web site
for more documentation.
@
text
@d1 2
a2 3
JServ - An Apache module for using Java servlets
by Alexei Kosut <akosut@@apache.org> 
and several others <java-apache@@list.working-dogs.com>
d4 2
a5 26
Release: 0.9.12-dev
Date: February 14, 1998

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 mod_jserv Module in Apache
- Compiling JServ
- Configuring Apache
- Configuring Apache to use Servlets
- <servlet> Tag Support
- Example Configuration
- Accessing Servlets
- Class reloading
- Servlet and Virtual Host
- JServ and Signals
- Session Handling
- Tracing JServ
- Running JServ Manually
- Accessing Java Servlets from Apache's mod_perl
- Contributing to the JServ project
- Notes
d13 28
a40 589
Note for JDK 1.1 users: see the section on the ServletClassPath directive.
You will need to add an extra entry to pick up the JSDK 1.1 classes, which
are included with the Apache JServ as of version 0.9.10.

INSTALLING THE MOD_JSERV MODULE IN APACHE:

Under Apache 1.1.x or 1.2.x:
   Copy mod_jserv.c into your Apache src/ directory.  Add the Module line 
   below to your Apache "Configuration" file:

   Module jserv_module mod_jserv.o

Under Apache 1.3.x:
   Copy mod_jserv.c into your Apache src/modules/extra/ directory.  Add the
   AddModule line below to your Apache "Configuration" file (which is
   in the src/ directory --  more documentation is at
   http://www.apache.org/docs/install.html, in the "Compiling Apache"
   section):

   AddModule modules/extra/mod_jserv.o

Run Configure to create a new Makefile, then recompile Apache -- this will
look something like the following:
   ./Configure
   make

COMPILING JSERV:

Cd to the directory where you unpack the mod_jserv distribution. Read
the first few lines of the Makefile to check that the path are ok for
your site. Then make the package. 

If you want the javadoc API, you can make doc.

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.5/bin/java"

* ServletBinaryArgument 

This gives additional command line arguments to the java interpreter. e.g.

ServletBinaryArgument -ms8m -mx16m

To specifiy startup and maximum heap size.

* 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.5/lib/classes.zip
ServletClassPath /usr/local/httpd/jserv/lib/servclasses.zip
ServletClassPath /usr/local/httpd/jserv/classes

Note that the servlets themselves do not have to be in these class
paths. Note however that if they are, they cannot be automatically
reloaded by JServ.  They will be added later with ServletAlias.

Note for JDK 1.1 users: the servclasses.zip file in your source distribution
will be installed in your installation lib directory.  You need to add a
ServletClassPath directive with its path so the JServ will use it.
The servclasses.zip file contains the javax.servlet.* and sun.servlet.*
classes from JSDK 1.1, and are included with this distribution with
permission from JavaSoft.

JDK 1.2 users must not include servclasses.zip in their ServletClassPath.
That's only for JDK 1.1 users to include the servlet classes they're
missing relative to JDK 1.2.

* ServletEnvironment

ServletEnvironment lets you pass and set 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). ServletEnvironment
takes either one or two parameters. The first parameter signifies the name
of an environment variable whose value to pass to the Java process, the
second parameter is optional and specifies a value for the environment
variable. For example, if you were using JDBC with Oracle, you might need
to use the following:

ServletEnvironment LD_LIBRARY_PATH
ServletEnvironment ORACLE_HOME

If you were using the staticly linked version of blackdown's java interpreter
on Linux, you might use:

ServletEnvironment NS_JAVA true

* 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.

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


The following directives in this section are relevant in either the main
server configuration or in any of the VirtualHost sections.

* ServerName (part of Apache configuration)
* ServletManagerHostName

ServletManagerHostName overrides ServerName; but if there is no
ServletManagerHostName directive, and there is at least one JServ
directive (Servlet*) in this VirtualHost section, the ServletName
directive will be used.  The value (which I'll call the host alias)
will be passed on to JServ when a request is recieved.

If you use automatic mode, and several VirtualHosts have the same
ServletManagerHostName (or the same ServerName, but different ports),
then the Apache directives listed below will be the same for all such
virtual hosts.  If you use manual mode, then each name must correspond
to an element in the "jserv.hosts" directive, and each must have
corresponding "jserv.{host_alias}.properties" and
"jserv.{host_alias}.repository" directives.

* ServletProperties

This directive gives the location (absolute or relative to Apache's
server root) of a 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 servlet
aliases, servlet init arguments, default init arguments and for a list
of servlet to launch on startup.

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

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 give that servlet init arguments by using a property like
this:

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

Each name=value pair will be accessible to the servlet using the
getInitParameter() method of the ServletConfig object.

You can also use a property named servlets.default.initArgs that list
default init arguments that every servlet should get. These init
arguments will be available to servlet invoked by alias or class
name. For example :

servlets.default.initArgs=arg1=val1,arg2=val2,...

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-delimited or comma-delimited 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.

* ServletAlias

This directive is explained in the next section; the set of these
corresponds to the "jserv.{host_alias}.repository" directive in the
manual version of JServ.

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

<SERVLET> TAG SUPPORT

To enable <servlet></servlet> tag style servlet invocation, 
add the following lines after the ServletAlias definition:

AddHandler jhtml-parser .jhtml
Action jhtml-parser <uri>/org.apache.jserv.JServSSI

Note: To enable support for the <servlet> tag, your ServletAlias 
directory has to be the same as your jserv servlets installation 
directory -- $SERVLETS_DIR. See the jserv Makefile.

See class documentation on org.apache.jserv.JServSSI for more 
information.

EXAMPLE CONFIGURATION

This is a template based on a running configuration.  Specific file paths
have been edited out since they wouldn't apply to your system.  Don't forget
to remove the []'s from the examples when you replace them - if there are
any square brackets left from this sample, you still have editing to do.

--begin example-----------------------------------------------------------
# mod_jserv: Java servlet module configuration
<IfModule mod_jserv.c>
  ServletProperties     conf/jserv.properties
  ServletPort           8007
  ServletBinary         [full path to your java executable]
  ServletClassPath      [full path to your JDK classes.zip file]
  ServletClassPath      [full path to your JSDK classes.zip file]
  ServletClassPath      [full path to your mod_jserv classes directory]
  ServletAlias          /servlets [full path to your servlets directory]
  ServletAuthExport     On
	AddHandler            jhtml-parser .jhtml
	Action                jhtml-parser /servlets/org.apache.jserv.JServSSI
</IfModule>
--end example-------------------------------------------------------------


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. For example, to invoke a servlet in the foo.bar package you
would use a url like http://host:port/servletalias/foo.bar.Servlet.

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". When a
servlet is accessed by its class name, JServ looks for a file named
classname.initArgs. If that file exists, it should contain properties
to give as init arguments to the servlet. For example, to have a
servlet foo.bar.Servlet initialized with a init argument foo=bar, you
would put a file named Servlet.initArgs in the foo/bar subdirectory of
the servlet path.

CLASS RELOADING

Classes, including servlets, may be loaded from a number of
locations.  In order, the dynamic, static, and system classpaths are
searched.  Each may contain any number of directories, zip files, or
jar files.

Classes loaded from the dynamic classpath will be automatically
reloaded when the file from which they are loaded is changed.  These
files are checked as each request is processed, and if any of the
files have changed then all classes from the dynamic classpath are
discarded and reloaded.

Auto reloading is controlled on a per-virtual host level.  To change
it, you should modify the properties file for each host you would like
to change, adding the following properties (the values should be either
"true" or "false"):

jserv.autoreload.classes - if this is set to false the modification time
of the loaded class won't be check for reloading. The class will only be 
reloaded when the servlet configuration file changes.

jserv.autoreload.file - if this is set to false, the modification time
of the servlet configuration file won't be check for autoreload. 

Thus, if you set both properties to false classes will never be reloaded.

Note that when several classloaders are in use, as is the case with
mod_jserv, the result of the expression

  com.victim.SomeClass.class

will be a different java.lang.Class object on the classloader of the
class that executed the statement.  Each of these classes will have
the same name, but different classloaders.  (TODO: JLS reference for
this behaviour.)

From the mailing list:  (TODO: Clean this up)

> From mbp@@pharos.com.au Tue Nov 11 11:40:40 1997
> Date: Mon, 10 Nov 1997 10:58:53 +1000 (EST)
> From: Martin Pool <mbp@@pharos.com.au>
> To: Java Apache Serlvet List <jsdk-apache@@latchkey.com>
> Subject: [ANNOUNCEMENT] Patch to auto-reload any class
> 
> I am happy to announce:
> 
> I have some code which automatically reloads servlet classes when any user
> classes have changed.  For example, if your servlet depends on a utility
> class or business-logic class and you edit and recompile that class, then
> the servlet engine will automatically reload that class.  This is based on
> and similar to Francis's patch 01.ClassReloadingVH.0.9.8.patch, but does
> not require you to touch the servlet class file. 
> 
> This code makes a distinction between user classes and system classes.
> User classes are candidates for reloading, and system classes are not.
> Currently, system classes are a VM-wide option -- they are loaded from the
> CLASSPATH used to start the VM -- and user classes are a per-virtual-host
> option.  More subtle distinctions, such as per-vhost system classes, could
> be added in the future.
> 
> User classes are loaded from a custom classloader.  As each request is
> handled, the classloader scans the origin files (.class, .zip, or .jar
> files) for each loaded class.  If any of them have changed, the
> classloader informs a manager object that a reload is necessary.  The
> manager discards the classloader (and implicitly all of the classes
> loaded by it.)  The manager creates a new classloader, and uses that
> classloader to load classes to service the request, including the
> servlet object and any other classes referenced by the servlet.
> 
> There is no need to determine dependency trees because all of the user
> classes are discarded when any class changes.  This behaviour is
> required -- as far as I know -- by the design of the ClassLoader
> system, because it's not possible to force classes to be discarded.
> This is actually quite a clean design, because it ensures that classes
> are always consistent with each other.
> 
> Classes are cleanly destroy()ed before unloading, and init()ed when
> they restart.  (I wouldn't bet on this, though... it'd be worth
> testing.  My java.sql.Connection objects seem to work OK in init and
> destroy.)
> 
> Subjectively, there seems to be no substantial performance loss from
> checking each class on each request.  I'd like to add an option to
> turn this behaviour on and off, but I haven't done so yet.
> 
> System classes referenced by the servlet, such as java.lang.String are
> delegated to the system classloader and so are only loaded once, when
> the VM starts.

> From mbp@@pharos.com.au Tue Nov 11 11:41:26 1997
> Date: Tue, 11 Nov 1997 08:43:59 +1000 (EST)
> From: Martin Pool <mbp@@pharos.com.au>
> To: Java Apache Serlvet List <jsdk-apache@@latchkey.com>
> Subject: Re: [ANNOUNCEMENT] Patch to auto-reload any class
> 
> On Mon, 10 Nov 1997, Francis J. Lacoste wrote:
> 
> > > I am happy to announce:
> > > 
> > > User classes are loaded from a custom classloader.  As each request is
> > > handled, the classloader scans the origin files (.class, .zip, or .jar
> > > files) for each loaded class.  If any of them have changed, the
> > > classloader informs a manager object that a reload is necessary.  The
> > > manager discards the classloader (and implicitly all of the classes
> > > loaded by it.)  The manager creates a new classloader, and uses that
> > > classloader to load classes to service the request, including the
> > > servlet object and any other classes referenced by the servlet.
> > > 
> > > [...]
> > > 
> > > Classes are cleanly destroy()ed before unloading, and init()ed when
> > > they restart.  (I wouldn't bet on this, though... it'd be worth
> > > testing.  My java.sql.Connection objects seem to work OK in init and
> > > destroy.)
> > > 
> > 
> > Are destroying every servlets, or just the one that references other
> > classes that need reloading ? You should really destroy (and maybe
> > reconstruct) *every* servlets. If not, old servlets will still
> > reference old version of the class (which is a problem with user-level
> > classes that should be shared between servlets).
> 
> Yes, my code destroys every servlet in that virtual host.  This design is,
> as far as I can tell, a forced move by the ClassLoader design simply
> because it is so hard (impossible, probably) to determine those
> dependencies. 
> 
> If one had a large number of servlets and classes in a virtual host, then
> killing and reloading them might be a bit expensive, but since this will
> only happen in development mode, not deployment I don't think it's a
> problem.  (But I'm willing to be proved wrong.)  We might want to look at
> supporting multiple classloaders per vhost in the future -- perhaps to
> give different users different isolated playgrounds.
> 
> In any case, there is very little subjective delay on reloading a
> moderately complex servlet application on my fairly humble machine buffalo
> (linux, pentium/133MHz, 96MB).  The reload time is reasonable because the
> core API is not discarded, so it doesn't have to load a hundred classes
> from java.lang.*.  (Do java -verbose someclass and you'll see what I
> mean.) 
> 
> Using classloaders means that you may have multiple java.lang.Class
> objects in your VM, with the same name and the same or different
> definitions.  They're different, and allowed to coexist, because they have
> different classloaders.  I can imagine this being confusing to people the
> first few times they encounter it. 
> 
> It's also important to make sure that your servlet's destroy() method
> fulfills its contract, because you can no longer count on the VM or
> OS-level process terminating at the same time as your servlet.  For
> example, if your servlet forked a thread, or opened a database connection
> it would have to kill them in destroy(), otherwise they'd be effectively
> orphaned with no reference to the new servlet object, or even to the new
> servlet class.
> 
> (I'll clip this mail into the README sometime.)
> 
> --
> Martin Pool, Pharos
>  
> "Success is 99% failure." -- Soichiro Honda
> 

SERVLET AND VIRTUAL HOST

Each virtual host (all that apply to virtual hosts, apply equally to
the main host, as far as JServ is concerned, the main host is just
another host) is in a different name space. This means that
getServlets() return only the servlets that are in that virtual
host. Symmetrically, getServlet( name ) will only return servlets
that are in the virtual host. Also since each host can have a separate
property file, it can define an alias with the same name but which maps
to a different class, or initialize each virtual server's set of servlets
with different arguments. 

JSERV AND SIGNALS

When you kill Apache using SIGTERM, JServ call destroy() on all its
servlets before exiting. If you restart Apache using SIGHUP, JServ
will destroy its servlets and reinit the servlet in the
servlets.startup property of the different virtual host. There is one
thing that JServ doesn't do when it is restarted like that : changes
that you made in the Apache configuration files to directive like
ServletAlias or ServletProperties won't be noticed by JServ. Also,
JServ doesn't reread the property files. (So change to servlet
aliases) won't take effect.

SESSION HANDLING

JServ 0.9.10 supports session handling as per the JDSK1.1
specification. (This is the specification that is distributed with
JDK1.2beta and that is included in the mod_jserv
distribution). Sessions are supported either via cookies or url
rewriting. Currently if you want to use url rewriting your servlet has
to call encodeUrl() on every url that it outputs.

Subsequent release may include an engine that will parse the outputs of
the servlet for url to rewrite. (Code always welcome.)

TRACING JSERV

Several parts of jserv can be traced to the ServletErrorLog. What is
traced is controlled via a bitmask. This bitmask is taken from the
system property jserv.tracing that can be set conviniently in a
ServletBinaryArgument directive.

Ex:

ServletBinaryArgument -Djserv.tracing=131

This will trace initialization of JServ, request servicing and servlet
manager activity. The possible flags (from JServDebug.java) are
     1	servlet engine initialization
     2	request processing
     4	request data
     8	response headers
    16	signals
    32	reserved - currently unused
    64	java exceptions
   128	class loader
   256  class loader (verbose version)

In addition, this can be set in the general properties file.  In manual
mode, described below, this is the properties file which contains
jserv.hosts, and is used to set up the different servlet managers.
In automatic mode, this file is set with the directive
ServletGeneralProperties.  That file also allows you to determine
if connections must come from the localhost (generally for manual
mode).

Using that file, you can change tracing by setting

jserv.tracing={number|name}[:{number|name}]*

The "*" indicates zero or more of the previous item, ie. the stuff
inside brakets ([]).  number can be any integer, and should be one of
the above numbers or a bit-wise OR of several of them; name can be one
of the following: Init, ServiceRequest, RequestData, ResponseHeaders,
Signal, ExceptionTracing, ServletManager, Classloader, ClassloaderVerbose
(these are much the same as the items identified above).

Tracing can also be turned on for any of these with directives as
follows:

jserv.tracing.{name}=(true|false)

Here, tracing is one of the above names, and it takes "true" or "false"
as the value.

 
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 distribution.

ACCESSING JAVA SERVLETS FROM APACHE'S MOD_PERL

For experimental use, there is a perl subdirectory which contains the
Apache::Servlet perl module for use with mod_perl.  By default, the
perl code is not built when you build mod_jserv and the Apache JServ
servlet engine.  However, if this interests you, see the perl/README file.

CONTRIBUTING TO THE JSERV PROJECT

If you find a bug or notice a feature that is missing, please feel free 
to contribute a patch, ask for CVS write access or make a suggestion! 

We request that patches are based on either the CVS version or based 
on the most recent JServ release. This makes integrating them into 
the core code much easier.

Documentation about the CVS process is available at:
<http://www.working-dogs.com/>

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
we 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 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 or there are questions about their implementation. They are marked 
with "FIXME". Anyone who has any ideas on how to fix those, please feel 
free to contribute patches.
@


1.26
log
@add to the description of how to do JServ tracing (which can also
be done w/ a "general properties" file, and with somewhat more simplicity
there).  Also, while I was at it, I noted 256 -- the verbose version
for class loader -- as one of the possible numbers.
@
text
@d52 4
a55 1
   AddModule line below to your Apache "Configuration" file:
d59 4
a62 1
Run Configure to create a new Makefile, then recompile Apache.
@


1.25
log
@Fixed minor typo.
@
text
@d544 29
@


1.24
log
@Note change to 0.9.12-dev
@
text
@d532 1
a532 1
ServletBinaryArguement -Djserv.tracing=131
@


1.23
log
@Document changes in autoreloading.
@
text
@d5 1
a5 1
Release: 0.9.11-dev
@


1.23.2.1
log
@release 0.9.11
@
text
@d2 2
a3 1
by the Java-Apache group <java-apache@@list.working-dogs.com>
d5 2
a6 2
Release: 0.9.11
Date: May 19, 1998
d9 2
a10 2
software is currently not fully tested or complete, and (as alpha
software) may not work as expected or at all.
d513 1
a513 1
As of v. 0.9.10, JServ supports session handling as per the JDSK1.1
@


1.22
log
@mod_jserv.c:

Changes to use ServletVMHost, to have ServletHost directive print an
appropriate error message and exit if present (so that people will need
to change to ServletVMHost), and to create ServletManagerHostName.

I didn't make the one of the changes which I discussed -- specifcally,
using r->server->server_hostname, rather than conf->host->server_hostname;
the effect of this is that if you have no JServ directives w/in a
VirtualHost section, requests to that VirtualHost will look to JServ as if
they were recieved by the primary/default server.

This could go either way, but I ultimately couldn't see out any need to
change it.

README:

Documented ServletManagerHostName, fixed a little bit of other
documentation (identifying which directives are relevant in VirtualHost
sections).
@
text
@d336 4
a339 1
Auto reloading can be controlled via two system properties :
@


1.22.2.1
log
@push documentation changes regarding autoreloading to this branch as
well.
@
text
@d336 1
a336 4
Auto reloading is controlled on a per-virtual host level.  To change
it, you should modify the properties file for each host you would like
to change, adding the following properties (the values should be either
"true" or "false"):
@


1.21
log
@Added line referring reader to HTML documentation in
org.apache.jserv.JServSSI regarding use of the <SERVLET> tag.
@
text
@a72 4
* ServerName (part of Apache configuration)

Make sure that the generic ServerName defined in httpd.conf is set correctly.

d152 31
d185 2
a186 3
This directive can be present in the main server or in the virtual host
section. It gives the location (absolute or relative to Apache's server root) of
a JServ properties file. The default is "ServletProperties
d226 1
a226 1
* ServletAuthExport
d228 3
a230 7
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".
@


1.20
log
@tiny readme fix
@
text
@d241 3
@


1.19
log
@What can I say... oops!
@
text
@d80 1
a80 1
the java binary, e.g. "ServletBinary /usr/local/jdk1.1.4/bin/java"
@


1.18
log
@README tweaks based on (probably stupid) questions on the mail list today
@
text
@d15 1
a15 1
- Installing the mod_jserb Module in Apache
@


1.17
log
@Differentiate between Apache 1.2.x and 1.3.x instructions.
@
text
@d15 1
a15 1
- Installing the Module
d42 1
a42 1
INSTALLING THE MODULE:
d46 1
a46 1
   below to your Apache Configuration file:
d52 1
a52 1
   Module line below to your Apache Configuration file:
@


1.16
log
@made ServletEnvironment nicer, pass TZ only when there
@
text
@d44 3
a46 2
Copy mod_jserv.c into your Apache src/ directory. Add the Module line 
below to your Apache Configuration file:
d48 7
a54 1
Module jserv_module mod_jserv.o
@


1.15
log
@added note for JDK 1.2 users that they must omit servclasses.zip
@
text
@d110 1
a110 1
ServletEnvironment lets you pass environment variables from Apache's
d112 6
a117 2
(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:
d119 7
a125 1
ServletEnvironment LD_LIBRARY_PATH ORACLE_HOME
@


1.14
log
@added JDK 1.1 notes about servclasses.zip
@
text
@d104 4
@


1.13
log
@bump versions to 0.9.11-dev
@
text
@d38 3
d96 7
@


1.12
log
@added READMEs about the optional Apache::Servlet perl module
@
text
@d5 2
a6 2
Release: 0.9.10
Date: February 11, 1998
@


1.11
log
@elaborated on debugging flag bits
@
text
@d28 1
d497 7
@


1.10
log
@- Added locking methods with timeout values in JServLock.
- Added InterruptedException to method signature of locking method to
  allows for interrupt.
- Don't wait more that jserv.timeout for the write lock when destroying a
  servlet.
- Added properties to control autoreload in JServServletManager.
@
text
@d475 9
a483 2
manager activity. For a description of the possible flags see
JServDebug.java.
@


1.9
log
@README typo fixes and added a bit about contributions
@
text
@d6 1
a6 1
Date: February 9, 1998
d278 11
@


1.8
log
@Merged in JSDK 1.1 implementation with cookies and session handling.
@
text
@d19 1
d28 1
d62 4
d85 1
a85 1
ServletClassPath /usr/local/jdk1.1.4/lib/classes.zip
d126 2
a127 2
This directive can be present in the main server or in virtual host
section. It give the location (absolute or relative to Apache's server root) of
a177 1

d197 3
a199 1
To enabled <servlet></servlet> tag style servlet invocation, 
a451 1

d455 1
a455 1
trace is controlled via a bitmask. This bitmask is taken from the
d479 12
d495 1
a495 1
I probably interpreted some of it slightly differently than others did,
d504 3
a506 2
right. They are marked with "FIXME". Anyone who has any ideas on how to
fix those, please do so.
@


1.7
log
@More documentation about the <servlet> tag support.
@
text
@d5 2
a6 2
Release: 0.9.8
Date: January 22, 1998
d24 1
a32 1
* JSDK 1.0 or later <http://jserv.javasoft.com>
d80 1
a80 1
ServletClassPath /usr/local/JSDK1.0/lib/classes.zip
d432 13
@


1.6
log
@corrections for README mailed in by "Steve M. Martin" <smartin@@wwnet.com>
@
text
@d192 9
d220 2
@


1.5
log
@oops... typo!  "my a configuration" should be "a configuration".
@
text
@d145 1
a145 1
You can also used a property named servlets.default.initArgs that list
d242 1
a242 1
classname.initArgs. If that file exists, it should contains properties
d406 3
a408 3
property file, it can defined alias with the same name but which maps
to different class, or init its set of servlets with different
arguments. 
d462 1
a462 1
right. There are marked with "FIXME". Anyone who has any ideas on how to
@


1.4
log
@added example configuration
@
text
@d195 1
a195 1
This is a template based on my a running configuration.  Specific file paths
@


1.3
log
@Updated todo list and change the attribution string and
release date in README.
@
text
@d19 1
d191 22
@


1.2
log
@Fixed typos and add documentation about tracing.
@
text
@d2 3
a4 2
by Alexei Kosut <akosut@@apache.org>

d6 1
a6 1
Date: December 1, 1997
@


1.1
log
@Initial revision
@
text
@d15 1
d19 4
a25 1

d43 7
d238 1
a238 1
mod_jserv, the resault of the expression
d240 1
a240 1
  com.victim.SomeClass.CLASS
d398 15
a431 4

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


1.1.1.1
log
@JServ 0.9.8
@
text
@@
