<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document [
  <!ENTITY project SYSTEM "project.xml">
]>
<document url="resources.html">

  &project;

  <properties>
    <title>The Resources Component</title>
  </properties>

<body>

<section name="Table of Contents">
<toc />
</section>

<section name="Introduction">

  <p>The <strong>Resources</strong> element represents all the resources
  available to the web application. This includes classes, JAR files, HTML, JSPs
  and any other files that contribute to the web application. Implementations
  are provided to use directories, JAR files and WARs as the source of these
  resources and the resources implementation may be extended to provide support
  for files stored in other forms such as in a database or a versioned
  repository.</p>

  <p>Resources are cached by default.</p>

  <p><strong>Note: Running a webapp with non-filesystem based
  Resources implementations is only possible when the webapp does not
  rely on direct filesystem access to its own resources, and uses the methods
  in the ServletContext interface to access them.</strong></p>

  <p>A Resources element MAY be nested inside a
  <a href="context.html">Context</a> component.  If it is not included,
  a default filesystem based Resources will be created automatically,
  which is sufficient for most requirements.</p>

</section>


<section name="Attributes">

  <subsection name="Common Attributes">

    <p>All implementations of <strong>Resources</strong> support the following
    attributes:</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 inside or
        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>The maximum size of the static resource cache in kilobytes.
        If not specified, the default value is <code>10240</code>
        (10 MiB). This value may be changed while the web application is
        running (e.g. via JMX). If the cache is using more memory than the new
        limit the cache will attempt to reduce in size over time to meet the
        new limit. If necessary, <strong>cacheObjectMaxSize</strong> will be
        reduced to ensure that it is no larger than
        <code>cacheMaxSize/20</code>.</p>
      </attribute>

      <attribute name="cacheObjectMaxSize" required="false">
        <p>Maximum size of the static resource that will be placed in the cache.
        If not specified, the default value is <code>512</code>
        (512 kilobytes). If this value is greater than
        <code>cacheMaxSize/20</code> it will be reduced to
        <code>cacheMaxSize/20</code>. This value may be changed while the web
        application is running (e.g. via JMX).</p>
      </attribute>

      <attribute name="cacheTtl" required="false">
        <p>The amount of time in milliseconds between the revalidation of cache
        entries. If not specified, the default value is <code>5000</code> (5
        seconds). This value may be changed while the web application is running
        (e.g. via JMX). When a resource is cached it will inherit the TTL in
        force at the time it was cached and retain that TTL until the resource
        is evicted from the cache regardless of any subsequent changes that may
        be made to this attribute.</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>. This value may be changed while the
        web application is running (e.g. via JMX). When the cache is disabled
        any resources currently in the cache are cleared from the cache.</p>
      </attribute>

      <attribute name="className" required="false">
        <p>Java class name of the implementation to use. This class must
        implement the <code>org.apache.catalina.WebResourceRoot</code>
        interface. If not specified, the standard value (defined below) will be
        used.</p>
      </attribute>

      <attribute name="trackLockedFiles" required="false">
        <p>Controls whether the track locked files feature is enabled. If
        enabled, all calls to methods that return objects that lock a file and
        need to be closed to release that lock (e.g.
        <code>ServletContext.getResourceAsStream()</code>) will perform a number
        of additional tasks.</p>
        <ul>
          <li>The stack trace at the point where the method was called will be
          recorded and associated with the returned object.</li>
          <li>The returned object will be wrapped so that the point where
          close() (or equivalent) is called to release the resources can be
          detected. Tracking of the object will cease once the resources have
          been released.</li>
          <li>All remaining locked resources on web application shutdown will be
          logged and then closed.</li>
        </ul>
        <p>If not specified, the default value of <code>false</code> will be
        used.</p>
      </attribute>

    </attributes>

  </subsection>


  <subsection name="Standard Implementation">

    <h3>Standard Root Implementation</h3>

    <p>The standard implementation of <strong>Resources</strong> is
    <strong>org.apache.catalina.webresources.StandardRoot</strong>. It does not
    support any additional attributes.</p>

    <h3>Extracting Root Implementation</h3>

    <p>The extracting implementation of <strong>Resources</strong> is
    <strong>org.apache.catalina.webresources.ExtractingRoot</strong>. It does not
    support any additional attributes.</p>

    <p>When deploying web applications as packed WAR files, the extracting root
    will extract any JAR files from <code>/WEB-INF/lib</code> to a
    <code>application-jars</code> directory located in the web
    application&apos;s working directory. These extracted JARs will be removed
    when the web application stops.</p>

    <p>Extracting JAR files from a packed WAR may provide a performance
    improvement, particularly at web application start when JAR scanning is
    required by the application.</p>

  </subsection>

</section>


<section name="Nested Components">

  <p>A web application&apos;s main resources are defined by the
  <strong>docBase</strong> defined for the <a href="context.html">Context</a>.
  Additional configuration settings and/or resources may be made available to
  the web application by defining one or more nested components.</p>

  <h3>PreResources</h3>

  <p>PreResources are searched before the main resources. They will be searched
  in the order they are defined. To configure PreResources, nest a
  &lt;PreResources&gt; element inside the &lt;Resources&gt; element with the
  following attributes:</p>

  <attributes>

    <attribute name="base" required="true">
      <p>Identifies where the resources to be used are located. This attribute
      is required by the <code>org.apache.catalina.WebResourceSet</code>
      implementations provided by Tomcat and should specify the absolute path to
      the file, directory or JAR where the resources are located. Custom
      implementations may not require it.</p>
    </attribute>

    <attribute name="className" required="true">
      <p>Java class name of the implementation to use. This class must
      implement the <code>org.apache.catalina.WebResourceSet</code> interface.
      Tomcat provides three standard implementations:
      <code>org.apache.catalina.webresources.DirResourceSet</code>,
      <code>org.apache.catalina.webresources.FileResourceSet</code> and
      <code>org.apache.catalina.webresources.JarResourceSet</code>. Custom
      implementations may also be used.
      </p>
    </attribute>

    <attribute name="internalPath" required="false">
      <p>Identifies the path within the <strong>base</strong> where the
      resources are to be found. This is typically only used with JAR files when
      the resources are not located at the root of the JAR as is the case with
      resource JARs. This attribute is required by the
      <code>org.apache.catalina.WebResourceSet</code> implementations provided
      by Tomcat and must start with '/'. Custom implementations may not require
      it. If not specified, the default value '/' will be used.</p>
    </attribute>

    <attribute name="readOnly" required="false">
      <p>If <code>true</code>, resources within this resource set may not be
      deleted, created or modified. For instance of
      <code>org.apache.catalina.webresources.JarResourceSet</code>, this
      attribute is hard-coded to <code>true</code> and may not be changed. For
      instances of <code>org.apache.catalina.webresources.DirResourceSet</code>
      and <code>org.apache.catalina.webresources.FileResourceSet</code> the
      default value of this attribute is <code>false</code>.</p>
    </attribute>

    <attribute name="webAppMount" required="false">
      <p>Identifies the path within the web application that these resources
      will be made available. For the
      <code>org.apache.catalina.WebResourceSet</code> implementations provided
      by Tomcat, this attribute is required and must start with '/'. Custom
      implementations may not require it. If not specified, the default value of
      '/' will be used.</p>
    </attribute>

  </attributes>

  <h3>JAR resources</h3>

  <p>JarResources are searched after the main resources but before the
  PostResources. They will be searched in the order they are defined. To
  configure JarResources, nest a &lt;JarResources&gt; element inside the
  &lt;Resources&gt; element. The configuration attributes are the same as for
  <strong>PreResources</strong>.
  </p>

  <p>During web application start, the JAR scanning process checks scanned JARs
  for content under <code>/META-INF/resources</code>. Where found, this static
  content is added to the JarResources.
  </p>

  <h3>Post-resources</h3>

  <p>PostResources are searched after the resource JARs. They will be searched
  in the order they are defined. To configure PostResources, nest a
  &lt;PostResources&gt; element inside the &lt;Resources&gt; element. The
  configuration attributes are the same as for <strong>PreResources</strong>.
  </p>

  <h3>Ordering</h3>

  <p>In addition to the sets of resources described above, the standard
  implementation also maintains ClassResources which represent the classes
  contained in the JAR files mapped to <code>/WEB-INF/classes</code>. This
  allows other components to search for classes with a single call rather than
  one call to search <code>/WEB-INF/classes</code> followed by another to search
  the JARs in <code>/WEB-INF/lib</code>. The ClassResources are populated
  from the JARs mapped to <code>/WEB-INF/lib</code> when the web application
  starts.</p>

  <p>Therefore, the complete search order is:</p>
  <ul>
    <li>PreResources</li>
    <li>MainResources</li>
    <li>ClassResources</li>
    <li>JarResources</li>
    <li>PostResources</li>
  </ul>

  <p>The population of ClassResources and JarResources at web application start
  means that care needs to be taken to add JAR based resources correctly to
  obtain the desired behaviour. Consider the following example:</p>

  <source><![CDATA[<Resources>
  <PostResources base="D:\Projects\external\classes"
                 className="org.apache.catalina.webresources.DirResourceSet"
                 webAppMount="/WEB-INF/classes"/>
  <PostResources base="D:\Projects\lib\library1.jar"
                 className="org.apache.catalina.webresources.FileResourceSet"
                 webAppMount="/WEB-INF/lib/library1.jar"/>
</Resources>]]></source>

  <p>Since both resources are PostResources, it might be expected that
  <code>D:\Projects\external\classes</code> will be searched for classes before
  <code>D:\Projects\lib\library1.jar</code>. However, by adding the JAR using a
  <code>FileResourceSet</code>, the JAR is mapped to <code>/WEB-INF/lib</code>
  and will be processed at application start along with the other JARs in
  <code>/WEB-INF/lib</code>. The classes from the JAR file will be added to the
  ClassResources which means they will be searched before the classes from
  <code>D:\Projects\external\classes</code>. If the desired behaviour is that
  <code>D:\Projects\external\classes</code> is searched before
  <code>D:\Projects\lib\library1.jar</code> then a slightly different
  configuration is required:</p>

  <source><![CDATA[<Resources>
  <PostResources base="D:\Projects\external\classes"
                 className="org.apache.catalina.webresources.DirResourceSet"
                 webAppMount="/WEB-INF/classes"/>
  <PostResources base="D:\Projects\lib\library1.jar"
                 className="org.apache.catalina.webresources.JarResourceSet"
                 webAppMount="/WEB-INF/classes"/>
</Resources>]]></source>

  <p>In short, the JAR file should be added as a <code>JarResourceSet</code>
  mapped to <code>/WEB-INF/classes</code> rather than using a
  <code>FileResourceSet</code> mapped to <code>/WEB-INF/lib</code>.
  </p>

  <h3>Cache Strategy</h3>

  <p>Additional control over the caching of static resources can be obtained by
     configuring a custom cache strategy. To configure a custom cache strategy,
     nest a &lt;CacheStrategy&gt; element inside the &lt;Resources&gt; element
     with the following attributes:</p>

  <attributes>

    <attribute name="className" required="true">
      <p>Java class name of the implementation to use. This class must implement
      the <code>org.apache.catalina.WebResourceRoot$CacheStrategy</code>
      interface.</p>
    </attribute>

  </attributes>

</section>


<section name="Special Features">

  <p>No special features are associated with a <strong>Resources</strong>
  element.</p>

</section>


</body>


</document>
