Resources and Resource Collections

## Resources

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 Ant 1.5.2, resources are available for explicit use beginning in Ant 1.7.

### The built-in resource types are:

- resource - a basic resource.
- bzip2resource - a BZip2 compressed resource.
- file - a file.
- gzipresource - a GZip compressed resource.
- javaresource - a resource loadable via a Java classloader.
- propertyresource - an Ant property.
- string - a text string.
- tarentry - an entry in a tar file.
- url - a URL.
- zipentry - an entry in a zip file.

#### resource

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.

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

Represents a file accessible via local filesystem conventions.

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

Represents a resource loadable via a Java classloader.

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

The classpath can also be specified as nested classpath element, where <classpath> is a path-like structure.

#### zipentry

Represents an entry in a ZIP archive. The archive can be specified using the archive attribute or a nested single-element resource collection. `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

Represents an entry in a TAR archive. The archive can be specified using the archive attribute or a nested single-element resource collection.

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

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.

#### bzip2resource

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.

#### url

Represents a URL.

Attribute | Description | Required
url | The url to expose | Exactly one of these
file | The file to expose as a file: url

#### string

Represents a Java String. As such a string is readable but not writable.

Attribute | Description | Required
value | The value of this resource | Yes

#### propertyresource

Represents an Ant property.

Attribute | Description | Required
name | The property name | Yes

## Resource Collections

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:

- fileset, dirset, filelist, and path (and derivative types) expose file resources
- tarfileset can expose file or tarentry resources depending on configuration
- zipfileset can expose file or zipentry resources depending on configuration
- propertyset exposes property resources

### The additional built-in resource collections are:

- resources - generic resource collection
- files - collection of files similar to fileset
- restrict - restrict a resource collection to include only resources meeting specified criteria
- sort - sorted resource collection
- first - first n resources from a nested collection
- tokens - string tokens gathered from a nested collection
- union - set union of nested resource collections
- intersect - set intersection of nested resource collections
- difference - set difference of nested resource collections

#### resources

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).

#### files

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.

#### restrict

Restricts another 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. 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.

> #### name

> Selects resources by name.

> Attribute | Description | Required
> name | The name pattern to test | Yes
> casesensitive | Whether name comparisons are case-sensitive | No, default true

> #### 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" | 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

> The following selects files a, b, c, and d:

>     <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>

#### sort

Sorts another 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.

#### first

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.

#### tokens

Includes the string tokens gathered from a nested resource collection. Uses the same tokenizers supported by the TokenFilter. Hint: 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.

#### Set operations

> 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