Unlock Tomcat’s Secrets: A Deep Dive into Its Architecture, Design Patterns, and Class Loading

Why Study Tomcat?

Tomcat has become a classic, mature Java web server. Even in an era of rapid innovation, understanding its design helps developers improve their "inner skills" by learning how seasoned engineers structure middleware systems.

Learning Objectives

Master Tomcat Architecture and Principles

Tomcat acts as an Http server + Servlet container, shielding application code from low‑level network details. It provides standard Request and Response objects, while frameworks like Spring MVC handle business logic without dealing with TCP or HTTP processing.

From Macro to Micro

At a high level, Tomcat isolates change points (e.g., specific protocols) from stable components using component‑based design. It employs the Template Method pattern to define a fixed processing skeleton while allowing subclasses to implement protocol‑specific behavior.

Overall Architecture Design

Tomcat’s startup sequence is:

startup.sh -> catalina.sh start -> java -jar org.apache.catalina.startup.Bootstrap.main()

Two core functions are provided by the connector:

Handle Socket connections and convert byte streams into Request and Response objects.

Load and manage Servlet instances, delegating the request to them.

The connector creates two main components: Connector (external communication) and Container (internal processing).

Connector Details

The connector supports multiple I/O models (NIO, NIO2, APR) and application‑layer protocols (HTTP/1.1, AJP, HTTP/2). A Service may have several Connector s, each linked to a Container .

Key sub‑modules: EndPoint: low‑level socket listener (e.g., NioEndpoint, Nio2Endpoint) with Acceptor and SocketProcessor. Processor: parses protocol data, creates Tomcat Request / Response, and passes them to the Adapter. Adapter (CoyoteAdapter): converts Tomcat’s internal request/response objects to standard ServletRequest / ServletResponse and invokes the servlet container.

The processing flow is:

Acceptor listens on a port and accepts new connections.

Accepted sockets are handed to a Poller (a Selector) that detects readable channels.

Readable channels generate SocketProcessor tasks submitted to a thread pool ( Executor). SocketProcessor invokes the appropriate Http11Processor, which creates a ServletRequest and calls the container.

Container Hierarchy

Tomcat uses a four‑level container tree: Engine – top‑level request dispatcher. Host – virtual host (site). Context – a web application. Wrapper – a single servlet.

Each container implements the Container interface, forming a composite structure (Composite pattern). The Lifecycle interface defines init(), start(), stop(), and destroy() methods, enabling one‑click start/stop via the Template Method pattern.

Request Routing

The Mapper component maps a request URL to the appropriate Wrapper (servlet) by examining the Host, Context, and servlet mappings stored in a hierarchical map.

Pipeline‑Valve Chain

Tomcat processes a request through a chain of Valve s (Tomcat‑specific) using the Pipeline‑Valve mechanism, which is a form of the Chain of Responsibility pattern. Valves operate at the container level, while standard Servlet Filter s operate at the application level.

Lifecycle Management

All containers inherit from LifecycleBase, which implements the observer pattern: listeners receive events such as BEFORE_INIT_EVENT, AFTER_START_EVENT, etc. This decouples lifecycle handling from component logic.

Class Loading Strategy

Tomcat breaks the parent‑delegation model with a custom WebAppClassLoader:

It first attempts to load classes from the web application’s /WEB‑INF/classes and /WEB‑INF/lib.

If not found, it delegates to the parent (the system class loader) but only after checking the ExtClassLoader to protect core JRE classes.

Three class‑loader tiers are used: CatalinaClassLoader – loads Tomcat’s own classes (isolated from web apps). SharedClassLoader – parent of each WebAppClassLoader, holds libraries shared across web applications. CommonClassLoader – parent of both CatalinaClassLoader and SharedClassLoader, loads libraries common to Tomcat and all apps.

This hierarchy ensures web‑app isolation, shared library reuse, and prevents web apps from overriding JRE core classes.

Hot Reload

Tomcat’s ContainerBackgroundProcessor periodically invokes backgroundProcess() on each container. Reloading a Context stops and destroys the old servlet instances, listeners, filters, pipelines, and its class loader, then creates a fresh class loader and re‑initializes the context.

How to Read Source Code Effectively

Adopt a macro‑first approach: understand the overall architecture, identify the main flow, and then drill down into specific modules. Use breakpoints to observe call stacks, focus on a single “core process”, and avoid getting lost in low‑level details unless you need to extend the code.

Practical Applications of Tomcat Design Patterns

Examples include implementing a responsibility‑chain for modular validation, using the Template Method for a financial‑analysis workflow, and applying the Strategy pattern to handle various bank‑statement formats. These patterns mirror Tomcat’s own use of Composite, Observer, Template Method, and Strategy, providing reusable blueprints for enterprise projects.

Embedded Tomcat debugging source: GitHub