Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Architecture and Install

Catalina Architecture: Server, Service, Engine, Host, Context

Understand Tomcat's component hierarchy: Server, Service, Connector, Engine, Host, Context and Wrapper, how server.xml describes them, and parse a server.xml with Java.

Tomcat's configuration looks scary until you see that it is a tree. A Server contains Services; a Service has Connectors and one Engine; an Engine contains Hosts; a Host contains Contexts (your web apps); a Context contains Wrappers (servlets). Every element in conf/server.xml is one of these nodes, and almost everything you will ever configure belongs to exactly one level of the tree.

This lesson explains each level, shows a complete server.xml, and then parses a copy with Java's XML API to print the hierarchy, which is a good way to read a file you did not write.

The hierarchy

flowchart TD
    S["Server<br/>one per JVM, shutdown port 8005"] --> SV["Service 'Catalina'"]
    SV --> C1["Connector HTTP/1.1 :8080"]
    SV --> C2["Connector HTTPS :8443"]
    SV --> E["Engine 'Catalina'<br/>defaultHost=localhost"]
    E --> H1["Host 'localhost'<br/>appBase=webapps"]
    E --> H2["Host 'blog.test'<br/>appBase=webapps-blog"]
    H1 --> X1["Context /shop"]
    H1 --> X2["Context / (ROOT)"]
    X1 --> W1["Wrapper: CartServlet"]

Containers (Engine, Host, Context, Wrapper) hold your code's routing; connectors only receive traffic.

The component tree

Server The whole Tomcat JVM
Service Connectors + one Engine
Host A virtual host
Context One web application

Wrapper = one servlet inside a Context.

1 / 2

What each level means

  • Server (<Server port="8005" shutdown="SHUTDOWN">): represents the entire Tomcat instance, one per JVM. Its port accepts the shutdown command. It also holds global JNDI resources and listeners that react to the lifecycle (version logging, memory-leak prevention).
  • Service: groups one or more connectors with a single engine. Most installations have exactly one service called Catalina. A second service lets you run, for example, an entirely separate set of hosts on other ports.
  • Connector: protocol handler plus port. HTTP/1.1 with port 8080 is the default; add one for TLS, or AJP if a proxy needs it. You will tune them in connectors and thread pools.
  • Engine: the request-processing engine of the service. It chooses the host by name and has a defaultHost. Its name (Catalina) is also the folder name under conf/ and work/.
  • Host: a virtual host, bound to a DNS name, with an appBase directory where applications live and settings such as unpackWARs and autoDeploy (virtual hosts).
  • Context: one web application at one context path. Usually implied by files in appBase, optionally described in a context XML (context descriptors).
  • Wrapper: one servlet definition inside a context. You rarely configure wrappers directly; Tomcat creates them from web.xml.

Nested components

Containers can contain:

  • Valve: pipeline stage (AccessLogValve, RemoteIpValve, ErrorReportValve).
  • Realm: where user names, passwords and roles come from.
  • Manager: how HTTP sessions are stored (standard in-memory, persistent, clustered).
  • Resources, Loader, Cookie processor: how static resources and classes are found.
  • Listener and Executor belong to Server or Service, e.g. a shared thread pool.

A complete default-style server.xml

Trimmed from the shape of Tomcat's shipped file (read-only):

XML
<Server port="8005" shutdown="SHUTDOWN">
  <Listener className="org.apache.catalina.startup.VersionLoggerListener" />
  <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener" />

  <GlobalNamingResources>
    <Resource name="UserDatabase" auth="Container"
              type="org.apache.catalina.UserDatabase"
              factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
              pathname="conf/tomcat-users.xml" />
  </GlobalNamingResources>

  <Service name="Catalina">
    <Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000" redirectPort="8443" />

    <Engine name="Catalina" defaultHost="localhost">
      <Realm className="org.apache.catalina.realm.LockOutRealm">
        <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
               resourceName="UserDatabase"/>
      </Realm>

      <Host name="localhost" appBase="webapps"
            unpackWARs="true" autoDeploy="true">
        <Valve className="org.apache.catalina.valves.AccessLogValve"
               directory="logs" prefix="localhost_access_log" suffix=".txt"
               pattern="%h %l %u %t &quot;%r&quot; %s %b" />
      </Host>
    </Engine>
  </Service>
</Server>

Read it top-down: one Server; global resources; one Service named Catalina with a single HTTP connector on 8080; an Engine whose default host is localhost; one Host with an access-log valve.

Reading a server.xml with Java

The stand-in below parses the XML above (shortened, in a text block) with the JDK DOM parser and prints an indented hierarchy, annotating each element with its most telling attributes. It is the same idea as Tomcat's Digester, which turns server.xml into Java objects at startup.

Java Print the component tree of a server.xml (stand-in for Digester)

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.

Lifecycle: how the tree starts

Every component implements the Lifecycle interface with states such as NEW, INITIALIZED, STARTING, STARTED, STOPPING and DESTROYED. Starting the Server starts its Services; a Service starts its Engine first, then its connectors, so the engine is ready before traffic can arrive; the Engine starts its Hosts, which deploy their Contexts. Shutdown runs in reverse. This stand-in models that parent-before-child start and child-before-parent stop order:

Java Lifecycle order (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.

(In the real server the Engine starts before the connectors, a detail the toy tree leaves out.)

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which element is the direct parent of Connector elements?

    A Service contains one or more Connectors that share a single Engine.
  2. 2. What does the Engine's defaultHost attribute control?

    When no Host name or alias matches the request, the Engine routes it to defaultHost.
  3. 3. What is a Wrapper?

    Wrappers sit below Contexts and represent individual servlet definitions.
  4. 4. Which port does <Server port="8005"> configure?

    The Server port listens for the shutdown string. It should be reachable only from localhost.

Summary

  • Tomcat's configuration is a tree: Server, Service, Connector and Engine, then Host, Context and Wrapper.
  • Connectors receive traffic; containers route it; Valves, Realms and Managers attach to containers.
  • server.xml describes the top three levels; contexts usually come from the appBase folder.
  • Components have a lifecycle; parents start children and stop them in reverse.
  • Reading a server.xml top-down shows you where every request goes.

Next: CATALINA_HOME and CATALINA_BASE