Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/apache/tomcat/llms.txt

Use this file to discover all available pages before exploring further.

Apache Tomcat is an open-source web application server that provides a pure-Java implementation of the Jakarta Servlet, Jakarta Pages (JSP), Jakarta Expression Language (EL), and Jakarta WebSocket specifications. Maintained by the Apache Software Foundation, Tomcat powers numerous large-scale, mission-critical web applications across industries worldwide. Unlike a full Jakarta EE application server, Tomcat focuses on the servlet container layer — giving teams a lightweight, highly configurable runtime for deploying Java web applications without the overhead of a complete enterprise platform.

​
Component Architecture

Tomcat’s internal structure is organized as a strict containment hierarchy. Each level in the hierarchy is responsible for a narrower scope of request processing, from the top-level server process down to individual servlet wrappers. Understanding this hierarchy is essential for reading conf/server.xml and tuning Tomcat for production.
ComponentClassResponsibility
Serverorg.apache.catalina.core.StandardServerRepresents the entire Tomcat JVM process. Listens on a shutdown port (default 8005) and owns one or more Services.
Serviceorg.apache.catalina.core.StandardServiceGroups one or more Connectors with a single Engine. The default service is named Catalina.
Engineorg.apache.catalina.core.StandardEngineThe top-level servlet container inside a Service. Routes incoming requests to the correct Host based on the Host header.
Hostorg.apache.catalina.core.StandardHostRepresents a virtual host (e.g., localhost). Its appBase attribute (default webapps) is the directory scanned for web applications.
Contextorg.apache.catalina.core.StandardContextRepresents a single web application. Maps to a URL path (e.g., /myapp). Manages the web application’s classloader, servlet registrations, and lifecycle.
Wrapperorg.apache.catalina.core.StandardWrapperWraps an individual jakarta.servlet.Servlet instance inside a Context. Manages servlet initialization, invocation, and destruction.
The nested structure maps directly to the XML layout of conf/server.xml: 
<Server port="8005" shutdown="SHUTDOWN">          <!-- StandardServer  -->
  <Service name="Catalina">                        <!-- StandardService -->
    <Connector port="8080" protocol="HTTP/1.1" />  <!-- Coyote Connector -->

    <Engine name="Catalina" defaultHost="localhost"> <!-- StandardEngine -->
      <Host name="localhost" appBase="webapps"       <!-- StandardHost   -->
            unpackWARs="true" autoDeploy="true">
        <!-- Context elements (one per web app)      <!-- StandardContext -->
        <!-- Wrapper elements live inside Contexts   <!-- StandardWrapper -->
      </Host>
    </Engine>
  </Service>
</Server>
A Server is not a Container, and neither is a Service. Valves — pipeline components that intercept requests — can only be attached at the Engine, Host, Context, and Wrapper levels.

​
Catalina, Coyote, and Jasper

Tomcat is built from three distinct subsystems that collaborate on every request: Catalina is the servlet container engine at Tomcat’s core. The org.apache.catalina.startup.Catalina class parses conf/server.xml, constructs the component hierarchy, and manages the Server lifecycle. The entry point for all Tomcat startups is org.apache.catalina.startup.Bootstrap, which initializes the three-tier classloader hierarchy (common, server, shared) before handing off to Catalina. Coyote is the connector framework that handles network I/O. It provides HTTP/1.1, HTTP/2, and AJP protocol implementations. Each <Connector> element in server.xml corresponds to a Coyote endpoint. Coyote is responsible for accepting TCP connections, parsing raw HTTP bytes into Request objects, and writing Response objects back to the wire. It is completely decoupled from the servlet API — the org.apache.catalina.connector.CoyoteAdapter bridges Coyote’s protocol-level objects into Catalina’s HttpServletRequest/HttpServletResponse types. Jasper is Tomcat’s JSP engine. It compiles .jsp and .jspx source files into Java servlet classes at request time (or at deployment time if precompilation is configured). Jasper implements the Jakarta Pages specification and integrates with Catalina’s classloader so that recompiled JSPs are hot-reloaded without restarting the application.

​
The Lifecycle Model

Every major Tomcat component — Server, Service, Engine, Host, Context, Wrapper, and connectors — implements the org.apache.catalina.Lifecycle interface. This interface defines a uniform state machine and an event notification mechanism so that components can be started, stopped, and destroyed in a coordinated way. A component transitions through the following states in order: 
NEW → INITIALIZING → INITIALIZED → STARTING_PREP → STARTING → STARTED
                                                                    ↓
DESTROYED ← DESTROYING ← STOPPED ← STOPPING ← STOPPING_PREP ←────┘
Any state can transition to FAILED. Once in FAILED, the component may transition to STOPPING_PREP (via an explicit stop() call) for coordinated shutdown, or to DESTROYING (via destroy()) which then proceeds to DESTROYED. External code observes these transitions by registering a LifecycleListener: 
// Register a custom listener on the Server
server.addLifecycleListener(event -> {
    if (Lifecycle.START_EVENT.equals(event.getType())) {
        System.out.println("Server started: " + event.getSource());
    }
});
Tomcat’s own conf/server.xml ships with several built-in listeners attached to the <Server> element: 
<Listener className="org.apache.catalina.startup.VersionLoggerListener" />
<Listener className="org.apache.catalina.security.SecurityListener" />
<Listener className="org.apache.catalina.core.AprLifecycleListener" />
<Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener" />
<Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />
<Listener className="org.apache.catalina.core.ThreadLocalLeakPreventionListener" />

​
Key Specifications Supported

Tomcat implements the following Jakarta EE specifications. Each major Tomcat release targets a specific generation of these APIs:
SpecificationVersionDescription
Jakarta Servlet6.xCore request/response API, filters, and async processing for Java web applications
Jakarta Pages (JSP)4.xServer-side page templating compiled to servlets by the Jasper engine
Jakarta Expression Language (EL)6.xLightweight expression language used in JSP, JSF, and CDI contexts
Jakarta WebSocket2.2Full-duplex, bidirectional communication channel over a single TCP connection
Jakarta Authentication (JASPIC)3.xPluggable authentication module SPI for web and EJB security
Tomcat 10.x and later use the jakarta.* package namespace introduced with Jakarta EE 9. Applications built against the older javax.* namespace (Java EE 8 and earlier) must be migrated or run on Tomcat 9.x. The webapps-javaee directory in newer Tomcat releases provides a migration-assist path.

Quickstart

Download Tomcat, configure environment variables, and deploy your first web application in under five minutes.

Configuration Reference

Deep-dive into every element of conf/server.xml, including Connectors, Realms, Valves, and Executors.

Build docs developers (and LLMs) love

Get started for freeTalk to us