Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท Getting Started

How a Request Travels Through Tomcat

Follow an HTTP request through Tomcat: connector, engine, host, context, valves, filters and servlet. See the mapping steps and build a pipeline stand-in in Java.

When a browser asks for http://www.example.com:8080/shop/cart?id=3, a surprising number of Tomcat components touch that request before your servlet's doGet runs, and the response passes back through most of them. Knowing the path explains why a request is routed to one application and not another, where access logs are written, where security checks happen and why a certain error page appears.

This lesson follows one request from the network socket to your code and back. It closes the Getting Started chapter; the next chapter explains each component in detail.

The journey in one picture

flowchart TD
    A["Browser request"] --> B["Connector (Coyote)<br/>port 8080, parses HTTP"]
    B --> C["Engine (Catalina)<br/>pipeline of valves"]
    C --> D["Host: www.example.com<br/>chosen by the Host header"]
    D --> E["Context: /shop<br/>chosen by the path prefix"]
    E --> F["Wrapper: servlet<br/>chosen by the servlet mapping"]
    F --> G["Filters, then your servlet"]
    G --> H["Response travels back"]

Each box is a Java object in Tomcat. The arrows show the order of the calls.

Five routing decisions

Connector Which port and protocol
Host Which virtual host
Context Which web application
Servlet Which url-pattern matches

Each step narrows down where the request goes.

1 / 2

Step by step

  1. Accept. A connector listens on a port. An acceptor thread accepts the TCP connection and hands it to a worker thread from the connector's pool. Worker threads are named like http-nio-8080-exec-5.
  2. Parse. The worker reads the request line and headers, decodes the URL, and creates a Request and Response pair. For HTTPS the TLS handshake happens first.
  3. Engine and valves. The connector passes the request to its service's engine. Every container (engine, host, context, wrapper) has a pipeline of valves: small components that can inspect or change a request before it moves on, such as an access-log valve, a remote-IP valve or an error-report valve. The last valve in each pipeline is the "basic" valve that calls the next container down.
  4. Host selection. The engine picks a host by the Host header (www.example.com), falling back to its defaultHost if nothing matches (virtual hosts).
  5. Context selection. The host picks the web application whose context path is the longest prefix of the URL path: /shop/cart matches /shop rather than the root / application.
  6. Wrapper selection. Inside the context, the URL remainder (/cart) is matched against the servlet mappings with the rules in the Servlet specification (web.xml and URL mapping). A wrapper represents one servlet declaration.
  7. Security and filters. Security constraints are checked, then the filter chain runs in the declared order, and the last filter calls the servlet.
  8. Servlet. service calls doGet. You write to the response.
  9. Return. The response flows back through filters and valves (where the access log line is written), and the worker thread returns to the pool, waiting for the next request or keeping the connection alive.

A pipeline in code

The stand-in below mimics the valve idea: each valve receives the request and a next handler, can act before and after, and can stop the chain. It is simplified but follows the real pattern (Tomcat's Valve.invoke(request, response) calls getNext().invoke(...)).

Java A valve pipeline (stand-in for Tomcat's pipeline)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Notice that the access log valve wraps everything: it logs after next.run() returns, so it records the final status, including the 403 produced by a later valve. That is why the access log is the most reliable record of what really happened.

Routing in code

The next program performs the three routing decisions on a table of hosts, contexts and servlets, using the same rules Tomcat applies: host by name with a default, context by longest path prefix, servlet by exact then prefix then default.

Java Host, context and servlet routing (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Check the last line: the unknown host name fell back to the default host, which is exactly what defaultHost in server.xml does.

Why this matters in practice

  • A 404 from Tomcat's own error page (not your app's) usually means no context matched: the app did not deploy, or the context path is wrong.
  • A 404 from your app means the context matched but no servlet mapping did.
  • Slow requests are either waiting for a worker thread (all busy) or running inside your code; the thread pool lesson separates the two.
  • The access log is written by a valve, so you can place one at the engine, host or context level to capture different scopes.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What selects the virtual host inside the Engine?

    The engine compares the Host header with its hosts' names and aliases and uses defaultHost when nothing matches.
  2. 2. A request for /shop/cart/view arrives. Contexts /shop and / exist. Which context handles it?

    Tomcat picks the context whose path is the longest prefix of the request path.
  3. 3. What is a valve?

    Valves are Tomcat-specific pipeline stages (access log, remote IP, error report). Filters are the standard servlet equivalent inside one web app.
  4. 4. Why does the access log valve record the final status code?

    A logging valve calls the rest of the pipeline and then writes its line, so it sees the final response.
  5. 5. Where do worker threads such as http-nio-8080-exec-3 come from?

    Each connector hands accepted requests to threads from its executor. The name shows protocol, port and worker number.

Summary

  • A request passes connector, engine, host, context, wrapper, filters and your servlet; the response goes back the same way.
  • Host is chosen by the Host header, context by the longest path prefix, servlet by the mapping rules.
  • Valves are Tomcat pipeline stages; filters belong to your application.
  • The access log valve sees the final status because it wraps the rest of the pipeline.
  • Distinguishing a Tomcat 404 from an application 404 tells you whether routing or deployment failed.

Next: Installing Tomcat