The Context Component

[Introduction] [Common Attributes] [Standard Implementation Attributes] [Utility Components] [Special Features]

Introduction

A Context component represents an individual web application that is running within a particular Host. Such a web application is based on a directory whose organization is described in the Servlet API Specification, version 2.2 -- including the web application deployment descriptor file, found in "WEB-INF/web.xml".

The web application used to process a particular 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, based on the request mapping rules that are also found in the servlet specification.

You may define as many Context components as you wish, nested within a Host component in the conf/server.xml file. Each such Context must have a unique context path, defined by the path attribute. In addition, you must define a context with a path equal to a zero-length string, which becomes the default web application to process requests when a different context cannot be matched. There are also special features of the Host configuration that enable automatic creation of Context components without having to explicitly mention them.

Request processing Valves that are nested here will be executed for every request received for processing by this web application.

Common Attributes

All implementations of the Context component support the following attributes:

Attribute	Description
`className`	Java class name of the implementation to use. This class must implement the `org.apache.catalina.Context` interface. If no class name is specified, the standard implementation will be used (`org.apache.catalina.core.StandardContext`).
`cookies`	Set to `true` if you want cookies to be used for session identifier communication (if supported by the client). Set to `false` if you want to skip even trying session id cookies, and rely only on URL rewriting. If not specified, the default value is `true`.
`crossContext`	Set to `true` of you want calls from within this application to `ServletContext.getContext()` to successfully return the `ServletContext` for other web applications running in this host. Set to `false` in security conscious environments, so that `getContext()` calls will return `null`. The default value is `false`.
`docBase`	The "document base" directory for this web application. This is the pathname of a directory that contains the static resources (such as HTML pages and images) for this application, plus a WEB-INF subdirectory containing the "web.xml" deployment descriptor and other configuration information. You may specify an absolute pathname to this directory, or a pathname that is relative to the "application base" for the Host within which this application is defined.
`path`	The context path for this web application, which is matched against the beginning of a request URI to select the appropriate application. All of the context paths within a particular Host must be unique. In addition, you must specify a Context with a `path` equal to a zero-length string, which will become the default context for this Host.
`reloadable`	Set this attribute to `true` if you wish to have Catalina check the classes in `WEB-INF/classes` and `WEB-INF/lib` for modification, and automatically reload this application if a change is detected. This feature is very useful during development; however, it requires significant runtime overhead so it is not recommended for production deployment scenarios.
`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, the standard value (`org.apache.catalina.core.StandardWrapper`) will be used.
`useNaming`	Set this attribute to `true` if you wish to have Catalina enable JNDI. Default is `true`.
`override`	Set this attribute to `true` if you wish to over ride the DefaultContext configuration. Default is `false`.

Standard Implementation Attributes

The standard implementation of the Context component also supports the following attributes:

Attribute Description

debug The level of debugging detail logged by this Context to the associated Logger, with higher numbers generating more detailed output. If not specified, the debugging detail level will be set to zero (0).

workDir Pathname to a scratch directory to be provided by this Context for temporary read-write use by servlets within this application. The corresponding directory will be made visible as a servlet context attribute (of type java.io.File) with the standard name assigned by the Servlet API Specification, version 2.2 (javax.servlet.context.tempdir). If not specified, a suitable directory underneath Catalina's home directory will be assigned automatically.

Attribute	Description
`debug`	The level of debugging detail logged by this Context to the associated Logger, with higher numbers generating more detailed output. If not specified, the debugging detail level will be set to zero (0).
`workDir`	Pathname to a scratch directory to be provided by this Context for temporary read-write use by servlets within this application. The corresponding directory will be made visible as a servlet context attribute (of type `java.io.File`) with the standard name assigned by the Servlet API Specification, version 2.2 (`javax.servlet.context.tempdir`). If not specified, a suitable directory underneath Catalina's home directory will be assigned automatically.

Utility Components

You can attach one or more of the following utility components by nesting a corresponding declaration inside your Context element.

Loader - Configure a class loader associated with this Context.
Logger - Configure a logger that will receive all log messages from this Context.
Manager - Configure a session manager for the sessions associated with this Context.
Realm - Configure a realm that will allow your database of users, and their associated roles, to be unique to this particular web application.
Resources - Configure access to the static resources associated with this Context

Special Features

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, in a standard format, for each HTTP request that was received, and responded to, by the web server. Catalina includes an optional Valve implementation that can create access logs in the same standard format created by web servers, or in any custom format desired.

You can ask Catalina to create an access log for all requests to this web application, by nesting an element like this inside your Context element:


    <Context path="/myapp" ...>
      ...
      <Valve className="org.apache.catalina.valves.AccessLogValve"
             prefix="myapp_access_log." suffix=".txt"
             pattern="common"/>
      ...
    </Context>

See Access Log Valve for more information on the configuration options that are supported.

Automatic Context Configuration

If you use the standard Context implementation, the following configuration occurs automatically when Catalina is started, or whenever this web application is restarted. No special configuration is necessary to enable this activity.

If you have not declared your own Loader to be installed, an instance of the standard Loader implementation class (org.apache.catalina.loader.WebappLoader) will be installed and configured.
If you have not declared your own Manager to be installed, an instance of the standard Manager implementation class (org.apache.catalina.session.StandardManager) will be installed and configured.
If you have not declared your own Resources to be installed, an instance of the standard Resources implementation class (org.apache.catalina.resources.StandardResources) will be installed and configured.
The web application properties for this application will be defaulted from the conf/web.xml file. This deployment descriptor can therefore be used to establish defaults for servlet mappings (such as the JSP servlet) and MIME types for all applications running in Catalina.
The web application properties for this application will then be customized from the WEB-INF/web.xml file for this application, if it exists. Such configuration information supplements that provided by the system-wide defaults described in the previous point.
If your web application has specified any security constraints, and you have not installed any Valves that implement the Authenticator interface, a standard Authenticator Valve will be installed, based on the selected <auth-method> you have specified.

NOTE: The automatic context configuration steps described above are applied both to contexts specifically listed in the conf/server.xml file, as well as contexts automatically created by the owning Host component.

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 the <Context> element. The class you specify in the className attribute of this Listener must implement the org.apache.catalina.LifecycleListener interface, and it will be notified about the occurrence of the corresponding lifecycle events.

Configuration for such a listener might look like this:


    <Context path="/myapp" ...>
      ...
      <Listener className="com.mycompany.MyAppListener"/>
      ...
    </Context>

Request Filters

You can ask Catalina to check the IP address, or host name, of an incoming request for this web application against a list of "accept" and "deny" filters, which are defined using the Regular Expression syntax supported by the jakarta-regexp regular expression library system. Requests that come from remote locations that are not accepted will be rejected with an HTTP "Forbidden" error. Example filter declarations:


    <Context path="/myapp" ...>
      ...
      <Valve className="org.apache.catalina.valves.RemoteHostValve"
             allow="*.mycompany.com,www.yourcompany.com"/>
      <Valve className="org.apache.catalina.valves.RemoteAddrValve"
             deny="192.168.1.*"
      ...
    </Context>

See Remote Address Filter or Remote Host Filter for more information on the syntax of these filters, and the logic that is applied when they are executed.