Author: markt
Date: Wed Sep 7 13:50:09 2016
New Revision: 1759611
URL: http://svn.apache.org/viewvc?rev=1759611&view=rev
Log:
Expand the documentation for the nested elements within a Resources element to
clarify the behaviour of different configuration options with respect to the
order in which resources are searched.
Modified:
tomcat/trunk/webapps/docs/changelog.xml
tomcat/trunk/webapps/docs/config/resources.xml
Modified: tomcat/trunk/webapps/docs/changelog.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/changelog.xml?rev=1759611&r1=1759610&r2=1759611&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/changelog.xml (original)
+++ tomcat/trunk/webapps/docs/changelog.xml Wed Sep 7 13:50:09 2016
@@ -73,6 +73,16 @@
</add>
</changelog>
</subsection>
+ <subsection name="Web applications">
+ <changelog>
+ <add>
+ Expand the documentation for the nested elements within a
+ <code>Resources</code> element to clarify the behaviour of different
+ configuration options with respect to the order in which resources are
+ searched. (markt)
+ </add>
+ </changelog>
+ </subsection>
<subsection name="Other">
<changelog>
<fix>
Modified: tomcat/trunk/webapps/docs/config/resources.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/config/resources.xml?rev=1759611&r1=1759610&r2=1759611&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/config/resources.xml (original)
+++ tomcat/trunk/webapps/docs/config/resources.xml Wed Sep 7 13:50:09 2016
@@ -233,6 +233,11 @@
<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
@@ -241,6 +246,65 @@
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>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
