Obsolete - July 29, 1998
describes the protocol used by JServ to communicate between mod_jserv.c
(the module)
and the Java servlet server (JServ). It works over a TCP socket.
The module starts up JServ during its initialization phase. It should run java, with the appropriate classpath to contain the JDK, JSDK and JServ classes. It may also contains servlets, but note that those cannot be reloaded if changed. JServ needs at least one command-line argument: the port it should listen on. The other command-line arguments are optional. The full usage is "<java interpreter> org.jserv.apache.JServ [-p configFile] [-a] port". If JServ is started with the "-a" 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 "-a". The "-p" command-line option can be used to tell JServ to use a configuration file instead of receiving information from System.in (stdin).
The module then passes, to the java process's stdin, the secret authentication key (a string randomly generated by the server) and a newline. After, for every host that will use servlets, it sends one line contains minimally three pieces of information separated by tab:hostname propertyfile (servlet_repository) +
The first element is the name of the host that can run servlets. The second argument is the path to the property file for that host. Finally, follows a tab-delimited list of servlet repositories, either directories or zip/jar files. When all the host data has been sent. The module send a line containing "end".
The request is made by opening a TCP connection to port JServ is running on. The socket should be opened to the loopback interface (127.0.0.1), request from any other address is refused by JServ.
The module sends the request metadata to JServ. 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.
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
The response consists of two parts, response headers and the response entity. This is sent basically the same way CGI responses are sent:
Since Java doesn't provide any facility for signal handling, after JServ is started and has read the host information via a stdin. It launches a thread that waits for signal token on stdin. 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 handles both SIGTERM (S15) and SIGHUP (S01) the same way : it calls destroy() on all its servlets and then quit via System.exit(0). If the signal was a SIGHUP, the parent process (Apache or standalonge JServ) will reinstall Java.
What this achieves is that the calling process can install a signal handler for itself and when receives such a signal sends it on stdin of JServ.
Copyright (c) 1997-98 The
Java Apache Project.
$Id: AJPv1.html,v 1.3 1999/06/09 05:21:29 jonbolt Exp $
All rights reserved.