Servlets and Tomcat

The Jakarta Servlet API defines a server-side request and response model. Apache Tomcat implements that API and supplies the Catalina servlet container, HTTP and AJP connectors, session management, deployment, and operational tooling. Tomcat 11 implements Jakarta Servlet 6.1 and requires Java 17; older applications that import javax.servlet.* need migration to the jakarta.servlet.* namespace or an older compatible container.

Web Application Layout #

A deployable web application can be an expanded directory or a WAR archive:

orders.war
|-- index.html
`-- WEB-INF
    |-- web.xml
    |-- classes/com/example/OrdersServlet.class
    `-- lib/orders-domain.jar

Resources below WEB-INF/ are not directly addressable by clients. WEB-INF/classes/ contains application classes and resources, while WEB-INF/lib/ contains dependency JARs. WEB-INF/web.xml is the deployment descriptor. Servlet 3.0 and later also support annotation-based registration and programmatic registration through ServletContainerInitializer, so web.xml can be absent unless deployment requires descriptor metadata or ordering.

Mapping and Request Dispatch #

A servlet mapping selects a servlet from a URL pattern. Exact mappings win over the longest path mapping, followed by extension mappings and the default / mapping. A filter can wrap requests and responses before or after the target, and listeners observe context, session, and request lifecycle events.

Dispatches have distinct DispatcherType values:

• REQUEST represents the original container dispatch.
• FORWARD transfers processing without a client round trip.
• INCLUDE inserts another resource’s output.
• ERROR invokes configured error handling.
• ASYNC continues an asynchronous request.

request.getRequestDispatcher("/WEB-INF/views/order.jsp")
       .forward(request, response);

A redirect instead sends a 3xx response, after which the client starts a new request. During a normal dispatch, the connector parses the request, Catalina selects the virtual host and web context, the filter chain runs, and one servlet instance handles the call. Containers call a servlet concurrently; mutable instance fields therefore require synchronization or, preferably, elimination.

Sessions are identified by a cookie or URL rewriting. Session attributes may be accessed by concurrent requests and must not be treated as thread-confined. Async processing releases the request thread, but the application must complete the AsyncContext and preserve any required security or logging context.

Tomcat’s Container Model #

org.apache.catalina.startup.Bootstrap starts a standalone installation. catalina.home points to the shared Tomcat binaries, while catalina.base points to an instance’s configuration, logs, temporary files, work directory, and deployed applications. Multiple instances can thus share one installation.

Catalina composes these elements:

1. A Server owns the Tomcat instance.
2. A Service associates one or more Connectors with one Engine.
3. An Engine routes requests to a Host.
4. A Host contains one or more web application Contexts.
5. A Wrapper represents an individual servlet.

Connectors own protocol processing and worker threads. Blocking servlet work occupies those threads, so connector limits, downstream timeouts, and application executor limits must form one capacity plan.

Class Loaders and Shutdown #

Tomcat separates bootstrap, system, common, and per-web-application class loaders. A web application sees its own WEB-INF/classes and WEB-INF/lib but not another application’s classes. Tomcat’s web loader uses local-first lookup for application classes, with mandatory delegation for Java, Jakarta Servlet, and container implementation APIs. Duplicate API JARs in WEB-INF/lib do not override container APIs and can cause linkage failures.

For graceful shutdown, stop accepting new traffic, allow in-flight work to finish within a deadline, and then stop the Server. Servlet context listeners and managed resources receive shutdown callbacks, but application-created executors and threads still need explicit termination. Session persistence depends on the configured manager and must not be assumed across a restart.

Primary References #

• Jakarta Servlet 6.1 specification
• Tomcat 11 architecture
• Tomcat class-loader documentation