Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 37 ยท Deployment and Contexts

Context Descriptors and context.xml

Learn the Tomcat Context element: where context descriptors live, docBase and path rules, META-INF/context.xml versus conf/Catalina/localhost, precedence, and common attributes.

The WAR file name gives a web application its URL, but many settings do not belong in a file name: where the files really are, how sessions are stored, which database resource the app can use, whether JSPs may be modified. For those, Tomcat uses an XML element called <Context>. This lesson shows where you can write it, which location wins, and the attributes you will use most.

You will read real descriptors (read-only) and run a stand-in that loads descriptors in Tomcat's order of precedence with Java's XML parser.

Where a Context can be defined

There are four places, from most to least specific for the same application:

  1. conf/Catalina/localhost/<name>.xml (inside CATALINA_BASE; Catalina is the engine name, localhost the host name). The file name provides the context path: shop.xml is /shop, ROOT.xml is /, a#b.xml is /a/b. This is the recommended location for server-side settings because the file is outside the application and survives redeploys.
  2. META-INF/context.xml inside the WAR/webapp. Travels with the application. Tomcat copies it to the location above when copyXML="true" and uses it only when deployXML="true" on the Host (the default).
  3. A <Context> element nested in server.xml's <Host>. Discouraged: changes require a restart of Tomcat.
  4. conf/context.xml and conf/Catalina/localhost/context.xml.default: defaults applied to all contexts (globally or per host).

Where Context settings live

conf/Catalina/localhost Per app, outside the WAR
META-INF/context.xml Packaged with the app
conf/context.xml Defaults for all apps

Prefer the first for server-specific settings.

1 / 2

path must not be set in descriptor files under conf/Catalina/localhost or META-INF: the file name determines it, and a wrong path is ignored or causes a warning. Only a <Context> inside server.xml needs path.

An example descriptor

conf/Catalina/localhost/shop.xml:

XML
<Context docBase="/srv/shop/current"
         reloadable="false"
         crossContext="false"
         cookies="true"
         sessionCookieName="SHOPSESSION"
         useHttpOnly="true">

  <Resources cachingAllowed="true" cacheMaxSize="102400" />

  <Environment name="feature.newCart" value="true" type="java.lang.String" override="false" />

  <Resource name="jdbc/shopDb" auth="Container" type="javax.sql.DataSource"
            driverClassName="org.postgresql.Driver"
            url="jdbc:postgresql://db.internal:5432/shop"
            username="shop" password="${DB_PASSWORD}"
            maxTotal="20" maxIdle="5" maxWaitMillis="10000" />

  <Manager className="org.apache.catalina.session.StandardManager"
           maxActiveSessions="5000" />

  <WatchedResource>WEB-INF/web.xml</WatchedResource>
</Context>

(Shown read-only. javax.sql.DataSource is a Java SE type, so it keeps its name on every Tomcat line. The ${DB_PASSWORD} form is replaced from a Java system property such as -DDB_PASSWORD=...; see JNDI resources.)

Important attributes

Attribute Meaning
docBase Directory or WAR holding the app. Relative values resolve against the host's appBase. Setting it lets the app live outside webapps.
reloadable If true, Tomcat watches WEB-INF/classes and lib and reloads on change. Convenient for development; costs CPU and risks memory leaks in production, so use false.
crossContext Lets the app obtain other contexts' dispatchers (getContext). Default false.
sessionCookieName, sessionCookiePath, useHttpOnly Customize the session cookie.
privileged Gives access to Tomcat's internal classes (only for Manager-like apps).
antiResourceLocking Windows only: copies resources to avoid file locks.
swallowOutput Redirects System.out/System.err to the context log.
unloadDelay Milliseconds to wait for servlets to finish at stop.

Nested elements include Resources, Loader, Manager, Environment, Resource, ResourceLink, Valve, Parameter (like <context-param>), WatchedResource, CookieProcessor and JarScanner.

Using docBase to deploy from elsewhere

A very common production pattern keeps releases in versioned directories and points a descriptor at the current one:

XML
<!-- conf/Catalina/localhost/ROOT.xml -->
<Context docBase="/srv/www/releases/2025-06-01-1530" />

To release a new version you unpack it in a new folder and change docBase; Tomcat redeploys the context when the descriptor changes. Rolling back is one edit.

Reading descriptors in order

The stand-in loads the three kinds of descriptor from strings, merges attributes with the same precedence idea (specific file wins over packaged META-INF/context.xml, which wins over global defaults) and prints the effective values. It is a conceptual model, not Tomcat's exact algorithm (real Tomcat treats conf/context.xml as contributing nested elements, not as overridable attribute defaults).

Java Effective Context attributes by precedence (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.

Reload versus redeploy

When a watched resource changes, Tomcat either reloads the context (stop, new class loader, start; the WAR is not re-extracted) or redeploys it (when the descriptor or WAR changes, which re-reads the descriptor). WatchedResource elements tell Tomcat which files trigger a reload: by default WEB-INF/web.xml, the descriptor itself and conf/web.xml.

A reload creates a new class loader. Anything that keeps references into the old one (a static field in a shared library, a thread you started, a JDBC driver registered in DriverManager) is a class loader leak: the old classes can never be garbage collected, and repeated reloads end in OutOfMemoryError: Metaspace. Class loading explains why.

The stand-in below models the trade-off using weak references. A "context" holds data; reloading drops it, and the leak case keeps a strong reference alive:

Java A leaked context survives its reload (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 your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does the context path come from for conf/Catalina/localhost/shop.xml?

    For descriptors in conf/Catalina/<host>/, the base name is the context path; do not set path inside.
  2. 2. Why is a docBase outside webapps useful?

    docBase points Tomcat at any directory or WAR, which supports versioned release folders and quick rollbacks.
  3. 3. Why is reloadable="true" discouraged in production?

    Watching classes and reloading creates new class loaders; leaks accumulate and the Metaspace can run out.
  4. 4. Which location is outside the WAR and survives redeploys?

    Descriptors in conf/Catalina/<host> live in CATALINA_BASE and are not replaced when the WAR changes.

Summary

  • A <Context> describes one application's server-side settings; it may live in conf/Catalina/<host>/<name>.xml, META-INF/context.xml, server.xml, or global defaults.
  • File name decides the path; docBase decides where the files are.
  • Use reloadable="false" in production; know that reloads can leak class loaders.
  • Nested elements declare resources, session managers, environment entries and valves.
  • Keep environment-specific settings outside the WAR.

Next: Virtual hosts