Apache JServ Protocol

The original document was written by Dan Milstein, [email protected] on December 2000. The present document is generated out of an xml file to allow a more easy integration in the Tomcat documentation. I am not one of the designers of this protocol -- I believe that Gal Shachor was the original designer. Everything in this document is derived from the actual implementation I found in the tomcat 3.x code. I hope it is useful, but I can't make any grand claims to perfect accuracy. I also don't know why certain design decisions were made. Where I was able, I've offered some possible justifications for certain choices, but those are only my guesses. In general, the C code which Shachor wrote is very clean and comprehensible (if almost totally undocumented). I've cleaned up the Java code, and I think it's reasonably readable. Increasing performance (speed, specifically). Adding support for SSL, so that isSecure() and getScheme() will function correctly within the servlet container. The client certificates and cipher suite will be available to servlets as request attributes. The ajp13 protocol is packet-oriented. A binary format was presumably chosen over the more readable plain text for reasons of performance. The web server communicates with the servlet container over TCP connections. To cut down on the expensive process of socket creation, the web server will attempt to maintain persistent TCP connections to the servlet container, and to reuse a connection for multiple request/response cycles. Once a connection is assigned to a particular request, it will not be used for any others until the request-handling cycle has terminated. In other words, requests are not multiplexed over connections. This makes for much simpler code at either end of the connection, although it does cause more connections to be open at once. Idle No request is being handled over this connection. Assigned The connecton is handling a specific request. SEND HEADERS Send a set of headers back to the browser. SEND BODY CHUNK Send a chunk of body data back to the browser. GET BODY CHUNK Get further data from the request if it hasn't all been transferred yet. This is necessary because the packets have a fixed maximum size and arbitrary amounts of data can be included the body of a request (for uploaded files, for example). (Note: this is unrelated to HTTP chunked tranfer). END RESPONSE Finish the request-handling cycle. Each message is accompanied by a differently formatted packet of data. See Response Packet Structures below for details. There are four data types in the protocol: bytes, booleans, integers and strings. Packets sent from the server to the container begin with 0x1234 . Packets sent from the container to the server begin with AB (that's the ASCII code for A followed by the ASCII code for B). After those first two bytes, there is an integer (encoded as above) with the length of the payload. Although this might suggest that the maximum payload could be as large as 2^16, in fact, the code sets the maximum to be 8K. For most packets, the first byte of the payload encodes the type of message. The exception is for request body packets sent from the server to the container -- they are sent with a standard packet header (0x1234 and then length of the packet), but without any prefix code after that (this seems like a mistake to me). To ensure some basic security, the container will only actually do the Shutdown if the request comes from the same machine on which it's hosted. The first Data packet is send immediatly after the Forward Request by the web server. 3 Send Body Chunk Send a chunk of the body from the servlet container to the web server (and presumably, onto the browser). 4 Send Headers Send the response headers from the servlet container to the web server (and presumably, onto the browser). 5 End Response Marks the end of the response (and thus the request-handling cycle). 6 Get Body Chunk Get further data from the request if it hasn't