The Context Container

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, nested within a Host element in
conf/server.xml. Each such Context MUST have a unique
context path, which is defined by the path attribute.
In addition, you MUST define a Context 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.

In addition to nesting Context elements inside a
Host element, you can also store them in
individual files (with a ".xml" extension) in the appBase
directory for a Host. See
Automatic
Application Deployment for more information.

The description below uses the variable name $CATALINA_HOME
to refer to the directory into which you have installed Tomcat 4,
and is the base directory against which most relative paths are
resolved. However, if you have configured Tomcat 4 for multiple
instances by setting a CATALINA_BASE directory, you should use
$CATALINA_BASE instead of $CATALINA_HOME for each of these
references.

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.

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.

override

Set to true to have explicit settings in this
Context element override any corresponding settings in the
DefaultContext element associated
with our owning Host. By default, settings
in the DefaultContext element will be used.

privileged

Set to true to allow this context to use container
servlets, like the manager servlet.

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.

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. 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.

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.

NOTE: This flag MUST NOT be set to true when using the deprecated
HTTP 1.1 connector as it will disable checks
that protect against mal-formed requests resulting in JSP source code
disclosure.

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.

cacheTTL

Amount of time in milliseconds between cache entries revalidation.
If not specified, the default value is 5000
(5 seconds).

cachingAllowed

This boolean flag indicates if the resources may be cached. It
defaults to true. If set to false, this
flag overrides the cached attribute of any contained
Resources
element.

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.

debug

The level of debugging detail logged by this Engine
to the associated Logger. Higher numbers
generate more detailed output. If not specified, the default
debugging detail level is zero (0).

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.

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.

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.

Logger -
Configure a logger that will receive
and process all log messages for this Context. This
includes application messages logged via calls to
ServletContext.log().

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.

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:

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.

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:

Set this to false if you do not want
a <context-param> 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().

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:

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
java:comp/env context.

override

Set this to false if you do not want
an <env-entry> 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
<env-entry-type> 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.

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.

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 the Regular Expression syntax supported
by the Jakarta Regexp
regular expression library. Requests that come from locations that are
not accepted will be rejected with an HTTP "Forbidden" error.
Example filter declarations:

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
Resource Parameters
for the same resource name, to configure
the object factory to be used (if not known to Tomcat already), and
the properties used to configure that object factory.

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 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 <resource-ref> element in the web
application deployment descriptor, but is optional if the
application uses a <resource-env-ref> 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.

This element is used to configure the resource manager (or object
factory) used to return objects when the web application performs a
JNDI lookup operation on the corresponding resource name. You
MUST define resource parameters for every resource name
that is specified by a <Resource> element inside a
<Context> or <DefaultContext>
element in $CATALINA_HOME/conf/server.xml, and/or for every
name declared in a <resource-ref> or
<resource-env-ref> element in the web application
deployment descriptor, before that resource can be successfully
accessed.

Resource parameters are defined by name, and the precise set of
parameter names supported depend on the resource manager (or object
factory) you are using - they must match the names of settable JavaBeans
properties on the corresponding factory class. The JNDI implementation
will configure an instance of the specified factory class specified by
calling all the corresponding JavaBeans property setters, and then
making the factory instance available via the JNDI lookup()
call.

The resource parameters for a JDBC data source might look something
like this:

If you need to specify the Java class name of a factory class for a
particular resource type, use a <parameter> entry
named factory nested inside the
<ResourceParams> element.

The valid attributes of a <ResourceParams> element
are as follows:

Attribute

Description

name

The name of the resource being configured, relative to the
java:comp/env contxt. This name MUST
match the name of a resource defined by a <Resource>
element in $CATALINA_HOME/conf/server.xml, and/or
referenced in a <resource-ref> or
<resource-env-ref> element in the web application
deployment descriptor.