From 753a6c60f47f3ac4f270005b65e9d6481de8eb68 Mon Sep 17 00:00:00 2001
From: Ashlee Young
+A file-like entity can be abstracted to the concept of a resource.
+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 Apache Ant 1.5.2, resources are available for
+explicit use beginning in Ant 1.7.
+ 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
+Resource Collections.
+ Represents a file accessible via local filesystem conventions. Represents a resource loadable via a Java classloader. The classpath can also be specified as nested classpath element,
+where <classpath> is a path-like structure. Loads the value of a java constant. As a specialisation of
+javaresource all of its attributes and nested elements are
+supported. A constant must be specified as public static otherwise it could not be loaded. Represents an entry in a ZIP archive. The archive can be specified
+using the archive attribute or a nested single-element resource
+collection. Represents an entry in a TAR archive. The archive can be specified
+using the archive attribute or a nested single-element resource
+collection. 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. 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. Represents a URL. Represents a Java String. It can be written to, but only once, after which
+it will be an error to write to again. The resource also supports nested text, which can only be supplied if the Resources
+The built-in resource types are:
+
+
+
+
+resource
+
+
+
+
+
+
+ Attribute
+ Description
+ Required
+
+
+ name
+ The name of this resource
+ No
+
+
+ exists
+ Whether this resource exists
+ No, default true
+
+
+ lastmodified
+ The last modification time of this resource
+ No
+
+
+ directory
+ Whether this resource is directory-like
+ No, default false
+
+
+size
+ The size of this resource
+ No
+ file
+
+
+
+
+
+
+ Attribute
+ Description
+ Required
+
+
+ file
+ The file represented by this resource
+ Yes
+
+
+basedir
+ 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.
+ No
+ javaresource
+
+
+
+
+
+
+ Attribute
+ Description
+ Required
+
+
+ name
+ The name of the resource.
+ Yes
+
+
+ classpath
+ the classpath to use when looking up a resource.
+ No
+
+
+ classpathref
+ the classpath to use when looking up a resource,
+ given as reference
+ to a
+ <path>
defined elsewhere..No
+
+
+ loaderRef
+ the name of the loader that is
+ used to load the resource, constructed from the specified classpath.
+ No
+
+
+parentFirst
+ Whether to consult the parent classloader first -
+ the parent classloader most likely is the system classloader -
+ when using a nested classpath. Defaults
+ to
+ true
.
+ Since Ant 1.8.0No
+ javaconstant
+
+
+
+
+ Attribute
+ Description
+ Required
+
+
+name
+ The name of the resource. Must be specified as full qualified
+ field name.
+
+ Yes
+ Examples
+This loads the value of the constant VERSION of the org.acme.Main class
+into the version-property. The classpath for finding that class is provided via
+nested classpath element.
+
+
+Create a new file c:/temp/org.apache.tools.ant.Main.DEFAULT_BUILD_FILENAME with the content
+of that constant (build.xml).
+<loadresource property="version">
+ <javaconstant name="org.acme.Main.VERSION">
+ <classpath>
+ <pathelement location="${acme.lib.dir}"/>
+ </classpath>
+ </javaconstant>
+ </loadresource>
+
+
+
+<copy todir="c:/temp">
+ <javaconstant name="org.apache.tools.ant.Main.DEFAULT_BUILD_FILENAME"/>
+</copy>
zipentry
+
+zipentry
only supports file system resources
+as nested elements.
+
+
+
+
+ Attribute
+ Description
+ Required
+
+
+ zipfile or its alias name archive
+ The zip file containing this resource
+ Yes, unless a nested resource
+ collection has been specified.
+
+
+ name
+ The name of the archived resource
+ Yes
+
+
+encoding
+ The encoding of the zipfile
+ No;
+ platform default used if unspecified
+ tarentry
+
+
+
+
+
+
+ Attribute
+ Description
+ Required
+
+
+ archive
+ The tar archive containing this resource
+ Yes, unless a nested resource
+ collection has been specified.
+
+
+name
+ The name of the archived resource
+ Yes
+ gzipresource
+
+bzip2resource
+
+url
+
+
+
+
+
+
+ Attribute
+ Description
+ Required
+
+
+ url
+ The url to expose
+ Exactly one of these
+
+
+ file
+ The file to expose as a file: url
+
+
+ baseUrl
+ The base URL which must be combined with relativePath
+
+
+relativePath
+ Relative path that defines the url combined with
+ baseUrl
+ If using baseUrl
+ string
+
+
+
+
+
+
+ Attribute
+ Description
+ Required
+
+
+value
+ The value of this resource
+ No
+ value
attribute is unset:
+
+ <string>
+ self.log("Ant version =${ant.version}");
+ </string>
+
+
+
Represents an Ant property.
+ +Attribute | +Description | +Required | +
name | +The property name | +Yes | +
+A Resource Collection is an abstraction of an entity that groups +together a number of resources. Several of +Ant's "legacy" datatypes have been modified to behave as Resource Collections: +
Strangely, some tasks can even legitimately behave as resource collections: +
A generic resource collection, designed for use with
+ references.
+ For example, if a third-party Ant task generates a Resource Collection
+ of an unknown type, it can still be accessed via a
+ <resources>
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 union).
+
++ ++
++ +Attribute +Description +Required ++ +cache +Whether to cache results. since Ant 1.8.0 +No, default false +
A group of files. These files are matched by absolute patterns
+ taken from a number of PatternSets.
+ These can be specified as nested <patternset>
+ elements. In addition, <files>
holds an implicit
+ PatternSet and supports the nested <include>
,
+ <includesfile>
, <exclude>
+ and <excludesfile>
elements of PatternSet directly,
+ as well as PatternSet's attributes.
+
File Selectors are available as nested
+ elements. A file must be selected by all selectors in order to be included;
+ <files>
is thus equivalent to an
+ <and>
file selector container.
+
More simply put, this type is equivalent to a + fileset with no base directory. + Please note that without a base directory, + filesystem scanning is based entirely on include and exclude patterns. + A filename (or any) + selector can only influence the scanning process after + the file has been included based on pattern-based selection. +
+ +Attribute | +Description | +Required | +
includes | +comma- or space-separated list of patterns + of files that must be included | +At least one of these | +
includesfile | +the name of a file; each line of this file is + taken to be an include pattern. | +|
excludes | +comma- or space-separated list of patterns + of files that must be excluded | +No, default none + (except default excludes when true) | +
excludesfile | +the name of a file; each line of this file is + taken to be an exclude pattern. | +|
defaultexcludes | +Whether + default excludes + should be used | +No, default true | +
casesensitive | +Whether patterns are case-sensitive | +No, default true | +
followsymlinks | +Whether to follow symbolic links + (see note below) | +No, default true | +
Note: 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. +
+ +Restricts a nested resource collection using resource selectors: +
++ ++
++ +Attribute +Description +Required ++ +cache +Whether to cache results; disabling + may seriously impact performance +No, default true +Parameters specified as nested elements
+A single resource collection is required.
+Nested resource selectors are used to "narrow down" the included + resources, combined via a logical AND. These are patterned + after file selectors but are, + unsurprisingly, targeted to resources. + Several built-in resource selectors are available in the internal + antlib +
+ +org.apache.tools.ant.types.resources.selectors
: ++
+ +- name - select resources by name.
+- exists - select existing resources.
+- date - select resources by date.
+- type - select resources by type.
+- size - select resources by size.
+- instanceof + - select resources by class or Ant datatype.
+- and - "and" nested resource selectors.
+- or - "or" nested resource selectors.
+- not - "not" a nested resource selector.
+- none + - select resources selected by no nested resource selectors.
+- majority - select resources selected + by a majority of nested resource selectors.
+- modified - select resources which + content has changed.
+- contains - select resources + containing a particular text string.
+- containsregexp - select + resources whose contents match a particular regular expression.
+- compare - select resources + based on comparison to other resources.
+- readable - + Select files (resources must be files) if they are readable.
+- writable - + Select files (resources must be files) if they are writable.
+name
+Selects resources by name.
++
+ ++ +Attribute +Description +Required ++ +name +The name pattern to test using standard Ant + patterns. +Exactly one of + the two ++ +regex +The regular expression matching files to select. ++ +casesensitive +Whether name comparisons are case-sensitive +No, default true ++ +handledirsep ++ 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. + Since Ant 1.8.0. + No +exists
+Selects existing resources.
+ +date
+Selects resources by date.
++
+ ++ +Attribute +Description +Required ++ +millis +The comparison date/time in ms since January 1, 1970 +One of these ++ +datetime +The formatted comparison date/time ++ +pattern +SimpleDateFormat-compatible pattern + for use with the +datetime
attribute+ No, default is "MM/DD/YYYY HH:MM AM_or_PM" ++ +granularity +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. +No; default varies by platform: + FAT filesystems = 2 sec; Unix = 1 sec; NTFS = 1 ms. ++ +when +One of "before", "after", "equal" +No, default "equal" +type
+Selects resources by type (file or directory).
++
+ ++ +Attribute +Description +Required ++ +type +One of "file", "dir", "any" (since Ant 1.8) +Yes +size
+Selects resources by size.
++
+ ++ +Attribute +Description +Required ++ +size +The size to compare +Yes ++ +when +One of "equal", "eq", "greater", "gt", "less", "lt", + "ge" (greater or equal), "ne" (not equal), "le" (less or equal) +No, default "equal" +instanceof
+Selects resources by type.
++
+ ++ +Attribute +Description +Required ++ +class +The class of which the resource must be an instance +One of these ++ +type +The Ant type that must + be assignable from the resource ++ +uri +The uri in which type must be defined +No +and
+Selects a resource if it is selected by all nested resource selectors.
+ +or
+Selects a resource if it is selected + by at least one nested resource selector.
+ +not
+Negates the selection result of the single + nested resource selector allowed.
+ +none
+Selects a resource if it is selected + by no nested resource selectors.
+ +majority
+Selects a resource if it is selected + by the majority of nested resource selectors.
++
+ ++ +Attribute +Description +Required ++ +allowtie +Whether a tie (when there is an even number + of nested resource selectors) is considered a majority +No, default true +compare
+Selects a resource based on its comparison to one or more "control" + resources using nested resource comparators.
++
++ +Attribute +Description +Required ++ +when +Comparison ("equal"/"eq", "greater"/"gt", "less"/"lt", + "le" (less or equal), "ge" (greater or equal), "ne" (not equal). +No, default "equal" ++ +against +Quantifier ("all"/"each"/"every", "any"/"some", + (exactly) "one", "most"/"majority", "none". +No, default "all" +Parameters specified as nested elements
+The resources against which comparisons will be made must be specified + using the nested <control> element, which denotes a + resources collection.
+Examples
+Assuming the namespace settings +
+rsel="antlib:org.apache.tools.ant.types.resources.selectors" + rcmp="antlib:org.apache.tools.ant.types.resources.comparators" +
+<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> ++Selects files a, b, c, and d.
++ <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> ++Creates the todir directory and copies (if present) the + files log4j.properties and default.properties + from the Classpath (already used while compiling). +
+ ++ <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> ++The resource collection allfiles defines a list of files which are expected. The restrict + missingfiles uses the <not><exists> selector for getting all files + which are not present. Finally we use the toString: pathshortcut for + getting them in a readable form: [echo] These files are missed: ....foo.txt;....bar.txt
+ +
Sorts a nested resource collection according to the resources' + natural order, or by one or more nested resource + comparators:
+++ ++
++ +Attribute +Description +Required ++ +cache +Whether to cache results; disabling + may seriously impact performance +No, default true +Parameters specified as nested elements
+A single resource collection is required.
+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 antlib +
+org.apache.tools.ant.types.resources.comparators
: +Resource Comparators:
++
+ +- name - sort resources by name
+- exists - sort resources by existence
+- date - sort resources by date
+- type - sort resources by type
+- size - sort resources by size
+- content - sort resources by content
+- reverse - reverse the natural sort order, + or that of a single nested resource comparator
+name
+Sort resources by name.
+ +exists
+Sort resources by existence. + Not existing is considered "less than" existing.
+ +date
+Sort resources by date.
+ +type
+Sort resources by type (file or directory). + Because directories contain files, they are considered "greater".
+ +size
+Sort resources by size.
+ +content
+Sort resources by content.
++
+ ++ +Attribute +Description +Required ++ +binary +Whether content should be compared in binary mode. + If false, content will be compared without regard to + platform-specific line-ending conventions. +No, default true +reverse
+Reverse the natural sort order, or that of a single nested comparator.
+ +Examples
++ <property name="eol" value="${line.separator}" /> + <pathconvert property="sorted" pathsep="${eol}"> + <sort> + <tokens> + <string value="foo bar etc baz" /> + <stringtokenizer /> + </tokens> + </sort> + </pathconvert>+The resource of type string "foo bar etc baz" is split into four tokens by + the stringtokenizer. These tokens are sorted and there sorted gets the value + of "bar baz etc foo".
+ ++ <sort> + <fileset dir="foo" /> + <reverse xmlns="antlib:org.apache.tools.ant.types.resources.comparators"> + <date /> + </reverse> + </sort>+This takes all files from foo + and sorts them by modification date in reverse order. + Because the resource comparators used (
+ +<reverse>
+ and<date>
) are in an internal antlib + their namespace must be set explicitly. +
Includes the first count resources from a nested resource collection. +This can be used in conjunction with the sort collection, +for example, to select the first few oldest, largest, etc. resources from a +larger collection.
+++ ++
++ +Attribute +Description +Required ++ +count +The number of resources to include +No, default 1 ++ +cache +Whether to cache results; disabling + may seriously impact performance +No, default true +Parameters specified as nested elements
+A single resource collection is required.
+
Includes the last count resources from a nested resource collection. +This can be used in conjunction with the sort collection, +for example, to select the last few oldest, largest, etc. resources from a +larger collection. Since Ant 1.7.1.
+++ ++
++ +Attribute +Description +Required ++ +count +The number of resources to include +No, default 1 ++ +cache +Whether to cache results; disabling + may seriously impact performance +No, default true +Parameters specified as nested elements
+A single resource collection is required.
+
Includes all elements except for the first count resources +from a nested resource collection. This can be used in conjunction +with the sort collection, for example, to select +all but the first few oldest, largest, etc. resources from a larger +collection. Since Ant 1.9.5.
+++ ++
++ +Attribute +Description +Required ++ +count +The number of resources to exclude +No, default 1 ++ +cache +Whether to cache results; disabling + may seriously impact performance +No, default true +Parameters specified as nested elements
+A single resource collection is required.
+
Includes all elements except for the last count resources +from a nested resource collection. This can be used in conjunction +with the sort collection, for example, to select +all but the last few oldest, largest, etc. resources from a larger +collection. Since Ant 1.9.5.
+++ ++
++ +Attribute +Description +Required ++ +count +The number of resources to exclude +No, default 1 ++ +cache +Whether to cache results; disabling + may seriously impact performance +No, default true +Parameters specified as nested elements
+A single resource collection is required.
+
Includes the string tokens gathered from a nested
+ resource collection. Uses the same tokenizers supported by the
+TokenFilter. Imaginative
+ use of this resource collection can implement equivalents for such Unix
+ functions as sort
, grep -c
, wc
and
+ wc -l
.
++ ++
++ +Attribute +Description +Required ++ +encoding +The encoding of the nested resources +No, default is platform default ++ +cache +Whether to cache results; disabling + may seriously impact performance +No, default true +Parameters specified as nested elements
++
+- A single resource collection is required.
+- One nested tokenizer may be specified. If omitted, a + LineTokenizer will be used. +
+Examples
+<concat> + <union> + <sort> + <tokens> + <resources refid="input" /> + <linetokenizer includedelims="true" /> + </tokens> + </sort> + </union> +</concat> ++Implements Unix sort -u against resource collection input.
+
++ +The following resource collections implement set operations:
++
+ +- union
+- intersect
+- difference
+union
+Union of nested resource collections.
+ +intersect
+Intersection of nested resource collections.
+ +difference
+Difference of nested resource collections.
+ +The following attributes apply to all set-operation resource collections: +
++
+ ++ +Attribute +Description +Required ++ +cache +Whether to cache results; disabling + may seriously impact performance +No, default true +Examples
++ <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> ++
Since Ant 1.8.0
+ +Wraps another resource collection and maps the names of the nested + resources using a mapper.
+ +Even if mappedresources wraps a resource collection that + consists of file-system based resources, mappedresources + will not appear to be file-system based. This means you can't + use mappedresources with tasks that only allow file-system + based resources.
+ +++ +Parameters specified as attributes
+ ++
+ ++ +Attribute +Description +Required ++ +cache +Whether to cache results; enabling + may improve performance. Since Ant 1.8.1 +No, default false ++ +enablemultiplemappings ++ 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. + since Ant 1.8.1. +No - defaults to false. +Parameters specified as nested elements
+A single resource collection is required.
+A single mapper 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.
+ +Examples
+ +Copies all files from a given directory to a target directory + adding ".bak" as an extension. Note this could be done with a + mapper nested into copy directly as well.
+ ++ <copy todir="${target}"> + <mappedresources> + <fileset dir="${src}"/> + <globmapper from="*" to="*.bak"/> + </mappedresources> + </copy> ++ +Creates a WAR archive adding all CLASSPATH entries that are files + to the
+ +WEB-INF/lib
directory without keeping their + files-system structure.+ <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> ++
Since Ant 1.8.0
+ +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 <archives>
are the contents of the nested
+ archives.
This resource collection is a generalization + of zipgroupfileset + which is only supported by the zip family of tasks.
+ +archives doesn't support any attributes.
+ +++ +Parameters specified as nested elements
+ ++ +
<archives>
has two nested + elements<zips>
and +<tars>
that are unions + themselves, i.e. they accept arbitrary many resource(collection)s + as nested elements.The nested resources of <zips> are treated as ZIP archives, + the nested resources of <tars> as TAR archives.
+ +Examples
+ +Copies all files from all jars that are on the classpath + to
+ +${target}
.+ <copy todir="${target}"> + <archives> + <zips> + <restrict> + <path path="${java.class.path}"/> + <name name="*.jar"/> + </restrict> + </zips> + </archives> + </copy> ++
Since Ant 1.8.0
+ +This resource collection accepts an arbitrary number of nested + resources, reads those resources and returns a resource for each + line read.
+ +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.
+ +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.
+ +<resourcelist>
is a generalization
+ of <filelist>
.
++ ++
++ +Attribute +Description +Required ++ +encoding +The encoding of the nested resources +No, default is platform default +
++ + + -- cgit 1.2.3-korgParameters specified as nested elements
+ ++ +
<resourcelist>
accepts arbitrary many + resource(collection)s as nested elements.In addition
+ +<resourcelist>
supports + nested<filterchain>
elements that can be used + to filter/modify the read resources before their lines get + expanded. Such a nested element corresponds to + a filterchain.Examples
+ +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
+ ++ mirrors.txt: +http://best.mirror.example.org/ +http://second.best.mirror.example.org/mirror/of/best/ +https://yet.another.mirror/ +http://the.original.site/ ++ ++ <copy todir="${target}"> + <first> + <restrict> + <resourcelist> + <file file="mirrors.txt"/> + </resourcelist> + <exists/> + </restrict> + </first> + </copy> ++