Unlocking Tomcat: Inside the Java Servlet Container Architecture and Lifecycle

Tomcat is an open‑source Java web application server that implements part of the Java EE specifications, including Servlets, JSP, JSTL, and WebSocket. It provides the essential Java Web container, while other Java EE features (EJB, JPA, JMS, etc.) require additional implementations.

The most common setup uses Tomcat as the web server together with Spring and other open‑source libraries to deliver business functionality.

Servlet Container

Tomcat composition : The server consists of Server , Service , Connector , and Container components.

Server manages multiple services, starts them, and listens on the shutdown port (default 8005) to stop the whole container.

Service groups a set of connectors and a container, sharing the same JVM resources while remaining independent.

Connector links Tomcat to the outside world, listening on a fixed port, receiving requests, passing them to the container, and returning the processed response.

Container (Catalina) is the servlet container that manages the servlet lifecycle and invokes servlet methods.

Other internal components include Loader (class loading), Realm (authentication and role management), JMX (monitoring), Jasper (JSP engine), Pipeline (valve chain), and Naming (JNDI support).

Container hierarchy : Engine (top‑level), Host (virtual host), Context (web application), Wrapper (individual servlet).

Lifecycle management : Tomcat defines twelve states (New, Initializing, Initialized, Started, etc.) and invokes corresponding methods (initInternal, startInternal, stopInternal, destroyInternal) as components transition.

Configuration is performed by adding listeners (e.g., EngineConfig, HostConfig, ContextConfig) in server.xml and related XML files.

JSP Engine

The JSP lifecycle consists of compilation, initialization, execution, and destruction phases, with JSP elements such as scriptlets, declarations, expressions, directives, actions, and implicit objects (request, response, session, etc.).

Connector

Tomcat supports three connector implementations: BIO (blocking I/O), NIO (non‑blocking I/O with selector‑based multiplexing), and APR (native I/O via Apache Portable Runtime). Each can be selected in server.xml.

Connector parameters include support for polling, maximum connections, request header/body handling, and response writing.

NIO Processing

An Acceptor thread accepts connections and creates PollerEvent objects; a Poller thread processes events using a Selector, creating Http11NioProcessor instances that delegate to the CoyoteAdapter and the container pipeline.

List<Future<Void>> results = new ArrayList<Future<Void>>();
for (int i = 0; i < children.length; i++) {
    results.add(startStopExecutor.submit(new StartChild(children[i])));
}
bool fail = false;
for (Future<Void> result : results) {
    try {
        result.get();
    } catch (Exception e) {
        log.error(sm.getString("containerBase.threadedStartFailed"), e);
        fail = true;
    }
}

Comet

Comet is a server‑push technique that enables real‑time data delivery before WebSocket existed. Tomcat implements Comet by having a servlet implement the CometProcessor interface, handling events such as Begin, Read, End, and Error.

Asynchronous Servlet

Traditional servlet processing blocks the request thread until the response is generated. Asynchronous servlets allow the request thread to be released after calling request.startAsync(), while the response remains open and is completed later by a separate thread.

Async events include onStartAsync , onComplete , onError , and onTimeout . After onError or onTimeout , onComplete is invoked, after which the request and response objects must no longer be used.