Subversion Repositories Integrator Subversion

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
771 blopes 1 
<!DOCTYPE html SYSTEM "about:legacy-compat">
2 
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="../images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 Configuration Reference (9.0.112) - The Resources Component</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="../images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="../images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9 Configuration Reference</h1><div class="versionInfo">
3 
            Version 9.0.112,
4 
            <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>Top Level Elements</h2><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul></div><div><h2>Executors</h2><ul><li><a href="executor.html">Executor</a></li></ul></div><div><h2>Connectors</h2><ul><li><a href="http.html">HTTP/1.1</a></li><li><a href="http2.html">HTTP/2</a></li><li><a href="ajp.html">AJP</a></li></ul></div><div><h2>Containers</h2><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul></div><div><h2>Nested Components</h2><ul><li><a href="cookie-processor.html">CookieProcessor</a></li><li><a href="credentialhandler.html">CredentialHandler</a></li><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="jar-scan-filter.html">JarScanFilter</a></li><li><a href="listeners.html">Listeners</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="sessionidgenerator.html">SessionIdGenerator</a></li><li><a href="valve.html">Valve</a></li></ul></div><div><h2>Cluster Elements</h2><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul></div><div><h2>web.xml</h2><ul><li><a href="filter.html">Filter</a></li></ul></div><div><h2>Other</h2><ul><li><a href="runtime-attributes.html">Runtime attributes</a></li><li><a href="systemprops.html">System properties</a></li><li><a href="jaspic.html">JASPIC</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>The Resources Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
5 
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#Standard_Implementation">Standard Implementation</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a></li></ul>
6 
</div><h3 id="Introduction">Introduction</h3><div class="text">
7 
 
8 
  <p>The <strong>Resources</strong> element represents all the resources
9 
  available to the web application. This includes classes, JAR files, HTML, JSPs
10 
  and any other files that contribute to the web application. Implementations
11 
  are provided to use directories, JAR files and WARs as the source of these
12 
  resources and the resources implementation may be extended to provide support
13 
  for files stored in other forms such as in a database or a versioned
14 
  repository.</p>
15 
 
16 
  <p>Resources are cached by default.</p>
17 
 
18 
  <p><strong>Note: Running a webapp with non-filesystem based
19 
  Resources implementations is only possible when the webapp does not
20 
  rely on direct filesystem access to its own resources, and uses the methods
21 
  in the ServletContext interface to access them.</strong></p>
22 
 
23 
  <p>A Resources element MAY be nested inside a
24 
  <a href="context.html">Context</a> component.  If it is not included,
25 
  a default filesystem based Resources will be created automatically,
26 
  which is sufficient for most requirements.</p>
27 
 
28 
</div><h3 id="Attributes">Attributes</h3><div class="text">
29 
 
30 
  <div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
31 
 
32 
    <p>All implementations of <strong>Resources</strong> support the following
33 
    attributes:</p>
34 
 
35 
    <table class="defaultTable"><tr><th style="width: 15%;">
36 
          Attribute
37 
        </th><th style="width: 85%;">
38 
          Description
39 
        </th></tr><tr id="Attributes_Common Attributes_allowLinking"><td><code class="attributeName">allowLinking</code></td><td>
40 
        <p>If the value of this flag is <code>true</code>, symlinks will be
41 
        allowed inside the web application, pointing to resources inside or
42 
        outside the web application base path. If not specified, the default
43 
        value of the flag is <code>false</code>.</p>
44 
        <p><b>NOTE: This flag MUST NOT be set to true on the Windows platform
45 
        (or any other OS which does not have a case sensitive filesystem),
46 
        as it will disable case sensitivity checks, allowing JSP source code
47 
        disclosure, among other security problems.</b></p>
48 
      </td></tr><tr id="Attributes_Common Attributes_archiveIndexStrategy"><td><code class="attributeName">archiveIndexStrategy</code></td><td>
49 
        <p>If this is <code>simple</code> then a hash map will be used for
50 
        JAR archive lookups, unless useBloomFilterForArchives in
51 
        <a href="context.html">Context</a> is explicitly defined.</p>
52 
        <p>If this is <code>bloom</code> then a bloom filter will be used to
53 
        speed up archive lookups. This can be beneficial to the deployment
54 
        speed to web applications that contain very large amount of JARs.</p>
55 
        <p>If this is <code>purged</code> then a bloom filter will be used to
56 
        speed up archive lookups, but can be purged at runtime. It is recommended
57 
        to use <code>bloom</code> to avoid reinitializing the bloom filters.</p>
58 
        <p>If not specified, the default value of <code>simple</code> will be
59 
        used.</p>
60 
      </td></tr><tr id="Attributes_Common Attributes_cacheMaxSize"><td><code class="attributeName">cacheMaxSize</code></td><td>
61 
        <p>The maximum size of the static resource cache in kilobytes.
62 
        If not specified, the default value is <code>10240</code>
63 
        (10 MiB). This value may be changed while the web application is
64 
        running (e.g. via JMX). If the cache is using more memory than the new
65 
        limit the cache will attempt to reduce in size over time to meet the
66 
        new limit. If necessary, <strong>cacheObjectMaxSize</strong> will be
67 
        reduced to ensure that it is no larger than
68 
        <code>cacheMaxSize/20</code>.</p>
69 
      </td></tr><tr id="Attributes_Common Attributes_cacheObjectMaxSize"><td><code class="attributeName">cacheObjectMaxSize</code></td><td>
70 
        <p>Maximum size of the static resource that will be placed in the cache.
71 
        If not specified, the default value is <code>512</code>
72 
        (512 kilobytes). If this value is greater than
73 
        <code>cacheMaxSize/20</code> it will be reduced to
74 
        <code>cacheMaxSize/20</code>. This value may be changed while the web
75 
        application is running (e.g. via JMX).</p>
76 
      </td></tr><tr id="Attributes_Common Attributes_cacheTtl"><td><code class="attributeName">cacheTtl</code></td><td>
77 
        <p>The amount of time in milliseconds between the revalidation of cache
78 
        entries. If not specified, the default value is <code>5000</code> (5
79 
        seconds). This value may be changed while the web application is running
80 
        (e.g. via JMX). When a resource is cached it will inherit the TTL in
81 
        force at the time it was cached and retain that TTL until the resource
82 
        is evicted from the cache regardless of any subsequent changes that may
83 
        be made to this attribute.</p>
84 
      </td></tr><tr id="Attributes_Common Attributes_cachingAllowed"><td><code class="attributeName">cachingAllowed</code></td><td>
85 
        <p>If the value of this flag is <code>true</code>, the cache for static
86 
        resources will be used. If not specified, the default value
87 
        of the flag is <code>true</code>. This value may be changed while the
88 
        web application is running (e.g. via JMX). When the cache is disabled
89 
        any resources currently in the cache are cleared from the cache.</p>
90 
      </td></tr><tr id="Attributes_Common Attributes_className"><td><code class="attributeName">className</code></td><td>
91 
        <p>Java class name of the implementation to use. This class must
92 
        implement the <code>org.apache.catalina.WebResourceRoot</code>
93 
        interface. If not specified, the standard value (defined below) will be
94 
        used.</p>
95 
      </td></tr><tr id="Attributes_Common Attributes_readOnly"><td><code class="attributeName">readOnly</code></td><td>
96 
        <p>If the value of this flag is <code>true</code>, then writing will
97 
        be disabled on the main resource set. The default value is
98 
        <code>false</code>.</p>
99 
      </td></tr><tr id="Attributes_Common Attributes_trackLockedFiles"><td><code class="attributeName">trackLockedFiles</code></td><td>
100 
        <p>Controls whether the track locked files feature is enabled. If
101 
        enabled, all calls to methods that return objects that lock a file and
102 
        need to be closed to release that lock (e.g.
103 
        <code>ServletContext.getResourceAsStream()</code>) will perform a number
104 
        of additional tasks.</p>
105 
        <ul>
106 
          <li>The stack trace at the point where the method was called will be
107 
          recorded and associated with the returned object.</li>
108 
          <li>The returned object will be wrapped so that the point where
109 
          close() (or equivalent) is called to release the resources can be
110 
          detected. Tracking of the object will cease once the resources have
111 
          been released.</li>
112 
          <li>All remaining locked resources on web application shutdown will be
113 
          logged and then closed.</li>
114 
        </ul>
115 
        <p>If not specified, the default value of <code>false</code> will be
116 
        used.</p>
117 
      </td></tr></table>
118 
 
119 
  </div></div>
120 
 
121 
 
122 
  <div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text">
123 
 
124 
    <h3>Standard Root Implementation</h3>
125 
 
126 
    <p>The standard implementation of <strong>Resources</strong> is
127 
    <strong>org.apache.catalina.webresources.StandardRoot</strong>. It does not
128 
    support any additional attributes.</p>
129 
 
130 
    <h3>Extracting Root Implementation</h3>
131 
 
132 
    <p>The extracting implementation of <strong>Resources</strong> is
133 
    <strong>org.apache.catalina.webresources.ExtractingRoot</strong>. It does not
134 
    support any additional attributes.</p>
135 
 
136 
    <p>When deploying web applications as packed WAR files, the extracting root
137 
    will extract any JAR files from <code>/WEB-INF/lib</code> to a
138 
    <code>application-jars</code> directory located in the web
139 
    application's working directory. These extracted JARs will be removed
140 
    when the web application stops.</p>
141 
 
142 
    <p>Extracting JAR files from a packed WAR may provide a performance
143 
    improvement, particularly at web application start when JAR scanning is
144 
    required by the application.</p>
145 
 
146 
  </div></div>
147 
 
148 
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
149 
 
150 
  <p>A web application's main resources are defined by the
151 
  <strong>docBase</strong> defined for the <a href="context.html">Context</a>.
152 
  Additional configuration settings and/or resources may be made available to
153 
  the web application by defining one or more nested components.</p>
154 
 
155 
  <h3>PreResources</h3>
156 
 
157 
  <p>PreResources are searched before the main resources. They will be searched
158 
  in the order they are defined. To configure PreResources, nest a
159 
  &lt;PreResources&gt; element inside the &lt;Resources&gt; element with the
160 
  following attributes:</p>
161 
 
162 
  <table class="defaultTable"><tr><th style="width: 15%;">
163 
          Attribute
164 
        </th><th style="width: 85%;">
165 
          Description
166 
        </th></tr><tr id="_Nested Components_allowLinking"><td><code class="attributeName">allowLinking</code></td><td>
167 
      <p>If the value of this flag is <code>true</code>, symlinks will be
168 
      allowed inside the web resource set, pointing to resources inside or
169 
      outside the web application base path. If not specified, the default
170 
      value of the flag is taken from the outer Resources implementation.</p>
171 
      <p>This attribute is only available for <code>DirResourceSet</code> and
172 
      <code>FileResourceSet</code>.</p>
173 
      <p><b>NOTE: This flag MUST NOT be set to true on the Windows platform
174 
      (or any other OS which does not have a case sensitive filesystem),
175 
      as it will disable case sensitivity checks, allowing JSP source code
176 
      disclosure, among other security problems.</b></p>
177 
    </td></tr><tr id="_Nested Components_base"><td><strong><code class="attributeName">base</code></strong></td><td>
178 
      <p>Identifies where the resources to be used are located. This attribute
179 
      is required by the <code>org.apache.catalina.WebResourceSet</code>
180 
      implementations provided by Tomcat and should specify the absolute path to
181 
      the file, directory or JAR where the resources are located. Custom
182 
      implementations may not require it.</p>
183 
    </td></tr><tr id="_Nested Components_className"><td><strong><code class="attributeName">className</code></strong></td><td>
184 
      <p>Java class name of the implementation to use. This class must
185 
      implement the <code>org.apache.catalina.WebResourceSet</code> interface.
186 
      Tomcat provides three standard implementations:
187 
      <code>org.apache.catalina.webresources.DirResourceSet</code>,
188 
      <code>org.apache.catalina.webresources.FileResourceSet</code> and
189 
      <code>org.apache.catalina.webresources.JarResourceSet</code>. Custom
190 
      implementations may also be used.
191 
      </p>
192 
    </td></tr><tr id="_Nested Components_internalPath"><td><code class="attributeName">internalPath</code></td><td>
193 
      <p>Identifies the path within the <strong>base</strong> where the
194 
      resources are to be found. This is typically only used with JAR files when
195 
      the resources are not located at the root of the JAR as is the case with
196 
      resource JARs. This attribute is required by the
197 
      <code>org.apache.catalina.WebResourceSet</code> implementations provided
198 
      by Tomcat and must start with '/'. Custom implementations may not require
199 
      it. If not specified, the default value '/' will be used.</p>
200 
    </td></tr><tr id="_Nested Components_readOnly"><td><code class="attributeName">readOnly</code></td><td>
201 
      <p>If <code>true</code>, resources within this resource set may not be
202 
      deleted, created or modified. For instance of
203 
      <code>org.apache.catalina.webresources.JarResourceSet</code>, this
204 
      attribute is hard-coded to <code>true</code> and may not be changed. For
205 
      instances of <code>org.apache.catalina.webresources.DirResourceSet</code>
206 
      and <code>org.apache.catalina.webresources.FileResourceSet</code> the
207 
      default value of this attribute is <code>false</code>.</p>
208 
    </td></tr><tr id="_Nested Components_webAppMount"><td><code class="attributeName">webAppMount</code></td><td>
209 
      <p>Identifies the path within the web application that these resources
210 
      will be made available. For the
211 
      <code>org.apache.catalina.WebResourceSet</code> implementations provided
212 
      by Tomcat, this attribute is required and must start with '/'. Custom
213 
      implementations may not require it. If not specified, the default value of
214 
      '/' will be used.</p>
215 
    </td></tr></table>
216 
 
217 
  <h3>JAR resources</h3>
218 
 
219 
  <p>JarResources are searched after the main resources but before the
220 
  PostResources. They will be searched in the order they are defined. To
221 
  configure JarResources, nest a &lt;JarResources&gt; element inside the
222 
  &lt;Resources&gt; element. The configuration attributes are the same as for
223 
  <strong>PreResources</strong>.
224 
  </p>
225 
 
226 
  <p>During web application start, the JAR scanning process checks scanned JARs
227 
  for content under <code>/META-INF/resources</code>. Where found, this static
228 
  content is added to the JarResources.
229 
  </p>
230 
 
231 
  <h3>Post-resources</h3>
232 
 
233 
  <p>PostResources are searched after the resource JARs. They will be searched
234 
  in the order they are defined. To configure PostResources, nest a
235 
  &lt;PostResources&gt; element inside the &lt;Resources&gt; element. The
236 
  configuration attributes are the same as for <strong>PreResources</strong>.
237 
  </p>
238 
 
239 
  <h3>Ordering</h3>
240 
 
241 
  <p>In addition to the sets of resources described above, the standard
242 
  implementation also maintains ClassResources which represent the classes
243 
  contained in the JAR files mapped to <code>/WEB-INF/classes</code>. This
244 
  allows other components to search for classes with a single call rather than
245 
  one call to search <code>/WEB-INF/classes</code> followed by another to search
246 
  the JARs in <code>/WEB-INF/lib</code>. The ClassResources are populated
247 
  from the JARs mapped to <code>/WEB-INF/lib</code> when the web application
248 
  starts.</p>
249 
 
250 
  <p>Therefore, the complete search order is:</p>
251 
  <ul>
252 
    <li>PreResources</li>
253 
    <li>MainResources</li>
254 
    <li>ClassResources</li>
255 
    <li>JarResources</li>
256 
    <li>PostResources</li>
257 
  </ul>
258 
 
259 
  <p>The population of ClassResources and JarResources at web application start
260 
  means that care needs to be taken to add JAR based resources correctly to
261 
  obtain the desired behaviour. Consider the following example:</p>
262 
 
263 
  <div class="codeBox"><pre><code>&lt;Resources&gt;
264 
  &lt;PostResources base="D:\Projects\external\classes"
265 
                 className="org.apache.catalina.webresources.DirResourceSet"
266 
                 webAppMount="/WEB-INF/classes"/&gt;
267 
  &lt;PostResources base="D:\Projects\lib\library1.jar"
268 
                 className="org.apache.catalina.webresources.FileResourceSet"
269 
                 webAppMount="/WEB-INF/lib/library1.jar"/&gt;
270 
&lt;/Resources&gt;</code></pre></div>
271 
 
272 
  <p>Since both resources are PostResources, it might be expected that
273 
  <code>D:\Projects\external\classes</code> will be searched for classes before
274 
  <code>D:\Projects\lib\library1.jar</code>. However, by adding the JAR using a
275 
  <code>FileResourceSet</code>, the JAR is mapped to <code>/WEB-INF/lib</code>
276 
  and will be processed at application start along with the other JARs in
277 
  <code>/WEB-INF/lib</code>. The classes from the JAR file will be added to the
278 
  ClassResources which means they will be searched before the classes from
279 
  <code>D:\Projects\external\classes</code>. If the desired behaviour is that
280 
  <code>D:\Projects\external\classes</code> is searched before
281 
  <code>D:\Projects\lib\library1.jar</code> then a slightly different
282 
  configuration is required:</p>
283 
 
284 
  <div class="codeBox"><pre><code>&lt;Resources&gt;
285 
  &lt;PostResources base="D:\Projects\external\classes"
286 
                 className="org.apache.catalina.webresources.DirResourceSet"
287 
                 webAppMount="/WEB-INF/classes"/&gt;
288 
  &lt;PostResources base="D:\Projects\lib\library1.jar"
289 
                 className="org.apache.catalina.webresources.JarResourceSet"
290 
                 webAppMount="/WEB-INF/classes"/&gt;
291 
&lt;/Resources&gt;</code></pre></div>
292 
 
293 
  <p>In short, the JAR file should be added as a <code>JarResourceSet</code>
294 
  mapped to <code>/WEB-INF/classes</code> rather than using a
295 
  <code>FileResourceSet</code> mapped to <code>/WEB-INF/lib</code>.
296 
  </p>
297 
 
298 
  <h3>Cache Strategy</h3>
299 
 
300 
  <p>Additional control over the caching of static resources can be obtained by
301 
     configuring a custom cache strategy. To configure a custom cache strategy,
302 
     nest a &lt;CacheStrategy&gt; element inside the &lt;Resources&gt; element
303 
     with the following attributes:</p>
304 
 
305 
  <table class="defaultTable"><tr><th style="width: 15%;">
306 
          Attribute
307 
        </th><th style="width: 85%;">
308 
          Description
309 
        </th></tr><tr id="_Nested Components_className"><td><strong><code class="attributeName">className</code></strong></td><td>
310 
      <p>Java class name of the implementation to use. This class must implement
311 
      the <code>org.apache.catalina.WebResourceRoot$CacheStrategy</code>
312 
      interface.</p>
313 
    </td></tr></table>
314 
 
315 
</div><h3 id="Special_Features">Special Features</h3><div class="text">
316 
 
317 
  <p>No special features are associated with a <strong>Resources</strong>
318 
  element.</p>
319 
 
320 
</div></div></div></div></div><footer><div id="footer">
321 
    Copyright &copy; 1999-2025, The Apache Software Foundation
322 
    <br>
323 
    Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
324 
    are either registered trademarks or trademarks of the Apache Software
325 
    Foundation.
326 
    </div></footer></div></body></html>