Author: markt
Date: Wed Sep 7 13:50:44 2016
New Revision: 1759612
URL: http://svn.apache.org/viewvc?rev=1759612&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/tc8.5.x/trunk/ (props changed)
tomcat/tc8.5.x/trunk/webapps/docs/changelog.xml
tomcat/tc8.5.x/trunk/webapps/docs/config/resources.xml
Propchange: tomcat/tc8.5.x/trunk/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Wed Sep 7 13:50:44 2016
@@ -1 +1 @@
-/tomcat/trunk:1734785,1734799,1734845,1734928,1735041,1735044,1735480,1735577,1735597,1735599-1735600,1735615,1736145,1736162,1736209,1736280,1736297,1736299,1736489,1736646,1736703,1736836,1736849,1737104-1737105,1737112,1737117,1737119-1737120,1737155,1737157,1737192,1737280,1737339,1737632,1737664,1737715,1737748,1737785,1737834,1737860,1737903,1737959,1738005,1738007,1738014-1738015,1738018,1738022,1738039,1738043,1738059-1738060,1738147,1738149,1738174-1738175,1738261,1738589,1738623-1738625,1738643,1738816,1738850,1738855,1738946-1738948,1738953-1738954,1738979,1738982,1739079-1739081,1739087,1739113,1739153,1739172,1739176,1739191,1739474,1739726,1739762,1739775,1739814,1739817-1739818,1739975,1740131,1740324,1740465,1740495,1740508-1740509,1740520,1740535,1740707,1740803,1740810,1740969,1740980,1740991,1740997,1741015,1741033,1741036,1741058,1741060,1741080,1741147,1741159,1741164,1741173,1741181,1741190,1741197,1741202,1741208,1741213,1741221,1741225,1741232,1741409,1741501
,1741677,1741892,1741896,1741984,1742023,1742042,1742071,1742090,1742093,1742101,1742105,1742111,1742139,1742146,1742148,1742166,1742181,1742184,1742187,1742246,1742248-1742251,1742263-1742264,1742268,1742276,1742369,1742387,1742448,1742509-1742512,1742917,1742919,1742933,1742975-1742976,1742984,1742986,1743019,1743115,1743117,1743124-1743125,1743134,1743425,1743554,1743679,1743696-1743698,1743700-1743701,1744058,1744064-1744065,1744125,1744194,1744229,1744270,1744323,1744432,1744684,1744697,1744705,1744713,1744760,1744786,1745083,1745142-1745143,1745145,1745177,1745179-1745180,1745227,1745248,1745254,1745337,1745467,1745473,1745576,1745735,1745744,1746304,1746306-1746307,1746319,1746327,1746338,1746340-1746341,1746344,1746427,1746441,1746473,1746490,1746492,1746495-1746496,1746499-1746501,1746503-1746507,1746509,1746549,1746551,1746554,1746556,1746558,1746584,1746620,1746649,1746724,1746939,1746989,1747014,1747028,1747035,1747210,1747225,1747234,1747253,1747404,1747506,1747536,1747
924,1747980,1747993,1748001,1748253,1748452,1748547,1748629,1748676,1748715,1749287,1749296,1749328,1749373,1749465,1749506,1749508,1749665-1749666,1749763,1749865-1749866,1749898,1749978,1749980,1750011,1750015,1750056,1750480,1750617,1750634,1750692,1750697,1750700,1750703,1750707,1750714,1750718,1750723,1750774,1750899,1750975,1750995,1751061,1751097,1751173,1751438,1751447,1751463,1751702,1752212,1752737,1752745,1753078,1753080,1753358,1753363,1754111,1754140-1754141,1754281,1754310,1754445,1754467,1754494,1754496,1754528,1754532-1754533,1754613,1754714,1754874,1754941,1754944,1754950-1754951,1755005,1755007,1755009,1755132,1755180-1755181,1755185,1755190,1755204-1755206,1755208,1755214,1755224,1755227,1755230,1755629,1755646-1755647,1755650,1755653,1755675,1755680,1755683,1755693,1755717,1755731-1755737,1755812,1755828,1755884,1755890,1755918-1755919,1755942,1755958,1755960,1755970,1755993,1756013,1756019,1756039,1756056,1756083-1756114,1756175,1756288-1756289,1756408-1756410,1
756778,1756798,1756878,1756898,1756939,1757123-1757124,1757126,1757128,1757132-1757133,1757136,1757145,1757167-1757168,1757175,1757180,1757182,1757195,1757271,1757278,1757347,1757353-1757354,1757363,1757374,1757399,1757406,1757408,1757485,1757495,1757499,1757527,1757578,1757684,1757722,1757727,1757853,1757903,1757997,1758072-1758075,1758078-1758079,1758292,1758369,1758423,1758425-1758427,1758430,1758459,1758483,1758486-1758487,1758499,1758525,1758556,1758582,1758584,1758588,1758842,1759019,1759212,1759224,1759227,1759252,1759274
+/tomcat/trunk:1734785,1734799,1734845,1734928,1735041,1735044,1735480,1735577,1735597,1735599-1735600,1735615,1736145,1736162,1736209,1736280,1736297,1736299,1736489,1736646,1736703,1736836,1736849,1737104-1737105,1737112,1737117,1737119-1737120,1737155,1737157,1737192,1737280,1737339,1737632,1737664,1737715,1737748,1737785,1737834,1737860,1737903,1737959,1738005,1738007,1738014-1738015,1738018,1738022,1738039,1738043,1738059-1738060,1738147,1738149,1738174-1738175,1738261,1738589,1738623-1738625,1738643,1738816,1738850,1738855,1738946-1738948,1738953-1738954,1738979,1738982,1739079-1739081,1739087,1739113,1739153,1739172,1739176,1739191,1739474,1739726,1739762,1739775,1739814,1739817-1739818,1739975,1740131,1740324,1740465,1740495,1740508-1740509,1740520,1740535,1740707,1740803,1740810,1740969,1740980,1740991,1740997,1741015,1741033,1741036,1741058,1741060,1741080,1741147,1741159,1741164,1741173,1741181,1741190,1741197,1741202,1741208,1741213,1741221,1741225,1741232,1741409,1741501
,1741677,1741892,1741896,1741984,1742023,1742042,1742071,1742090,1742093,1742101,1742105,1742111,1742139,1742146,1742148,1742166,1742181,1742184,1742187,1742246,1742248-1742251,1742263-1742264,1742268,1742276,1742369,1742387,1742448,1742509-1742512,1742917,1742919,1742933,1742975-1742976,1742984,1742986,1743019,1743115,1743117,1743124-1743125,1743134,1743425,1743554,1743679,1743696-1743698,1743700-1743701,1744058,1744064-1744065,1744125,1744194,1744229,1744270,1744323,1744432,1744684,1744697,1744705,1744713,1744760,1744786,1745083,1745142-1745143,1745145,1745177,1745179-1745180,1745227,1745248,1745254,1745337,1745467,1745473,1745576,1745735,1745744,1746304,1746306-1746307,1746319,1746327,1746338,1746340-1746341,1746344,1746427,1746441,1746473,1746490,1746492,1746495-1746496,1746499-1746501,1746503-1746507,1746509,1746549,1746551,1746554,1746556,1746558,1746584,1746620,1746649,1746724,1746939,1746989,1747014,1747028,1747035,1747210,1747225,1747234,1747253,1747404,1747506,1747536,1747
924,1747980,1747993,1748001,1748253,1748452,1748547,1748629,1748676,1748715,1749287,1749296,1749328,1749373,1749465,1749506,1749508,1749665-1749666,1749763,1749865-1749866,1749898,1749978,1749980,1750011,1750015,1750056,1750480,1750617,1750634,1750692,1750697,1750700,1750703,1750707,1750714,1750718,1750723,1750774,1750899,1750975,1750995,1751061,1751097,1751173,1751438,1751447,1751463,1751702,1752212,1752737,1752745,1753078,1753080,1753358,1753363,1754111,1754140-1754141,1754281,1754310,1754445,1754467,1754494,1754496,1754528,1754532-1754533,1754613,1754714,1754874,1754941,1754944,1754950-1754951,1755005,1755007,1755009,1755132,1755180-1755181,1755185,1755190,1755204-1755206,1755208,1755214,1755224,1755227,1755230,1755629,1755646-1755647,1755650,1755653,1755675,1755680,1755683,1755693,1755717,1755731-1755737,1755812,1755828,1755884,1755890,1755918-1755919,1755942,1755958,1755960,1755970,1755993,1756013,1756019,1756039,1756056,1756083-1756114,1756175,1756288-1756289,1756408-1756410,1
756778,1756798,1756878,1756898,1756939,1757123-1757124,1757126,1757128,1757132-1757133,1757136,1757145,1757167-1757168,1757175,1757180,1757182,1757195,1757271,1757278,1757347,1757353-1757354,1757363,1757374,1757399,1757406,1757408,1757485,1757495,1757499,1757527,1757578,1757684,1757722,1757727,1757853,1757903,1757997,1758072-1758075,1758078-1758079,1758292,1758369,1758423,1758425-1758427,1758430,1758459,1758483,1758486-1758487,1758499,1758525,1758556,1758582,1758584,1758588,1758842,1759019,1759212,1759224,1759227,1759252,1759274,1759611
Modified: tomcat/tc8.5.x/trunk/webapps/docs/changelog.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc8.5.x/trunk/webapps/docs/changelog.xml?rev=1759612&r1=1759611&r2=1759612&view=diff
==============================================================================
--- tomcat/tc8.5.x/trunk/webapps/docs/changelog.xml (original)
+++ tomcat/tc8.5.x/trunk/webapps/docs/changelog.xml Wed Sep 7 13:50:44 2016
@@ -68,6 +68,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/tc8.5.x/trunk/webapps/docs/config/resources.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc8.5.x/trunk/webapps/docs/config/resources.xml?rev=1759612&r1=1759611&r2=1759612&view=diff
==============================================================================
--- tomcat/tc8.5.x/trunk/webapps/docs/config/resources.xml (original)
+++ tomcat/tc8.5.x/trunk/webapps/docs/config/resources.xml Wed Sep 7 13:50:44
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
