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.
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 |
allowMultipleLeadingForwardSlashInPath |
Tomcat normalises sequences of multiple |
altDDName |
The absolute path to the alternative deployment descriptor for this
context. This overrides the default deployment descriptor located at
|
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 |
containerSciFilter |
The regular expression that specifies which container provided SCIs
should be filtered out and not used for this context. Matching uses
|
cookies |
Set to |
crossContext |
Set to |
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 The value of this field must not be set unless the Context element is
defined in server.xml or the 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 |
failCtxIfServletStartFails |
Set to If not specified, the attribute of the same name in the parent Host
configuration is used if specified. Otherwise the default value of
|
fireRequestListenersOnForwards |
Set to |
logEffectiveWebXml |
Set to |
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 |
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 |
override |
Set to |
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 |
preemptiveAuthentication |
When set to |
privileged |
Set to |
reloadable |
Set to |
resourceOnlyServlets |
Comma separated list of Servlet names (as used in
|
sendRedirectBody |
If |
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 |
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
Note: Once one web application using
|
sessionCookiePathUsesTrailingSlash |
Some browsers, such as Internet Explorer, Safari and Edge, will send
a session cookie for a context with a path of |
swallowAbortedUploads |
Set to false if Tomcat should not read any additional request body data for aborted uploads and instead abort the client connection. This setting is used in the following situations:
Not reading the additional data will free the request processing thread more quickly. Unfortunately most HTTP clients will not read the response if they cannot write the full request. The default is Note if an error occurs during the request processing that triggers a 5xx response, any unread request data will always be ignored and the client connection will be closed once the error response has been written. |
swallowOutput |
If the value of this flag is |
tldValidation |
If the value of this flag is |
useHttpOnly |
Should the HttpOnly flag be set on session cookies to prevent client
side script from accessing the session ID? Defaults to
|
useRelativeRedirects |
Controls whether HTTP 1.1 and later location headers generated by a
call to
|
validateClientProvidedNewSessionId |
When a client provides the ID for a new session, this attribute controls whether that ID is validated. The only use case for using a client provided session ID is to have a common session ID across multiple web applications. Therefore, any client provided session ID should already exist in another web application. If this check is enabled, the client provided session ID will only be used if the session ID exists in at least one other web application for the current host. Note that the following additional tests are always applied, irrespective of this setting:
If not specified, the default value of |
wrapperClass |
Java class name of the |
xmlBlockExternal |
If the value of this flag is |
xmlNamespaceAware |
If the value of this flag is |
xmlValidation |
If the value of this flag is |
Standard Implementation
The standard implementation of Context is org.apache.catalina.core.StandardContext. It supports the following additional attributes (in addition to the common attributes listed above):
Attribute | Description |
---|---|
addWebinfClassesResources |
This attribute controls if, in addition to static resources being
served from |
antiResourceLocking |
If true, Tomcat will prevent any file locking.
This will significantly impact startup time of applications,
but allows full webapp hot deploy and undeploy on platforms
or configurations where file locking can occur.
If not specified, the default value is Please note that setting this to Please note that setting this flag to true in applications that are
outside the appBase for the Host (the |
clearReferencesHttpClientKeepAliveThread |
If |
clearReferencesObjectStreamClassCaches |
If |
clearReferencesRmiTargets |
If |
clearReferencesStopThreads |
If |
clearReferencesStopTimerThreads |
If |
copyXML |
Set to |
jndiExceptionOnFailedWrite |
If |
renewThreadsWhenStoppingContext |
If |
unloadDelay |
Number of ms that the container will wait for servlets to unload.
If not specified, the default value is |
unpackWAR |
If |
useNaming |
Set to |
workDir |
Pathname to a scratch directory to be provided by this Context
for temporary read-write use by servlets within the associated web
application. This directory will be made visible to servlets in the
web application by a servlet context attribute (of type
|
Nested Components
You can nest at most one instance of the following utility components by nesting a corresponding element inside your Context element:
- Cookie Processor - Configure parsing and generation of HTTP cookie headers.
- Loader - Configure the web application class loader that will be used to load servlet and bean classes for this web application. Normally, the default configuration of the class loader will be sufficient.
- Manager - Configure the session manager that will be used to create, destroy, and persist HTTP sessions for this web application. Normally, the default configuration of the session manager will be sufficient.
- Realm - Configure a realm that will allow its database of users, and their associated roles, to be utilized solely for this particular web application. If not specified, this web application will utilize the Realm associated with the owning Host or Engine.
- Resources - Configure the resource manager that will be used to access the static resources associated with this web application. Normally, the default configuration of the resource manager will be sufficient.
- WatchedResource - The auto deployer will monitor the specified static resource of the web application for updates, and will reload the web application if it is updated. The content of this element must be a string.
- JarScanner - Configure the Jar Scanner that will be used to scan the web application for JAR files and directories of class files. It is typically used during web application start to identify configuration files such as TLDs o web-fragment.xml files that must be processed as part of the web application initialisation. Normally, the default Jar Scanner configuration will be sufficient.
Special Features
Logging
A context is associated with the
org.apache.catalina.core.ContainerBase.[enginename].[hostname].[path]
log category. Note that the brackets are actually part of the name, don't omit them.
Access Logs
When you run a web server, one of the output files normally generated is an access log, which generates one line of information for each request processed by the server, in a standard format. Catalina includes an optional Valve implementation that can create access logs in the same standard format created by web servers, or in any number of custom formats.
You can ask Catalina to create an access log for all requests processed by an Engine, Host, or Context by nesting a Valve element like this:
<Context>
...
<Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="localhost_access_log" suffix=".txt"
pattern="common"/>
...
</Context>
See Access Logging Valves for more information on the configuration attributes that are supported.
Automatic Context Configuration
If you use the standard Context implementation, the following configuration steps occur automatically when Catalina is started, or whenever this web application is reloaded. No special configuration is required to enable this feature.
- If you have not declared your own Loader element, a standard web application class loader will be configured.
- If you have not declared your own Manager element, a standard session manager will be configured.
- If you have not declared your own Resources element, a standard resources manager will be configured.
- The web application properties listed in
conf/web.xml
will be processed as defaults for this web application. This is used to establish default mappings (such as mapping the*.jsp
extension to the corresponding JSP servlet), and other standard features that apply to all web applications. - The web application properties listed in the
/WEB-INF/web.xml
resource for this web application will be processed (if this resource exists). - If your web application has specified security constraints that might require user authentication, an appropriate Authenticator that implements the login method you have selected will be configured.
Context Parameters
You can configure named values that will be made visible to the
web application as servlet context initialization parameters by nesting
<Parameter>
elements inside this element. For
example, you can create an initialization parameter like this:
<Context>
...
<Parameter name="companyName" value="My Company, Incorporated"
override="false"/>
...
</Context>
This is equivalent to the inclusion of the following element in the
web application deployment descriptor (/WEB-INF/web.xml
):
<context-param>
<param-name>companyName</param-name>
<param-value>My Company, Incorporated</param-value>
</context-param>
but does not require modification of the deployment descriptor to customize this value.
The valid attributes for a <Parameter>
element
are as follows:
Attribute | Description |
---|---|
description |
Optional, human-readable description of this context initialization parameter. |
name |
The name of the context initialization parameter to be created. |
override |
Set this to |
value |
The parameter value that will be presented to the application
when requested by calling
|
Environment Entries
You can configure named values that will be made visible to the
web application as environment entry resources, by nesting
<Environment>
entries inside this element. For
example, you can create an environment entry like this:
<Context>
...
<Environment name="maxExemptions" value="10"
type="java.lang.Integer" override="false"/>
...
</Context>
This is equivalent to the inclusion of the following element in the
web application deployment descriptor (/WEB-INF/web.xml
):
<env-entry>
<env-entry-name>maxExemptions</env-entry-name>
<env-entry-value>10</env-entry-value>
<env-entry-type>java.lang.Integer</env-entry-type>
</env-entry>
but does not require modification of the deployment descriptor to customize this value.
The valid attributes for an <Environment>
element
are as follows:
Attribute | Description |
---|---|
description |
Optional, human-readable description of this environment entry. |
name |
The name of the environment entry to be created, relative to the
|
override |
Set this to |
type |
The fully qualified Java class name expected by the web application
for this environment entry. Must be a legal value for
|
value |
The parameter value that will be presented to the application
when requested from the JNDI context. This value must be convertable
to the Java type defined by the |
Lifecycle Listeners
If you have implemented a Java object that needs to know when this
Context is started or stopped, you can declare it by
nesting a Listener element inside this element. The
class name you specify must implement the
org.apache.catalina.LifecycleListener
interface, and
the class must be packaged in a jar and placed in the
$CATALINA_HOME/lib
directory.
It will be notified about the occurrence of the corresponding
lifecycle events. Configuration of such a listener looks like this:
<Context>
...
<Listener className="com.mycompany.mypackage.MyListener" ... >
...
</Context>
Note that a Listener can have any number of additional properties that may be configured from this element. Attribute names are matched to corresponding JavaBean property names using the standard property method naming patterns.
Request Filters
You can ask Catalina to check the IP address, or host name, on every
incoming request directed to the surrounding
Engine, Host, or
Context element. The remote address or name
will be checked against configured "accept" and/or "deny"
filters, which are defined using java.util.regex
Regular
Expression syntax. Requests that come from locations that are
not accepted will be rejected with an HTTP "Forbidden" error.
Example filter declarations:
<Context>
...
<Valve className="org.apache.catalina.valves.RemoteHostValve"
allow=".*\.mycompany\.com|www\.yourcompany\.com"/>
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
deny="192\.168\.1\.\d+"/>
...
</Context>
See Remote Address Filter and Remote Host Filter for more information about the configuration options that are supported.
Resource Definitions
You can declare the characteristics of the resource
to be returned for JNDI lookups of <resource-ref>
and
<resource-env-ref>
elements in the web application
deployment descriptor. You MUST also define
the needed resource parameters as attributes of the 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
|
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 For Apache Commons DBCP 2 and Apache Tomcat JDBC connection pools
you can use |
description |
Optional, human-readable description of this resource. |
name |
The name of the resource to be created, relative to the
|
scope |
Specify whether connections obtained through this resource
manager can be shared. The value of this attribute must be
|
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 |
type |
The fully qualified Java class name expected by the web application when it performs a lookup for this resource. |
Resource Links
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
|
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 |
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 |
|
password |
|
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. |