Inside Tomcat: Unveiling Its Architecture, Lifecycle, and Connector Mechanics

Tomcat Overview

Tomcat is an open‑source Java web application server that implements the Servlet, JSP, JSTL and WebSocket specifications of Java EE. It acts as a lightweight servlet container, often used together with frameworks such as Spring to provide additional services.

Core Architecture

Server : The top‑level component that holds one or more Service instances and listens on the shutdown port (default 8005) to stop the whole container.

Service : Groups a Connector and a Container. Each Service runs independently but shares the same JVM.

Connector : Handles communication with the outside world (HTTP, AJP). It receives raw requests, creates Tomcat Request / Response objects and forwards them to the container pipeline.

Container (Catalina) : The servlet container that manages the lifecycle of servlets, filters, listeners and other web components.

Container Hierarchy

Engine : The top‑level Container that can host multiple Host elements.

Host : Represents a virtual host; each host has its own appBase directory where web applications are deployed.

Context : The web‑application context. It contains a set of Wrapper objects, each wrapping a single servlet.

Wrapper : Wraps a servlet instance, handling its creation, execution and destruction.

Loader : Encapsulates a Java ClassLoader used to load classes for the web application.

Realm : Provides authentication and role‑based access control for the application.

JMX : Exposes management beans so that Tomcat can be monitored and controlled remotely.

Jasper : The JSP compilation engine that translates JSP pages into servlet classes.

Session : Manages HTTP sessions, supporting persistence and clustering.

Pipeline and Valve : Implement a chain of request/response processing steps; each Valve can modify or short‑circuit the request.

Lifecycle Management

Every Tomcat component implements the Lifecycle interface, which defines twelve states (e.g., NEW, INITIALIZING, STARTED, STOPPED, DESTROYED). Concrete components override initInternal(), startInternal(), stopInternal() and destroyInternal() to perform work when the state changes. Listeners configured in server.xml receive LifecycleEvent notifications and can react accordingly.

Web Application Deployment

Deployment is driven by server.xml:

Host element defines appBase (default $catalina.base/webapps/).

Context element defines docBase for each web app.

During startup, HostConfig scans the appBase for directories and WAR files, parses each META-INF/context.xml, creates a StandardContext and attaches it to the corresponding Host. Configuration files are processed in a deterministic order: global config/context.xml, host‑level defaults, then application‑level context.xml. The same ordering applies to web.xml and any web-fragment.xml files found in WEB-INF/lib.

Servlet Lifecycle

Request arrives and is mapped to a servlet.

If the servlet instance does not exist, Tomcat instantiates it and calls init().

Tomcat creates Request and Response objects and invokes the servlet’s service() method. service() delegates to doGet, doPost, etc., where business logic runs.

When the servlet is no longer needed, destroy() is called.

The load-on-startup attribute (positive integer) forces early instantiation; a negative value or omission defers creation until the first request. The deprecated singleThreadModel is discouraged because it does not guarantee thread safety.

JSP Engine (Jasper)

JSP pages are compiled into servlet classes by Jasper. The JSP lifecycle consists of compilation, initialization, execution and destruction. JSP elements include:

Scriptlet <% … %> Declaration <%! … %> Expression <%= … %> Directive <%@ … %> Implicit objects such as request, response, session, out, etc.

Connector Implementations

Tomcat supports three connector types, selectable in server.xml:

BIO (JIO) : Blocking I/O based on java.io. Each request occupies a thread for the entire duration.

NIO : Non‑blocking I/O using java.nio with a selector‑based event loop, allowing a small thread pool to handle many connections.

APR : Uses the Apache Portable Runtime via JNI, providing native I/O features such as sendfile, epoll and OpenSSL for high‑performance networking.

Key connector parameters include support for polling, maximum poll size, request header parsing, request body handling and response writing.

NIO Processing Classes

Acceptor : Accepts new socket connections and registers them with a PollerEvent.

Poller : Retrieves events from the queue, creates Http11NioProcessor instances and hands them to a worker thread pool.

CoyoteAdapter : Adapts the low‑level connector request to the Tomcat container pipeline.

Mapper : Resolves URL‑to‑servlet mappings.

Comet (Server‑Push) Support

Before WebSocket, Tomcat provided server‑push via the Comet API. A servlet implements CometProcessor and receives events: begin: Connection established; response can be stored for later writes. read: Data is available to read. end: Stream closed or client disconnected. error: I/O error, timeout or other failure.

Implementations must ensure thread‑safety and close the CometEvent when end or error occurs.

Asynchronous Servlet Support

Async servlets allow the container thread to be released while the request remains open. Typical flow:

Client sends request.

Servlet calls request.startAsync() and returns.

An application thread (e.g., from a thread pool) performs business logic using the saved AsyncContext.

When processing finishes, asyncContext.complete() sends the response.

Async listeners ( onStartAsync, onComplete, onError, onTimeout) provide hooks for lifecycle events. After onComplete the request/response objects must not be accessed.

Pipeline and Valve Mechanism

Each Container has a Pipeline that holds a chain of Valve objects. The last valve in the chain is the basic valve , which ultimately invokes the next container (e.g., from Engine to Host to Context to Wrapper). Valves can modify the request, perform authentication, logging, compression, etc., and decide whether to pass control to the next valve.

Key Configuration Files

server.xml

: Defines Server, Service, Connector, Engine and Host elements. context.xml (global, host‑level, application‑level): Configures Context attributes, resources, JNDI entries. web.xml and web-fragment.xml: Declare servlets, filters, listeners, security constraints and other web components.

During startup, EngineConfig logs start/stop events, HostConfig scans appBase and creates StandardContext objects, and ContextConfig merges the various web.xml files and processes annotations.

Reference

Original article: https://juejin.cn/post/6844903473482317837