<?xml version="1.0"?>
<!DOCTYPE document [
  <!ENTITY project SYSTEM "project.xml">
]>
<document url="defaultcontext.html">

  &project;

  <properties>
    <author email="craigmcc@apache.org">Craig R. McClanahan</author>
    <title>The DefaultContext Component</title>
  </properties>

<body>


<section name="Introduction">

  <p>The <strong>DefaultContext</strong> element represents a subset of
  the configuration settings for a <a href="context.html">Context</a>,
  and can be nested inside an <a href="engine.html">Engine</a> or
  <a href="host.html">Host</a> element to represent <em>default
  configuration properties</em> for Contexts that are automatically
  created.</p>

  <p>See <a href="host.html#Automatic Application Deployment">Automatic
  Application Deployment</a> and
  <a href="host.html#User Web Applications">User Web Applications</a>
  for more information about the circumstances in which Catalina will
  automatically create Contexts for you, based on the configuration
  properties that are stored here.</p>

</section>


<section name="Attributes">

  <subsection name="Common Attributes">

    <p>All implementations of <strong>Host</strong>
    support the following attributes:</p>

    <attributes>

      <attribute name="cookies" required="false">
        <p>Set to <code>true</code> if you want cookies to be used for
        session identifier communication if supported by the client (this
        is the default).  Set to <code>false</code> if you want to disable
        the use of cookies for session identifier communication, and rely
        only on URL rewriting by the application.</p>
      </attribute>

      <attribute name="crossContext" required="false">
        <p>Set to <code>true</code> if you want calls within this application
        to <code>ServletContext.getContext()</code> to successfully return a
        request dispatcher for other web applications running on this virtual
        host.  Set to <code>false</code> (the default) in security
        conscious environments, to make <code>getContext()</code> always
        return <code>null</code>.</p>
      </attribute>

      <attribute name="reloadable" required="false">
        <p>Set to <code>true</code> if you want Catalina to monitor classes in
        <code>/WEB-INF/classes/</code> and <code>/WEB-INF/lib</code> 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 <a href="../manager-howto.html">Manager</a> web
        application, however, to trigger reloads of deployed applications
        on demand.</p>
      </attribute>

      <attribute name="wrapperClass" required="false">
        <p>Java class name of the <code>org.apache.catalina.Wrapper</code>
        implementation class that will be used for servlets managed by this
        Context.  If not specified, a standard default value will be used.</p>
      </attribute>

    </attributes>

  </subsection>


  <subsection name="Standard Implementation">

    <p>The standard implementation of <strong>DefaultContext</strong> is
    <strong>org.apache.catalina.core.DefaultContext</strong>.
    It supports the following additional attributes (in addition to the
    common attributes listed above):</p>

    <attributes>

      <attribute name="allowLinking" required="false">
        <p>If the value of this flag is <code>true</code>, 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 <code>false</code>.</p>
        <p><b>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.</b></p>
      </attribute>

      <attribute name="cacheMaxSize" required="false">
        <p>Maximum size of the static resource cache in kilobytes. 
        If not specified, the default value is <code>10240</code>
        (10 megabytes).</p>
      </attribute>

      <attribute name="cacheTTL" required="false">
        <p>Amount of time in milliseconds between cache entries revalidation.
        If not specified, the default value is <code>5000</code> 
        (5 seconds).</p>
      </attribute>

      <attribute name="cachingAllowed" required="false">
        <p>If the value of this flag is <code>true</code>, the cache for static
        resources will be used. If not specified, the default value
        of the flag is <code>true</code>.</p>
      </attribute>

      <attribute name="caseSensitive" required="false">
        <p>If the value of this flag is <code>true</code>, all case sensitivity
        checks will be disabled. If not 
        specified, the default value of the flag is <code>true</code>.</p>
        <p><b>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.</b></p>
      </attribute>

      <attribute name="managerChecksFrequency" required="false">
        <p>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.
        </p>
      </attribute>

      <attribute name="swallowOutput" required="false">
        <p>If the value of this flag is <code>true</code>, 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 <code>false</code>.</p>
      </attribute>

      <attribute name="useNaming" required="false">
        <p>Set to <code>true</code> (the default) to have Catalina enable a
        JNDI <code>InitialContext</code> for this web application that is
        compatible with Java2 Enterprise Edition (J2EE) platform
        conventions.</p>
      </attribute>

    </attributes>

  </subsection>


</section>


<section name="Nested Components">

  <p>You can nest at most one instance of the following utility components
  by nesting a corresponding element inside your
  <strong>DefaultContext</strong> element:</p>
  <ul>
  <li><a href="loader.html"><strong>Loader</strong></a> -
      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.</li>
  <!--
  <li><a href="logger.html"><strong>Logger</strong></a> -
      Configure a logger that will receive
      and process all log messages for each <strong>Context</strong>.  This
      includes application messages logged via calls to
      <code>ServletContext.log()</code>.</li>
  <li><a href="manager.html"><strong>Manager</strong></a> -
      Configure the session manager that will be used to create, destroy,
      and persist HTTP sessions for each web application.  Normally, the
      default configuration of the session manager will be sufficient.</li>
  <li><a href="realm.html"><strong>Realm</strong></a> -
      Configure a realm that will allow its
      database of users, and their associated roles, to be utilized solely
      for each particular web application.  If not specified, this web
      application will utilize the Realm associated with the owning
      <a href="host.html">Host</a> or <a href="engine.html">Engine</a>.</li>
  <li><a href="resources.html"><strong>Resources</strong></a> -
      Configure the resource manager that will be used to access the static
      resources associated with each web application.  Normally, the
      default configuration of the resource manager will be sufficient.</li>
  -->
  </ul>

</section>


<section name="Special Features">


  <subsection name="Context Parameters">

    <p>You can configure named values that will be made visible to
    web applications as servlet context initialization parameters by nesting
    <code>&lt;Parameter&gt;</code> elements inside this element.  For
    example, you can create an initialization parameter like this:</p>
<source>
&lt;DefaultContext ...&gt;
  ...
  &lt;Parameter name="companyName" value="My Company, Incorporated"
         override="false"/&gt;
  ...
&lt;/DefaultContext&gt;
</source>

    <p>This is equivalent to the inclusion of the following element in the
    web application deployment descriptor (<code>/WEB-INF/web.xml</code>):
    </p>
<source>
&lt;context-param&gt;
  &lt;param-name&gt;companyName&lt;/param-name&gt;
  &lt;param-value&gt;My Company, Incorporated&lt;/param-value&gt;
&lt;/context-param&gt;
</source>
    <p>but does <em>not</em> require modification of the deployment descriptor
    to customize this value.</p>

    <p>The valid attributes for a <code>&lt;Parameter&gt;</code> element
    are as follows:</p>

    <attributes>

      <attribute name="description" required="false">
        <p>Optional, human-readable description of this context
        initialization parameter.</p>
      </attribute>

      <attribute name="name" required="true">
        <p>The name of the context initialization parameter to be created.</p>
      </attribute>

      <attribute name="override" required="false">
        <p>Set this to <code>false</code> if you do <strong>not</strong> want
        a <code>&lt;context-param&gt;</code> for the same parameter name,
        found in the web application deployment descriptor, to override the
        value specified here.  By default, overrides are allowed.</p>
      </attribute>

      <attribute name="value" required="true">
        <p>The parameter value that will be presented to the application
        when requested by calling
        <code>ServletContext.getInitParameter()</code>.</p>
      </attribute>

    </attributes>

  </subsection>


  <subsection name="Environment Entries">

    <p>You can configure named values that will be made visible to
    web applications as environment entry resources, by nesting
    <code>&lt;Environment&gt;</code> entries inside this element.  For
    example, you can create an environment entry like this:</p>
<source>
&lt;DefaultContext ...&gt;
  ...
  &lt;Environment name="maxExemptions" value="10"
         type="java.lang.Integer" override="false"/&gt;
  ...
&lt;/DefaultContext&gt;
</source>

    <p>This is equivalent to the inclusion of the following element in the
    web application deployment descriptor (<code>/WEB-INF/web.xml</code>):
    </p>
<source>
&lt;env-entry&gt;
  &lt;env-entry-name&gt;maxExemptions&lt;/param-name&gt;
  &lt;env-entry-value&gt;10&lt;/env-entry-value&gt;
  &lt;env-entry-type&gt;java.lang.Integer&lt;/env-entry-type&gt;
&lt;/env-entry&gt;
</source>
    <p>but does <em>not</em> require modification of the deployment descriptor
    to customize this value.</p>

    <p>The valid attributes for an <code>&lt;Environment&gt;</code> element
    are as follows:</p>

    <attributes>

      <attribute name="description" required="false">
        <p>Optional, human-readable description of this environment entry.</p>
      </attribute>

      <attribute name="name" required="true">
        <p>The name of the environment entry to be created, relative to the
        <code>java:comp/env</code> context.</p>
      </attribute>

      <attribute name="override" required="false">
        <p>Set this to <code>false</code> if you do <strong>not</strong> want
        an <code>&lt;env-entry&gt;</code> for the same environment entry name,
        found in the web application deployment descriptor, to override the
        value specified here.  By default, overrides are allowed.</p>
      </attribute>

      <attribute name="type" required="true">
        <p>The fully qualified Java class name expected by the web application
        for this environment entry.  Must be one of the legal values for
        <code>&lt;env-entry-type&gt;</code> in the web application deployment
        descriptor:  <code>java.lang.Boolean</code>,
        <code>java.lang.Byte</code>, <code>java.lang.Character</code>,
        <code>java.lang.Double</code>, <code>java.lang.Float</code>,
        <code>java.lang.Integer</code>, <code>java.lang.Long</code>,
        <code>java.lang.Short</code>, or <code>java.lang.String</code>.</p>
      </attribute>

      <attribute name="value" required="true">
        <p>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 <code>type</code> attribute.</p>
      </attribute>

    </attributes>

  </subsection>


  <subsection name="Lifecycle Listeners">

    <p>If you have implemented a Java object that needs to know when this
    <strong>Context</strong> is started or stopped, you can declare it by
    nesting a <strong>Listener</strong> element inside this element.  The
    class name you specify must implement the
    <code>org.apache.catalina.LifecycleListener</code> interface, and
    it will be notified about the occurrence of the coresponding
    lifecycle events.  Configuration of such a listener looks like this:</p>

<source>
&lt;DefaultContext  ...&gt;
  ...
  &lt;Listener className="com.mycompany.mypackage.MyListener" ... &gt;
  ...
&lt;/DefaultContext&gt;
</source>

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

  </subsection>


  <subsection name="Resource Definitions">

    <p>You can declare the characteristics of the resource
    to be returned for JNDI lookups of <code>&lt;resource-ref&gt;</code> and
    <code>&lt;resource-env-ref&gt;</code> elements in the web application
    deployment descriptor.  You <strong>MUST</strong> also define
    <a href="#Resource Parameters">Resource Parameters</a>
    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.</p>

    <p>For example, you can create a resource definition like this:</p>
<source>
&lt;DefaultContext ...&gt;
  ...
  &lt;Resource name="jdbc/EmployeeDB" auth="Container"
            type="javax.sql.DataSource"
     description="Employees Database for HR Applications"/&gt;
  ...
&lt;/DefaultContext&gt;
</source>

    <p>This is equivalent to the inclusion of the following element in the
    web application deployment descriptor (<code>/WEB-INF/web.xml</code>):</p>
<source>
&lt;resource-ref&gt;
  &lt;description&gt;Employees Database for HR Applications&lt;/description&gt;
  &lt;res-ref-name&gt;jdbc/EmployeeDB&lt;/res-ref-name&gt;
  &lt;res-ref-type&gt;javax.sql.DataSource&lt;/res-ref-type&gt;
  &lt;res-auth&gt;Container&lt;/res-auth&gt;
&lt;/resource-ref&gt;
</source>

    <p>but does <em>not</em> require modification of the deployment
    descriptor to customize this value.</p>

    <p>The valid attriutes for a <code>&lt;Resource&gt;</code> element
    are as follows:</p>

    <attributes>

      <attribute name="auth" required="false">
        <p>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
        <code>Application</code> or <code>Container</code>.  This
        attribute is <strong>required</strong> if the web application
        will use a <code>&lt;resource-ref&gt;</code> element in the web
        application deployment descriptor, but is optional if the
        application uses a <code>&lt;resource-env-ref&gt;</code> instead.</p>
      </attribute>

      <attribute name="description" required="false">
        <p>Optional, human-readable description of this resource.</p>
      </attribute>

      <attribute name="name" required="true">
        <p>The name of the resource to be created, relative to the
        <code>java:comp/env</code> context.</p>
      </attribute>

      <attribute name="scope" required="false">
        <p>Specify whether connections obtained through this resource
        manager can be shared.  The value of this attribute must be
        <code>Shareable</code> or <code>Unshareable</code>.  By default,
        connections are assumed to be shareable.</p>
      </attribute>

      <attribute name="type" required="true">
        <p>The fully qualified Java class name expected by the web
        application when it performs a lookup for this resource.</p>
      </attribute>

    </attributes>


  </subsection>


  <subsection name="Resource Parameters">

    <p>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
    <strong>MUST</strong> define resource parameters for every resource name
    that is specified by a <code>&lt;Resource&gt;</code> element inside a
    <code>&lt;Context&gt;</code> or <code>&lt;DefaultContext&gt;</code>
    element in <code>$CATALINA_HOME/conf/server.xml</code>, and/or for every
    name declared in a <code>&lt;resource-ref&gt;</code> or
    <code>&lt;resource-env-ref&gt;</code> element in the web application
    deployment descriptor, before that resource can be successfully
    accessed.</p>

    <p>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 <code>lookup()</code>
    call.</p>

    <p>The resource parameters for a JDBC data source might look something
    like this:</p>
<source>
&lt;DefaultContext ...&gt;
  ...
  &lt;ResourceParams name="jdbc/EmployeeDB"&gt;
    &lt;parameter&gt;
      &lt;name&gt;driverClassName&lt;/name&gt;
      &lt;value&gt;org.hsql.jdbcDriver&lt;/value&gt;
    &lt;/parameter&gt;
    &lt;parameter&gt;
      &lt;name&gt;driverName&lt;/name&gt;
      &lt;/value&gt;jdbc:HypersonicSQL:database&lt;/value&gt;
    &lt;/parameter&gt;
    &lt;parameter&gt;
      &lt;name&gt;user&lt;/name&gt;
      &lt;value&gt;dbusername&lt;/value&gt;
    &lt;/parameter&gt;
    &lt;parameter&gt;
      &lt;name&gt;password&lt;/name&gt;
      &lt;value&gt;dbpassword&lt;/value&gt;
    &lt;/parameter&gt;
  &lt;/ResourceParams&gt;
  ...
&lt;/DefaultContext&gt;
</source>

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

    <p>The valid attributes of a <code>&lt;ResourceParams&gt;</code> element
    are as follows:</p>

    <attributes>

      <attribute name="name" required="true">
        <p>The name of the resource being configured, relative to the
        <code>java:comp/env</code> contxt.  This name <strong>MUST</strong>
        match the name of a resource defined by a <code>&lt;Resource&gt;</code>
        element in <code>$CATALINA_HOME/conf/server.xml</code>, and/or
        referenced in a <code>&lt;resource-ref&gt;</code> or
        <code>&lt;resource-env-ref&gt;</code> element in the web application
        deployment descriptor.</p>
      </attribute>

    </attributes>

  </subsection>


  <subsection name="Resource Links">

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

    <p>For example, you can create a resource link like this:</p>
<source>
&lt;DefaultContext ...&gt;
  ...
  &lt;ResourceLink name="linkToGlobalResource"
            global="simpleValue"
            type="java.lang.Integer"
  ...
&lt;/DefaultContext&gt;
</source>

    <p>The valid attributes for a <code>&lt;ResourceLink&gt;</code> element
    are as follows:</p>

    <attributes>

      <attribute name="global" required="true">
        <p>The name of the linked global resource in the 
        gobal JNDI context.</p>
      </attribute>

      <attribute name="name" required="true">
        <p>The name of the resource link to be created, relative to the
        <code>java:comp/env</code> context.</p>
      </attribute>

      <attribute name="type" required="true">
        <p>The fully qualified Java class name expected by the web
        application when it performs a lookup for this resource link.</p>
      </attribute>

    </attributes>

  </subsection>

</section>


</body>


</document>
