This document describes the protocol used by JServ to communicate between
mod_jserv.c (the module) and the Java servlet server (JServHandler). It
works over a TCP socket.

* STARTUP

The module starts up JServHandler during its initialization phase. It
should run java, with the appropriate classpath to contain any servlets
that the server might want to run. It should pass JServHandler two
command-line arguments, the name of the jserv.properties file, and the
port it should run on. e.g.:
"java jserv.apache.JServHandler /local/httpd/conf/servlets.properties 8007"

Then module then passes, to the java process's stdin, the secret
authentication key (a string randomly generated by the server) and a
newline.

Any additional data passed through to stdin should be taken as a signal
token. These are three character strings (not newline-terminated) of the
form "S##", where ## is the number (with leading 0, if neccessary)
indicating a POSIX signal has been received, that JServ should deal
with. Currently, JServ supports "S01" (SIGHUP) to restart the servlets, and
"S15" (SIGTERM) to clean up and terminate the Java process.

If JServHandler is started with the "-m" command-line option, it will
deactivate the authentication. This means that anyone on the machine can
run servlets, so beware. Normally, it is started automatically by the
module, without -m.

The "-t" command-line option can also be used. If present, it will cause
JServ to print a stack trace to System.err (stderr) whenever the servlet
throws an exception or an error. This is in addition to the error it
normally logs with the name and message of the exception.

The servlets.properties file (or whatever it is called) should contain
Java Property lines. The only supported use for this file is to send init
arguments to the servlets. It takes the following form:

Classname.initArgs=arg1=val1,arg2=val2,...

Note that Classname should be the full name of the class, including the
package. Servlet "aliases" are not supported.

* REQUEST

The request is made by opening a TCP connection to port JServHandler is
running on. The socket should be opened to the loopback interface
(127.0.0.1), so the data does not escape the server.

The module sends the request metadata to JServHandler. These are sent as
lines, with two parts: A one-character identifier, and the
data. This is preceded with a four-digit hex number indicating the length
of the following string (with leading 0s), e.g. "000dHDate Friday", where
"000d" is the length, "H" is the identifier, and "Date Friday" is the
data.
 
a) Authentication and Initliazation

The module sends "A<auth data><tab><class name>". 

<auth data> is the secret key generated by the server and passed to JServ
earlier. If this is not correct, JServHandler will reject the response.

The module sends the name of the class to run in <class name>. This
should be the final name of the class, without any path, in correct
dotted package notation, etc... JServHandler will look for the class name
in its class path.

This must be the first thing sent by the module.

b) Environment variables

The module sends "E<var name><tab><var value>". The vars should contain all
the standard CGI variables, but should not include the HTTP_ set, since
the HTTP headers are sent later.

e.g, "EPATH_INFO	/foo"

The following variables are required. Most are CGI/1.1 variables, but a
few are Apache-specific. The following should all be sent (except for
those marked with an asterix(*), which should only be sent if
appropriate), as well as any additional CGI variables available:

AUTH_TYPE(*):       The type of authentication used
CONTENT_LENGTH(*):  The length of the request entity
CONTENT_TYPE(*):    The media type of the request entity
DOCUMENT_ROOT:      The server's main document root.
PATH_INFO(*):       Extra URI path information
PATH_TRANSLATED(*): The translated path info
QUERY_STRING(*):    The query arguments
REQUEST_METHOD:     The method used for the request
REMOTE_USER(*):     The authenticated username used for the request
REMOTE_ADDR:        The IP address of the requesting host
REMOTE_HOST:        The hostname of the requesting host (if available)
SCRIPT_NAME:        The URI portion that refers to the servlet
SERVER_NAME:        The hostname of the server
SERVER_PORT:        The port number of the server
SERVER_PROTOCOL:    The protocol used for the request
SERVER_SOFTWARE:    The name of the server software

c) Request headers

The module sends all of the client's request headers, in the form
"H<header name><tab><header value>".

e.g., "HUser-Agent	Mozilla/4.0 (Windows NT)"

d) A blank line

When all the E and H lines (they may be interpolated), the module sends a
blank line. (i.e., 0-length) This indicates that the metadata has been
completed.

e) The request entity

If there is a request entity, it is sent. If not, nothing further is sent.

* RESPONSE

The response consists of two parts, response headers and the response
entity. This is sent basically the same way CGI responses are sent:

a) Response Headers

The headers to be set for the response should then be sent, in MIME
format: "<header name>: <header value>", terminated with a crlf.

Headers set here will be outputted by the server. The server will add the
HTTP line, and Server:, Date: and other headers, so only headers that the
servlet needs to set should be set. e.g., Content-type, Cookie,
whatever.

A few headers have special meanings:

Status: <code> <string>
This sets the response status to <code>, with a status message of 
<string>. This is the same as the CGI output header of the same name.
e.g., "Status: 404 Not Found"

Servlet-Log: <string>
This sends a message to be logged in the server's log.

Servlet-Error: <message>
This indicates that JServHandler had an error occur. The server should
send an error response back to the browser, with the status set by a
seperate Status: header (see above) - 500 should be used if Status: is
not present. The <message> strong should be logged to the server's error
log, as the reason why the request failed. No response entity will be
present for this response.

When the last header has been sent, a blank line should be sent.

b) Response Entity

JServHandler ouputs the contents of the response to the module through the
socket. When it is finished, JServHandler closes the socket. This will
indicate to the module that the request has been completed.
