Understanding Tomcat Context Containers

In this article, we will outline the way that Tomcat uses Contexts to distribute requests to the appropriate servlets, and look at how the methods of defining Contexts vary from one another.

What is a Tomcat Context

In Tomcat, the Context Container represents a single web application running within a given instance of Tomcat.  A web site is made up of one or more Contexts.  For each explicitly configured web application, there should be one context element either in server.xml or in a separate context XML fragment file.

Once a Context has been defined, Catalina will attempt to match incoming HTTP requests to its context path.  There is no limit to the number of Contexts that can be defined, as long as each Context is given its own unique context path.  The context path, which is contained within the context, specifies where the application's resources can be located.  Applications can either be stored in a Web Application Archive (WAR) file, in which case they will be dynamically uncompressed as needed, or as organized unpacked resources in a directory.

Don't do the same Context configuration work twice. Tcat lets you save complete server configuration profiles, and apply them to new instances with a single click. 

Once Catalina has matched a context with a request, the selected Context passes the request to the correct servlet to process the request, based on definitions contained in the web application deployment descriptor file.  

In summary, when an HTTP request is made, Catalina receives it, and passes it to the appropriate Context, which in turn passes the request to the appropriate servlet to serve it.

In the event that the request does not match any specific context paths, Catalina passes the request to a Context whose context path is a zero-length string.  This Context is required for Tomcat to run properly, because it is considered the "default" web application, responsible for processing requests that do not match any other specific context paths. 

How To Define A Context

There are five primary ways in which Contexts can be defined.  Each of these methods is suited to a specific desired functionality.


Contexts defined using this technique will have their element information loaded by all webapps.


Contexts defined using this technique will have their element information loaded by all web apps contained in the specified host.

Individual XML files located in $CATALINA_HOME/conf/[enginename]/[hostname]/ 

The name of each individual XML file will define a new context path.  For example, "test.xml" will yield the context path "/test".  

The "#" character can be used to define multi-level paths.  A file named "test#path.xml" will yield the context path "test/path".

You can also use this technique to define the default web application, by creating a file named "ROOT.xml".  Note that this filename is case-sensitive.

An individual file within the application files at /META-INF/context.xml

This technique allows context files to be packaged within WARs.  

This "/META-INF/context.xml" file will be automatically copied to "$CATALINA_HOME/conf/[enginename]/[hostname]/", after being renamed to mirror the application's context path.  

Once the "context.xml" file has been renamed and copied to the "[hostname]" directory, it will not be replaced, even if the WAR is updated with a new "/META-INF/context.xml" file.

This technique can only be used if no context file already exists for the application in hostname directory.

A Context element contained within a Host element in the main "conf/server.xml" file

This technique allows Contexts to be defined in the central server configuration file.  This technique was common through Tomcat 4.x, but is deprecated as of Tomcat 5.  Using this technique makes Context editing a more disruptive process, as Tomcat must be restarted in order for "conf/server.xml" to be reloaded.