Server Configuration Reference

The DefaultContext Component

The DefaultContext element represents a subset of the configuration settings for a Context, and can be nested inside an Engine or Host element to represent default configuration properties for Contexts that are automatically created.

See Automatic Application Deployment and User Web Applications for more information about the circumstances in which Catalina will automatically create Contexts for you, based on the configuration properties that are stored here.

Attributes

Common Attributes

All implementations of DefaultContext support the following attributes:

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

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 DefaultContext is org.apache.catalina.core.DefaultContext. It supports the following additional attributes (in addition to the common attributes listed above):

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

Nested Components

You can nest at most one instance of the following utility components by nesting a corresponding element inside your DefaultContext element:

Loader - Configure the web application class loader that will be used to load servlet and bean classes for each web application. Normally, the default configuration of the class loader will be sufficient.

Special Features

Context Parameters
You can configure named values that will be made visible to web applications as servlet context initialization parameters by nesting <Parameter> elements inside this element. For example, you can create an initialization parameter like this:
<DefaultContext ...>
  ...
  <Parameter name="companyName" value="My Company, Incorporated"
         override="false"/>
  ...
</DefaultContext>
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 web applications as environment entry resources, by nesting <Environment> entries inside this element. For example, you can create an environment entry like this:
<DefaultContext ...>
  ...
  <Environment name="maxExemptions" value="10"
         type="java.lang.Integer" override="false"/>
  ...
</DefaultContext>
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:
<DefaultContext  ...>
  ...
  <Listener className="com.mycompany.mypackage.MyListener" ... >
  ...
</DefaultContext>
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.
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:
<DefaultContext ...>
  ...
  <Resource name="jdbc/EmployeeDB" auth="Container"
            type="javax.sql.DataSource"
     description="Employees Database for HR Applications"/>
  ...
</DefaultContext>
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 attriutes 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:
<DefaultContext ...>
  ...
  <ResourceParams name="jdbc/EmployeeDB">
    <parameter>
      <name>driverClassName</name>
      <value>org.hsql.jdbcDriver</value>
    </parameter>
    <parameter>
      <name>driverName</name>
      </value>jdbc:HypersonicSQL:database</value>
    </parameter>
    <parameter>
      <name>user</name>
      <value>dbusername</value>
    </parameter>
    <parameter>
      <name>password</name>
      <value>dbpassword</value>
    </parameter>
  </ResourceParams>
  ...
</DefaultContext>
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:
<DefaultContext ...>
  ...
  <ResourceLink name="linkToGlobalResource"
            global="simpleValue"
            type="java.lang.Integer"
  ...
</DefaultContext>
The valid attributes for a <ResourceLink> element are as follows:

Attribute Description
global
The name of the linked global resource in the gobal 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.