document mappedresources

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@718633 13f79535-47bb-0310-9956-ffa450edef68
16 years ago · 0da719e8f5
--- a/+ 5
+++ b/+ 5
@@ -534,6 +534,11 @@ Other changes:
   operating systems repsectively.
   Bugzilla Report 7624.

 * a new resource collection <mappedresources> generalizes the prefix
   and fullpath attributes of <zipfileset> to arbitrary mappers that
   can be applied to arbitrary resource collections.
   Bugzilla Report 4240.

 Changes from Ant 1.7.0 TO Ant 1.7.1
 =============================================

--- a/docs/manual/CoreTypes/resources.html
+++ b/docs/manual/CoreTypes/resources.html
@@ -346,6 +346,9 @@ Ant's "legacy" datatypes have been modified to behave as Resource Collections:
    of nested resource collections</li>
  <li><a href="#difference">difference</a> - set difference
    of nested resource collections</li>
  <li><a href="#mappedresources">mappedresources</a> - generic
    resource collection wrapper that maps the names of the nested
    resources using a <a href="mapper.html">mapper</a>.</li>
 </ul>
 <h4><a name="resources">resources</a></h4>
 <p>A generic resource collection, designed for use with
@@ -1017,7 +1020,60 @@ larger collection. <strong>Since Ant 1.7.1</strong>.</p>
  </pre>
 </blockquote>

 <h4><a name="mappedresources">mappedresources</a></h4>

 <p>Wraps another resource collection and maps the names of the nested
  resources using a <a href="mapper.html">mapper</a>.</p>

 <p>Even if <em>mappedresources</em> wraps a resource collection that
  consists of file-system based resources, <em>mappedresources</em>
  will not appear to be file-system based.  This means you can't
  use <em>mappedresources</em> with tasks that only allow file-system
  based resources.</p>

 <p><em>mappedresources</em> doesn't support any attributes.</p>

 <blockquote>
  <h4>Parameters specified as nested elements</h4>
  <p>A single resource collection is required.</p>
  <p>A single <a href="mapper.html">mapper</a> can be used to map
    names.  If no mapper has been given (which doesn't make any sense,
    honestly), an identity mapper will be used.</p>

  <h4>Examples</h4>

  <p>Copies all files from a given directory to a target directory
    adding ".bak" as an extension.  Note this could be done with a
    <em>mapper</em> nested into <em>copy</em> directly as well.</p>

  <pre>
    &lt;copy todir="${target}"&gt;
      &lt;mapperesources&gt;
        &lt;fileset dir="${src}"/&gt;
        &lt;globmapper from="*" to="*.bak"/&gt;
      &lt;/mapperesources&gt;
    &lt;/copy&gt;
  </pre>

  <p>Creates a WAR archive adding all CLASSPATH entries that are files
    to the <code>WEB-INF/lib</code> directory without keeping their
    files-system structure.</p>

  <pre>
    &lt;war destfile="${output}"&gt;
      &lt;mappedresources&gt;
        &lt;restrict&gt;
          &lt;path path="${java.class.path}"/&gt;
          &lt;type type="file"/&gt;
        &lt;/restrict&gt;
        &lt;chainedmapper&gt;
          &lt;flattenmapper/&gt;
          &lt;globmapper from="*" to="WEB-INF/lib/*"/&gt;
        &lt;/chainedmapper&gt;
      &lt;/mappedresources&gt;
    &lt;/war&gt;
  </pre>    
 </blockquote>

 </body>
 </html>
--- a/src/tests/antunit/taskdefs/war-test.xml
+++ b/src/tests/antunit/taskdefs/war-test.xml
@@ -168,4 +168,22 @@
    <au:assertFileExists file="${working.dir}/WEB-INF/lib/web.xml" />
  </target>

  <target name="testMappedClasspathFromManual">
    <mkdir dir="${input}"/>
    <mkdir dir="${output}/out"/>
    <war destfile="${output}/test.war" webxml="${ant.file}">
      <mappedresources>
        <restrict>
          <path path="${java.class.path}"/>
          <type type="file"/>
        </restrict>
        <chainedmapper>
          <flattenmapper/>
          <globmapper from="*" to="WEB-INF/lib/*"/>
        </chainedmapper>
      </mappedresources>
    </war>
    <unzip src="${output}/test.war" dest="${output}/out"/>
    <au:assertFileExists file="${output}/out/WEB-INF/lib/ant.jar"/>
  </target>
 </project>