341 lines
14 KiB
XML
341 lines
14 KiB
XML
<?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 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">
|
|
|
|
<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'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'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>
|
|
|
|
<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
|
|
<PostResources> element inside the <Resources> 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>
|
|
|
|
</section>
|
|
|
|
|
|
<section name="Special Features">
|
|
|
|
<p>No special features are associated with a <strong>Resources</strong>
|
|
element.</p>
|
|
|
|
</section>
|
|
|
|
|
|
</body>
|
|
|
|
|
|
</document>
|