Tomcat Architecture Principles and Design Insights

Tomcat has matured into a stable HTTP server and servlet container, but understanding its internal architecture remains valuable for improving system design skills.

At a macro level, Tomcat functions as an Http server plus a Servlet container, exposing Request and Response objects while delegating business logic to frameworks such as Spring MVC.

Internally, Tomcat separates changeable and invariant parts using componentization: a Connector (the external communication point) and a Container (the internal processing engine). The connector consists of three core sub‑components— Endpoint , Processor , and Adapter —which handle socket I/O, protocol parsing, and adaptation to the servlet API respectively.

The Endpoint abstracts socket handling (NIO, NIO2, APR) and works with an Acceptor and SocketProcessor that are scheduled on a thread pool. The Processor creates Tomcat‑specific request/response objects and forwards them to the Adapter , which converts them to standard ServletRequest / ServletResponse and invokes the servlet pipeline.

Tomcat’s container hierarchy follows a composite pattern: Server → Service → Engine → Host → Context → Wrapper . Each level implements the Container interface and inherits a Lifecycle that defines init() , start() , stop() , and destroy() methods. The lifecycle is managed by a template‑method implementation in LifecycleBase , while events are dispatched via an observer pattern.

Request routing is performed by the Mapper , which maps URLs to the appropriate Wrapper (Servlet) based on host, context, and servlet mappings.

Tomcat also customizes class loading to isolate web applications. The WebAppClassLoader breaks the parent‑delegation model by first attempting to load classes from the web app, then delegating to the extension class loader to protect core JRE classes, and finally to the system class loader. A SharedClassLoader enables sharing of common libraries, while a separate CatalinaClassLoader isolates Tomcat’s own classes.

Hot‑reloading is achieved by a background processor that periodically invokes backgroundProcess() on containers, destroying and recreating contexts, listeners, filters, pipelines, and class loaders as needed.

The article concludes with practical advice on reading source code, emphasizing a top‑down approach, focusing on change points versus stable points, and applying design patterns such as chain‑of‑responsibility, template method, and strategy in real‑world projects.