Apache JServ Mode of Operation

Abstract

This document describes the way Apache JServ works and it is intended to give detailed information on its mode of operation to quickly bring new developers up to speed. It may give nice information for power users looking for a deeper knowledge for better configuration and fine tuning.

Glossary

Client
The Apache Web Server (AWS) process/thread becomes the client in the context of this document because it initiates the request and waits for the response.
Server
The Apache JServ Servlet Engine (AJ) performs the server function in the context of the this document.
Connection
A finite-duration link between client and server, upon which all transmissions occur. This can theoretically be over any reliable ordered-stream transport but is expected to usually be delivered over a TCP-based socket.
Apache JServ Protocol (AJP)
The protocol used on the connection to handle communication between client and server (see the specification for more detailed info)
Request
The full process of request handling, started by the client and terminated by the server.
Servlet
The compiled (.class) version of the servlet
Servlet Full Name
The full dot-format class name of the servlet (without the .class extension)
Servlet Repository
A directory or archive where some servlets reside. A repository may contain more java packages.
Servlet Zone
A set of servlet repositories that share common configuration parameters. Servlets with same full name are not allowed in the same zone, but they are allowed if they are contained by different servlet zones.

Sides

AJ is composed by two sides: client side and server side. They are also referred to as C side and Java side when more precise definition may generate misunderstandings.

Client side is responsible of making requests to the server side and waiting for a response, while server side handles the client requests, executes the requested servlets and sends back the generated response.

Client Side

Let us suppose that we have these web server configurations (and others that are not important in this context):

ServerName java.apache.org ApJServMount /servlets ajpv11://localhost:8007/root ApJServMount /servlets/admin ajpv11://jserv.apache.org:9009/admin ApJServAction .jhtml /org.apache.jserv.servlets.JServSSI

Now we analyze the behavior of different URLs requested to the web server:

http://java.apache.org/servlets/HelloWorldServlet
This URL gets parsed by the web server and passed to mod_jserv, that opens a connection to localhost on port 8007 using AJP version 1.1 (that currently is the only one supported, but other versions of the protocol will be implemented in the future), authenticates the connection, requests the servlet HelloWorldServlet on servlet zone root and waits for a response. When the response arrives, it is encapsulated with the right http headers (based on web server information and response information) and sent to the http client.

http://java.apache.org/servlets/admin/HelloWorldServlet
This URL is passed to mod_jserv but the connection is now open on port 9009 of a host named jserv.apache.org, using AJP version 1.1 and following the above path.

http://java.apache.org/servlets/admin.HelloWorldServlet
This URL is exactly equivalent to the one above.

http://java.apache.org/servlets/apache/HelloWorldServlet
This URL follows the same path as the one above, but the servlet requested is now apache.HelloWorldServlet, since directories are dot-formatted by the module if not recognized as mount points.

http://java.apache.org/servlets/admin.HelloWorldServlet.class
This URL looks for a servlet with full name admin.HelloWorldServlet.class, so that the name of the source file should have been class.java. This is why .class extension should be removed from the servlet URL requested.

http://java.apache.org/apache/HelloWorld.jhtml
This URL is passed to the .jhtml handler that actually is a servlet. So it is passed again to mod_jserv that requests the servlet org.apache.jserv.servlets.JServSSI on the protocol://host:port/zone defined for that mount point. Note that this class is always found by the servlet engine class loader because it resides on the class path (or, at least, it should).

For deeper understandings of the request/response process, please, refer to the protocol specifications for more details.

Server Side

When AJ is started (either automatically or manually), a .properties file (usually named jserv.properties) is passed to the org.apache.jserv.JServ class as a command line parameter. This file specifies the configuration parameters needed by AJ to start. They include the port, the servlet zones with their configuration files, and security parameters. Also, a fine grain tracing capability is included for both debugging and logging purposes.

After parsing these configurations, servlet zones are loaded constructing an org.apache.jserv.JServServletManager class for each servlet zone, and the server bounds to the configured port, listening for connections.

When a connection is requested to its port, AJ filters the incoming connection closing it if it does not come from an allowed IP address. This is used against denial of service attacks. If the address is allowed, the connection is authenticated (see authentication on AJPv1.1). If authentication is successful, a new org.apache.jserv.JServConnection is constructed to handle the request process and, since it extends Runnable, it is passed to a thread for multithreading serving behavior. This allows AJ to the able to handle many concurrent simultaneous requests.

The JServConnection class receives the request parameters, then calls the right JServServletManager (specified by the request servlet zone) and obtains the requested servlet. Then, it sets up the environment for execution and calls the servlet's service() method. JServConnection, together with JServContext and JServSession, provide all the hooks to the Servlet APIs methods needed by the servlet to execute. JServConnection also encapsulates servlet input and output streams.

When servlet service() method is over and all output data has been passed to the client, JServConnection closes the socket connection, indicating the termination of the request process. Returning from its run() method causes both the thread and the class itself to be garbage collectable.