web.xml

Other

The Resources Component

Table of Contents

Introduction

The Resources 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.

Resources are cached by default.

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.

A Resources element MAY be nested inside a
Context component. If it is not included,
a default filesystem based Resources will be created automatically,
which is sufficient for most requirements.

Attributes

Common Attributes

All implementations of Resources support the following
attributes:

Attribute

Description

allowLinking

If the value of this flag is true, 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 false.

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.

cacheMaxSize

The maximum size of the static resource cache in kilobytes.
If not specified, the default value is 10240
(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, cacheObjectMaxSize will be
reduced to ensure that it is no larger than
cacheMaxSize/20.

cacheObjectMaxSize

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

cacheTtl

The amount of time in milliseconds between the revalidation of cache
entries. If not specified, the default value is 5000 (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.

cachingAllowed

If the value of this flag is true, the cache for static
resources will be used. If not specified, the default value
of the flag is true. 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.

className

Java class name of the implementation to use. This class must
implement the org.apache.catalina.WebResourceRoot
interface. If not specified, the standard value (defined below) will be
used.

trackLockedFiles

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.
ServletContext.getResourceAsStream()) will perform a number
of additional tasks.

The stack trace at the point where the method was called will be
recorded and associated with the returned object.

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.

All remaining locked resources on web application shutdown will be
logged and then closed.

If not specified, the default value of false will be
used.

Standard Implementation

Standard Root Implementation

The standard implementation of Resources is
org.apache.catalina.webresources.StandardRoot. It does not
support any additional attributes.

Extracting Root Implementation

The extracting implementation of Resources is
org.apache.catalina.webresources.ExtractingRoot. It does not
support any additional attributes.

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

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.

Nested Components

A web application's main resources are defined by the
docBase defined for the Context.
Additional resources may be made available to the web application by defining
one or more nested components.

PreResources

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:

Attribute

Description

base

Identifies where the resources to be used are located. This attribute
is required by the org.apache.catalina.WebResourceSet
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.

className

Java class name of the implementation to use. This class must
implement the org.apache.catalina.WebResourceSet interface.
Tomcat provides three standard implementations:
org.apache.catalina.webresources.DirResourceSet,
org.apache.catalina.webresources.FileResourceSet and
org.apache.catalina.webresources.JarResourceSet. Custom
implementations may also be used.

internalPath

Identifies the path within the base 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
org.apache.catalina.WebResourceSet implementations provided
by Tomcat and must start with '/'. Custom implementations may not require
it. If not specified, the default value '/' will be used.

readOnly

If true, resources within this resource set may not be
deleted, created or modified. For instance of
org.apache.catalina.webresources.JarResourceSet, this
attribute is hard-coded to true and may not be changed. For
instances of org.apache.catalina.webresources.DirResourceSet
and org.apache.catalina.webresources.FileResourceSet the
default value of this attribute is false.

webAppMount

Identifies the path within the web application that these resources
will be made available. For the
org.apache.catalina.WebResourceSet 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.

JAR resources

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
PreResources.

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

Post-resources

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 PreResources.

Ordering

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 /WEB-INF/classes. This
allows other components to search for classes with a single call rather than
one call to search /WEB-INF/classes followed by another to search
the JARs in /WEB-INF/lib. The ClassResources are populated
from the JARs mapped to /WEB-INF/lib when the web application
starts.

Therefore, the complete search order is:

PreResources

MainResources

ClassResources

JarResources

PostResources

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:

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