Apache Tomcat Configuration Reference - The Context Container
The Apache Tomcat 5.5 Servlet/JSP Container
Links
Docs Home
Config Ref. Home
Top Level Elements
Server
Service
Connectors
HTTP
AJP
Containers
Context
Engine
Host
Nested Components
Global Resources
Loader
Manager
Realm
Resources
Valve
Other
Filter
System properties
Apache Tomcat Configuration Reference
The Context Container
Table of Contents
Introduction
Attributes
Common Attributes
Standard Implementation
Nested Components
Special Features
Logging
Access Logs
Automatic Context Configuration
Context Parameters
Environment Entries
Lifecycle Listeners
Request Filters
Resource Definitions
Resource Links
Transaction
Introduction
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
in the
web application deployment descriptor
file (which MUST
be located at
/WEB-INF/web.xml
within the web app's
directory hierarchy).
You may define as many
Context
elements as you
wish. Each such Context MUST have a unique context path. 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.
For Tomcat 5, unlike Tomcat 4.x, it is NOT recommended to place
This
is because it makes modifying the
Context
configuration
more invasive since the main
conf/server.xml
file cannot be
reloaded without restarting Tomcat.
Context
elements may be explicitly defined:
In the
$CATALINA_HOME/conf/context.xml
file:
the Context element information will be loaded by all webapps.
In the
$CATALINA_HOME/conf/[enginename]/[hostname]/context.xml.default
file: the Context element information will be loaded by all webapps of that
host.
In individual files (with a ".xml" extension) in the
$CATALINA_HOME/conf/[enginename]/[hostname]/
directory.
The name of the file (less the .xml) extension will be used as the
context path. Multi-level context paths may be defined using #, e.g.
foo#bar.xml
for a context path of
/foo/bar
. The
default web application may be defined by using a file called
ROOT.xml
Only if a context file does not exist for the application in the
$CATALINA_HOME/conf/[enginename]/[hostname]/
; in an individual
file at
/META-INF/context.xml
inside the application files. If
the web application is packaged as a WAR then
/META-INF/context.xml
will be copied to
$CATALINA_HOME/conf/[enginename]/[hostname]/
and renamed to
match the application's context path. Once this file exists, it will not be
replaced if a new WAR with a newer
/META-INF/context.xml
is
placed in the host's appBase.
inside a
Host
element in the main
conf/server.xml
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.
The description below uses the variable name $CATALINA_HOME
to refer to the directory into which you have installed Tomcat 5,
and is the base directory against which most relative paths are
resolved. However, if you have configured Tomcat 5 for multiple
instances by setting a CATALINA_BASE directory, you should use
$CATALINA_BASE instead of $CATALINA_HOME for each of these
references.
Attributes
Common Attributes
All implementations of
Context
support the following attributes:
Attribute
Description
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.
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
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.
Do not choose a docBase that starts with your Host's appBase string.
The default appBase is "webapps" so do not choose a docBase like
"webapps-foo." Doing so will lead to deployment errors: see
Bugzilla
for details.
The value of this field must not be set when the Context is
configured using a
META-INF/context.xml
file as it will be
inferred by the automatic deployment process.
override
Set to
true
to have explicit settings in this
Context element override any corresponding settings in the
default settings associated with the owning
Host
. The default is
false
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
Catalina
class loader rather than the
Shared
class
loader.
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.
The value of this field must not be set except when statically
defining a Context in server.xml, as it will be inferred from the
filenames used for either the .xml context file or the docBase.
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.
wrapperClass
Java class name of the
org.apache.catalina.Wrapper
implementation class that will be used for servlets managed by this
Context. If not specified, a standard default value will be used.
useHttpOnly
Should the HttpOnly flag be set on session cookies to prevent client
side script from accessing the session ID? Defaults to
false
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
allowLinking
If the value of this flag is
true
, symlinks will be
allowed inside the web application, pointing to resources outside the
web application base path. If not specified, the default value
of the flag is
false
NOTE: This flag MUST NOT be set to true on the Windows platform
(or any other OS which does not have a case sensitive filesystem),
as it will disable case sensitivity checks, allowing JSP source code
disclosure, among other security problems.
antiJARLocking
If true, the Tomcat classloader will take extra measures to avoid
JAR file locking when resources are accessed inside JARs through URLs.
This will impact startup time of applications, but could prove to be
useful on platforms or configurations where file locking can occur.
If not specified, the default value is
false
antiJARLocking
is a subset of
antiResourceLocking
and therefore, to prevent duplicate
work and possible issues, only one of these attributes should be set
to
true
at any one time.
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
false
antiJARLocking
is a subset of
antiResourceLocking
and therefore, to prevent duplicate
work and possible issues, only one of these attributes should be set
to
true
at any one time.
Please note that setting this to
true
has some side
effects, including the disabling of JSP reloading in a running server:
see
Bugzilla 37668
Please note that setting this flag to true in applications that are
outside the appBase for the Host (the
webapps
directory
by default) will cause the application to be
deleted
on
Tomcat shutdown. You probably don't want to do this, so think twice
before setting antiResourceLocking=true on a webapp that's outside the
appBase for its Host.
cacheMaxSize
Maximum size of the static resource cache in kilobytes.
If not specified, the default value is
10240
(10 megabytes).
cacheTTL
Amount of time in milliseconds between cache entries revalidation.
If not specified, the default value is
5000
(5 seconds).
cachingAllowed
If the value of this flag is
true
, the cache for static
resources will be used. If not specified, the default value
of the flag is
true
caseSensitive
If the value of this flag is
false
, all case sensitivity
checks will be disabled. If not
specified, the default value of the flag is
true
NOTE: This flag MUST NOT be set to false on the Windows platform
(or any other OS which does not have a case sensitive filesystem),
as it will disable case sensitivity checks, allowing JSP source code
disclosure, among other security problems.
processTlds
Whether the context should process TLDs on startup. The default
is true. The false setting is intended for special cases
that know in advance TLDs are not part of the webapp.
swallowOutput
If the value of this flag is
true
, the bytes output to
System.out and System.err by the web application will be redirected to
the web application logger. If not specified, the default value
of the flag is
false
tldNamespaceAware
If the value of this flag is
true
, the TLD files
XML validation will be namespace-aware. If you turn this flag on,
you should probably also turn
tldValidation
on. The
default value for this flag is
false
, and setting it
to true will incur a performance penalty.
tldValidation
If the value of this flag is
true
, the TLD files
will be XML validated on context startup. The default value for
this flag is
false
, and setting it to true will incur
a performance penalty.
unloadDelay
Amount of ms that the container will wait for servlets to unload.
If not specified, the default value of the flag is
2000
ms.
unpackWAR
If true, Tomcat will unpack all compressed web applications before
running them.
If not specified, the default value is
true
useNaming
Set to
true
(the default) to have Catalina enable a
JNDI
InitialContext
for this web application that is
compatible with Java2 Enterprise Edition (J2EE) platform
conventions.
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
java.io.File
) named
javax.servlet.context.tempdir
as described in the
Servlet Specification. If not specified, a suitable directory
underneath
$CATALINA_HOME/work
will be provided.
Nested Components
You can nest at most one instance of the following utility components
by nesting a corresponding element inside your
Context
element:
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 is is updated. The content of this element
must be a string.
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:
...
pattern="common"/>
...
See
Access Log Valve
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 automtically 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
elements inside this element. For
example, you can create an initialization parameter like this:
...
...
This is equivalent to the inclusion of the following element in the
web application deployment descriptor (
/WEB-INF/web.xml
):
but does
not
require modification of the deployment descriptor
to customize this value.
The valid attributes for a
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
false
if you do
not
want
for the same parameter name,
found in the web application deployment descriptor, to override the
value specified here. By default, overrides are allowed.
value
The parameter value that will be presented to the application
when requested by calling
ServletContext.getInitParameter()
Environment Entries
You can configure named values that will be made visible to the
web application as environment entry resources, by nesting
entries inside this element. For
example, you can create an environment entry like this:
...
...
This is equivalent to the inclusion of the following element in the
web application deployment descriptor (
/WEB-INF/web.xml
):
but does
not
require modification of the deployment descriptor
to customize this value.
The valid attributes for an
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
java:comp/env
context.
override
Set this to
false
if you do
not
want
an
for the same environment entry name,
found in the web application deployment descriptor, to override the
value specified here. By default, overrides are allowed.
type
The fully qualified Java class name expected by the web application
for this environment entry. Must be one of the legal values for
in the web application deployment
descriptor:
java.lang.Boolean
java.lang.Byte
java.lang.Character
java.lang.Double
java.lang.Float
java.lang.Integer
java.lang.Long
java.lang.Short
, or
java.lang.String
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
type
attribute.
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
it will be notified about the occurrence of the coresponding
lifecycle events. Configuration of such a listener looks like this:
...
...
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 a configured list of "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:
...
...
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
and
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:
...
description="Employees Database for HR Applications"/>
...
This is equivalent to the inclusion of the following element in the
web application deployment descriptor (
/WEB-INF/web.xml
):
but does
not
require modification of the deployment
descriptor to customize this value.
The valid attributes for a
element
are as follows:
Attribute
Description
auth
Specify whether the web Application code signs on to the
corresponding resource manager programatically, 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
element in the web
application deployment descriptor, but is optional if the
application uses a
instead.
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.
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:
...
type="java.lang.Integer"
...
The valid attributes for a
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.
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
element
are as follows:
Attribute
Description
factory
The class name for the JNDI object factory.
Copyright © 1999-2012, Apache Software Foundation
US