Processes a set of XML documents via XSLT. This is useful for building views of XML based documentation.

<patternset> ...

Named collection of include/exclude tags.

Moved out of MatchingTask to make it a standalone object that could be referenced (by scripts for example).

Attribute	Description	Type	Required
includes	Appends includes to the current list of include patterns. Patterns may be separated by a comma or a space.	String	?
refid	Makes this instance in effect a reference to another PatternSet instance. You must not set another attribute or nest elements inside this element if you make it a reference.	Reference	?
excludesfile	Sets the name of the file containing the excludes patterns.	File	?
includesfile	Sets the name of the file containing the includes patterns.	File	?
excludes	Appends excludes to the current list of exclude patterns. Patterns may be separated by a comma or a space.	String	?

<exclude>

inner class to hold a name on list. "If" and "Unless" attributes may be used to invalidate the entry based on the existence of a property (typically set thru the use of the Available task).

Attribute	Description	Type	Required
name	Sets the name pattern.	String	?
unless	Sets the unless attribute. This attribute and the "if" attribute are used to validate the name, based in the existence of the property.	String	?
if	Sets the if attribute. This attribute and the "unless" attribute are used to validate the name, based in the existence of the property.	String	?

<include>

inner class to hold a name on list. "If" and "Unless" attributes may be used to invalidate the entry based on the existence of a property (typically set thru the use of the Available task).

Attribute	Description	Type	Required
name	Sets the name pattern.	String	?
unless	Sets the unless attribute. This attribute and the "if" attribute are used to validate the name, based in the existence of the property.	String	?
if	Sets the if attribute. This attribute and the "unless" attribute are used to validate the name, based in the existence of the property.	String	?

<custom> (Of type ExtendSelector )

Selector that selects files by forwarding the request on to other classes.

Attribute	Description	Type	Required
classpath	Set the classpath to load the classname specified using an attribute.	Path	?
error		String	?
classpathref	Set the classpath to use for loading a custom selector by using a reference.	Reference	?
refid		Reference	?
classname	Sets the classname of the custom selector.	String	?

<present> (Of type PresentSelector )

Selector that filters files based on whether they appear in another directory tree. It can contain a mapper element, so isn't available as an ExtendSelector (since those parameters can't hold other elements).

Attribute	Description	Type	Required
error		String	?
targetdir	The name of the file or directory which is checked for matching files.	File	?
refid		Reference	?
present	This sets whether to select a file if its dest file is present. It could be a negate boolean, but by doing things this way, we get some documentation on how the system works. A user looking at the documentation should clearly understand that the ONLY files whose presence is being tested are those that already exist in the source directory, hence the lack of a destonly option.	String ["srconly", "both"]	?

<none> (Of type NoneSelector )

This selector has a collection of other selectors. All of those selectors must refuse to select a file before the file is considered selected by this selector.

Attribute	Description	Type	Required
error		String	?
refid		Reference	?

<not> (Of type NotSelector )

This selector has one other selectors whose meaning it inverts. It actually relies on NoneSelector for its implementation of the isSelected() method, but it adds a check to ensure there is only one other selector contained within.

Attribute	Description	Type	Required
error		String	?
refid		Reference	?

<type> (Of type TypeSelector )

Selector that selects a certain kind of file: directory or regular.

Attribute	Description	Type	Required
error		String	?
refid		Reference	?
type	Set the type of file to require.	String ["file", "dir"]	?

<factory> ...

The factory element to configure a transformer factory

Attribute	Description	Type	Required
name	Set the name of the factory	String	?

<modified> (Of type ModifiedSelector )

Selector class that uses Algorithm, Cache and Comparator for its work. The Algorithm is used for computing a hashvalue for a file. The Comparator decides whether to select or not. The Cache stores the other value for comparison by the Comparator in a persistent manner.

The ModifiedSelector is implemented as a CoreSelector and uses default values for all its attributes therefore the simpliest example is

The same example rewritten as CoreSelector with setting the all values (same as defaults are) would be

And the same rewritten as CustomSelector would be

All these three examples copy the files from src to dest using the ModifiedSelector. The ModifiedSelector uses the PropertyfileCache , the DigestAlgorithm and the EqualComparator for its work. The PropertyfileCache stores key-value-pairs in a simple java properties file. The filename is cache.properties. The update flag lets the selector update the values in the cache (and on first call creates the cache). The DigestAlgorithm computes a hashvalue using the java.security.MessageDigest class with its MD5-Algorithm and its standard provider. The new computed hashvalue and the stored one are compared by the EqualComparator which returns 'true' (more correct a value not equals zero (1)) if the values are not the same using simple String comparison.

A useful scenario for this selector is inside a build environment for homepage generation (e.g. with Apache Forrest).

 
      generate the site using forrest 
     

      upload the changed files 
     
         
             
         
     
 
 

Here all changed files are uploaded to the server. The ModifiedSelector saves therefore much upload time.

This selector supports the following nested param's:

name	values	description	required
cache	propertyfile	which cache implementation should be used propertyfile - using java.util.Properties	no, defaults to 'propertyfile'
algorithm	hashvalue | digest	which algorithm implementation should be used hashvalue - loads the file content into a String and uses its hashValue() method digest - uses java.security.MessageDigest class	no, defaults to digest
comparator	equal | role	which comparator implementation should be used equal - simple comparison using String.equals() role - uses java.text.RuleBasedCollator class	no, defaults to equal
update	true | false	If set to true, the cache will be stored, otherwise the values will be lost.	no, defaults to true
seldirs	true | false	If set to true, directories will be selected otherwise not	no, defaults to true
cache.*	depends on used cache	value is stored and given to the Cache-Object for initialisation	depends on used cache
algorithm.*	depends on used algorithm	value is stored and given to the Algorithm-Object for initialisation	depends on used algorithm
comparator.*	depends on used comparator	value is stored and given to the Comparator-Object for initialisation	depends on used comparator

If another name is used a BuildException "Invalid parameter" is thrown.

This selector uses reflection for setting the values of its three interfaces (using org.apache.tools.ant.IntrospectionHelper) therefore no special 'configuration interfaces' has to be implemented by new caches, algorithms or comparators. All present setXX methods can be used. E.g. the DigestAlgorithm can use a specified provider for computing its value. For selecting this there is a setProvider(String providername) method. So you can use a nested .

Attribute	Description	Type	Required
comparator		String ["equal", "rule"]	?
seldirs	Support for seldirs attribute.	boolean	?
algorithm		String ["hashvalue", "digest"]	?
cache		String ["propertyfile"]	?
error		String	?
refid		Reference	?
update	Support for update attribute.	boolean	?

<param>

The Param inner class used to store XSL parameters

Attribute	Description	Type	Required
name	Set the parameter name.	String	?
unless	Set whether this param should NOT be used. It will not be used if the property has been set, otherwise it will be used.	String	?
if	Set whether this param should be used. It will be used if the property has been set, otherwise it won't.	String	?
expression	The parameter value NOTE : was intended to be an XSL expression.	String	?

<or> (Of type OrSelector )

This selector has a collection of other selectors, any of which have to select a file in order for this selector to select it.

Attribute	Description	Type	Required
error		String	?
refid		Reference	?

<contains> (Of type ContainsSelector )

Selector that filters files based on whether they contain a particular string.

Attribute	Description	Type	Required
error		String	?
casesensitive	Whether to ignore case in the string being searched.	boolean	?
refid		Reference	?
ignorewhitespace	Whether to ignore whitespace in the string being searched.	boolean	?
text	The string to search for within a file.	String	?

<depend> (Of type DependSelector )

Selector that filters files based on whether they are newer than a matching file in another directory tree. It can contain a mapper element, so isn't available as an ExtendSelector (since those parameters can't hold other elements).

Attribute	Description	Type	Required
error		String	?
targetdir		File	?
refid		Reference	?
granularity		int	?

<classpath> ...

This object represents a path as used by CLASSPATH or PATH environment variable.

<sometask>
  <somepath>
    <pathelement location="/path/to/file.jar" />
    <pathelement path="/path/to/file2.jar:/path/to/class2;/path/to/class3" />
    <pathelement location="/path/to/file3.jar" />
    <pathelement location="/path/to/file4.jar" />
  </somepath>
</sometask>


The object implemention sometask must provide a method called createSomepath which returns an instance of Path. Nested path definitions are handled by the Path object and must be labeled pathelement.

The path element takes a parameter path which will be parsed and split into single elements. It will usually be used to define a path from an environment variable.

Attribute	Description	Type	Required
refid	Makes this instance in effect a reference to another Path instance. You must not set another attribute or nest elements inside this element if you make it a reference.	Reference	?
path	Parses a path definition and creates single PathElements.	String	?

<different> (Of type DifferentSelector )

This selector selects files against a mapped set of target files, selecting all those files which are different. Files with different lengths are deemed different automatically Files with identical timestamps are viewed as matching by default, unless you specify otherwise. Contents are compared if the lengths are the same and the timestamps are ignored or the same, except if you decide to ignore contents to gain speed.

This is a useful selector to work with programs and tasks that don't handle dependency checking properly; Even if a predecessor task always creates its output files, followup tasks can be driven off copies made with a different selector, so their dependencies are driven on the absolute state of the files, not a timestamp.

Clearly, however, bulk file comparisons is inefficient; anything that can use timestamps is to be preferred. If this selector must be used, use it over as few files as possible, perhaps following it with an <uptodate;> to keep the descendent routines conditional.

Attribute	Description	Type	Required
ignorecontents	This flag tells the selector to ignore contents	boolean	?
error		String	?
targetdir		File	?
refid		Reference	?
ignorefiletimes	This flag tells the selector to ignore file times in the comparison	boolean	?
granularity		int	?

<size> (Of type SizeSelector )

Selector that filters files based on their size.

Attribute	Description	Type	Required
when	This specifies when the file should be selected, whether it be when the file matches a particular size, when it is smaller, or whether it is larger.	String ["less", "more", "equal"]	?
units	Sets the units to use for the comparison. This is a little complicated because common usage has created standards that play havoc with capitalization rules. Thus, some people will use "K" for indicating 1000's, when the SI standard calls for "k". Others have tried to introduce "K" as a multiple of 1024, but that falls down when you reach "M", since "m" is already defined as 0.001. To get around this complexity, a number of standards bodies have proposed the 2^10 standard, and at least one has adopted it. But we are still left with a populace that isn't clear on how capitalization should work. We therefore ignore capitalization as much as possible. Completely mixed case is not possible, but all upper and lower forms are accepted for all long and short forms. Since we have no need to work with the 0.001 case, this practice works here. This function translates all the long and short forms that a unit prefix can occur in and translates them into a single multiplier.	String ["K", "k", "kilo", "KILO", "Ki", "KI", "ki", "kibi", "KIBI", "M", "m", "mega", "MEGA", "Mi", "MI", "mi", "mebi", "MEBI", "G", "g", "giga", "GIGA", "Gi", "GI", "gi", "gibi", "GIBI", "T", "t", "tera", "TERA", "Ti", "TI", "ti", "tebi", "TEBI"]	?
error		String	?
refid		Reference	?
value	A size selector needs to know what size to base its selecting on. This will be further modified by the multiplier to get an actual size limit.	long	?

<majority> (Of type MajoritySelector )

This selector is here just to shake up your thinking a bit. Don't get too caught up in boolean, there are other ways you can evaluate a collection of selectors. This one takes a vote of the selectors it contains, and majority wins. You could also have an "all-but-one" selector, a "weighted-average" selector, and so on. These are left as exercises for the reader (as are the usecases where this would be necessary).

Attribute	Description	Type	Required
error		String	?
refid		Reference	?
allowtie	A attribute to specify what will happen if number of yes votes is the same as the number of no votes defaults to true	boolean	?

<containsregexp> (Of type ContainsRegexpSelector )

Selector that filters files based on a regular expression.

Attribute	Description	Type	Required
error		String	?
refid		Reference	?
expression	The regular expression used to search the file.	String	?

<filename> (Of type FilenameSelector )

Selector that filters files based on the filename.

Attribute	Description	Type	Required
error		String	?
casesensitive	Whether to ignore case when checking filenames.	boolean	?
name	The name of the file, or the pattern for the name, that should be used for selection.	String	?
refid		Reference	?
negate	You can optionally reverse the selection of this selector, thereby emulating an <exclude> tag, by setting the attribute negate to true. This is identical to surrounding the selector with <not></not>.	boolean	?

<xmlcatalog> ...

This data type provides a catalog of resource locations (such as DTDs and XML entities), based on the OASIS "Open Catalog" standard. The catalog entries are used both for Entity resolution and URI resolution, in accordance with the {@link org.xml.sax.EntityResolver EntityResolver} and {@link javax.xml.transform.URIResolver URIResolver} interfaces as defined in the Java API for XML Processing Specification.

Resource locations can be specified either in-line or in external catalog file(s), or both. In order to use an external catalog file, the xml-commons resolver library ("resolver.jar") must be in your classpath. External catalog files may be either plain text format or XML format. If the xml-commons resolver library is not found in the classpath, external catalog files, specified in <catalogpath> paths, will be ignored and a warning will be logged. In this case, however, processing of inline entries will proceed normally.

Currently, only <dtd> and <entity> elements may be specified inline; these correspond to OASIS catalog entry types PUBLIC and URI respectively.

The following is a usage example:

<xmlcatalog>
  <dtd publicId="" location="/path/to/file.jar" />
  <dtd publicId="" location="/path/to/file2.jar" />
  <entity publicId="" location="/path/to/file3.jar" />
  <entity publicId="" location="/path/to/file4.jar" />
  <catalogpath>
    <pathelement location="/etc/sgml/catalog"/>
  </catalogpath>
  <catalogfiles dir="/opt/catalogs/" includes="**\catalog.xml" />
</xmlcatalog>


Tasks wishing to use <xmlcatalog> must provide a method called createXMLCatalog which returns an instance of XMLCatalog. Nested DTD and entity definitions are handled by the XMLCatalog object and must be labeled dtd and entity respectively.

The following is a description of the resolution algorithm: entities/URIs/dtds are looked up in each of the following contexts, stopping when a valid and readable resource is found:

1. In the local filesystem
2. In the classpath
3. Using the Apache xml-commons resolver (if it is available)
4. In URL-space

See {@link org.apache.tools.ant.taskdefs.optional.XMLValidateTask XMLValidateTask} for an example of a task that has integrated support for XMLCatalogs.

Possible future extension could provide for additional OASIS entry types to be specified inline.

Attribute	Description	Type	Required
catalogpathref	Allows catalogpath reference. Not allowed if this catalog is itself a reference to another catalog -- that is, a catalog cannot both refer to another and contain elements or other attributes.	Reference	?
classpath	Allows simple classpath string. Not allowed if this catalog is itself a reference to another catalog -- that is, a catalog cannot both refer to another and contain elements or other attributes.	Path	?
classpathref	Allows classpath reference. Not allowed if this catalog is itself a reference to another catalog -- that is, a catalog cannot both refer to another and contain elements or other attributes.	Reference	?
refid	Makes this instance in effect a reference to another XMLCatalog instance. You must not set another attribute or nest elements inside this element if you make it a reference. That is, a catalog cannot both refer to another and contain elements or attributes.	Reference	?

<selector> (Of type SelectSelector )

This selector just holds one other selector and forwards all requests to it. It exists so that there is a single selector type that can exist outside of any targets, as an element of project. It overrides all of the reference stuff so that it works as expected. Note that this is the only selector you can reference.

Attribute	Description	Type	Required
error		String	?
refid		Reference	?
unless	Sets the unless attribute to a property which cannot exist for the selector to select any files.	String	?
if	Sets the if attribute to a property which must exist for the selector to select any files.	String	?

<includesfile>

inner class to hold a name on list. "If" and "Unless" attributes may be used to invalidate the entry based on the existence of a property (typically set thru the use of the Available task).

Attribute	Description	Type	Required
name	Sets the name pattern.	String	?
unless	Sets the unless attribute. This attribute and the "if" attribute are used to validate the name, based in the existence of the property.	String	?
if	Sets the if attribute. This attribute and the "unless" attribute are used to validate the name, based in the existence of the property.	String	?

<outputproperty>

Specify how the result tree should be output as specified in the specification.

Attribute	Description	Type	Required
name	set the name for this property	String	?
value	set the value for this property	String	?

<mapper> ...

Element to define a FileNameMapper.

Attribute	Description	Type	Required
classpath	Set the classpath to load the FileNameMapper through (attribute).	Path	?
classpathref	Set the classpath to load the FileNameMapper through via reference (attribute).	Reference	?
refid	Make this Mapper instance a reference to another Mapper. You must not set any other attribute if you make it a reference.	Reference	?
type	Set the type of FileNameMapper to use.	String ["identity", "flatten", "glob", "merge", "regexp", "package", "unpackage"]	?
classname	Set the class name of the FileNameMapper to use.	String	?
from	Set the argument to FileNameMapper.setFrom	String	?
to	Set the argument to FileNameMapper.setTo	String	?

<date> (Of type DateSelector )

Selector that chooses files based on their last modified date.

Attribute	Description	Type	Required
refid		Reference	?
millis	For users that prefer to express time in milliseconds since 1970	long	?
checkdirs	Should we be checking dates on directories?	boolean	?
datetime	Sets the date. The user must supply it in MM/DD/YYYY HH:MM AM_PM format	String	?
granularity	Sets the number of milliseconds leeway we will give before we consider a file not to have matched a date.	int	?
pattern	Sets the pattern to be used for the SimpleDateFormat	String	?
when	Sets the type of comparison to be done on the file's last modified date.	String ["before", "after", "equal"]	?
error		String	?

<excludesfile>

inner class to hold a name on list. "If" and "Unless" attributes may be used to invalidate the entry based on the existence of a property (typically set thru the use of the Available task).

Attribute	Description	Type	Required
name	Sets the name pattern.	String	?
unless	Sets the unless attribute. This attribute and the "if" attribute are used to validate the name, based in the existence of the property.	String	?
if	Sets the if attribute. This attribute and the "unless" attribute are used to validate the name, based in the existence of the property.	String	?

<depth> (Of type DepthSelector )

Selector that filters files based on the how deep in the directory tree they are.

Attribute	Description	Type	Required
max	The minimum depth below the basedir before a file is selected.	int	?
error		String	?
min	The minimum depth below the basedir before a file is selected.	int	?
refid		Reference	?

<and> (Of type AndSelector )

This selector has a collection of other selectors, all of which have to select a file in order for this selector to select it.

Attribute	Description	Type	Required
error		String	?
refid		Reference	?