Apache Tomcat 8 Configuration Reference

• Introduction
• Attributes
  1. Common Attributes
  2. Standard Implementation
• Nested Components
• Special Features

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.

A web application's main resources are defined by the docBase defined for the Context. Additional configuration settings and/or 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:

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:

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

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:

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

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

Cache Strategy

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 <CacheStrategy> element inside the <Resources> element with the following attributes:

No special features are associated with a Resources element.