1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<meta HTTP-EQUIV="Content-Type" CONTENT="text/html;CHARSET=iso-8859-1">
<meta NAME="Author" CONTENT="Alexei Kosut">
<title>Apache JServ Protocol Version 1 (AJPv1) - July 29, 1998 - Obsolete</title>
</head>
<body BGCOLOR="#FFFFFF">
<p align="center"><a href="http://java.apache.org/" target="_top"><img SRC="../images/java-apache-project.gif" BORDER="0" WIDTH="609"
HEIGHT="100" ALT="The Java Apache Project"></a></p>
<h1 ALIGN="CENTER">Apache JServ Protocol Version 1.0</h1>
<p ALIGN="CENTER">Obsolete - July 29, 1998</p>
<p ALIGN="CENTER">describes the protocol used by JServ to communicate between mod_jserv.c
(the module) <br>
and the Java servlet server (JServ). It works over a TCP socket.</p>
<h3>Startup</h3>
<blockquote>
<p>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).<br>
<br>
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:</p>
<blockquote>
<p>hostname propertyfile (servlet_repository) + </p>
</blockquote>
<p>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". </p>
</blockquote>
<h3><b>Request</b></h3>
<blockquote>
<p>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.<br>
<br>
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. </p>
</blockquote>
<ol>
<ol>
<li><b>Authentication and initialization</b><br>
The module sends "A<auth data>" where <auth data> is the secret key
generated by the server and passed to JServ earlier. If this is not correct, JServ will
reject the response. </li>
<li><b>Server name</b> <br>
The module sends "S<hostname>". This is the host in which this servlet
should be requested. This will determine where JServ will look to service the servlet. </li>
<li><b>Repository and class name <br>
</b>The module sends "C<rep_name><tab><classname>". The first
element is the repository to which the servlet has been map. This is currently unused but
reserved for future extension where repository may be assigned a security model. The class
name is the fully qualified name of the class in dot notation. i.e. foo.bar.Servlet. The
servlet would load from one of the repository defined for that host or from the CLASSPATH.
</li>
<li><b>Environment variables <br>
</b>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: <ul>
<p>AUTH_TYPE(*): The type of authentication used<br>
CONTENT_LENGTH(*): The length of the request entity<br>
CONTENT_TYPE(*): The media type of the request entity<br>
DOCUMENT_ROOT: The server's main document root<br>
PATH_INFO(*): Extra URI path information<br>
PATH_TRANSLATED(*): The translated path info<br>
QUERY_STRING(*): The query arguments<br>
REQUEST_METHOD: The method used for the request<br>
REMOTE_USER(*): The authenticated username used for the request<br>
REMOTE_ADDR: The IP address of the requesting host<br>
REMOTE_HOST: The hostname of the requesting host (if available)<br>
SCRIPT_NAME: The URI portion that refers to the servlet<br>
SERVER_NAME: The hostname of the server<br>
SERVER_PORT: The port number of the server<br>
SERVER_PROTOCOL: The protocol used for the request<br>
SERVER_SOFTWARE: The name of the server software </p>
</ul>
</li>
<li><b>Request headers</b><br>
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)" </li>
<li><b>A blank line</b><br>
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. </li>
<li><b>The request entity</b><br>
If there is a request entity, it is sent. If not, nothing further is sent. </li>
</ol>
</ol>
<h3>Response</h3>
<blockquote>
<p>The response consists of two parts, response headers and the response entity. This is
sent basically the same way CGI responses are sent:</p>
</blockquote>
<ol>
<ol>
<li><b>Response headers<br>
</b>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. When the last header has been sent, a blank line
should be sent.<br>
A few headers have special meanings: <ul>
<li>Status: <code> <string><br>
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" </li>
<li>Servlet-Log: <string><br>
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 separate 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. </li>
</ul>
</li>
<li><b>Response entity<br>
</b>JServHandler outputs the contents of the response to the module through the socket.
When it is finished, JServ closes the socket. This will indicate to the module that the
request has been completed. </li>
</ol>
</ol>
<h3>Signal Handling</h3>
<blockquote>
<p>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.<br>
<br>
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.</p>
</blockquote>
<p ALIGN="CENTER"><font SIZE="2">Copyright (c) 1997-98 <a HREF="http://java.apache.org/" target="_top">The
Java Apache Project</a>.<br>
</font><font SIZE="-1">$Id: AJPv1.html,v 1.3 1999/06/09 05:21:29 jonbolt Exp $</font><font SIZE="2"><br>
All rights reserved.</font></p>
</body>
</html>
|
