Server Configuration Reference - The Context Container

# Server Configuration Reference ## The Context Container |
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, 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 `$CATALINA_HOME/conf/[enginename]/[hostname]/` directory. See Automatic Application Deployment for more information. This method allows dynamic reconfiguration of the web application, since the main `conf/server.xml` file cannot be reloaded without restarting Tomcat. 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.
> > `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.
> 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.
> > `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 `true`, 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).
> > `managerChecksFrequency` | Frequency of the session expiration, and related manager operations. Manager operations will be done once for the specified amount of backgrondProcess calls (ie, the lower the amount, the most often the checks will occur). The minimum value is 1, and the default value is 6.
> > `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.
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. 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.
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 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 path="/examples" ...>
> >       ...
> >       <Valve className="org.apache.catalina.valves.AccessLogValve"
> >              prefix="localhost_access_log." suffix=".txt"
> >              pattern="common"/>
> >       ...
> >     </Context>
> 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 `<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 `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()`.
> 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</param-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 `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.
> 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:
> >     <Context path="/examples" ...>
> >       ...
> >       <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 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:
> >     <Context path="/examples" ...>
> >       ...
> >       <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 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 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. 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 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.
> Resource Parameters
> > 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:
> >     <Context ...>
> >       ...
> >       <ResourceParams name="jdbc/EmployeeDB">
> >         <parameter>
> >           <name>driverClassName</name>
> >           <value>org.hsql.jdbcDriver</value>
> >         </parameter>
> >         <parameter>
> >           <name>url</name>
> >           </value>jdbc:HypersonicSQL:database</value>
> >         </parameter>
> >         <parameter>
> >           <name>user</name>
> >           <value>dbusername</value>
> >         </parameter>
> >         <parameter>
> >           <name>password</name>
> >           <value>dbpassword</value>
> >         </parameter>
> >       </ResourceParams>
> >       ...
> >     </Context>
> > 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.
> 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 `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.
Copyright © 1999-2003, Apache Software Foundation