Tomcat Words Explained: Catalina, Coyote, Connector, Context, Valve, Poller

October 1, 2026 · How It Actually Works: Real Systems as State Machines (part 4)

▶ Watch on YouTube & subscribe to The Stack Underflow

The Tomcat state-machine video labels its boxes with words like Catalina, Coyote, Engine, Context, Valve and Poller. This primer explains each one first, with one running example: bookstore.war, deployed at /bookstore, and a browser asking it for book 42 on port 8080.

The one-line version: Coyote speaks HTTP, Catalina runs servlets, and everything in between is a box inside a box: Server, Service, Engine, Host, Context, Wrapper.

Last verified against the Apache Tomcat 11.0 documentation (version 11.0.26): 1 October 2026. Scope: Apache Tomcat 11, which implements Jakarta Servlet 6.1. Every claim links to its source at the bottom of the page.

One picture: Tomcat is a hotel

Every word gets a memory peg from one picture. The pegs are an analogy, a teaching aid, not a technical claim; where one breaks, the table says so. Your web apps are the tenants, and requests are the guests. The pegs chain the way Tomcat nests: the whole building, a wing, the entrance, the operations team, the street address, one tenant business, one service counter.

What Tomcat is

Starting Tomcat: folders, files, first objects

The container tree

This nesting is the most important picture in the deep-dive video.

Engine, Host, Context and Wrapper are containers. A Connector is not; it hands requests to one.

One request: GET /bookstore/books/42

1. The browser opens a TCP connection to port 8080. On the default NIO connector, an Acceptor thread (peg: the doorman) accepts it and registers it with the Poller (peg: the concierge), which watches many open connections with one Java NIO selector instead of a thread per connection.
2. When the request bytes arrive, the socket is processed on a worker thread (peg: the staff), from the connector’s private internal pool or a shared Executor.
3. Coyote parses the request, and the CoyoteAdapter hands it to Catalina. Tomcat’s own docs describe this path: requests “start processing in an endpoint, then get passed to the protocol and then the Coyote adapter which is the common entry point for all servlet request processing.”
4. The Mapper picks Host localhost, Context /bookstore, and the Wrapper for BookServlet.
5. Each container has one Pipeline of Valves (peg: the corridor checkpoints; the AccessLogValve is the visitor log). The last, basic Valve of each level passes the request down a level.
6. The Wrapper’s valve builds the filter chain (peg: the tenant’s front-desk check). Filters are application code that can inspect or change the request before the servlet and the response after it. Then BookServlet writes book 42.

Valves belong to Tomcat; filters belong to your app. A Valve sits in the pipeline of an Engine, Host or Context and is configured in Tomcat’s configuration; a filter is part of the Servlet API and ships inside your WAR.

The three capacity numbers

Where the peg breaks: the queue outside is kept by the operating system, not by Tomcat, and the docs add that “the operating system may ignore this setting and use a different size for the queue.” Guests inside may also be idle keep-alive connections waiting in the Poller, not requests being served.

Starting and stopping

• Listener (peg: the tenant’s opening routine): a ServletContextListener is told when the web app starts and stops.
• load-on-startup (peg: ready before opening): at deploy, the Servlet specification’s order is listeners’ contextInitialized(), then each filter’s init(), then servlets marked load-on-startup in the order of their values. Other servlets are initialized lazily, on their first request.
• Lifecycle states (peg: the opening and closing procedure): every component from the Server down to each Wrapper follows the same twelve states: NEW, INITIALIZING, INITIALIZED, STARTING_PREP, STARTING, STARTED, STOPPING_PREP, STOPPING, STOPPED, DESTROYING, DESTROYED and FAILED. “Any state can transition to FAILED”, and FAILED is not always the end: stop() moves a failed component on to STOPPING and STOPPED.

Pause & Prove

1. All 200 worker threads are busy and 8192 connections are open on a default connector. Where does the next new connection wait, and how many can wait there?

• Waiting for a free worker thread. Tempting: work on connections Tomcat has already accepted can wait for a thread. But a brand-new connection must be accepted first, and maxConnections is reached.
• Inside the Poller. Connections already accepted wait there; this one hasn’t been accepted, because maxConnections is reached.
• In the operating system’s queue, up to acceptCount, 100 by default. ✓ maxThreads 200 is the staff, maxConnections 8192 the guests inside, acceptCount the queue outside (and the OS may use a different size).
• Nowhere: it is refused immediately. Only once the OS queue is full too may new connections be refused or time out.

2. Which part of Tomcat speaks HTTP on the network side? (Community poll)

• Catalina. The servlet container: it runs servlets, after the protocol work is done.
• Coyote. ✓ Tomcat’s connector code: HTTP/1.1, HTTP/2 and AJP.
• Jasper. The JSP engine, which compiles JSP pages into servlets.
• A Valve. Tomcat’s own per-container step in a Pipeline, after the request has already been parsed.

3. Peg drill

Say the peg for each before reading on: Coyote, Context, Poller, server.xml, Wrapper.

Answers: Coyote is the reception desk. A Context is one tenant business. The Poller is the concierge. server.xml is the building’s floor plan. A Wrapper is one service counter. The chain, building to counter, is Server, Connector, Engine, Host, Context, Wrapper.

Before / after this video

• Before: Backend words: port, socket, reverse proxy, JVM, pod, SIGTERM
• After: What Apache Tomcat actually does with your request, the deep dive that uses every word on this page.

Sources

Checked on 1 October 2026 (Tomcat docs version 11.0.26, dated 9 Sep 2026), plus the video’s own verified sources:

• Which version do I want?: Tomcat 11.0.x implements Servlet 6.1, JSP 4.0, EL 6.0, WebSocket 2.2, Authentication 3.1; 11.0.26 is the latest release
• HTTP Connector: NIO default, maxThreads, maxConnections, acceptCount defaults and meaning, acceptor and poller, private internal executor
• Architecture overview: Server, Service, Engine, Host, Connector, Context
• Request processing: endpoint, protocol, Coyote adapter
• The Server component: Catalina servlet container, shutdown port and command
• The Engine container and the Host container: one Engine per Service, appBase, deployOnStartup
• The Context container: web application, WAR, context path from file name, longest-prefix match, context.xml locations
• The Valve component: Valves in the Engine, Host or Context pipeline; AccessLogValve
• Class loader how-to: Bootstrap, System, Common, per-webapp loaders and search order
• Introduction: CATALINA_HOME, CATALINA_BASE, server.xml, Context
• Lifecycle (Javadoc): the twelve states, “any state can transition to FAILED”, FAILED to STOPPING on stop()
• Jakarta Servlet 6.1 specification: servlet container, filters, deployment order (listeners, filters, load-on-startup servlets); checked for the video on 29 September 2026
• Jasper how-to: Jasper 2, Jakarta Pages 4.0, JspServlet; checked for the video on 29 September 2026

Change notes

• 1 Oct 2026: first published. Added two details from the HTTP Connector page that the video doesn’t spell out: the operating system may use a different queue size than acceptCount, and maxThreads is ignored when a shared Executor is used.

Not affiliated with or endorsed by the Apache Software Foundation. Apache Tomcat is a trademark of the ASF. Found a mistake? Tell us in the video’s comments and we’ll correct this page.