Inside Tomcat: How Java’s Popular Backend Server Works

What is Tomcat

Tomcat is an open‑source Java Web application server that implements part of the Java EE specifications, such as Servlet, JSP, JSTL and WebSocket. Java EE is a standard platform defined by Sun/Oracle for enterprise‑level development, including EJB, JavaMail, JPA, JTA, JMS and other specifications that require container implementations.

The diagram compares Java EE container implementations; Tomcat and Jetty provide only the Servlet and JSP specifications, so developers must add other open‑source libraries for additional functionality. GlassFish, released by Sun, is the reference implementation for the latest Java EE specifications.

Servlet Container

Server – the whole Tomcat instance, managing multiple Services and listening on the shutdown port.

Service – a complete web service exposing Connectors and a Container, independent of other Services but sharing the same JVM.

Connector – the bridge between Tomcat and the outside world, listening on a fixed port, passing requests to the Container and returning responses.

Container (Catalina) – the Servlet container, composed of multiple sub‑containers that manage the Servlet lifecycle.

Loader – wraps a Java ClassLoader to load classes for the Container.

Realm – provides authentication and role management for web applications.

JMX – a Java SE management framework that allows remote monitoring of Tomcat.

Jasper – the JSP engine that compiles JSP pages into Java classes.

Session – manages session creation, persistence and clustering.

Pipeline – a chain of Valves that process requests and responses in a configurable way.

Naming – JNDI support for resource lookup and configuration.

Container Composition

Engine – the top‑level container that can contain multiple Host sub‑containers.

Host – a virtual host that deploys web applications and creates Contexts.

Context – the web‑application context that contains multiple Wrappers and parses web configuration.

Wrapper – the lowest‑level container that wraps a Servlet, handling its creation, execution and destruction.

Lifecycle Management

Tomcat defines twelve lifecycle states from creation, start, stop to destroy. Components implement methods such as initInternal, startInternal, stopInternal, and destroyInternal to perform actions at each stage. For example, during initialization Tomcat checks whether the current state is New ; if not, it throws a lifecycle exception. If the state is New , it transitions to Initializing , invokes initInternal, and upon success moves to Initialized , otherwise to Failed .

Configuration Listeners

EngineConfig – logs startup and shutdown events.

HostConfig – processes deployment, parses META-INF/context.xml and creates Contexts.

ContextConfig – merges web.xml, scans for filters, servlets, listeners and other resources.

Tomcat Startup Process

The startup begins with the start.sh script, which calls the Bootstrap main method. Bootstrap loads and starts the Catalina component. The load method uses Digester to parse conf/server.xml, creates the container hierarchy, and sets properties. Then StandardServer invokes init and start, which initialize and start all Services, Engines, Hosts and Contexts. The server then listens on the shutdown port (default 8005) and, upon receiving a shutdown command, executes stop and destroy to cleanly terminate.

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

Web Application Deployment

Key directories: catalina.home (installation directory) and catalina.base (working directory, default user.dir). In server.xml, the Host element’s appBase defaults to $catalina.base/webapps/. The Context element’s docBase points to the web‑application location. Custom configurations can be placed under $catalina.base/EngineName/HostName/.

During startup, HostConfig scans the appBase directory for folders and WAR files, parses each META-INF/context.xml, creates a StandardContext, and adds it to the Host. It also parses any user‑provided Context XML files under the Engine/Host directory. ContextConfig then merges the global config/web.xml, the Host default web.xml.default, and the application’s META-INF/web.xml, finally scanning WEB-INF/lib for web‑fragment.xml files.

Servlet Lifecycle

The request arrives and the server maps the URL to a Servlet.

If the Servlet instance does not exist, it is loaded, instantiated and its init method is called.

The server creates Request and Response objects and invokes the Servlet’s service method, which delegates to the appropriate doXXX method based on the HTTP verb.

The doXXX method executes business logic, reads request parameters and writes the result to the response.

When the server shuts down or the Servlet is no longer needed, its destroy method is called.

load‑on‑startup

If the value is 0 or a positive integer, the container loads the Servlet at application startup; a negative value or omission means the Servlet is loaded on first request. Smaller positive numbers indicate higher loading priority.

single‑thread model

In this model a new Servlet instance is created for each request, but thread safety is not guaranteed and Tomcat limits the number of instances. Best practice is to avoid this model and keep Servlets stateless.

Request Processing

The Connector defined in server.xml listens on a port for HTTP or AJP requests.

When a request arrives, a connection is accepted, parameters are parsed, and Request / Response objects are created; the top‑level Pipeline’s first Valve is invoked.

Through a chain of Valves, the request eventually reaches the target Servlet’s service method.

The Connector writes the response data back to the socket.

Pipeline and Valve

A Pipeline is analogous to a physical pipe; Valves act as configurable gates. Each container’s Pipeline contains a mandatory basic Valve that is invoked last and forwards processing to the next Valve. Valves implement setNext, getNext and invoke, forming a singly‑linked chain. The basic Valves are StandardEngineValve, StandardHostValve, StandardContextValve and StandardWrapperValve.

JSP Engine

JSP pages are compiled into Servlets by the Jasper engine. The JSP lifecycle consists of compilation, initialization, execution, and destruction. JSP elements include scriptlets ( <% … %>), declarations ( <%! … %>), expressions ( <%= … %>), comments ( <%-- … --%>), directives ( <%@ … %>), actions ( <jsp:… />), standard HTML tags, and implicit objects such as request, response, out, session, application, config, pageContext, page and exception. During parsing, scriptlets and expressions are emitted directly in the generated _jspService() method, declarations are placed in the generated class, and directives affect compilation and runtime behavior.

Connector

Tomcat supports HTTP and AJP (Apache JServ Protocol) connectors. Connectors can operate in blocking I/O (BIO), non‑blocking I/O (NIO) or using the Apache Portable Runtime (APR). BIO uses java.io and blocks on read/write. NIO uses java.nio and leverages I/O multiplexing (selectors). APR is a native library accessed via JNI, providing high‑performance I/O features such as sendfile, epoll and OpenSSL.

Key connector characteristics include support for polling, maximum polling size, whether the thread releases while waiting for the next request, and whether request headers, request body and response writing are blocking.

NIO Processing Classes

Acceptor – a thread that accepts new connections, creates a PollerEvent with OP_READ and enqueues it.

Poller – takes PollerEvent from the queue, registers the socket with a Selector, and when readable creates an Http11NioProcessor to handle the request.

CoyoteAdapter – adapts the Connector to the Container, creating Request and Response objects and invoking the first Valve in the Pipeline.

Mapper – parses URL‑to‑Servlet mapping rules and provides the map method.

Comet

Comet is a server‑push technique that allows the server to push updates to the client without the client polling. In Tomcat, a Comet implementation extends HttpServlet and implements the CometProcessor interface, handling begin, read, end and error events.

Asynchronous Servlet

Traditional processing ties a request to a servlet thread for its entire lifetime. Asynchronous processing lets the servlet start asynchronous handling via request.startAsync(), release the servlet thread back to the pool while keeping the response open, and complete the response later from another thread using the saved AsyncContext. This improves scalability for long‑running operations such as slow database queries or external API calls.

Async event listeners include onStartAsync (when startAsync is called), onComplete (when complete is invoked), onError (on processing errors), and onTimeout (on socket timeout). After onError or onTimeout, onComplete is triggered, after which the request and response can no longer be used.

Original source: Juejin article