diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Types/resources.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/Types/resources.html | 1380 |
1 files changed, 1380 insertions, 0 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/resources.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/resources.html new file mode 100644 index 00000000..58cefde1 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/resources.html @@ -0,0 +1,1380 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>Resources and Resource Collections</title> +</head> + +<body> + +<h2><a name="resource">Resources</a></h2> +<p> +A file-like entity can be abstracted to the concept of a <i>resource</i>. +In addition to providing access to file-like attributes, a resource +implementation should, when possible, provide the means to read content +from and/or write content to the underlying entity. Although the resource +concept was introduced in <i>Apache Ant 1.5.2</i>, resources are available for +explicit use beginning in <b>Ant 1.7</b>. +</p> + +<h3>The built-in resource types are:</h3> + +<ul> + <li><a href="#basic">resource</a> - a basic resource.</li> + <li><a href="#bzip2resource">bzip2resource</a> - a BZip2 compressed resource.</li> + <li><a href="#file">file</a> - a file.</li> + <li><a href="#gzipresource">gzipresource</a> - a GZip compressed resource.</li> + <li><a href="#javaresource">javaresource</a> - a resource loadable + via a Java classloader.</li> + <li><a href="#javaconstant">javaconstant</a> - a constant in a class loadable + via a Java classloader.</li> + <li><a href="#propertyresource">propertyresource</a> - an Ant property.</li> + <li><a href="#string">string</a> - a text string.</li> + <li><a href="#tarentry">tarentry</a> - an entry in a tar file.</li> + <li><a href="#url">url</a> - a URL.</li> + <li><a href="#zipentry">zipentry</a> - an entry in a zip file.</li> +</ul> + +<h4><a name="basic">resource</a></h4> + +<p>A basic resource. Other resource types derive from this basic +type; as such all its attributes are available, though in most cases +irrelevant attributes will be ignored. This and all resource +implementations are also usable as single-element +<a href="#collection">Resource Collections</a>. +</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name of this resource</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">exists</td> + <td valign="top">Whether this resource exists</td> + <td align="center" valign="top">No, default <i>true</i></td> + </tr> + <tr> + <td valign="top">lastmodified</td> + <td valign="top">The last modification time of this resource</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">directory</td> + <td valign="top">Whether this resource is directory-like</td> + <td align="center" valign="top">No, default <i>false</i></td> + </tr> + <tr> + <td valign="top">size</td> + <td valign="top">The size of this resource</td> + <td align="center" valign="top">No</td> + </tr> +</table> + +<h4><a name="file">file</a></h4> + +<p>Represents a file accessible via local filesystem conventions.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">file</td> + <td valign="top">The file represented by this resource</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">basedir</td> + <td valign="top">The base directory of this resource. When this + attribute is set, attempts to access the name of the resource + will yield a path relative to this location.</td> + <td align="center" valign="top">No</td> + </tr> +</table> + +<h4><a name="javaresource">javaresource</a></h4> + +<p>Represents a resource loadable via a Java classloader.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name of the resource.</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">classpath</td> + <td valign="top">the classpath to use when looking up a resource.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">classpathref</td> + <td valign="top">the classpath to use when looking up a resource, + given as <a href="../using.html#references">reference</a> + to a <code><path></code> defined elsewhere..</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">loaderRef</td> + <td valign="top">the name of the loader that is + used to load the resource, constructed from the specified classpath.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">parentFirst</td> + <td valign="top">Whether to consult the parent classloader first - + the parent classloader most likely is the system classloader - + when using a nested classpath. Defaults + to <code>true</code>.<br/> + <em>Since Ant 1.8.0</em></td> + <td align="center" valign="top">No</td> + </tr> +</table> + +<p>The classpath can also be specified as nested classpath element, +where <b><classpath></b> is a <a +href="../using.html#path">path-like structure</a>.</p> + + +<h4><a name="javaconstant">javaconstant</a></h4> +<p>Loads the value of a java constant. As a specialisation of +<a href="#javaresource">javaresource</a> all of its attributes and nested elements are +supported. A constant must be specified as <tt>public static</tt> otherwise it could not be loaded.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name of the resource. Must be specified as full qualified + field name. + </td> + <td align="center" valign="top">Yes</td> + </tr> +</table> +<h5>Examples</h5> +This loads the value of the constant <tt>VERSION</tt> of the <tt>org.acme.Main</tt> class +into the <tt>version</tt>-property. The classpath for finding that class is provided via +nested classpath element. +<pre><code><loadresource property="version"> + <javaconstant name="org.acme.Main.VERSION"> + <classpath> + <pathelement location="${acme.lib.dir}"/> + </classpath> + </javaconstant> + </loadresource> +</code></pre> + +Create a new file <tt>c:/temp/org.apache.tools.ant.Main.DEFAULT_BUILD_FILENAME</tt> with the content +of that constant (<tt>build.xml</tt>). +<pre><code><copy todir="c:/temp"> + <javaconstant name="org.apache.tools.ant.Main.DEFAULT_BUILD_FILENAME"/> +</copy></code></pre> + + +<h4><a name="zipentry">zipentry</a></h4> + +<p>Represents an entry in a ZIP archive. The archive can be specified +using the archive attribute or a nested single-element resource +collection. <code>zipentry</code> only supports file system resources +as nested elements.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">zipfile or its alias name archive</td> + <td valign="top">The zip file containing this resource</td> + <td align="center" valign="top">Yes, unless a nested resource + collection has been specified.</td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name of the archived resource</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">encoding</td> + <td valign="top">The encoding of the zipfile</td> + <td align="center" valign="top">No; + platform default used if unspecified</td> + </tr> +</table> + +<h4><a name="tarentry">tarentry</a></h4> + +<p>Represents an entry in a TAR archive. The archive can be specified +using the archive attribute or a nested single-element resource +collection.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">archive</td> + <td valign="top">The tar archive containing this resource</td> + <td align="center" valign="top">Yes, unless a nested resource + collection has been specified.</td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name of the archived resource</td> + <td align="center" valign="top">Yes</td> + </tr> +</table> + +<h4><a name="gzipresource">gzipresource</a></h4> + +<p>This is not a stand-alone resource, but a wrapper around another +resource providing compression of the resource's contents on the fly. +A single element resource collection must be specified as a nested +element.</p> + +<h4><a name="bzip2resource">bzip2resource</a></h4> + +<p>This is not a stand-alone resource, but a wrapper around another +resource providing compression of the resource's contents on the fly. +A single element resource collection must be specified as a nested +element.</p> + +<h4><a name="url">url</a></h4> + +<p>Represents a URL.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">url</td> + <td valign="top">The url to expose</td> + <td rowspan="3" align="center" valign="middle">Exactly one of these</td> + </tr> + <tr> + <td valign="top">file</td> + <td valign="top">The file to expose as a file: url</td> + </tr> + <tr> + <td valign="top">baseUrl</td> + <td valign="top">The base URL which must be combined with relativePath</td> + </tr> + <tr> + <td valign="top">relativePath</td> + <td valign="top">Relative path that defines the url combined with + baseUrl</td> + <td align="center" valign="top">If using baseUrl</td> + </tr> +</table> + +<h4><a name="string">string</a></h4> + +<p>Represents a Java String. It can be written to, but only once, after which +it will be an error to write to again.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">value</td> + <td valign="top">The value of this resource</td> + <td align="center" valign="top">No</td> + </tr> +</table> + +<p>The resource also supports nested text, which can only be supplied if the <code>value</code> attribute is unset: + </p> +<pre> + <string> + self.log("Ant version =${ant.version}"); + </string> +</pre> + +</p> + +<h4><a name="propertyresource">propertyresource</a></h4> + +<p>Represents an Ant property.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The property name</td> + <td align="center" valign="top">Yes</td> + </tr> +</table> + +<hr> +<h2><a name="collection">Resource Collections</a></h2> +<p> +A Resource Collection is an abstraction of an entity that groups +together a number of <a href="#resource">resources</a>. Several of +Ant's "legacy" datatypes have been modified to behave as Resource Collections: +<ul> + <li><a href="fileset.html">fileset</a>, + <a href="dirset.html">dirset</a>, + <a href="multirootfileset.html">multirootfileset</a>, + <a href="filelist.html">filelist</a>, and + <a href="../using.html#path">path</a> + (and derivative types) expose <a href="#file">file</a> resources + </li> + <li><a href="tarfileset.html">tarfileset</a> + can expose <a href="#file">file</a> or <a href="#tarentry">tarentry</a> + resources depending on configuration + </li> + <li><a href="zipfileset.html">zipfileset</a> + can expose <a href="#file">file</a> or <a href="#zipentry">zipentry</a> + resources depending on configuration + </li> + <li><a href="propertyset.html">propertyset</a> + exposes <a href="#propertyresource">property</a> resources + </li> +</ul> +</p> +<p>Strangely, some tasks can even legitimately behave as resource collections: +<ul> + <li><a href="../Tasks/concat.html">concat</a> + exposes a concatenated resource, and adds e.g. + <a href="filterchain.html">filtering</a> + to Ant's resource-related capabilities. + </li> +</ul> +</p> +<h3>The additional built-in resource collections are:</h3> +<ul> + <li><a href="#resources">resources</a> - generic resource collection</li> + <li><a href="#files">files</a> - collection of files similar to + <a href="fileset.html">fileset</a></li> + <li><a href="#restrict">restrict</a> - restrict a resource collection + to include only resources meeting specified criteria</li> + <li><a href="#sort">sort</a> - sorted resource collection</li> + <li><a href="#first">first</a> - first <i>n</i> resources from a + nested collection</li> + <li><a href="#last">last</a> - last <i>n</i> resources from a + nested collection</li> + <li><a href="#allbutfirst">allbutfirst</a> - all except the + first <i>n</i> resources from a nested collection</li> + <li><a href="#allbutlast">allbutlast</a> - all except the last <i>n</i> + resources from a nested collection</li> + <li><a href="#tokens">tokens</a> - <a href="#string">string</a> tokens + gathered from a nested collection</li> + <li><a href="#union">union</a> - set union of nested resource collections</li> + <li><a href="#intersect">intersect</a> - set intersection + 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> + <li><a href="#archives">archives</a> - wraps around different + resource collections and treats the nested resources as ZIP or TAR + archives that will be extracted on the fly.</li> + <li><a href="#resourcelist">resourcelist</a> - a collection of + resources whose names have been read from another resource.</li> +</ul> +<h4><a name="resources">resources</a></h4> +<p>A generic resource collection, designed for use with + <a href="../using.html#references">references</a>. + For example, if a third-party Ant task generates a Resource Collection + of an unknown type, it can still be accessed via a + <code><resources></code> collection. The secondary use of this + collection type is as a container of other resource collections, + preserving the order of nested collections as well as + duplicate resources (contrast with <a href="#union">union</a>). +</p> +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results. <em>since Ant 1.8.0</em></td> + <td valign="top" align="center">No, default <i>false</i></td> + </tr> + </table> +</blockquote> + +<h4><a name="files">files</a></h4> +<p>A group of files. These files are matched by <b>absolute</b> patterns + taken from a number of <a href="patternset.html">PatternSets</a>. + These can be specified as nested <code><patternset></code> + elements. In addition, <code><files></code> holds an implicit + PatternSet and supports the nested <code><include></code>, + <code><includesfile></code>, <code><exclude></code> + and <code><excludesfile></code> elements of PatternSet directly, + as well as PatternSet's attributes. +</p> +<p><a href="selectors.html">File Selectors</a> are available as nested + elements. A file must be selected by all selectors in order to be included; + <code><files></code> is thus equivalent to an + <code><and></code> file selector container. +</p> +<p><b>More simply put</b>, this type is equivalent to a + <a href="fileset.html">fileset</a> with no base directory. + <b>Please note</b> that without a base directory, + filesystem scanning is based entirely on include and exclude patterns. + A <a href="selectors.html#filenameselect">filename</a> (or any) + selector can <i>only</i> influence the scanning process <i>after</i> + the file has been included based on pattern-based selection. +</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">includes</td> + <td valign="top">comma- or space-separated list of patterns + of files that must be included</td> + <td rowspan="2" valign="middle" align="center">At least one of these</td> + </tr> + <tr> + <td valign="top">includesfile</td> + <td valign="top">the name of a file; each line of this file is + taken to be an include pattern.</td> + </tr> + <tr> + <td valign="top">excludes</td> + <td valign="top">comma- or space-separated list of patterns + of files that must be excluded</td> + <td rowspan="2" valign="top" align="center">No, default none + (except default excludes when true)</td> + </tr> + <tr> + <td valign="top">excludesfile</td> + <td valign="top">the name of a file; each line of this file is + taken to be an exclude pattern.</td> + </tr> + <tr> + <td valign="top">defaultexcludes</td> + <td valign="top">Whether + <a href="../dirtasks.html#defaultexcludes">default excludes</a> + should be used</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + <tr> + <td valign="top">casesensitive</td> + <td valign="top">Whether patterns are case-sensitive</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + <tr> + <td valign="top">followsymlinks</td> + <td valign="top">Whether to follow symbolic links + (see note <a href="#symlink">below</a>)</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> +</table> + +<p><a name="symlink"><b>Note</b></a>: All files/directories for which +the canonical path is different from its path are considered symbolic +links. On Unix systems this usually means the file really is a +symbolic link but it may lead to false results on other +platforms. +</p> + +<h4><a name="restrict">restrict</a></h4> +<p>Restricts a nested resource collection using resource selectors: +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; disabling + may seriously impact performance</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + </table> + <h4>Parameters specified as nested elements</h4> + <p>A single resource collection is required.</p> + <p>Nested resource selectors are used to "narrow down" the included + resources, combined via a logical <i>AND</i>. These are patterned + after <a href="selectors.html">file selectors</a> but are, + unsurprisingly, targeted to resources. + Several built-in resource selectors are available in the internal + <a href="antlib.html">antlib</a> + <code>org.apache.tools.ant.types.resources.selectors</code>: + </p> + + <ul> + <li><a href="#rsel.name">name</a> - select resources by name.</li> + <li><a href="#rsel.exists">exists</a> - select existing resources.</li> + <li><a href="#rsel.date">date</a> - select resources by date.</li> + <li><a href="#rsel.type">type</a> - select resources by type.</li> + <li><a href="#rsel.size">size</a> - select resources by size.</li> + <li><a href="#rsel.instanceof">instanceof</a> + - select resources by class or Ant datatype.</li> + <li><a href="#rsel.and">and</a> - "and" nested resource selectors.</li> + <li><a href="#rsel.or">or</a> - "or" nested resource selectors.</li> + <li><a href="#rsel.not">not</a> - "not" a nested resource selector.</li> + <li><a href="#rsel.none">none</a> + - select resources selected by no nested resource selectors.</li> + <li><a href="#rsel.majority">majority</a> - select resources selected + by a majority of nested resource selectors.</li> + <li><a href="selectors.html#modified">modified</a> - select resources which + content has changed.</li> + <li><a href="selectors.html#containsselect">contains</a> - select resources + containing a particular text string.</li> + <li><a href="selectors.html#regexpselect">containsregexp</a> - select + resources whose contents match a particular regular expression.</li> + <li><a href="#rsel.compare">compare</a> - select resources + based on comparison to other resources.</li> + <li><a href="selectors.html#readable">readable</a> - + Select files (resources must be files) if they are readable.</li> + <li><a href="selectors.html#writable">writable</a> - + Select files (resources must be files) if they are writable.</li> + </ul> + + <h4><a name="rsel.name">name</a></h4> + <p>Selects resources by name.</p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name pattern to test using standard Ant + patterns.</td> + <td valign="top" align="center" rowspan="2">Exactly one of + the two</td> + </tr> + <tr> + <td valign="top">regex</td> + <td valign="top">The regular expression matching files to select.</td> + </tr> + <tr> + <td valign="top">casesensitive</td> + <td valign="top">Whether name comparisons are case-sensitive</td> + <td align="center" valign="top">No, default <i>true</i></td> + </tr> + <tr> + <td valign="top">handledirsep</td> + <td valign="top"> + If this is specified, the mapper will treat a \ character in a + resource name or name attribute as a / for the purposes of + matching. This attribute can be true or false, the default is + false. + <em>Since Ant 1.8.0.</em> + <td align="center" valign="top">No</td> + </tr> + </table> + + <h4><a name="rsel.exists">exists</a></h4> + <p>Selects existing resources.</p> + + <h4><a name="rsel.date">date</a></h4> + <p>Selects resources by date.</p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">millis</td> + <td valign="top">The comparison date/time in ms since January 1, 1970</td> + <td rowspan="2" align="center" valign="middle">One of these</td> + </tr> + <tr> + <td valign="top">datetime</td> + <td valign="top">The formatted comparison date/time</td> + </tr> + <tr> + <td valign="top">pattern</td> + <td valign="top">SimpleDateFormat-compatible pattern + for use with the <code>datetime</code> attribute</td> + <td align="center" valign="top"> + No, default is "MM/DD/YYYY HH:MM AM_or_PM"</td> + </tr> + <tr> + <td valign="top">granularity</td> + <td valign="top">The number of milliseconds leeway to use when + comparing file modification times. This is needed because not + every file system supports tracking the last modified time to + the millisecond level.</td> + <td align="center" valign="top">No; default varies by platform: + FAT filesystems = 2 sec; Unix = 1 sec; NTFS = 1 ms.</td> + </tr> + <tr> + <td valign="top">when</td> + <td valign="top">One of "before", "after", "equal"</td> + <td align="center" valign="top">No, default "equal"</td> + </tr> + </table> + + <h4><a name="rsel.type">type</a></h4> + <p>Selects resources by type (file or directory).</p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">type</td> + <td valign="top">One of "file", "dir", "any" (since Ant 1.8)</td> + <td align="center" valign="top">Yes</td> + </tr> + </table> + + <h4><a name="rsel.size">size</a></h4> + <p>Selects resources by size.</p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">size</td> + <td valign="top">The size to compare</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">when</td> + <td valign="top">One of "equal", "eq", "greater", "gt", "less", "lt", + "ge" (greater or equal), "ne" (not equal), "le" (less or equal)</td> + <td align="center" valign="top">No, default "equal"</td> + </tr> + </table> + + <h4><a name="rsel.instanceof">instanceof</a></h4> + <p>Selects resources by type.</p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">class</td> + <td valign="top">The class of which the resource must be an instance</td> + <td rowspan="2" align="center" valign="middle">One of these</td> + </tr> + <tr> + <td valign="top">type</td> + <td valign="top">The Ant type that must + be assignable from the resource</td> + </tr> + <tr> + <td valign="top">uri</td> + <td valign="top">The uri in which <i>type</i> must be defined</td> + <td valign="top">No</td> + </tr> + </table> + + <h4><a name="rsel.and">and</a></h4> + <p>Selects a resource if it is selected by all nested resource selectors.</p> + + <h4><a name="rsel.or">or</a></h4> + <p>Selects a resource if it is selected + by at least one nested resource selector.</p> + + <h4><a name="rsel.not">not</a></h4> + <p>Negates the selection result of the single + nested resource selector allowed.</p> + + <h4><a name="rsel.none">none</a></h4> + <p>Selects a resource if it is selected + by no nested resource selectors.</p> + + <h4><a name="rsel.majority">majority</a></h4> + <p>Selects a resource if it is selected + by the majority of nested resource selectors.</p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">allowtie</td> + <td valign="top">Whether a tie (when there is an even number + of nested resource selectors) is considered a majority</td> + <td valign="top">No, default <i>true</i></td> + </tr> + </table> + + <h4><a name="rsel.compare">compare</a></h4> + <p>Selects a resource based on its comparison to one or more "control" + resources using nested <a href="#rcmp">resource comparators</a>.</p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">when</td> + <td valign="top">Comparison ("equal"/"eq", "greater"/"gt", "less"/"lt", + "le" (less or equal), "ge" (greater or equal), "ne" (not equal).</td> + <td valign="top">No, default "equal"</td> + </tr> + <tr> + <td valign="top">against</td> + <td valign="top">Quantifier ("all"/"each"/"every", "any"/"some", + (exactly) "one", "most"/"majority", "none".</td> + <td valign="top">No, default "all"</td> + </tr> + </table> + <h4>Parameters specified as nested elements</h4> + <p>The resources against which comparisons will be made must be specified + using the nested <control> element, which denotes a + <a href="#resources">resources</a> collection.</p> + <h4>Examples</h4> + <p>Assuming the namespace settings +<pre><code> rsel="antlib:org.apache.tools.ant.types.resources.selectors" + rcmp="antlib:org.apache.tools.ant.types.resources.comparators" +</code></pre></p> + <pre> +<restrict> + <fileset dir="src" includes="a,b,c,d,e,f,g" /> + <rsel:compare when="le" against="all"> + <control> + <resource name="d" /> + </control> + <rcmp:name /> + </rsel:compare> +</restrict> + </pre> + <p>Selects files a, b, c, and d.</p> + <pre> + <project rsel="antlib:org.apache.tools.ant.types.resources.selectors"> + <macrodef name="copyFromPath"> + <attribute name="todir"/> + <attribute name="refid"/> + <element name="nested-resource-selectors" optional="yes" implicit="true"/> + <sequential> + <mkdir dir="@{todir}" taskname="copyFromPath"/> + <copy todir="@{todir}" taskname="copyFromPath"> + <restrict> + <path refid="@{refid}"/> + <rsel:or> + <nested-resource-selectors/> + </rsel:or> + </restrict> + <flattenmapper/> + </copy> + </sequential> + </macrodef> + <copyFromPath refid="classpath" todir="todir"> + <rsel:name name="log4j.properties"/> + <rsel:name name="default.properties"/> + </copyFromPath> + </project> + </pre> + <p>Creates the <tt>todir</tt> directory and copies (if present) the + files <tt>log4j.properties</tt> and <tt>default.properties</tt> + from the Classpath (already used while compiling). + </p> + + <pre> + <project> + <filelist id="allfiles" dir="${ant.home}/bin" files="ant.cmd,foo.txt,ant.bat,bar.txt,ant"/> + <restrict id="missingfiles"> + <filelist refid="allfiles"/> + <rsel:not xmlns:rsel="antlib:org.apache.tools.ant.types.resources.selectors"> + <rsel:exists/> + </rsel:not> + </restrict> + <echo>These files are missed: ${toString:missingfiles}</echo> + </project> + </pre> + <p>The resource collection <i>allfiles</i> defines a list of files which are expected. The restrict + <i>missingfiles</i> uses the <tt><not><exists></tt> selector for getting all files + which are not present. Finally we use the <i>toString:</i> <a href="../using.html#pathshortcut">pathshortcut</a> for + getting them in a readable form: <tt>[echo] These files are missed: ....foo.txt;....bar.txt</tt></p> + +</blockquote> + +<h4><a name="sort">sort</a></h4> + +<p>Sorts a nested resource collection according to the resources' + natural order, or by one or more nested <a href="#rcmp">resource + comparators</a>:</p> +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; disabling + may seriously impact performance</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + </table> + <h4>Parameters specified as nested elements</h4> + <p>A single resource collection is required.</p> + <p>The sort can be controlled and customized by specifying one or more + resource comparators. Resources can be sorted according to multiple + criteria; the first specified is the "outermost", while the last + specified is the "innermost". Several built-in resource comparators + are available in the internal <a href="antlib.html">antlib</a> + <code>org.apache.tools.ant.types.resources.comparators</code>: + </p> + <h4><a name="rcmp">Resource Comparators:</a></h4> + <ul> + <li><a href="#rcmp.name">name</a> - sort resources by name</li> + <li><a href="#rcmp.exists">exists</a> - sort resources by existence</li> + <li><a href="#rcmp.date">date</a> - sort resources by date</li> + <li><a href="#rcmp.type">type</a> - sort resources by type</li> + <li><a href="#rcmp.size">size</a> - sort resources by size</li> + <li><a href="#rcmp.content">content</a> - sort resources by content</li> + <li><a href="#rcmp.reverse">reverse</a> - reverse the natural sort order, + or that of a single nested resource comparator</li> + </ul> + + <h4><a name="rcmp.name">name</a></h4> + <p>Sort resources by name.</p> + + <h4><a name="rcmp.exists">exists</a></h4> + <p>Sort resources by existence. + Not existing is considered "less than" existing.</p> + + <h4><a name="rcmp.date">date</a></h4> + <p>Sort resources by date.</p> + + <h4><a name="rcmp.type">type</a></h4> + <p>Sort resources by type (file or directory). + Because directories contain files, they are considered "greater".</p> + + <h4><a name="rcmp.size">size</a></h4> + <p>Sort resources by size.</p> + + <h4><a name="rcmp.content">content</a></h4> + <p>Sort resources by content.</p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">binary</td> + <td valign="top">Whether content should be compared in binary mode. + If <i>false<i>, content will be compared without regard to + platform-specific line-ending conventions.</td> + <td valign="top">No, default <i>true</i></td> + </tr> + </table> + + <h4><a name="rcmp.reverse">reverse</a></h4> + <p>Reverse the natural sort order, or that of a single nested comparator.</p> + + <h4>Examples</h4> + <pre> + <property name="eol" value="${line.separator}" /> + <pathconvert property="sorted" pathsep="${eol}"> + <sort> + <tokens> + <string value="foo bar etc baz" /> + <stringtokenizer /> + </tokens> + </sort> + </pathconvert></pre> + <p>The resource of type string "foo bar etc baz" is split into four tokens by + the stringtokenizer. These tokens are sorted and there <i>sorted</i> gets the value + of "bar baz etc foo".</p> + + <pre> + <sort> + <fileset dir="foo" /> + <reverse xmlns="antlib:org.apache.tools.ant.types.resources.comparators"> + <date /> + </reverse> + </sort></pre> + <p>This takes all files from <i>foo</i> + and sorts them by modification date in reverse order. + Because the resource comparators used (<code><reverse></code> + and <code><date></code>) are in an internal antlib + their namespace must be set explicitly. + </p> + +</blockquote> + +<h4><a name="first">first</a></h4> +<p>Includes the first <i>count</i> resources from a nested resource collection. +This can be used in conjunction with the <a href="#sort">sort</a> collection, +for example, to select the first few oldest, largest, etc. resources from a +larger collection.</p> +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">count</td> + <td valign="top">The number of resources to include</td> + <td valign="top" align="center">No, default 1</td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; disabling + may seriously impact performance</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + </table> + <h4>Parameters specified as nested elements</h4> + <p>A single resource collection is required.</p> +</blockquote> + +<h4><a name="last">last</a></h4> +<p>Includes the last <i>count</i> resources from a nested resource collection. +This can be used in conjunction with the <a href="#sort">sort</a> collection, +for example, to select the last few oldest, largest, etc. resources from a +larger collection. <strong>Since Ant 1.7.1</strong>.</p> +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">count</td> + <td valign="top">The number of resources to include</td> + <td valign="top" align="center">No, default 1</td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; disabling + may seriously impact performance</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + </table> + <h4>Parameters specified as nested elements</h4> + <p>A single resource collection is required.</p> +</blockquote> + +<h4><a name="allbutfirst">allbutfirst</a></h4> +<p>Includes all elements except for the first <i>count</i> resources +from a nested resource collection. This can be used in conjunction +with the <a href="#sort">sort</a> collection, for example, to select +all but the first few oldest, largest, etc. resources from a larger +collection. <strong>Since Ant 1.9.5</strong>.</p> +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">count</td> + <td valign="top">The number of resources to exclude</td> + <td valign="top" align="center">No, default 1</td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; disabling + may seriously impact performance</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + </table> + <h4>Parameters specified as nested elements</h4> + <p>A single resource collection is required.</p> +</blockquote> + +<h4><a name="allbutlast">allbutlast</a></h4> +<p>Includes all elements except for the last <i>count</i> resources +from a nested resource collection. This can be used in conjunction +with the <a href="#sort">sort</a> collection, for example, to select +all but the last few oldest, largest, etc. resources from a larger +collection. <strong>Since Ant 1.9.5</strong>.</p> +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">count</td> + <td valign="top">The number of resources to exclude</td> + <td valign="top" align="center">No, default 1</td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; disabling + may seriously impact performance</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + </table> + <h4>Parameters specified as nested elements</h4> + <p>A single resource collection is required.</p> +</blockquote> + +<h4><a name="tokens">tokens</a></h4> +<p>Includes the <a href="#string">string</a> tokens gathered from a nested + resource collection. Uses the same tokenizers supported by the +<a href="filterchain.html#tokenfilter">TokenFilter</a>. Imaginative + use of this resource collection can implement equivalents for such Unix + functions as <code>sort</code>, <code>grep -c</code>, <code>wc</code> and + <code>wc -l</code>.</p> +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">encoding</td> + <td valign="top">The encoding of the nested resources</td> + <td valign="top" align="center">No, default is platform default</td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; disabling + may seriously impact performance</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + </table> + <h4>Parameters specified as nested elements</h4> + <ul> + <li>A single resource collection is required.</li> + <li>One nested tokenizer may be specified. If omitted, a + <a href="filterchain.html#linetokenizer">LineTokenizer</a> will be used. + </li> + </ul> + <h4>Examples</h4> + <pre><concat> + <union> + <sort> + <tokens> + <resources refid="input" /> + <linetokenizer includedelims="true" /> + </tokens> + </sort> + </union> +</concat> + </pre> + <p>Implements Unix <i>sort -u</i> against resource collection <i>input</i>.</p> +</blockquote> + +<h4><a name="setlogic">Set operations</a></h4> +<blockquote> + <p>The following resource collections implement set operations:</p> + <ul> + <li><a href="#union">union</a></li> + <li><a href="#intersect">intersect</a></li> + <li><a href="#difference">difference</a></li> + </ul> + + <h4><a name="union">union</a></h4> + <p>Union of nested resource collections.</p> + + <h4><a name="intersect">intersect</a></h4> + <p>Intersection of nested resource collections.</p> + + <h4><a name="difference">difference</a></h4> + <p>Difference of nested resource collections.</p> + + <p>The following attributes apply to all set-operation resource collections: + </p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; disabling + may seriously impact performance</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + </table> + + <h4>Examples</h4> + <pre> + <resources id="A"> + <string value="a"/> + <string value="b"/> + </resources> + <resources id="B"> + <string value="b"/> + <string value="c"/> + </resources> + <union id="union"><resources refid="A"/><resources refid="B"/></union> + <intersect id="intersect"><resources refid="A"/><resources refid="B"/></intersect> + <difference id="difference"><resources refid="A"/><resources refid="B"/></difference> + <echo> + A: ${toString:A} = a;b + B: ${toString:B} = b;c + + union : ${toString:union} = a;b;c + intersect : ${toString:intersect} = b + difference: ${toString:difference} = a;c + </echo> + </pre> +</blockquote> + +<h4><a name="mappedresources">mappedresources</a></h4> + +<p><em>Since Ant 1.8.0</em></p> + +<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> + +<blockquote> + <h4>Parameters specified as attributes</h4> + + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; enabling + may improve performance. <em>Since Ant 1.8.1</em></td> + <td valign="top" align="center">No, default <i>false</i></td> + </tr> + <tr> + <td valign="top">enablemultiplemappings</td> + <td valign="top"> + If true the the collection will use all the mappings for a + given source path. If false the it will only process the first + resource. + <em>since Ant 1.8.1</em>.</td> + <td align="center">No - defaults to false.</td> + </tr> + </table> + + <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> + <copy todir="${target}"> + <mappedresources> + <fileset dir="${src}"/> + <globmapper from="*" to="*.bak"/> + </mappedresources> + </copy> + </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> + <war destfile="${output}"> + <mappedresources> + <restrict> + <path path="${java.class.path}"/> + <type type="file"/> + </restrict> + <chainedmapper> + <flattenmapper/> + <globmapper from="*" to="WEB-INF/lib/*"/> + </chainedmapper> + </mappedresources> + </war> + </pre> +</blockquote> + +<h4><a name="archives">archives</a></h4> + +<p><em>Since Ant 1.8.0</em></p> + +<p>This resource collection accepts an arbitrary number of nested + resources and assumes that all those resources must be either ZIP or + TAR archives. The resources returned + by <code><archives></code> are the contents of the nested + archives.</p> + +<p>This resource collection is a generalization + of <a href="../Tasks/zip.html#zipgroupfileset">zipgroupfileset</a> + which is only supported by the zip family of tasks.</p> + +<p><em>archives</em> doesn't support any attributes.</p> + +<blockquote> + <h4>Parameters specified as nested elements</h4> + + <p><code><archives></code> has two nested + elements <code><zips></code> and + <code><tars></code> that are <a href="#union">unions</a> + themselves, i.e. they accept arbitrary many resource(collection)s + as nested elements.</p> + + <p>The nested resources of <zips> are treated as ZIP archives, + the nested resources of <tars> as TAR archives.</p> + + <h4>Examples</h4> + + <p>Copies all files from all jars that are on the classpath + to <code>${target}</code>.</p> + + <pre> + <copy todir="${target}"> + <archives> + <zips> + <restrict> + <path path="${java.class.path}"/> + <name name="*.jar"/> + </restrict> + </zips> + </archives> + </copy> + </pre> +</blockquote> + +<h4><a name="resourcelist">resourcelist</a></h4> + +<p><em>Since Ant 1.8.0</em></p> + +<p>This resource collection accepts an arbitrary number of nested + resources, reads those resources and returns a resource for each + line read.</p> + +<p>If the line contains a colon, Ant will try to use it as an URL and + if that fails (or the line doesn't contain a colon) will return a + file resource with the line's content as its name.</p> + +<p>Properties will be expanded for each line. If the property + expansion yields a resource object rather than a string (for example + because of custom property helpers), the resources will be returned + directly.</p> + +<p><code><resourcelist></code> is a generalization + of <a href="filelist.html"><code><filelist></code></a>.</p> + +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">encoding</td> + <td valign="top">The encoding of the nested resources</td> + <td valign="top" align="center">No, default is platform default</td> + </tr> + </table> +</blockquote> + +<blockquote> + <h4>Parameters specified as nested elements</h4> + + <p><code><resourcelist></code> accepts arbitrary many + resource(collection)s as nested elements.</p> + + <p>In addition <code><resourcelist></code> supports + nested <code><filterchain></code> elements that can be used + to filter/modify the read resources before their lines get + expanded. Such a nested element corresponds to + a <a href="filterchain.html">filterchain</a>.</p> + + <h4>Examples</h4> + + <p>The following example copies a file from the first URL of + several alternatives that can actually be reached. It assumes + that the file mirrors.txt looks like</p> + + <pre> + mirrors.txt: +http://best.mirror.example.org/ +http://second.best.mirror.example.org/mirror/of/best/ +https://yet.another.mirror/ +http://the.original.site/ + </pre> + + <pre> + <copy todir="${target}"> + <first> + <restrict> + <resourcelist> + <file file="mirrors.txt"/> + </resourcelist> + <exists/> + </restrict> + </first> + </copy> + </pre> +</blockquote> + +</body> +</html> |