Author: bodewig
Date: Wed Sep 9 09:26:10 2009
New Revision: 812851
URL: http://svn.apache.org/viewvc?rev=812851&view=rev
Log:
document *entry resources
Added:
ant/sandbox/antlibs/compress/trunk/docs/entry.html (contents, props
changed)
- copied, changed from r812756,
ant/core/trunk/docs/manual/CoreTypes/resources.html
Copied: ant/sandbox/antlibs/compress/trunk/docs/entry.html (from r812756,
ant/core/trunk/docs/manual/CoreTypes/resources.html)
URL:
http://svn.apache.org/viewvc/ant/sandbox/antlibs/compress/trunk/docs/entry.html?p2=ant/sandbox/antlibs/compress/trunk/docs/entry.html&p1=ant/core/trunk/docs/manual/CoreTypes/resources.html&r1=812756&r2=812851&rev=812851&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/CoreTypes/resources.html (original)
+++ ant/sandbox/antlibs/compress/trunk/docs/entry.html Wed Sep 9 09:26:10 2009
@@ -18,107 +18,23 @@
<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>
+<link rel="stylesheet" type="text/css" href="style.css">
+<title>Archive Entries</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>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="#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>
+<h2><a name="archiveentry">Archive Entries</h2>
-<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>
+<p>For each of the supported archiving formats there is a
+ correspondig <code>entry</code> resource that represents a single
+ entry in such an archive.</p>
-<h4><a name="javaresource">javaresource</a></h4>
+<p>All of these resources need to know the archive the entry should be
+ read from, it can be specifed as either the archive attribute or a
+ nested single-element resource collection.</p>
-<p>Represents a resource loadable via a Java classloader.</p>
+<p>The <code>entry</code> types share the following set of attributes:</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
@@ -127,59 +43,8 @@
<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="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 valign="top">archive</td>
+ <td valign="top">The archive containing this resource</td>
<td align="center" valign="top">Yes, unless a nested resource
collection has been specified.</td>
</tr>
@@ -190,960 +55,79 @@
</tr>
<tr>
<td valign="top">encoding</td>
- <td valign="top">The encoding of the zipfile</td>
+ <td valign="top">The encoding of filenames inside the archive</td>
<td align="center" valign="top">No;
- platform default used if unspecified</td>
+ platform default used if unspecified. Currently ignored by all
+ but <code>zipentry</code></td>
</tr>
</table>
-<h4><a name="tarentry">tarentry</a></h4>
+<h2><a name="arentry">arentry</a></h2>
-<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>
+<p>An <a href="#archiveentry">archive entry</a> representing an entry
+ in a AR archive.</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>Examples</h4>
-<h4><a name="gzipresource">gzipresource</a></h4>
+<pre>
+<cmp:arentry xmlns:cmp="antlib:org.apache.ant.compress"
+ name="some-file.txt">
+ <file file="some-archive.ar"/>
+</cmp:arentry>
+</pre>
-<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>
+<p>Represents the entry named some-file.txt in archive some-archive.ar.</p>
-<h4><a name="bzip2resource">bzip2resource</a></h4>
+<h2><a name="cpioentry">cpioentry</a></h2>
-<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>
+<p>An <a href="#archiveentry">archive entry</a> representing an entry
+ in a CPIO archive.</p>
-<h4><a name="url">url</a></h4>
+<h4>Examples</h4>
-<p>Represents a URL.</p>
+<pre>
+<cmp:cpioentry xmlns:cmp="antlib:org.apache.ant.compress"
+ name="some-file.txt">
+ <file file="some-archive.cpio"/>
+</cmp:cpioentry>
+</pre>
-<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>
-</table>
+<p>Represents the entry named some-file.txt in archive some-archive.cpio.</p>
-<h4><a name="string">string</a></h4>
+<h2><a name="tarentry">tarentry</a></h2>
-<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>
+<p>An <a href="#archiveentry">archive entry</a> representing an entry
+ in a TAR archive.</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>
+<h4>Examples</h4>
-<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>
+<cmp:tarentry xmlns:cmp="antlib:org.apache.ant.compress"
+ name="some-file.txt">
+ <file file="some-archive.tar"/>
+</cmp:tarentry>
</pre>
-
-</p>
-<h4><a name="propertyresource">propertyresource</a></h4>
+<p>Represents the entry named some-file.txt in archive some-archive.tar.</p>
-<p>Represents an Ant property.</p>
+<h2><a name="zipentry">zipentry</a></h2>
-<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>
+<p>An <a href="#archiveentry">archive entry</a> representing an entry
+ in a ZIP archive.</p>
-<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="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="../CoreTasks/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="#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>
-</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>
-
-<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>
+<p>Unlike
+ its <a
href="http://ant.apache.org/manual/CoreTypes/resources.html#zipentry";>counterpart
+ in Ant's core</a> this Antlib's <code>zipentry</code> can work on
+ archives that are not file system resources.</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>
+<h4>Examples</h4>
+
+<pre>
+<cmp:zipentry xmlns:cmp="antlib:org.apache.ant.compress"
+ name="some-file.txt">
+ <file file="some-archive.zip"/>
+</cmp:zipentry>
+</pre>
-<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. 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>
- </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="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>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>
- <copy todir="${target}">
- <mapperesources>
- <fileset dir="${src}"/>
- <globmapper from="*" to="*.bak"/>
- </mapperesources>
- </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>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="../CoreTasks/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>
+<p>Represents the entry named some-file.txt in archive some-archive.zip.</p>
-</body>
-</html>
Propchange: ant/sandbox/antlibs/compress/trunk/docs/entry.html
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: ant/sandbox/antlibs/compress/trunk/docs/entry.html
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Propchange: ant/sandbox/antlibs/compress/trunk/docs/entry.html
------------------------------------------------------------------------------
svn:mergeinfo =
