| <?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 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 megabytes). 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"> |
| |
| <p>The standard implementation of <strong>Resources</strong> is |
| <strong>org.apache.catalina.webresources.StandardRoot</strong>, and |
| is configured by its parent Context element.</p> |
| |
| </subsection> |
| |
| </section> |
| |
| |
| <section name="Nested Components"> |
| |
| <p>A web application's main resources are defined by the |
| <strong>docBase</strong> defined for the <a href="context.html">Context</a>. |
| Additional 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 |
| <PreResources> element inside the <Resources> 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 <JarResources> element inside the |
| <Resources> element. The configuration attributes are the same as for |
| <strong>PreResources</strong>. |
| </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 |
| <PostResources> element inside the <Resources> element. The |
| configuration attributes are the same as for <strong>PreResources</strong>. |
| </p> |
| |
| </section> |
| |
| |
| <section name="Special Features"> |
| |
| <p>No special features are associated with a <strong>Resources</strong> |
| element.</p> |
| |
| </section> |
| |
| |
| </body> |
| |
| |
| </document> |