The Context Container

Table of Contents

Introduction

The description below uses the variable name $CATALINA_BASE to refer the base directory against which most relative paths are resolved. If you have not configured Tomcat for multiple instances by setting a CATALINA_BASE directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, the directory into which you have installed Tomcat.

The Context element represents a web application, which is run within a particular virtual host. Each web application is based on a Web Application Archive (WAR) file, or a corresponding directory containing the corresponding unpacked contents, as described in the Servlet Specification (version 2.2 or later). For more information about web application archives, you can download the Servlet Specification, and review the Tomcat Application Developer's Guide.

The web application used to process each HTTP request is selected by Catalina based on matching the longest possible prefix of the Request URI against the context path of each defined Context. Once selected, that Context will select an appropriate servlet to process the incoming request, according to the servlet mappings defined by the web application deployment.

You may define as many Context elements as you wish. Each such Context MUST have a unique context name within a virtual host. The context path does not need to be unique (see parallel deployment below). In addition, a Context must be present with a context path equal to a zero-length string. This Context becomes the default web application for this virtual host, and is used to process all requests that do not match any other Context's context path.

Parallel deployment

You may deploy multiple versions of a web application with the same context path at the same time. The rules used to match requests to a context version are as follows:

  • If no session information is present in the request, use the latest version.
  • If session information is present in the request, check the session manager of each version for a matching session and if one is found, use that version.
  • If session information is present in the request but no matching session can be found, use the latest version.

The Host may be configured (via the undeployOldVersions) to remove old versions deployed in this way once they are no longer in use.

Naming

When autoDeploy or deployOnStartup operations are performed by a Host, the name and context path of the web application are derived from the name(s) of the file(s) that define(s) the web application. Consequently, the context path may not be defined in a META-INF/context.xml embedded in the application and there is a close relationship between the context name, context path, context version and the base file name (the name minus any .war or .xml extension) of the file.

If no version is specified then the context name is always the same as the context path. If the context path is the empty string then the base name will be ROOT (always in upper case) otherwise the base name will be the context path with the leading '/' removed and any remaining '/' characters replaced with '#'.

If a version is specified then the context path remains unchanged and both the context name and the base name have the string '##' appended to them followed by the version identifier.

Some examples of these naming conventions are given below.

Context Path Context Version Context Name Base File Name Example File Names (.xml, .war & directory)
/foo None /foo foo foo.xml, foo.war, foo
/foo/bar None /foo/bar foo#bar foo#bar.xml, foo#bar.war, foo#bar
Empty String None Empty String ROOT ROOT.xml, ROOT.war, ROOT
/foo 42 /foo##42 foo##42 foo##42.xml, foo##42.war, foo##42
/foo/bar 42 /foo/bar##42 foo#bar##42 foo#bar##42.xml, foo#bar##42.war, foo#bar##42
Empty String 42 ##42 ROOT##42 ROOT##42.xml, ROOT##42.war, ROOT##42

The version component is treated as a String both for performance reasons and to allow flexibility in versioning schemes. String comparisons are used to determine version order. If version is not specified, it is treated as the empty string. Therefore, foo.war will be treated as an earlier version than foo##11.war and foo##11.war will be treated as an earlier version than foo##2.war. If using a purely numerical versioning scheme it is recommended that zero padding is used so that foo##002.war is treated as an earlier version than foo##011.war.

If you want to deploy a WAR file or a directory using a context path that is not related to the base file name then one of the following options must be used to prevent double-deployment:

  • Disable autoDeploy and deployOnStartup and define all Contexts in server.xml
  • Locate the WAR and/or directory outside of the Host's appBase and use a context.xml file with a docBase attribute to define it.

Defining a context

It is NOT recommended to place <Context> elements directly in the server.xml file. This is because it makes modifying the Context configuration more invasive since the main conf/server.xml file cannot be reloaded without restarting Tomcat. Default Context elements (see below) will also overwrite the configuration of any <Context> elements placed directly in server.xml. To prevent this, the override attribute of the <Context> element defined in server.xml should be set to true.

Individual Context elements may be explicitly defined:

  • In an individual file at /META-INF/context.xml inside the application files. Optionally (based on the Host's copyXML attribute) this may be copied to $CATALINA_BASE/conf/[enginename]/[hostname]/ and renamed to application's base file name plus a ".xml" extension.
  • In individual files (with a ".xml" extension) in the $CATALINA_BASE/conf/[enginename]/[hostname]/ directory. The context path and version will be derived from the base name of the file (the file name less the .xml extension). This file will always take precedence over any context.xml file packaged in the web application's META-INF directory.
  • Inside a Host element in the main conf/server.xml.

Default Context elements may be defined that apply to multiple web applications. Configuration for an individual web application will override anything configured in one of these defaults. Any nested elements, e.g. <Resource> elements, that are defined in a default Context will be created once for each Context to which the default applies. They will not be shared between Context elements.

  • In the $CATALINA_BASE/conf/context.xml file: the Context element information will be loaded by all web applications.
  • In the $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml.default file: the Context element information will be loaded by all web applications of that host.

With the exception of server.xml, files that define Context elements may only define a single Context element.

In addition to explicitly specified Context elements, there are several techniques by which Context elements can be created automatically for you. See Automatic Application Deployment and User Web Applications for more information.

To define multiple contexts that use a single WAR file or directory, use one of the options described in the Naming section above for creating a Context that has a path that is not related to the base file name.

Attributes

Common Attributes

All implementations of Context support the following attributes:

Attribute Description
allowCasualMultipartParsing

Set to true if Tomcat should automatically parse multipart/form-data request bodies when HttpServletRequest.getPart* or HttpServletRequest.getParameter* is called, even when the target servlet isn't marked with the @MultipartConfig annotation (See Servlet Specification 3.0, Section 3.2 for details). Note that any setting other than false causes Tomcat to behave in a way that is not technically spec-compliant. The default is false

allowMultipleLeadingForwardSlashInPath

Tomcat normalises sequences of multiple / characters in a URI to a single /. This is for consistencuy with the behaviour of file systems as URIs are often translated to file system paths. As a result, the return value of HttpServletRequest#getContextPath() is expected to start with multiple / characters for some URIs. This will cause problems if this value is used directly with HttpServletResponse#sendRedirect() as redirect paths that start with // are treated as protocol relative redirects. To avoid potential issues, Tomcat will collapse multiple leading / characters at the start of the return value for HttpServletRequest#getContextPath() to a single /. This attribute has a default value of false which enables the collapsing of multiple / characters. To disable this behaviour, set this attribute to true.

altDDName

The absolute path to the alternative deployment descriptor for this context. This overrides the default deployment descriptor located at /WEB-INF/web.xml.

backgroundProcessorDelay

This value represents the delay in seconds between the invocation of the backgroundProcess method on this context and its child containers, including all wrappers. Child containers will not be invoked if their delay value is not negative (which would mean they are using their own processing thread). Setting this to a positive value will cause a thread to be spawn. After waiting the specified amount of time, the thread will invoke the backgroundProcess method on this host and all its child containers. A context will use background processing to perform session expiration and class monitoring for reloading. If not specified, the default value for this attribute is -1, which means the context will rely on the background processing thread of its parent host.

className

Java class name of the implementation to use. This class must implement the org.apache.catalina.Context interface. If not specified, the standard value (defined below) will be used.

containerSciFilter

The regular expression that specifies which container provided SCIs should be filtered out and not used for this context. Matching uses java.util.regex.Matcher.find() so the regular expression only has to match a sub-string of the fully qualified class name of the container provided SCI for it to be filtered out. If not specified, no filtering will be applied.

cookies

Set to true if you want cookies to be used for session identifier communication if supported by the client (this is the default). Set to false if you want to disable the use of cookies for session identifier communication, and rely only on URL rewriting by the application.

crossContext

Set to true if you want calls within this application to ServletContext.getContext() to successfully return a request dispatcher for other web applications running on this virtual host. Set to false (the default) in security conscious environments, to make getContext() always return null.

docBase

The Document Base (also known as the Context Root) directory for this web application, or the pathname to the web application archive file (if this web application is being executed directly from the WAR file). You may specify an absolute pathname for this directory or WAR file, or a pathname that is relative to the appBase directory of the owning Host.

The value of this field must not be set unless the Context element is defined in server.xml or the docBase is not located under the Host's appBase.

If a symbolic link is used for docBase then changes to the symbolic link will only be effective after a Tomcat restart or by undeploying and redeploying the context. A context reload is not sufficient.

dispatchersUseEncodedPaths

Controls whether paths used in calls to obtain a request dispatcher ares expected to be encoded. This affects both how Tomcat handles calls to obtain a request dispatcher as well as how Tomcat generates paths used to obtain request dispatchers internally. If not specified, the default value of true is used.

failCtxIfServletStartFails

Set to true to have the context fail its startup if any servlet that has load-on-startup >=0 fails its own startup.

If not specified, the attribute of the same name in the parent Host configuration is used if specified. Otherwise the default value of false is used.

fireRequestListenersOnForwards

Set to true to fire any configured ServletRequestListeners when Tomcat forwards a request. This is primarily of use to users of CDI frameworks that use ServletRequestListeners to configure the necessary environment for a request. If not specified, the default value of false is used.

logEffectiveWebXml

Set to true if you want the effective web.xml used for a web application to be logged (at INFO level) when the application starts. The effective web.xml is the result of combining the application's web.xml with any defaults configured by Tomcat and any web-fragment.xml files and annotations discovered. If not specified, the default value of false is used.

mapperContextRootRedirectEnabled

If enabled, requests for a web application context root will be redirected (adding a trailing slash) if necessary by the Mapper rather than the default Servlet. This is more efficient but has the side effect of confirming that the context path exists. If not specified, the default value of true is used.

mapperDirectoryRedirectEnabled

If enabled, requests for a web application directory will be redirected (adding a trailing slash) if necessary by the Mapper rather than the default Servlet. This is more efficient but has the side effect of confirming that the directory is exists. If not specified, the default value of false is used.

override

Set to true to ignore any settings in both the global or Host default contexts. By default, settings from a default context will be used but may be overridden by a setting the same attribute explicitly for the Context.

path

The context path of this web application, which is matched against the beginning of each request URI to select the appropriate web application for processing. All of the context paths within a particular Host must be unique. If you specify a context path of an empty string (""), you are defining the default web application for this Host, which will process all requests not assigned to other Contexts.

This attribute must only be used when statically defining a Context in server.xml. In all other circumstances, the path will be inferred from the filenames used for either the .xml context file or the docBase.

Even when statically defining a Context in server.xml, this attribute must not be set unless either the docBase is not located under the Host's appBase or both deployOnStartup and autoDeploy are false. If this rule is not followed, double deployment is likely to result.

preemptiveAuthentication

When set to true and the user presents credentials for a resource that is not protected by a security constraint, if the authenticator supports preemptive authentication (the standard authenticators provided with Tomcat do) then the user' credentials will be processed. If not specified, the default of false is used.

privileged

Set to true to allow this context to use container servlets, like the manager servlet. Use of the privileged attribute will change the context's parent class loader to be the Server class loader rather than the Shared class loader. Note that in a default installation, the Common class loader is used for both the Server and the Shared class loaders.

reloadable

Set to true if you want Catalina to monitor classes in /WEB-INF/classes/ and /WEB-INF/lib for changes, and automatically reload the web application if a change is detected. This feature is very useful during application development, but it requires significant runtime overhead and is not recommended for use on deployed production applications. That's why the default setting for this attribute is false. You can use the Manager web application, however, to trigger reloads of deployed applications on demand.

resourceOnlyServlets

Comma separated list of Servlet names (as used in /WEB-INF/web.xml) that expect a resource to be present. Ensures that welcome files associated with Servlets that expect a resource to be present (such as the JSP Servlet) are not used when there is no resource present. This prevents issues caused by the clarification of welcome file mapping in section 10.10 of the Servlet 3.0 specification. If the org.apache.catalina.STRICT_SERVLET_COMPLIANCE system property is set to true, the default value of this attribute will be the empty string, else the default value will be jsp.

sendRedirectBody

If true, redirect responses will include a short response body that includes details of the redirect as recommended by RFC 2616. This is disabled by default since including a response body may cause problems for some application component such as compression filters.

sessionCookieDomain

The domain to be used for all session cookies created for this context. If set, this overrides any domain set by the web application. If not set, the value specified by the web application, if any, will be used.

sessionCookieName

The name to be used for all session cookies created for this context. If set, this overrides any name set by the web application. If not set, the value specified by the web application, if any, will be used, or the name JSESSIONID if the web application does not explicitly set one.

sessionCookiePath

The path to be used for all session cookies created for this context. If set, this overrides any path set by the web application. If not set, the value specified by the web application will be used, or the context path used if the web application does not explicitly set one. To configure all web application to use an empty path (this can be useful for portlet specification implementations) set this attribute to / in the global CATALINA_BASE/conf/context.xml file.

Note: Once one web application using sessionCookiePath="/" obtains a session, all subsequent sessions for any other web application in the same host also configured with sessionCookiePath="/" will always use the same session ID. This holds even if the session is invalidated and a new one created. This makes session fixation protection more difficult and requires custom, Tomcat specific code to change the session ID shared by the multiple applications.

code>Resource element, to configure the object factory to be used (if not known to Tomcat already), and the properties used to configure that object factory.

For example, you can create a resource definition like this:

<Context>
  ...
  <Resource name="jdbc/EmployeeDB" auth="Container"
            type="javax.sql.DataSource"
     description="Employees Database for HR Applications"/>
  ...
</Context>

This is equivalent to the inclusion of the following element in the web application deployment descriptor (/WEB-INF/web.xml):

<resource-ref>
  <description>Employees Database for HR Applications</description>
  <res-ref-name>jdbc/EmployeeDB</res-ref-name>
  <res-ref-type>javax.sql.DataSource</res-ref-type>
  <res-auth>Container</res-auth>
</resource-ref>

but does not require modification of the deployment descriptor to customize this value.

The valid attributes for a <Resource> element are as follows:

Attribute Description
auth

Specify whether the web Application code signs on to the corresponding resource manager programmatically, or whether the Container will sign on to the resource manager on behalf of the application. The value of this attribute must be Application or Container. This attribute is required if the web application will use a <resource-ref> element in the web application deployment descriptor, but is optional if the application uses a <resource-env-ref> instead.

closeMethod

Name of the zero-argument method to call on a singleton resource when it is no longer required. This is intended to speed up clean-up of resources that would otherwise happen as part of garbage collection. This attribute is ignored if the singleton attribute is false. If not specified, no default is defined and no close method will be called.

For Apache Commons DBCP 2 and Apache Tomcat JDBC connection pools you can use closeMethod="close".

description

Optional, human-readable description of this resource.

name

The name of the resource to be created, relative to the java:comp/env context.

scope

Specify whether connections obtained through this resource manager can be shared. The value of this attribute must be Shareable or Unshareable. By default, connections are assumed to be shareable.

singleton

Specify whether this resource definition is for a singleton resource, i.e. one where there is only a single instance of the resource. If this attribute is true, multiple JNDI lookups for this resource will return the same object. If this attribute is false, multiple JNDI lookups for this resource will return different objects. This attribute must be true for javax.sql.DataSource resources to enable JMX registration of the DataSource. The value of this attribute must be true or false. By default, this attribute is true.

type

The fully qualified Java class name expected by the web application when it performs a lookup for this resource.

This element is used to create a link to a global JNDI resource. Doing a JNDI lookup on the link name will then return the linked global resource.

For example, you can create a resource link like this:

<Context>
  ...
  <ResourceLink name="linkToGlobalResource"
            global="simpleValue"
            type="java.lang.Integer"
  ...
</Context>

The valid attributes for a <ResourceLink> element are as follows:

Attribute Description
global

The name of the linked global resource in the global JNDI context.

name

The name of the resource link to be created, relative to the java:comp/env context.

type

The fully qualified Java class name expected by the web application when it performs a lookup for this resource link.

factory

The fully qualified Java class name for the class creating these objects. This class should implement the javax.naming.spi.ObjectFactory interface.

When the attribute factory="org.apache.naming.factory.DataSourceLinkFactory" the resource link can be used with two additional attributes to allow a shared data source to be used with different credentials. When these two additional attributes are used in combination with the javax.sql.DataSource type, different contexts can share a global data source with different credentials. Under the hood, what happens is that a call to getConnection() is simply translated to a call getConnection(username, password) on the global data source. This is an easy way to get code to be transparent to what schemas are being used, yet be able to control connections (or pools) in the global configuration.

Attribute Description
username

username value for the getConnection(username, password) call on the linked global DataSource.

password

password value for the getConnection(username, password) call on the linked global DataSource.

Shared Data Source Example:

Warning: This feature works only if the global DataSource supports getConnection(username, password) method. Apache Commons DBCP 2 pool that Tomcat uses by default does not support it. See its Javadoc for BasicDataSource class. Apache Tomcat JDBC pool does support it, but by default this support is disabled and can be enabled by alternateUsernameAllowed attribute. See its documentation for details.

<GlobalNamingResources>
  ...
  <Resource name="sharedDataSource"
            global="sharedDataSource"
            type="javax.sql.DataSource"
            factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
            alternateUsernameAllowed="true"
            username="bar"
            password="barpass"
            ...
  ...
</GlobalNamingResources>

<Context path="/foo"...>
  ...
  <ResourceLink
            name="appDataSource"
            global="sharedDataSource"
            type="javax.sql.DataSource"
            factory="org.apache.naming.factory.DataSourceLinkFactory"
            username="foo"
            password="foopass"
  ...
</Context>
<Context path="/bar"...>
  ...
  <ResourceLink
            name="appDataSource"
            global="sharedDataSource"
            type="javax.sql.DataSource"
  ...
</Context>

When a request for getConnection() is made in the /foo context, the request is translated into getConnection("foo","foopass"), while a request in the /bar gets passed straight through.

Transaction

You can declare the characteristics of the UserTransaction to be returned for JNDI lookup for java:comp/UserTransaction. You MUST define an object factory class to instantiate this object as well as the needed resource parameters as attributes of the Transaction element, and the properties used to configure that object factory.

The valid attributes for the <Transaction> element are as follows:

Attribute Description
factory

The class name for the JNDI object factory.

Comments

Notice: This comments section collects your suggestions on improving documentation for Apache Tomcat.

If you have trouble and need help, read Find Help page and ask your question on the tomcat-users mailing list. Do not ask such questions here. This is not a Q&A section.

The Apache Comments System is explained here. Comments may be removed by our moderators if they are either implemented or considered invalid/off-topic.