Inside Tomcat: Architecture, Connectors, Containers, and Class Loaders Explained

Tomcat Startup

Tomcat is started by executing startup.sh → catalina.sh start → Java class org.apache.catalina.startup.Bootstrap. The bootstrap creates a Server component that contains a Service, which holds one or more Connector objects and a single Container (the Engine).

Core Components

Connector

The connector bridges external network communication and the internal servlet container. It consists of three sub‑components:

Endpoint – listens on a TCP port, accepts raw Socket connections and hands a Channel to a Poller.

Processor – parses the byte stream according to the configured protocol (HTTP/1.1, AJP, HTTP/2) and creates Tomcat’s internal Request and Response objects.

Adapter (CoyoteAdapter) – converts the internal Request / Response to the standard ServletRequest / ServletResponse and invokes the container pipeline.

Supported I/O models are NIO (non‑blocking java.nio), NIO2 (asynchronous channels introduced in JDK 7) and APR (native C/C++ library based on Apache Portable Runtime). Each protocol is implemented by a subclass of AbstractProtocol (e.g. AbstractHttp11Protocol, AbstractAjpProtocol).

connector.getService().getContainer()
        .getPipeline().getFirst().invoke(request, response);

Container Hierarchy

Tomcat’s servlet container is a tree of four component types that implement the Container interface and inherit the Lifecycle interface: Engine – top‑level container for a Tomcat instance. Host – represents a virtual host (domain). Context – a single web application. Wrapper – a specific servlet instance.

The composite pattern allows code to treat a single Wrapper and an entire subtree uniformly. Requests are routed by a Mapper that matches the request URL to a Host, then a Context, and finally the Wrapper defined in web.xml.

Pipeline‑Valve Chain

Each container owns a Pipeline of Valve objects. A Valve processes the request and then calls getNext().invoke(). The last valve ( BasicValve) forwards the request to the child container’s pipeline, forming a recursive chain of responsibility.

public interface Valve {
    Valve getNext();
    void setNext(Valve valve);
    void invoke(Request request, Response response);
}
public interface Pipeline {
    void addValve(Valve valve);
    Valve getBasic();
    void setBasic(Valve valve);
    Valve getFirst();
}

Lifecycle Management

All containers implement Lifecycle with methods init(), start(), stop(), and destroy(). The abstract class LifecycleBase provides a template‑method implementation that handles state transitions, event firing and listener notification (observer pattern). This enables uniform start‑up and shutdown by invoking init() and start() on the top‑level Server component.

public abstract class LifecycleBase implements Lifecycle {
    // fireLifecycleEvent, init(), start() etc.
}

Class Loader Architecture

Tomcat isolates each web application with a dedicated WebAppClassLoader. The loader follows a “parent‑last” strategy: it first attempts to load classes from /WEB-INF/classes and /WEB-INF/lib, then delegates to its parent. This prevents a web app from overriding JRE core classes.

Three class‑loader tiers are used:

WebAppClassLoader – one instance per Context, loads the web‑app classes.

SharedClassLoader – parent of all WebAppClassLoader instances, holds libraries shared across applications.

CatalinaClassLoader – loads Tomcat’s own classes; its parent is CommonClassLoader, which loads libraries common to both Tomcat and web apps.

The WebAppClassLoader overrides findClass and loadClass to implement the parent‑last lookup and to consult the ExtClassLoader first, ensuring that JRE core classes are never shadowed.

public Class<?> findClass(String name) throws ClassNotFoundException {
    Class<?> clazz = findClassInternal(name); // web‑app
    if (clazz == null) {
        clazz = super.findClass(name); // parent
        if (clazz == null) throw new ClassNotFoundException(name);
    }
    return clazz;
}

Hot Reload

Each Context runs a background thread ( ContainerBackgroundProcessor) that periodically calls backgroundProcess() on itself and its children. Reloading a context performs the following steps:

Stop and destroy the existing Context and all child Wrapper instances.

Stop listeners and filters associated with the context.

Destroy the context’s pipeline and valves.

Dispose the context’s class loader, releasing all loaded classes.

Create a new class loader and re‑initialize the context.

Design Patterns Used in Tomcat

Composite – container hierarchy (Engine → Host → Context → Wrapper).

Template Method – LifecycleBase and protocol handlers.

Observer – lifecycle event listeners.

Adapter – CoyoteAdapter bridges Tomcat’s internal request model to the Servlet API.

Strategy – class‑loader selection (WebApp, Shared, Catalina).

Chain of Responsibility – pipeline‑valve mechanism.

Reference Implementation

Embedded Tomcat source for debugging: https://github.com/UniqueDong/tomcat-embedded