diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Types')
26 files changed, 9653 insertions, 0 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/antlib.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/antlib.html new file mode 100644 index 00000000..925320ae --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/antlib.html @@ -0,0 +1,266 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + + <head> + <meta http-equiv="Content-Language" content="en-us"></meta> + <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> + <title>AntLib</title> + </head> + + <body> + <h2><a name="antlib">Antlib</a></h2> + + + <h3>Description</h3> + <p> + An antlib file is an xml file with a root element of "antlib". + Antlib's elements are Apache Ant definition tasks - like + <a href="../Tasks/taskdef.html">Taskdef</a> + or any Ant task that extends + <code>org.apache.tools.ant.taskdefs.AntlibDefinition</code>. + </p> + <p> + The current set of declarations bundled with Ant that do this are: + </p> + <ol> + <li><a href="../Tasks/typedef.html">Typedef</a> + </li> + <li><a href="../Tasks/taskdef.html">Taskdef</a> + </li> + <li><a href="../Tasks/macrodef.html">Macrodef</a> + </li> + <li><a href="../Tasks/presetdef.html">Presetdef</a> + </li> + <li><a href="../Tasks/scriptdef.html">Scriptdef</a> + </li> + </ol> + <p> + A group of tasks and types may be defined together in an antlib + file. For example the file <i>sample.xml</i> contains the following: + </p> + <blockquote> + <pre> +<?xml version="1.0"?> +<antlib> + <typedef name="if" classname="org.acme.ant.If"/> + <typedef name="scriptpathmapper" + classname="org.acme.ant.ScriptPathMapper" + onerror="ignore"/> + <macrodef name="print"> + <attribute name="file"/> + <sequential> + <concat taskname="print"> + <fileset dir="." includes="@{file}"/> + </concat> + </sequential> + </macrodef> +</antlib> + </pre> + </blockquote> + <p> + It defines two types or tasks, <i>if</i> and <i>scriptpathmapper</i>. + This antlib file may be used in a build script as follows: + </p> + <blockquote> + <pre> +<typedef file="sample.xml"/> + </pre> + </blockquote> + <p> + The other attributes of <code><typedef></code> may be used as well. + For example, assuming that the <i>sample.xml</i> is in a jar + file <i>sample.jar</i> also containing the classes, the + following build fragment will define the <i>if</i> and <i>scriptpathmapper</i> + tasks/types and place them in the namespace uri <i>samples:/acme.org</i>. + </p> + <blockquote> + <pre> +<typedef resource="org/acme/ant/sample.xml" + uri="samples:/acme.org"/> + </pre> + </blockquote> + <p> + The definitions may then be used as follows: + </p> + <blockquote> + <pre> +<sample:if valuetrue="${props}" xmlns:sample="samples:/acme.org"> + <sample:scriptpathmapper language="beanshell"> + some bean shell + </sample:scriptpathmapper> +</sample:if> + </pre> + </blockquote> + + + <h3><a name="antlibnamespace">Antlib namespace</a></h3> + <p> + The name space URIs with the pattern <b>antlib:<i>java package</i></b> + are given special treatment. + </p> + <p> + When Ant encounters a element with a namespace URI with this pattern, it + will check to see if there is a resource of the name <i>antlib.xml</i> in + the package directory in the default classpath. + </p> + <p> + For example, assuming that the file <i>antcontrib.jar</i> has been placed + in the directory <i>${ant.home}/lib</i> and it contains the resource + <i>net/sf/antcontrib/antlib.xml</i> which has all antcontrib's definitions + defined, the following build file will automatically load the antcontrib + definitions at location <i>HERE</i>: + </p> + <blockquote> + <pre> +<project default="deletetest" xmlns:antcontrib="antlib:net.sf.antcontrib"> + <macrodef name="showdir"> + <attribute name="dir"/> + <sequential> + <antcontrib:shellscript shell="bash"> <!-- HERE --> + ls -Rl @{dir} + </antcontrib:shellscript> + </sequential> + </macrodef> + + <target name="deletetest"> + <delete dir="a" quiet="yes"/> + <mkdir dir="a/b"/> + <touch file="a/a.txt"/> + <touch file="a/b/b.txt"/> + <delete> + <fileset dir="a"/> + </delete> + <showdir dir="a"/> + </target> +</project> + </pre> + </blockquote> + <p> + The requirement that the resource is in the default classpath + may be removed in future versions of Ant.</p> + </p> + + + <h3><a name="loadFromInside">Load antlib from inside of the buildfile</a></h3> + <p> + If you want to separate the antlib from your local Ant installation, e.g. because you + want to hold that jar in your projects SCM system, you have to specify a classpath, so + that Ant could find that jar. The best solution is loading the antlib with <tt><taskdef></tt>. + </p> + <blockquote> + <pre> +<project xmlns:<font color="green">antcontrib</font>="<font color="red">antlib:net.sf.antcontrib</font>"> + <taskdef uri="<font color="red">antlib:net.sf.antcontrib</font>" + resource="net/sf/antcontrib/antlib.xml" + classpath="path/to/ant-contrib.jar"/> + + <target name="iterate"> + <<font color="green">antcontrib</font>:for param="file"> + <fileset dir="."/> + <sequential> + <echo message="- @{file}"/> + </sequential> + </antcontrib:for> + </target> +</project> + </pre> + </blockquote> + + + + + <h3><a name="currentnamespace">Current namespace</a></h3> + <p> + Definitions defined in antlibs may be used in antlibs. However + the namespace that definitions are placed in are dependent on + the <code><typedef></code> that uses the antlib. To deal with this + problem, the definitions are placed in the namespace URI <i>ant:current</i> + for the duration of the antlib execution. + For example the following antlib defines the task <code><if></code>, the + type <code><isallowed></code> and a macro + <code><ifallowed></code> that makes use of the task and type: + </p> + <blockquote> + <pre> +<antlib xmlns:current="ant:current"> + <taskdef name="if" classname="org.acme.ant.If"/> + <typedef name="isallowed" classname="org.acme.ant.Isallowed"/> + <macrodef name="ifallowed"> + <attribute name="action"/> + <element name="do"/> + <sequential> + <current:if> + <current:isallowed test="@{action}"/> + <current:then> + <do/> + </current:then> + </current:if> + </sequential> + </macrodef> +</antlib> + </pre> + </blockquote> + + + <h3>Other examples and comments</h3> + <p> + Antlibs may make use of other antlibs. + </p> + <p> + As the names defined in the antlib are in the namespace uri as + specified by the calling <code><typedef></code> or by automatic element + resolution, one may reuse names from core ant types and tasks, + provided the caller uses a namespace uri. For example, the + following antlib may be used to define defaults for various + tasks: + </p> + <blockquote> + <pre> +<antlib xmlns:antcontrib="antlib:net.sf.antcontrib"> + <presetdef name="javac"> + <javac deprecation="${deprecation}" + debug="${debug}"/> + </presetdef> + <presetdef name="delete"> + <delete quiet="yes"/> + </presetdef> + <presetdef name="shellscript"> + <antcontrib:shellscript shell="bash"/> + </presetdef> +</antlib> + </pre> + </blockquote> + <p> + This may be used as follows: + </p> + <blockquote> + <pre> +<project xmlns:local="localpresets"> + <typedef file="localpresets.xml" uri="localpresets"/> + <local:shellscript> + echo "hello world" + </local:shellscript> +</project> + </pre> + </blockquote> + + + +</body> +</html> + diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/assertions.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/assertions.html new file mode 100644 index 00000000..e168969f --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/assertions.html @@ -0,0 +1,208 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>Assertions type</title> +</head> + +<body> + +<h2><a name="assertions">Assertions</a></h2> +<p> +The <tt>assertions</tt> type enables or disables the Java 1.4 assertions feature, +on a whole Java program, or components of a program. It can be used +in <a href="../Tasks/java.html"><code><java></code></a> and +<a href="../Tasks/junit.html"><code><junit></code></a> to add extra validation to code. + +<p> +Assertions are covered in the +<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/language/assert.html">Java SE documentation</a>, +and the +<a href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-14.html#jls-14.10">Java Language Specification</a>. + +<p> +The key points to note are that a <tt>java.lang.AssertionError</tt> +is thrown when an assertion fails, and that the facility is only available +on Java 1.4 and later. To enable assertions one must set <tt>source="1.4"</tt> +(or later) in <tt><javac></tt> when the source is being compiled, and +that the code must contain <tt>assert</tt> statements to be tested. The +result of such an action is code that neither compiles or runs on earlier +versions of Java. For this reason Apache Ant itself currently contains no assertions. +<p> + +When assertions are enabled (or disabled) in a task through nested +assertions elements, the class loader or command line is modified with the +appropriate options. This means that the JVM executed must be a Java 1.4 +or later JVM, even if there are no assertions in the code. Attempting to +enable assertions on earlier VMs will result in an "Unrecognized option" +error and the JVM will not start. + +<p> +<h4>Attributes</h4> +<p> + + +</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">enableSystemAssertions</td> + <td valign="top">Flag to turn system assertions on or off.</td> + <td valign="top" align="center">No; default is "unspecified"</td> + </tr> +</table> +<p> +When system assertions have been neither enabled nor disabled, then +the JVM is not given any assertion information - the default action of the + current JVMs is to disable system assertions. +<p> +Note also that there is no apparent documentation for what parts of the +JRE come with useful assertions. + +<h3>Nested elements</h3> + +<h4>enable</h4> +<p> +Enable assertions in portions of code. +If neither a package nor class is specified, assertions are turned on in <i>all</i> (user) code. +</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 name of a class on which to enable assertions.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">package</td> + <td valign="top"> + The name of a package in which to enable assertions on all classes. (Includes subpackages.) + Use "<tt>...</tt>" for the anonymous package. + </td> + <td valign="top" align="center">No</td> + </tr> +</table> + +<h4>disable</h4> +<p> +Disable assertions in portions of code. + +</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 name of a class on which to disable assertions.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">package</td> + <td valign="top"> + The name of a package in which to disable assertions on all classes. (Includes subpackages.) + Use "<tt>...</tt>" for the anonymous package. + </td> + <td valign="top" align="center">No</td> + </tr> +</table> +<p> + +Because assertions are disabled by default, it only makes sense to disable +assertions where they have been enabled in a parent package. + + +<h4>Examples</h4> + +<h5>Example: enable assertions in all user classes</h5> + +All classes not in the JRE (i.e. all non-system classes) will have assertions turned on. +<pre> +<assertions> + <enable/> +</assertions> +</pre> + +<h5>Example: enable a single class</h5> + +Enable assertions in a class called Test +<pre> +<assertions> + <enable class="Test"/> +</assertions> +</pre> + +<h5>Example: enable a package</h5> + +Enable assertions in the <tt>org.apache</tt> package +and all packages starting with the <tt>org.apache.</tt> prefix +<pre> +<assertions> + <enable package="org.apache"/> +</assertions> +</pre> + +<h5>Example: System assertions</h5> + +Example: enable system assertions and assertions in all <tt>org.apache</tt> packages except +for Ant (but including <tt>org.apache.tools.ant.Main</tt>) +<pre> +<assertions enableSystemAssertions="true"> + <enable package="org.apache"/> + <disable package="org.apache.tools.ant"/> + <enable class="org.apache.tools.ant.Main"/> +</assertions> +</pre> + +<h5>Example: disabled and anonymous package assertions</h5> + +Disable system assertions; enable those in the anonymous package +<pre> +<assertions enableSystemAssertions="false"> + <enable package="..."/> +</assertions> +</pre> + + +<h5>Example: referenced assertions</h5> + +This type is a datatype, so you can declare assertions and use them later + +<pre> +<assertions id="project.assertions"> + <enable package="org.apache.test"/> +</assertions> + +<assertions refid="project.assertions"/> +</pre> + + +</body> +</html> diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/classfileset.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/classfileset.html new file mode 100644 index 00000000..6145d979 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/classfileset.html @@ -0,0 +1,119 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>ClassFileSet Type</title> +</head> + +<body> +<h2><a name="fileset">ClassFileSet</a></h2> +<p>A classfileset is a specialized type of fileset which, given a set of +"root" classes, will include all of the class files upon which the +root classes depend. This is typically used to create a jar with all of the +required classes for a particular application. +</p> +<p> +classfilesets are typically used by reference. They are declared with an +"id" value and this is then used as a reference where a normal fileset +is expected. +</p> +<p> +This type requires the <code>BCEL</code> library. +</p> + + +<h3>Attributes</h3> +<p>The class fileset support the following attributes in addition +to those supported by the +<a href="../Types/fileset.html">standard fileset</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">rootclass</td> + <td valign="top">A single root class name</td> + <td valign="top" align="center">No</td> + </tr> +</table> + +<h3>Nested Elements</h3> + +<h4>Root</h4> +<p> +When more than one root class is required, multiple nested <code><root></code> elements +may be used +</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">classname</td> + <td valign="top">The fully qualified name of the root class</td> + <td align="center" valign="top">Yes</td> + </tr> +</table> + +<h4>RootFileSet</h4> +<p> +A root fileset is used to add a set of root classes from a fileset. In this case the entries in +the fileset are expected to be Java class files. The name of the Java class is determined by the +relative location of the classfile in the fileset. So, the file +<code>org/apache/tools/ant/Project.class</code> corresponds to the Java class +<code>org.apache.tools.ant.Project</code>.</p> + +<h4>Examples</h4> +<blockquote><pre> +<classfileset id="reqdClasses" dir="${classes.dir}"> + <root classname="org.apache.tools.ant.Project"/> +</classfileset> +</pre></blockquote> + +<p>This example creates a fileset containing all the class files upon which the +<code>org.apache.tools.ant.Project</code> class depends. This fileset could +then be used to create a jar. +</p> + +<blockquote><pre> +<jar destfile="minimal.jar"> + <fileset refid="reqdClasses"/> +</jar> +</pre></blockquote> + +<blockquote><pre> +<classfileset id="reqdClasses" dir="${classes.dir}"> + <rootfileset dir="${classes.dir}" includes="org/apache/tools/ant/Project*.class"/> +</classfileset> +</pre></blockquote> + +<p>This example constructs the classfileset using all the class with names starting with Project +in the org.apache.tools.ant package</p> + + + +</body> +</html> + diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/custom-programming.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/custom-programming.html new file mode 100644 index 00000000..96bade33 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/custom-programming.html @@ -0,0 +1,415 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + <head> + <meta http-equiv="Content-Language" content="en-us"></meta> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>Custom Components</title> + </head> + <body> + <h2>Custom Components</h2> + <h3>Overview</h3> + <p> + Custom components are conditions, selectors, filters and other + objects that are defined outside Apache Ant core. + </p> + <p> + In Ant 1.6 custom conditions, selectors and filters has + been overhauled. + </p> + <p> + It is now possible to define custom conditions, selectors and filters + that behave like Ant Core components. + This is achieved by allowing datatypes defined in build scripts + to be used as custom components if the class of the datatype + is compatible, or has been adapted by an adapter class. + </p> + <p> + The old methods of defining custom components are still supported. + </p> + <h3>Definition and use</h3> + <p> + A custom component is a normal Java class that implements a particular + interface or extends a particular class, or has been adapted to the + interface or class. + </p> + <p> + It is exactly like writing a + <a href="../develop.html#writingowntask">custom task</a>. + One defines attributes and nested elements by writing <i>setter</i> + methods and <i>add</i> methods. + </p> + <p> + After the class has been written, it is added to the ant system + by using <code><typedef></code>. + </p> + <h3><a name="customconditions">Custom Conditions</a></h3> + <p> + Custom conditions are datatypes that implement + <code>org.apache.tools.ant.taskdefs.condition.Condition</code>. + For example a custom condition that returns true if a + string is all upper case could be written as: + </p> + <blockquote> + <pre> +package com.mydomain; + +import org.apache.tools.ant.BuildException; +import org.apache.tools.ant.taskdefs.condition.Condition; + +public class AllUpperCaseCondition implements Condition { + private String value; + + // The setter for the "value" attribute + public void setValue(String value) { + this.value = value; + } + + // This method evaluates the condition + public boolean eval() { + if (value == null) { + throw new BuildException("value attribute is not set"); + } + return value.toUpperCase().equals(value); + } +} + </pre> + </blockquote> + + <p> + Adding the condition to the system is achieved as follows: + </p> + <blockquote> + <pre> +<typedef + name="alluppercase" + classname="com.mydomain.AllUpperCaseCondition" + classpath="${mydomain.classes}"/> + </pre> + </blockquote> + <p> + This condition can now be used wherever a Core Ant condition + is used. + </p> + <blockquote> + <pre> +<condition property="allupper"> + <alluppercase value="THIS IS ALL UPPER CASE"/> +</condition> + </pre> + </blockquote> + <h3><a name="customselectors">Custom Selectors</a></h3> + <p> + Custom selectors are datatypes that implement + <code>org.apache.tools.ant.types.selectors.FileSelector</code>. + </p> + <p>There is only one method required. + <code>public boolean isSelected(File basedir, String filename, + File file)</code>. + It returns true + or false depending on whether the given file should be + selected or not. + </p> + <p> + An example of a custom selection that selects filenames ending + in ".java" would be: + </p> + <blockquote> + <pre> +package com.mydomain; +import java.io.File; +import org.apache.tools.ant.types.selectors.FileSelector; +public class JavaSelector implements FileSelector { + public boolean isSelected(File b, String filename, File f) { + return filename.toLowerCase().endsWith(".java"); + } +} + </pre> + </blockquote> + <p> + Adding the selector to the system is achieved as follows: + </p> + <blockquote> + <pre> +<typedef + name="javaselector" + classname="com.mydomain.JavaSelector" + classpath="${mydomain.classes}"/> + </pre> + </blockquote> + <p> + This selector can now be used wherever a Core Ant selector + is used, for example: + </p> + <blockquote> + <pre> +<copy todir="to"> + <fileset dir="src"> + <javaselector/> + </fileset> +</copy> + </pre> + </blockquote> + + <p> + One may use + <code>org.apache.tools.ant.types.selectors.BaseSelector</code>, + a convenience class that provides reasonable default + behaviour. + It has some predefined behaviours you can take advantage + of. Any time you encounter a problem when setting attributes or + adding tags, you can call setError(String errmsg) and the class + will know that there is a problem. Then, at the top of your + <code>isSelected()</code> method call <code>validate()</code> and + a BuildException will be thrown with the contents of your error + message. The <code>validate()</code> method also gives you a + last chance to check your settings for consistency because it + calls <code>verifySettings()</code>. Override this method and + call <code>setError()</code> within it if you detect any + problems in how your selector is set up. + </p> + <p> + To write custom selector containers one should extend + <code>org.apache.tools.ant.types.selectors.BaseSelectorContainer</code>. + Implement the + <code>public boolean isSelected(File baseDir, String filename, File file)</code> + method to do the right thing. Chances are you'll want to iterate + over the selectors under you, so use + <code>selectorElements()</code> to get an iterator that will do + that. + </p> + <p> + For example to create a selector container that will select files + if a certain number of contained selectors select, one could write + a selector as follows: + </p> + <blockquote> + <pre> +public class MatchNumberSelectors extends BaseSelectorContainer { + private int number = -1; + public void setNumber(int number) { + this.number = number; + } + public void verifySettings() { + if (number < 0) { + throw new BuildException("Number attribute should be set"); + } + } + public boolean isSelected(File baseDir, String filename, File file) { + validate(); + int numberSelected = 0; + for (Enumeration e = selectorElements(); e.hasNextElement();) { + FileSelector s = (FileSelector) e.nextElement(); + if (s.isSelected(baseDir, filename, file)) { + numberSelected++; + } + } + return numberSelected == number; + } +} + </pre> + </blockquote> + <p> + To define and use this selector one could do: + </p> + <blockquote> + <pre> +<typedef name="numberselected" + classname="com.mydomain.MatchNumberSelectors"/> +... +<fileset dir="${src.path}"> + <numberselected number="2"> + <contains text="script" casesensitive="no"/> + <size value="4" units="Ki" when="more"/> + <javaselector/> + </numberselected> +</fileset> + </pre> + </blockquote> + <p> + <i>The custom selector</i> + </p> + <p> + The custom selector was the pre ant 1.6 way of defining custom selectors. + This method is still supported for backward compatibility. + </p> + <p>You can write your own selectors and use them within the selector + containers by specifying them within the <code><custom></code> tag.</p> + + <p>To create a new Custom Selector, you have to create a class that + implements + <code>org.apache.tools.ant.types.selectors.ExtendFileSelector</code>. + The easiest way to do that is through the convenience base class + <code>org.apache.tools.ant.types.selectors.BaseExtendSelector</code>, + which provides all of the methods for supporting + <code><param></code> tags. First, override the + <code>isSelected()</code> method, and optionally the + <code>verifySettings()</code> method. If your custom + selector requires parameters to be set, you can also override + the <code>setParameters()</code> method and interpret the + parameters that are passed in any way you like. Several of the + core selectors demonstrate how to do that because they can + also be used as custom selectors.</p> + + + <p>Once that is written, you include it in your build file by using + the <code><custom></code> tag. + </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">classname</td> + <td valign="top">The name of your class that implements + <code>org.apache.tools.ant.types.selectors.FileSelector</code>. + </td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">classpath</td> + <td valign="top">The classpath to use in order to load the + custom selector class. If neither this classpath nor the + classpathref are specified, the class will be + loaded from the classpath that Ant uses. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">classpathref</td> + <td valign="top">A reference to a classpath previously + defined. If neither this reference nor the + classpath above are specified, the class will be + loaded from the classpath that Ant uses. + </td> + <td valign="top" align="center">No</td> + </tr> + </table> + + <p>Here is how you use <code><custom></code> to + use your class as a selector: + </p> + + <blockquote><pre> +<fileset dir="${mydir}" includes="**/*"> + <custom classname="com.mydomain.MySelector"> + <param name="myattribute" value="myvalue"/> + </custom> +</fileset> + </pre></blockquote> + + + <p>The core selectors that can also be used as custom selectors + are</p> + + <ul> + <li><a href="selectors.html#containsselect">Contains Selector</a> with + classname <code>org.apache.tools.ant.types.selectors.ContainsSelector</code> + </li> + <li><a href="selectors.html#dateselect">Date Selector</a> with + classname <code>org.apache.tools.ant.types.selectors.DateSelector</code> + </li> + <li><a href="selectors.html#depthselect">Depth Selector</a> with + classname <code>org.apache.tools.ant.types.selectors.DepthSelector</code> + </li> + <li><a href="selectors.html#filenameselect">Filename Selector</a> with + classname <code>org.apache.tools.ant.types.selectors.FilenameSelector</code> + </li> + <li><a href="selectors.html#sizeselect">Size Selector</a> with + classname <code>org.apache.tools.ant.types.selectors.SizeSelector</code> + </li> + </ul> + + <p>Here is the example from the Depth Selector section rewritten + to use the selector through <code><custom></code>.</p> + + <blockquote><pre> +<fileset dir="${doc.path}" includes="**/*"> + <custom classname="org.apache.tools.ant.types.selectors.DepthSelector"> + <param name="max" value="1"/> + </custom> +</fileset> + </pre></blockquote> + + <p>Selects all files in the base directory and one directory below + that.</p> + + <h3><a name="filterreaders">Custom Filter Readers</a></h3> + <p> + Custom filter readers selectors are datatypes that implement + <code>org.apache.tools.ant.types.filters.ChainableReader</code>. + </p> + <p>There is only one method required. + <code>Reader chain(Reader reader)</code>. + This returns a reader that filters input from the specified + reader. + </p> + <p> + For example a filterreader that removes every second character + could be: + </p> + <blockquote> + <pre> +public class RemoveOddCharacters implements ChainableReader { + public Reader chain(Reader reader) { + return new BaseFilterReader(reader) { + int count = 0; + public int read() throws IOException { + while (true) { + int c = in.read(); + if (c == -1) { + return c; + } + count++; + if ((count % 2) == 1) { + return c; + } + } + } + } + } +} + </pre> + </blockquote> + <p> + For line oriented filters it may be easier to extend + <code>ChainableFilterReader</code> an inner class of + <code>org.apache.tools.ant.filters.TokenFilter</code>. + </p> + <p> + For example a filter that appends the line number could be + </p> + <blockquote> + <pre> +public class AddLineNumber extends ChainableReaderFilter { + private void lineNumber = 0; + public String filter(String string) { + lineNumber++; + return "" + lineNumber + "\t" + string; + } +} + </pre> + </blockquote> + + + <hr></hr> + </body> +</html> + diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/description.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/description.html new file mode 100644 index 00000000..85942be0 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/description.html @@ -0,0 +1,46 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>Apache Ant User Manual</title> +</head> + +<body> + +<h2><a name="description">Description</a></h2> +<h3>Description</h3> +<p>Allows for a description of the project to be specified that +will be included in the output of the <code>ant ‑projecthelp</code> +command.</p> + +<h3>Parameters</h3> +<p>(none)</p> +<h3>Examples</h3> +<pre> +<description> +This buildfile is used to build the Foo subproject within +the large, complex Bar project. +</description> +</pre> + + +</body> +</html> + diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/dirset.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/dirset.html new file mode 100644 index 00000000..0434e9c2 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/dirset.html @@ -0,0 +1,154 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>DirSet Type</title> +</head> + +<body> + +<h2><a name="dirset">DirSet</a></h2> +<p>A DirSet is a group of directories. These directories can be found in a +directory tree starting in a base directory and are matched by +patterns taken from a number of <a href="patternset.html">PatternSets</a> +and <a href="selectors.html">Selectors</a>. +</p> +<p>PatternSets can be specified as nested +<code><patternset></code> elements. In addition, DirSet holds +an implicit PatternSet and supports the nested +<code><include></code>, <code><includesfile></code>, +<code><exclude></code> and <code><excludesfile></code> +elements of <code><patternset></code> directly, as well as +<code><patternset></code>'s attributes.</p> +<p>Selectors are available as nested elements within the DirSet. +If any of the selectors within the DirSet do not select the directory, it +is not considered part of the DirSet. This makes a DirSet +equivalent to an <code><and></code> selector container.</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">dir</td> + <td valign="top">The root of the directory tree of this DirSet.</td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">includes</td> + <td valign="top">A comma- or space-separated list of patterns of directories that + must be included; all directories are included when omitted.</td> + <td valign="top" align="center">No</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. + <b>Note:</b> if the file is empty and there are no other + patterns defined for the fileset, all directories will be included. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">excludes</td> + <td valign="top">A comma- or space-separated list of patterns of directories that + must be excluded; no directories are excluded when omitted.</td> + <td valign="top" align="center">No</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> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">casesensitive</td> + <td valign="top">Specifies whether case-sensitivity should be applied + (<code>true</code>|<code>yes</code>|<code>on</code> or + <code>false</code>|<code>no</code>|<code>off</code>).</td> + <td valign="top" align="center">No; defaults to true.</td> + </tr> + <tr> + <td valign="top">followsymlinks</td> + <td valign="top">Shall symbolic links be followed? Defaults to + true. See <a href="fileset.html#symlink">fileset's documentation</a>.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">erroronmissingdir</td> + <td valign="top"> + Specify what happens if the base directory does not exist. + If true a build error will happen, if false, the dirset + will be ignored/empty. + Defaults to true. + <em>Since Apache Ant 1.7.1 (default is true for backward compatibility + reasons.)</em> + </td> + <td valign="top" align="center">No</td> + </tr> +</table> + +<h4>Examples</h4> + +<blockquote><pre> +<dirset dir="${build.dir}"> + <include name="apps/**/classes"/> + <exclude name="apps/**/*Test*"/> +</dirset> +</pre></blockquote> +<p>Groups all directories named <code>classes</code> found under the +<code>apps</code> subdirectory of <code>${build.dir}</code>, except those +that have the text <code>Test</code> in their name.</p> + +<blockquote><pre> +<dirset dir="${build.dir}"> + <patternset id="non.test.classes"> + <include name="apps/**/classes"/> + <exclude name="apps/**/*Test*"/> + </patternset> +</dirset> +</pre></blockquote> +<p>Groups the same directories as the above example, but also establishes +a PatternSet that can be referenced in other +<code><dirset></code> elements, rooted at a different directory.</p> + +<blockquote><pre> +<dirset dir="${debug_build.dir}"> + <patternset refid="non.test.classes"/> +</dirset> +</pre></blockquote> +<p>Groups all directories in directory <code>${debug_build.dir}</code>, +using the same patterns as the above example.</p> + +<blockquote><pre> +<dirset id="dirset" dir="${workingdir}"> + <present targetdir="${workingdir}"> + <mapper type="glob" from="*" to="*/${markerfile}" /> + </present> +</dirset> +</pre></blockquote> +<p>Selects all directories somewhere under <code>${workingdir}</code> +which contain a <code>${markerfile}</code>.</p> + + +</body> +</html> + diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/extension.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/extension.html new file mode 100644 index 00000000..b05c0a65 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/extension.html @@ -0,0 +1,114 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>Extension Type</title> +</head> + +<body> +<h2><a name="fileset">Extension</a></h2> +<p>Utility type that represents either an available "Optional Package" + (formerly known as "Standard Extension") as described in the manifest + of a JAR file, or the requirement for such an optional package.</p> +<p>Note that this type +works with extensions as defined by the "Optional Package" specification. + For more information about optional packages, see the document +<em>Optional Package Versioning</em> in the documentation bundle for your +Java2 Standard Edition package, in file +<code>guide/extensions/versioning.html</code> or the online +<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/versioning/spec/versioning2.html#wp90779"> +Package Versioning documentation.</p> + +<h3>Attributes</h3> +<p>The extension type supports the following attributes</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">extensionName</td> + <td valign="top">The name of extension</td> + <td valign="top" align="center">yes</td> + </tr> + <tr> + <td valign="top">specificationVersion</td> + <td valign="top">The version of extension specification (Must be in + dewey decimal aka dotted decimal notation. 3.2.4)</td> + <td valign="top" align="center">no</td> + </tr> + <tr> + <td valign="top">specificationVendor</td> + <td valign="top">The specification vendor</td> + <td valign="top" align="center">no</td> + </tr> + <tr> + <td valign="top">implementationVersion</td> + <td valign="top">The version of extension implementation (Must be in + dewey decimal aka dotted decimal notation. 3.2.4)</td> + <td valign="top" align="center">no</td> + </tr> + <tr> + <td valign="top">implementationVendor</td> + <td valign="top">The implementation vendor</td> + <td valign="top" align="center">no</td> + </tr> + <tr> + <td valign="top">implementationVendorId</td> + <td valign="top">The implementation vendor ID</td> + <td valign="top" align="center">no</td> + </tr> + <tr> + <td valign="top">implementationURL</td> + <td valign="top">The url from which to retrieve extension.</td> + <td valign="top" align="center">no</td> + </tr> +</table> + +<h4>Examples</h4> +<blockquote><pre> +<extension id="e1" + extensionName="MyExtensions" + specificationVersion="1.0" + specificationVendor="Peter Donald" + implementationVendorID="vv" + implementationVendor="Apache" + implementationVersion="2.0" + implementationURL="http://somewhere.com/myExt.jar"/> +</pre></blockquote> + +<p>Fully specific extension object.</p> + +<blockquote><pre> +<extension id="e1" + extensionName="MyExtensions" + specificationVersion="1.0" + specificationVendor="Peter Donald"/> +</pre></blockquote> + +<p>Extension object that just species the specification details.</p> + + + +</body> +</html> + diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/extensionset.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/extensionset.html new file mode 100644 index 00000000..f38c1ed1 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/extensionset.html @@ -0,0 +1,83 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>ExtensionSet Type</title> +</head> + +<body> +<h2><a>ExtensionSet</a></h2> +<p>Utility type that represents a set of Extensions.</p> +<p>Note that this type +works with extensions as defined by the "Optional Package" specification. + For more information about optional packages, see the document +<em>Optional Package Versioning</em> in the documentation bundle for your +Java2 Standard Edition package, in file +<code>guide/extensions/versioning.html</code> or online at +<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/versioning/spec/versioning2.html#wp90779"> +Package Versioning documentation.</p> + +<h3>Nested Elements</h3> + +<h4>extension</h4> +<p><a href="extension.html">Extension</a> object to add to set.</p> + +<h4>fileset</h4> + <p><a href="../Types/fileset.html">FileSet</a>s all files contained + contained within set that are jars and implement an extension are added + to extension set.</p> + +<h4>LibFileSet</h4> + <p>All files contained contained within set that are jars and implement + an extension are added to extension set. However the extension information + may be modified by attributes of libfileset</p> + +<h4>Examples</h4> +<blockquote><pre> +<extension id="e1" + extensionName="MyExtensions" + specificationVersion="1.0" + specificationVendor="Peter Donald" + implementationVendorID="vv" + implementationVendor="Apache" + implementationVersion="2.0" + implementationURL="http://somewhere.com/myExt.jar"/> + +<libfileset id="lfs" + includeUrl="true" + includeImpl="false" + dir="tools/lib"> + <include name="*.jar"/> +</libfileset> + +<extensionSet id="exts"> + <libfileset dir="lib"> + <include name="*.jar"/> + </libfileset> + <libfileset refid="lfs"/> + <extension refid="e1"/> +</extensionSet> + +</pre></blockquote> + + + +</body> +</html> + diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/filelist.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/filelist.html new file mode 100644 index 00000000..57c981d3 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/filelist.html @@ -0,0 +1,120 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>FileList Type</title> +</head> + +<body> + +<h2><a name="filelist">FileList</a></h2> + +<p>FileLists are explicitly named lists of files. Whereas FileSets +act as filters, returning only those files that exist in the file +system and match specified patterns, FileLists are useful for +specifying files that may or may not exist. Multiple files are +specified as a list of files, relative to the specified directory, +with no support for wildcard expansion (filenames with wildcards will be +included in the list unchanged). +FileLists can appear inside tasks that support this feature or as stand-alone +types. +</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">dir</td> + <td valign="top">The base directory of this FileList.</td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">files</td> + <td valign="top">The list of file names. This is a list of + file name separated by whitespace, or by commas.</td> + <td valign="top" align="center"> + Yes, unless there is a nested file element</td> + </tr> +</table> + <h4>Nested Element: file</h4> + <p> + This represents a file name. The nested element allows filenames containing + white space and commas. + </p> + <p><em>Since Apache Ant 1.6.2</em></p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name of the file.</td> + <td valign="top" align="center">Yes</td> + </tr> +</table> +<h4>Examples</h4> +<blockquote><pre> +<filelist + id="docfiles" + dir="${doc.src}" + files="foo.xml,bar.xml"/> +</pre></blockquote> + +<p>The files <code>${doc.src}/foo.xml</code> and +<code>${doc.src}/bar.xml</code>. Note that these files may not (yet) +actually exist. +</p> + +<blockquote><pre> +<filelist + id="docfiles" + dir="${doc.src}" + files="foo.xml + bar.xml"/> +</pre></blockquote> + +<p>Same files as the example above.</p> + +<blockquote><pre> +<filelist refid="docfiles"/> +</pre></blockquote> + +<p>Same files as the example above.</p> + +<blockquote><pre> +<filelist + id="docfiles" + dir="${doc.src}"> + <file name="foo.xml"/> + <file name="bar.xml"/> +</filelist> +</pre></blockquote> + +<p>Same files as the example above.</p> + + + +</body> +</html> + diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/fileset.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/fileset.html new file mode 100644 index 00000000..9a7c7d71 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/fileset.html @@ -0,0 +1,186 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>FileSet Type</title> +</head> + +<body> + +<h2><a name="fileset">FileSet</a></h2> +<p>A FileSet is a group of files. These files can be found in a +directory tree starting in a base directory and are matched by +patterns taken from a number of <a +href="patternset.html">PatternSets</a> and +<a href="selectors.html">Selectors</a>. +<p>PatternSets can be specified as nested +<code><patternset></code> elements. In addition, FileSet 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>Selectors are available as nested elements within the FileSet. +If any of the selectors within the FileSet do not select the file, the +file is not considered part of the FileSet. This makes a FileSet +equivalent to an <code><and></code> selector container.</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">dir</td> + <td valign="top">the root of the directory tree of this FileSet.</td> + <td valign="middle" align="center" rowspan="2">Either dir or file must be specified</td> + </tr> + <tr> + <td valign="top">file</td> + <td valign="top">shortcut for specifying a single-file fileset</td> + </tr> + <tr> + <td valign="top">defaultexcludes</td> + <td valign="top">indicates whether <a href="../dirtasks.html#defaultexcludes">default excludes</a> should be used or not + (<code>yes | no</code>); default excludes are used when omitted.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">includes</td> + <td valign="top">comma- or space-separated list of patterns of files that must be + included; all files are included when omitted.</td> + <td valign="top" align="center">No</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.<br/> + <b>Note:</b> if the file is empty and there are no other + patterns defined for the fileset, all files will be included. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">excludes</td> + <td valign="top">comma- or space-separated list of patterns of files that must be + excluded; no files (except default excludes) are excluded when omitted.</td> + <td valign="top" align="center">No</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> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">casesensitive</td> + <td valign="top">Must the include and exclude patterns be treated in a case sensitive way? + Defaults to true.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">followsymlinks</td> + <td valign="top">Shall symbolic links be followed? Defaults to + true. See the note <a href="#symlink">below</a>.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">erroronmissingdir</td> + <td valign="top"> + Specify what happens if the base directory does not exist. + If true a build error will happen, if false, the fileset + will be ignored/empty. + Defaults to true. + <em>Since Apache Ant 1.7.1 (default is true for backward compatibility + reasons.)</em> + </td> + <td valign="top" align="center">No</td> + </tr> +</table> + +<p><a name="symlink"><b>Note</b></a>: All files/directories for which +the canonical path is different from its path are considered symbolic +links. On Unix systems this usually means the file really is a +symbolic link but it may lead to false results on other +platforms.</p> + +<h4>Examples</h4> +<blockquote><pre> +<fileset dir="${server.src}" casesensitive="yes"> + <include name="**/*.java"/> + <exclude name="**/*Test*"/> +</fileset> +</pre></blockquote> +<p>Groups all files in directory <code>${server.src}</code> that are Java +source files and don't have the text <code>Test</code> in their +name.</p> + +<blockquote><pre> +<fileset dir="${server.src}" casesensitive="yes"> + <patternset id="non.test.sources"> + <include name="**/*.java"/> + <exclude name="**/*Test*"/> + </patternset> +</fileset> +</pre></blockquote> +<p>Groups the same files as the above example, but also establishes +a PatternSet that can be referenced in other +<code><fileset></code> elements, rooted at a different directory.</p> + +<blockquote><pre> +<fileset dir="${client.src}" > + <patternset refid="non.test.sources"/> +</fileset> +</pre></blockquote> +<p>Groups all files in directory <code>${client.src}</code>, using the +same patterns as the above example.</p> + +<blockquote><pre> +<fileset dir="${server.src}" casesensitive="yes"> + <filename name="**/*.java"/> + <filename name="**/*Test*" negate="true"/> +</fileset> +</pre></blockquote> +<p>Groups the same files as the top example, but using the +<code><filename></code> selector.</p> + +<blockquote><pre> +<fileset dir="${server.src}" casesensitive="yes"> + <filename name="**/*.java"/> + <not> + <filename name="**/*Test*"/> + </not> +</fileset> +</pre></blockquote> +<p>Groups the same files as the previous example using a combination of the +<code><filename></code> selector and the <code><not></code> +selector container.</p> + +<blockquote><pre> +<fileset dir="src" includes="main/" /> +</pre></blockquote> +<p>Selects all files in <i>src/main</i> (e.g. <i>src/main/Foo.java</i> or +<i>src/main/application/Bar.java</i>).</p> + + + +</body> +</html> + diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/filterchain.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/filterchain.html new file mode 100644 index 00000000..4de10ea3 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/filterchain.html @@ -0,0 +1,1739 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> + +<html> +<head> + <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>FilterChains and FilterReaders</title> +</head> + +<body> + +<h2>FilterChains and FilterReaders</h2> +Consider the flexibility of Unix pipes. If you wanted, +for example, to copy just those lines that contained the +string blee from the first 10 lines of a text file 'foo' +(<em>you wouldn't want to filter a binary file</em>) +to a file 'bar', you would do something like:<p> +<code> +cat foo|head -n10|grep blee > bar +</code><p> +Apache Ant was not flexible enough. There was no way for the +<code><copy></code> task to do something similar. If you wanted +the <code><copy></code> task to get the first 10 lines, you would have +had to create special attributes:<p> +<code> +<copy file="foo" tofile="bar" head="10" contains="blee"/> +</code><p> +The obvious problem thus surfaced: Ant tasks would not be able +to accommodate such data transformation attributes as they would +be endless. The task would also not know in which order these +attributes were to be interpreted. That is, must the task execute the +contains attribute first and then the head attribute or vice-versa? +What Ant tasks needed was a mechanism to allow pluggable filter (data +transformer) chains. Ant would provide a few filters for which there +have been repeated requests. Users with special filtering needs +would be able to easily write their own and plug them in.<p> + +The solution was to refactor data transformation oriented +tasks to support FilterChains. A FilterChain is a group of +ordered FilterReaders. Users can define their own FilterReaders +by just extending the java.io.FilterReader class. Such custom +FilterReaders can be easily plugged in as nested elements of +<code><filterchain></code> by using <code><filterreader></code> elements. +<p> +Example: +<blockquote><pre> +<copy file="${src.file}" tofile="${dest.file}"> + <filterchain> + <filterreader classname="your.extension.of.java.io.FilterReader"> + <param name="foo" value="bar"/> + </filterreader> + <filterreader classname="another.extension.of.java.io.FilterReader"> + <classpath> + <pathelement path="${classpath}"/> + </classpath> + <param name="blah" value="blee"/> + <param type="abra" value="cadabra"/> + </filterreader> + </filterchain> +</copy> +</pre></blockquote> + +Ant provides some built-in filter readers. These filter readers +can also be declared using a syntax similar to the above syntax. +However, they can be declared using some simpler syntax also.<p> +Example: +<blockquote><pre> +<loadfile srcfile="${src.file}" property="src.file.head"> + <filterchain> + <headfilter lines="15"/> + </filterchain> +</loadfile> +</pre></blockquote> +is equivalent to: +<blockquote><pre> +<loadfile srcfile="${src.file}" property="src.file.head"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.HeadFilter"> + <param name="lines" value="15"/> + </filterreader> + </filterchain> +</loadfile> +</pre></blockquote> + +The following built-in tasks support nested <code><filterchain></code> elements.<br> +<a href="../Tasks/concat.html">Concat</a>,<br> +<a href="../Tasks/copy.html">Copy</a>,<br> +<a href="../Tasks/loadfile.html">LoadFile</a>,<br> +<a href="../Tasks/loadproperties.html">LoadProperties</a>,<br> +<a href="../Tasks/loadresource.html">LoadResource</a>,<br> +<a href="../Tasks/move.html">Move</a><br><br> + +A FilterChain is formed by defining zero or more of the following +nested elements.<br> +<a href="#filterreader">FilterReader</a><br> +<a href="#classconstants">ClassConstants</a><br> +<a href="#escapeunicode">EscapeUnicode</a><br> +<a href="#expandproperties">ExpandProperties</a><br> +<a href="#headfilter">HeadFilter</a><br> +<a href="#linecontains">LineContains</a><br> +<a href="#linecontainsregexp">LineContainsRegExp</a><br> +<a href="#prefixlines">PrefixLines</a><br> +<a href="#replacetokens">ReplaceTokens</a><br> +<a href="#stripjavacomments">StripJavaComments</a><br> +<a href="#striplinebreaks">StripLineBreaks</a><br> +<a href="#striplinecomments">StripLineComments</a><br> +<a href="#suffixlines">SuffixLines</a><br> +<a href="#tabstospaces">TabsToSpaces</a><br> +<a href="#tailfilter">TailFilter</a><br> +<a href="#deletecharacters">DeleteCharacters</a><br> +<a href="#concatfilter">ConcatFilter</a><br> +<a href="#tokenfilter">TokenFilter</a><br> +<a href="../Tasks/fixcrlf.html">FixCRLF</a><br> +<a href="#sortfilter">SortFilter</a><br> + +<h3><a name="filterreader">FilterReader</a></h3> + +The filterreader element is the generic way to +define a filter. User defined filter elements are +defined in the build file using this. Please note that +built in filter readers can also be defined using this +syntax. + +A FilterReader element must be supplied with a class name as +an attribute value. The class resolved by this name must +extend java.io.FilterReader. If the custom filter reader +needs to be parameterized, it must implement +org.apache.tools.type.Parameterizable. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>classname</td> + <td vAlign=top>The class name of the filter reader.</td> + <td vAlign=top align="center">Yes</td> + </tr> +</table> + +<p> +<h4>Nested Elements:</h4> +<code><filterreader></code> supports <code><classpath></code> and <code><param></code> +as nested elements. Each <code><param></code> element may take in the following +attributes - name, type and value. +<p> +The following FilterReaders are supplied with the default +distribution. + +<h3><a name="classconstants">ClassConstants</a></h3> +<p> + This filters basic constants defined in a Java Class, + and outputs them in lines composed of the format <i>name</i>=<i>value</i>. + This filter uses the <em>bcel</em> library to understand the Java Class file. + See <a href="../install.html#librarydependencies">Library Dependencies</a>. +<p> + <p> + <em><b>Important:</b></em> + This filter is different from most of the other filters. + Most of the filters operate on a sequence of characters. + This filter operates on the sequence of bytes that makes up + a class. However the bytes arrive to the filter as a sequence + of characters. This means that one must be careful on the + choice of character encoding to use. Most encoding lose information + on conversion from an arbitrary sequence of bytes to characters + and back again to bytes. In particular the usual default + character encodings (CP152 and UTF-8) do. + For this reason, <em>since Ant 1.7</em>, the character + encoding <b>ISO-8859-1</b> is used to convert from characters back to + bytes, so one <b>has</b> to use this encoding for reading the java + class file. +<h4>Example:</h4> + +This loads the basic constants defined in a Java class as Ant properties. + +<blockquote><pre> +<loadproperties srcfile="foo.class" encoding="ISO-8859-1"> + <filterchain> + <classconstants/> + </filterchain> +</loadproperties> +</pre></blockquote> + +This loads the constants from a Java class file as Ant properties, +prepending the names with a prefix. + + <blockquote><pre> +<loadproperties srcfile="build/classes/org/acme/bar.class" + encoding="ISO-8859-1"> + <filterchain> + <classconstants/> + <prefixlines prefix="ini."/> + </filterchain> +</loadproperties> +</pre></blockquote> +<h3><a name="escapeunicode">EscapeUnicode</a></h3> +<p> +This filter converts its input by changing all non US-ASCII characters +into their equivalent unicode escape backslash u plus 4 digits.</p> + +<p><em>since Ant 1.6</em></p> + +<h4>Example:</h4> + +This loads the basic constants defined in a Java class as Ant properties. +<blockquote><pre> +<loadproperties srcfile="non_ascii_property.properties"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.EscapeUnicode"/> + </filterchain> +</loadproperties> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<loadproperties srcfile="non_ascii_property.properties"> + <filterchain> + <escapeunicode/> + </filterchain> +</loadproperties> +</pre></blockquote> + +<h3><a name="expandproperties">ExpandProperties</a></h3> +<p> +If the data contains data that represents Ant +properties (of the form ${...}), that is substituted +with the property's actual value. +<p> +<h4>Example:</h4> + +This results in the property modifiedmessage holding the value +"All these moments will be lost in time, like teardrops in the rain" +<blockquote><pre> +<echo + message="All these moments will be lost in time, like teardrops in the ${weather}" + file="loadfile1.tmp" + /> +<property name="weather" value="rain"/> +<loadfile property="modifiedmessage" srcFile="loadfile1.tmp"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.ExpandProperties"/> + </filterchain> +</loadfile> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<echo + message="All these moments will be lost in time, like teardrops in the ${weather}" + file="loadfile1.tmp" + /> +<property name="weather" value="rain"/> +<loadfile property="modifiedmessage" srcFile="loadfile1.tmp"> + <filterchain> + <expandproperties/> + </filterchain> +</loadfile> +</pre></blockquote> + +<p>As of Ant <strong>1.8.3</strong>, a nested + <a href="propertyset.html">PropertySet</a> can be specified: + +<blockquote><pre> +<property name="weather" value="rain"/> +<loadfile property="modifiedmessage" srcFile="loadfile1.tmp"> + <filterchain> + <expandproperties> + <propertyset> + <propertyref name="weather" /> + </propertyset> + </expandproperties> + </filterchain> +</loadfile> +</pre></blockquote> + +<h3><a name="headfilter">HeadFilter</a></h3> + +This filter reads the first few lines from the data supplied to it. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>lines</td> + <td vAlign=top align="center">Number of lines to be read. + Defaults to "10" <br> A negative value means that all lines are + passed (useful with <i>skip</i>)</td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>skip</td> + <td vAlign=top align="center">Number of lines to be skipped (from the beginning). + Defaults to "0"</td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<p> +<h4>Example:</h4> + +This stores the first 15 lines of the supplied data in the property src.file.head +<blockquote><pre> +<loadfile srcfile="${src.file}" property="src.file.head"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.HeadFilter"> + <param name="lines" value="15"/> + </filterreader> + </filterchain> +</loadfile> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<loadfile srcfile="${src.file}" property="src.file.head"> + <filterchain> + <headfilter lines="15"/> + </filterchain> +</loadfile> +</pre></blockquote> + +This stores the first 15 lines, skipping the first 2 lines, of the supplied data +in the property src.file.head. (Means: lines 3-17) +<blockquote><pre> +<loadfile srcfile="${src.file}" property="src.file.head"> + <filterchain> + <headfilter lines="15" skip="2"/> + </filterchain> +</loadfile> +</pre></blockquote> + +See the testcases for more examples (<i>src\etc\testcases\filters\head-tail.xml</i> in the +source distribution). + +<h3><a name="linecontains">LineContains</a></h3> + +This filter includes only those lines that contain all the user-specified +strings. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Type</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>contains</td> + <td vAlign=top align="center">Substring to be searched for.</td> + <td vAlign=top align="center">Yes</td> + </tr> + <tr> + <td vAlign=top>negate</td> + <td vAlign=top align="center">Whether to select + <i>non-</i>matching lines only. <b>Since Ant 1.7</b></td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<p> +<h4>Example:</h4> + +This will include only those lines that contain <code>foo</code> and +<code>bar</code>. +<blockquote><pre> +<filterreader classname="org.apache.tools.ant.filters.LineContains"> + <param type="contains" value="foo"/> + <param type="contains" value="bar"/> +</filterreader> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<linecontains> + <contains value="foo"/> + <contains value="bar"/> +</linecontains> +</pre></blockquote> + +Negation: +<blockquote><pre> +<filterreader classname="org.apache.tools.ant.filters.LineContains"> + <param type="negate" value="true"/> + <param type="contains" value="foo"/> + <param type="contains" value="bar"/> +</filterreader> +</pre></blockquote> +<i>or</i> +<blockquote><pre> +<linecontains negate="true"> + <contains value="foo"/> + <contains value="bar"/> +</linecontains> +</pre></blockquote> + +<h3><a name="linecontainsregexp">LineContainsRegExp</a></h3> + +Filter which includes only those lines that contain the user-specified +regular expression matching strings. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Type</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>regexp</td> + <td vAlign=top align="center">Regular expression to be searched for.</td> + <td vAlign=top align="center">Yes</td> + </tr> + <tr> + <td vAlign=top>negate</td> + <td vAlign=top align="center">Whether to select + <i>non-</i>matching lines only. <b>Since Ant 1.7</b></td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>casesensitive</td> + <td vAlign=top align="center">Perform a case sensitive + match. Default is true. <b>Since Ant 1.8.2</b></td> + <td vAlign=top align="center">No</td> + </tr> +</table> + +See <a href="regexp.html">Regexp Type</a> for the description of the nested element regexp and of +the choice of regular expression implementation. +<h4>Example:</h4> + +This will fetch all those lines that contain the pattern <code>foo</code> +<blockquote><pre> +<filterreader classname="org.apache.tools.ant.filters.LineContainsRegExp"> + <param type="regexp" value="foo*"/> +</filterreader> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<linecontainsregexp> + <regexp pattern="foo*"/> +</linecontainsregexp> +</pre></blockquote> + +Negation: +<blockquote><pre> +<filterreader classname="org.apache.tools.ant.filters.LineContainsRegExp"> + <param type="negate" value="true"/> + <param type="regexp" value="foo*"/> +</filterreader> +</pre></blockquote> +<i>or</i> +<blockquote><pre> +<linecontainsregexp negate="true"> + <regexp pattern="foo*"/> +</linecontainsregexp> +</pre></blockquote> + +<h3><a name="prefixlines">PrefixLines</a></h3> + +Attaches a prefix to every line. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>prefix</td> + <td vAlign=top align="center">Prefix to be attached to lines.</td> + <td vAlign=top align="center">Yes</td> + </tr> +</table> +<p> +<h4>Example:</h4> + +This will attach the prefix <code>Foo</code> to all lines. +<blockquote><pre> +<filterreader classname="org.apache.tools.ant.filters.PrefixLines"> + <param name="prefix" value="Foo"/> +</filterreader> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<prefixlines prefix="Foo"/> +</pre></blockquote> + +<h3><a name="suffixlines">SuffixLines</a></h3> + +Attaches a suffix to every line. + +<p><em>since Ant 1.8.0</em></p> + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>suffix</td> + <td vAlign=top align="center">Suffix to be attached to lines.</td> + <td vAlign=top align="center">Yes</td> + </tr> +</table> +<p> +<h4>Example:</h4> + +This will attach the suffix <code>Foo</code> to all lines. +<blockquote><pre> +<filterreader classname="org.apache.tools.ant.filters.SuffixLines"> + <param name="suffix" value="Foo"/> +</filterreader> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<suffixlines suffix="Foo"/> +</pre></blockquote> + +<h3><a name="replacetokens">ReplaceTokens</a></h3> + +This filter reader replaces all strings that are +sandwiched between begintoken and endtoken with +user defined values. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Type</b></td> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>tokenchar</td> + <td vAlign=top>begintoken</td> + <td vAlign=top>String marking the + beginning of a token. Defaults to @</td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>tokenchar</td> + <td vAlign=top>endtoken</td> + <td vAlign=top>String marking the + end of a token. Defaults to @</td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>User defined String.</td> + <td vAlign=top>token</td> + <td vAlign=top>User defined search String.</td> + <td vAlign=top align="center">Yes</td> + </tr> + <tr> + <td vAlign=top>Not applicable.</td> + <td vAlign=top>propertiesfile</td> + <td vAlign=top>Properties file to take tokens from.</td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>Not applicable.</td> + <td vAlign=top>propertiesResource</td> + <td vAlign=top>Properties resource to take tokens from. + Note this only works is you use the + "convenience" <code><replacetokens></code> syntax. + <em>since Ant 1.8.0</em></td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>User defined String.</td> + <td vAlign=top>value</td> + <td vAlign=top>Replace-value for the token</td> + <td vAlign=top align="center">No</td> + </tr></table> +<p> + +<h4>Example:</h4> + +This replaces occurrences of the string @DATE@ in the data +with today's date and stores it in the property ${src.file.replaced}. +<blockquote><pre> +<tstamp/> +<!-- just for explaining the use of the properties --> +<property name="src.file" value="orders.csv"/> +<property name="src.file.replaced" value="orders.replaced"/> + +<!-- do the loading and filtering --> +<loadfile srcfile="${src.file}" property="${src.file.replaced}"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.ReplaceTokens"> + <param type="token" name="DATE" value="${TODAY}"/> + </filterreader> + </filterchain> +</loadfile> + +<!-- just for explaining the use of the properties --> +<echo message="${orders.replaced}"/> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<tstamp/> +<loadfile srcfile="${src.file}" property="${src.file.replaced}"> + <filterchain> + <replacetokens> + <token key="DATE" value="${TODAY}"/> + </replacetokens> + </filterchain> +</loadfile> +</pre></blockquote> + +This replaces occurrences of the string {{DATE}} in the data +with today's date and stores it in the property ${src.file.replaced}. +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.replaced}"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.ReplaceTokens"> + <param type="tokenchar" name="begintoken" value="{{"/> + <param type="tokenchar" name="endtoken" value="}}"/> + </filterreader> + </filterchain> +</loadfile> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<tstamp/> +<loadfile srcfile="${src.file}" property="${src.file.replaced}"> + <filterchain> + <replacetokens begintoken="{{" endtoken="}}"> + <token key="DATE" value="${TODAY}"/> + </replacetokens> + </filterchain> +</loadfile> +</pre></blockquote> + +This will treat each properties file entry in sample.properties as a token/key pair : +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.replaced}"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.ReplaceTokens"> + <param type="propertiesfile" value="sample.properties"/> + </filterreader> + </filterchain> +</loadfile> +</pre></blockquote> + +This reads the properties from an Ant resource referenced by its id: +<blockquote><pre> +<string id="embedded-properties"> +foo=bar +baz=xyzzy +</string> +<loadfile srcfile="${src.file}" property="${src.file.replaced}"> + <filterchain> + <replacetokens propertiesResource="${ant.refid:embedded-properties}"/> + </filterchain> +</loadfile> +</pre></blockquote> + +<h3><a name="stripjavacomments">StripJavaComments</a></h3> + +This filter reader strips away comments from the data, +using Java syntax guidelines. This filter does not +take in any parameters. +<p> +<h4>Example:</h4> + +<blockquote><pre> +<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.StripJavaComments"/> + </filterchain> +</loadfile> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}"> + <filterchain> + <stripjavacomments/> + </filterchain> +</loadfile> +</pre></blockquote> + +<h3><a name="striplinebreaks">StripLineBreaks</a></h3> + +This filter reader strips away specific characters +from the data supplied to it. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>linebreaks</td> + <td vAlign=top align="center">Characters that are to + be stripped out. Defaults to "\r\n"</td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<p> +<h4>Examples:</h4> + +This strips the '\r' and '\n' characters. +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.contents}"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.StripLineBreaks"/> + </filterchain> +</loadfile> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.contents}"> + <filterchain> + <striplinebreaks/> + </filterchain> +</loadfile> +</pre></blockquote> + +This treats the '(' and ')' characters as line break characters and +strips them. +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.contents}"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.StripLineBreaks"> + <param name="linebreaks" value="()"/> + </filterreader> + </filterchain> +</loadfile> +</pre></blockquote> + +<h3><a name="striplinecomments">StripLineComments</a></h3> + +This filter removes all those lines that begin with strings +that represent comments as specified by the user. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Type</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>comment</td> + <td vAlign=top align="center">Strings that identify a line as a comment + when they appear at the start of the line.</td> + <td vAlign=top align="center">Yes</td> + </tr> +</table> +<p> +<h4>Examples:</h4> + +This removes all lines that begin with #, --, REM, rem and // +<blockquote><pre> +<filterreader classname="org.apache.tools.ant.filters.StripLineComments"> + <param type="comment" value="#"/> + <param type="comment" value="--"/> + <param type="comment" value="REM "/> + <param type="comment" value="rem "/> + <param type="comment" value="//"/> +</filterreader> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<striplinecomments> + <comment value="#"/> + <comment value="--"/> + <comment value="REM "/> + <comment value="rem "/> + <comment value="//"/> +</striplinecomments> +</pre></blockquote> + +<h3><a name="tabstospaces">TabsToSpaces</a></h3> + +This filter replaces tabs with spaces + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>tablength</td> + <td vAlign=top align="center">Defaults to "8"</td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<p> +<h4>Examples:</h4> + +This replaces tabs in ${src.file} with spaces. +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.notab}"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.TabsToSpaces"/> + </filterchain> +</loadfile> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.notab}"> + <filterchain> + <tabstospaces/> + </filterchain> +</loadfile> +</pre></blockquote> + +<h3><a name="tailfilter">TailFilter</a></h3> + +This filter reads the last few lines from the data supplied to it. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>lines</td> + <td vAlign=top align="center">Number of lines to be read. + Defaults to "10" <br> A negative value means that all lines are + passed (useful with <i>skip</i>)</td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>skip</td> + <td vAlign=top align="center">Number of lines to be skipped (from the end). + Defaults to "0" </td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<p> + +<h4>Background:</h4> +With HeadFilter and TailFilter you can extract each part of a text file you want. +This graphic shows the dependencies: + +<table cellSpacing=0 cellPadding=2 border=1> +<tr> + <th> Content </th> + <th></th> + <th></th> + <th></th> + <th> Filter </th> +</tr> +<tr> + <td> Line 1 </td> + <td rowspan="2" bgcolor="#C0C0C0"> </td> + <td rowspan="9" bgcolor="#FF00FF"> </td> + <td rowspan="4"> </td> + <td rowspan="11"> + <table> + <tr> + <td bgcolor="#C0C0C0"> </td> + <td><pre><filterchain> + <headfilter lines="2"/> +</filterchain></pre></td> + </tr> + <tr> + <td bgcolor="#FF00FF"> </td> + <td><pre><filterchain> + <tailfilter lines="-1" skip="2"/> +</filterchain></pre></td> + </tr> + <tr> + <td bgcolor="#008000"> </td> + <td><pre><filterchain> + <headfilter lines="-1" skip="2"/> +</filterchain></pre></td> + </tr> + <tr> + <td bgcolor="#0000FF"> </td> + <td><pre><filterchain> + <headfilter lines="-1" skip="2"/> + <tailfilter lines="-1" skip="2"/> +</filterchain></pre></td> + </tr> + <tr> + <td bgcolor="#00FF00"> </td> + <td><pre><filterchain> + <tailfilter lines="2"/> +</filterchain></pre></td> + </tr> + </table> + </td> +</tr> +<tr> + <td> Line 2 </td> +</tr> +<tr> + <td> Line 3 </td> + <td rowspan="9" bgcolor="#008000"> </td> +</tr> +<tr> + <td> Line 4 </td> +</tr> +<tr> + <td> Line 5 </td> + <td rowspan="3" bgcolor="#0000FF"> </td> +</tr> +<tr> + <td> Lines ... </td> +</tr> +<tr> + <td> Line 95 </td> +</tr> +<tr> + <td> Line 96 </td> + <td rowspan="4"> </td> +</tr> +<tr> + <td> Line 97 </td> +</tr> +<tr> + <td> Line 98 </td> + <td rowspan="2" bgcolor="#00FF00"> </td> +</tr> +<tr> + <td> Line 99 </td> +</tr> +</table> + + + +<h4>Examples:</h4> + +This stores the last 15 lines of the supplied data in the property ${src.file.tail} +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.tail}"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.TailFilter"> + <param name="lines" value="15"/> + </filterreader> + </filterchain> +</loadfile> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.tail}"> + <filterchain> + <tailfilter lines="15"/> + </filterchain> +</loadfile> +</pre></blockquote> + + +This stores the last 5 lines of the first 15 lines of the supplied +data in the property ${src.file.mid} +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.mid}"> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.HeadFilter"> + <param name="lines" value="15"/> + </filterreader> + <filterreader classname="org.apache.tools.ant.filters.TailFilter"> + <param name="lines" value="5"/> + </filterreader> + </filterchain> +</loadfile> +</pre></blockquote> + +Convenience method: +<blockquote><pre> +<loadfile srcfile="${src.file}" property="${src.file.mid}"> + <filterchain> + <headfilter lines="15"/> + <tailfilter lines="5"/> + </filterchain> +</loadfile> +</pre></blockquote> + + +This stores the last 10 lines, skipping the last 2 lines, of the supplied data +in the property src.file.head. (Means: if supplied data contains 60 lines, +lines 49-58 are extracted) +<blockquote><pre> +<loadfile srcfile="${src.file}" property="src.file.head"> + <filterchain> + <tailfilter lines="10" skip="2"/> + </filterchain> +</loadfile> +</pre></blockquote> + +<h3><a name="deletecharacters">DeleteCharacters</a></h3> + + <p>This filter deletes specified characters.</p> + <p><em>since Ant 1.6</em></p> + <p>This filter is only available in the convenience form.</p> + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>chars</td> + <td vAlign=top> + The characters to delete. This attribute is + <a href="#backslash">backslash enabled</a>. + </td> + <td vAlign=top align="center">Yes</td> + </tr> +</table> +<p> +<h4>Examples:</h4> + +Delete tabs and returns from the data. +<blockquote><pre> +<deletecharacters chars="\t\r"/> +</pre></blockquote> + +<h3><a name="concatfilter">ConcatFilter</a></h3> + <p>This filter prepends or appends the content file to the filtered files.</p> + <p><em>since Ant 1.6</em></p> +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>prepend</td> + <td vAlign=top> + The name of the file which content should be prepended to the file. + </td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>append</td> + <td vAlign=top> + The name of the file which content should be appended to the file. + </td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<p> + +<h4>Examples:</h4> + +Do nothing: +<blockquote><pre> +<filterchain> + <concatfilter/> +</filterchain> +</pre></blockquote> + +Adds a license text before each java source: +<blockquote><pre> +<filterchain> + <concatfilter prepend="apache-license-java.txt"/> +</filterchain> +</pre></blockquote> + + + +<h3><a name="tokenfilter">TokenFilter</a></h3> +This filter tokenizes the inputstream into strings and passes these +strings to filters of strings. Unlike the other filterreaders, this does +not support params, only convenience methods are implemented. +The tokenizer and the string filters are defined by nested elements. +<p><em>since Ant 1.6</em></p> +<p> +Only one tokenizer element may be used, the LineTokenizer is the +default if none are specified. A tokenizer +splits the input into token strings and trailing delimiter strings. +<p> +There may be zero or more string filters. A string filter processes +a token and either returns a string or a null. +It the string is not null it is passed to the next filter. This +proceeds until all the filters are called. +If a string is returned after all the filters, the string is +outputs with its associated token delimiter +(if one is present). +The trailing delimiter may be overridden by the <i>delimOutput</i> +attribute. +<p> +<a name="backslash"><em>backslash interpretation</em></a> +A number of attributes (including <i>delimOutput</i>) interpret +backslash escapes. The following are understood: \n, \r, \f, \t +and \\. + + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>delimOutput</td> + <td vAlign=top> + This overrides the tokendelimiter + returned by the tokenizer if it is not empty. This + attribute is backslash enabled. +</td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<p> + + The following tokenizers are provided by the default distribution. + <p> + <a href="#linetokenizer">LineTokenizer</a><br> + <a href="#filetokenizer">FileTokenizer</a><br> + <a href="#stringtokenizer">StringTokenizer</a><br> + </p> + + The following string filters are provided by the default distribution. + <p> + <a href="#replacestring">ReplaceString</a><br> + <a href="#containsstring">ContainsString</a><br> + <a href="#replaceregex">ReplaceRegex</a><br> + <a href="#containsregex">ContainsRegex</a><br> + <a href="#trim">Trim</a><br> + <a href="#ignoreblank">IgnoreBlank</a><br> + <a href="#filterdeletecharacters">DeleteCharacters</a><br> + <a href="#uniqfilter">UniqFilter</a><br> + </p> + + The following string filters are provided by the optional distribution. + <p> + <a href="#scriptfilter">ScriptFilter</a><br> + </p> + +Some of the filters may be used directly within a filter chain. In this +case a tokenfilter is created implicitly. An extra attribute "byline" +is added to the filter to specify whether to use a linetokenizer +(byline="true") or a filetokenizer (byline="false"). The default +is "true". +<p> + +<p><b><em><a name="linetokenizer">LineTokenizer</a></em></b></p> +This tokenizer splits the input into lines. +The tokenizer delimits lines +by "\r", "\n" or "\r\n". +This is the default tokenizer. +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>includeDelims</td> + <td vAlign=top> + Include the line endings in the token. + Default is false. + </td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<h4>Examples:</h4> + +Convert input current line endings to unix style line endings. +<blockquote><pre> +<tokenfilter delimoutput="\n"/> +</pre></blockquote> + + +Remove blank lines. +<blockquote><pre> +<tokenfilter> + <ignoreblank/> +</tokenfilter> + +</pre></blockquote> + +<p><b><em><a name="filetokenizer">FileTokenizer</a></em></b></p> +This tokenizer treats <b>all</b> the input as a token. So be +careful not to use this on very large input. +<h4>Examples:</h4> + +Replace the first occurrence of package with //package. +<blockquote><pre> +<tokenfilter> + <filetokenizer/> + <replaceregex pattern="([\n\r]+[ \t]*|^[ \t]*)package" + flags="s" + replace="\1//package"/> +</tokenfilter> +</pre></blockquote> + +<p><b><em><a name="stringtokenizer">StringTokenizer</a></em></b></p> +This tokenizer is based on java.util.StringTokenizer. +It splits up the input into strings separated by white space, or +by a specified list of delimiting characters. +If the stream starts with delimiter characters, the first +token will be the empty string (unless the <i>delimsaretokens</i> +attribute is used). + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>delims</td> + <td vAlign=top>The delimiter characters. White space + is used if this is not set. (White space is defined + in this case by java.lang.Character.isWhitespace()). + </td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td valign="top">delimsaretokens</td> + <td valign="top">If this is true, + each delimiter character is returned as a token. + Default is false. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">suppressdelims</td> + <td valign="top"> + If this is true, delimiters are not returned. + Default is false. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td vAlign=top>includeDelims</td> + <td vAlign=top> + Include the delimiters in the token. + Default is false. + </td> + <td vAlign=top align="center">No</td> + </tr> +</table> + +<h4>Examples:</h4> + +Surround each non space token with a "[]". + +<blockquote><pre> +<tokenfilter> + <stringtokenizer/> + <replaceregex pattern="(.+)" replace="[\1]"/> +</tokenfilter> + +</pre></blockquote> + +<p><b><em><a name="replacestring">ReplaceString</a></em></b></p> +This is a simple filter to replace strings. +This filter may be used directly within a filterchain. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>from</td> + <td vAlign=top>The string that must be replaced.</td> + <td vAlign=top align="center">Yes</td> + </tr> + <tr> + <td valign="top">to</td> + <td valign="top">The new value for the replaced string. When omitted + an empty string is used. + </td> + <td valign="top" align="center">No</td> + </tr> +</table> + +<h4>Examples:</h4> + +Replace "sun" with "moon". + +<blockquote><pre> +<tokenfilter> + <replacestring from="sun" to="moon"/> +</tokenfilter> +</pre></blockquote> + +<p><b><em><a name="containsstring">ContainsString</a></em></b></p> +This is a simple filter to filter tokens that contains +a specified string. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>contains</td> + <td vAlign=top>The string that the token must contain.</td> + <td vAlign=top align="center">Yes</td> + </tr> +</table> + +<h4>Examples:</h4> + +Include only lines that contain "foo"; + +<blockquote><pre> +<tokenfilter> + <containsstring contains="foo"/> +</tokenfilter> + +</pre></blockquote> + +<p><b><em><a name="replaceregex">ReplaceRegex</a></em></b></p> +This string filter replaces regular expressions. +This filter may be used directly within a filterchain. +<p> + See <a href="regexp.html#implementation">Regexp Type</a> +concerning the choice of the implementation. +</p> + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>pattern</td> + <td vAlign=top>The regular expression pattern to match in + the token.</td> + <td vAlign=top align="center">Yes</td> + </tr> + <tr> + <td vAlign=top>replace</td> + <td vAlign=top>The substitution pattern to replace the matched + regular expression. When omitted an empty string is used.</td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>flags</td> + <td vAlign=top>See +<a href="../Tasks/replaceregexp.html">ReplaceRegexp</a> +for an explanation of regex flags.</td> + <td vAlign=top align="center">No</td> + </tr> +</table> +<h4>Examples:</h4> + +Replace all occurrences of "hello" with "world", ignoring case. + +<blockquote><pre> +<tokenfilter> + <replaceregex pattern="hello" replace="world" flags="gi"/> +</tokenfilter> + +</pre></blockquote> + +<p><b><em><a name="containsregex">ContainsRegex</a></em></b></p> +This filters strings that match regular expressions. +The filter may optionally replace the matched regular expression. +This filter may be used directly within a filterchain. +<p> +See +<a href="regexp.html#implementation">Regexp Type</a> +concerning the choice of regular expression implementation. +</p> +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>pattern</td> + <td vAlign=top>The regular expression pattern to match in + the token.</td> + <td vAlign=top align="center">Yes</td> + </tr> + <tr> + <td vAlign=top>replace</td> + <td vAlign=top>The substitution pattern to replace the matched + regular expression. When omitted the original token is returned. + </td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>flags</td> + <td vAlign=top>See +<a href="../Tasks/replaceregexp.html">ReplaceRegexp</a> +for an explanation of regex flags.</td> + <td vAlign=top align="center">No</td> + </tr> +</table> + +<h4>Examples:</h4> + +Filter lines that contain "hello" or "world", ignoring case. + +<blockquote><pre> +<tokenfilter> + <containsregex pattern="(hello|world)" flags="i"/> +</tokenfilter> + +</pre></blockquote> + +This example replaces lines like "SUITE(TestSuite, bits);" with +"void register_bits();" and removes other lines. + +<blockquote><pre> +<tokenfilter> + <containsregex + pattern="^ *SUITE\(.*,\s*(.*)\s*\).*" + replace="void register_\1();"/> +</tokenfilter> +</pre></blockquote> + +<p><b><em><a name="trim">Trim</a></em></b></p> +This filter trims whitespace from the start and end of +tokens. +This filter may be used directly within a filterchain. +<p><b><em><a name="ignoreblank">IgnoreBlank</a></em></b></p> +This filter removes empty tokens. +This filter may be used directly within a filterchain. +<p><b><em><a name="filterdeletecharacters">DeleteCharacters</a></em></b></p> +This filter deletes specified characters from tokens. + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>chars</td> + <td vAlign=top>The characters to delete. This attribute + is backslash enabled.</td> + <td vAlign=top align="center">Yes</td> + </tr> +</table> + +<h4>Examples:</h4> + +Delete tabs from lines, trim the lines and removes empty lines. + +<blockquote><pre> +<tokenfilter> + <deletecharacters chars="\t"/> + <trim/> + <ignoreblank/> +</tokenfilter> + +</pre></blockquote> + +<p><b><em><a name="uniqfilter">UniqFilter</a></em></b></p> + +<p>Suppresses all tokens that match their ancestor token. It is most + useful if combined with a sort filter.</p> + +<p>This filter may be used directly within a filterchain.</p> + +<h4>Example:</h4> + +This suppresses duplicate lines. +<blockquote><pre> +<tokenfilter> + <uniqfilter/> +</tokenfilter> +</pre></blockquote> + +<p><b><em><a name="scriptfilter">ScriptFilter</a></em></b></p> +This is an optional filter that executes a script in a +<a href="http://jakarta.apache.org/bsf" target="_top">Apache BSF</a> + or + <a href="https://scripting.dev.java.net">JSR 223</a> +supported language.</p> +See the <a href="../Tasks/script.html">Script</a> task for +an explanation of scripts and dependencies. +</p> +<p> +The script is provided with an object <i>self</i> that has +getToken() and setToken(String) methods. +The getToken() method returns the current token. The setToken(String) +method replaces the current token. +</p> + +This filter may be used directly within a filterchain.<p> +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>language</td> + <td vAlign=top> The programming language the script is written in. +Must be a supported Apache BSF or JSR 223 language</td> + <td vAlign=top align="center">Yes</td> + </tr> + <tr> + <td valign="top">manager</td> + <td valign="top"> + The script engine manager to use. + See the <a href="../Tasks/script.html">script</a> task + for using this attribute. + </td> + <td valign="top" align="center">No - default is "auto"</td> + </tr> + <tr> + <td vAlign=top>src</td> + <td vAlign=top>The location of the script as a file, if not inline + </td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td valign="top">setbeans</td> + <td valign="top">whether to have all properties, references and targets as + global variables in the script. <em>since Ant 1.8.0</em></td> + <td valign="top" align="center">No, default is "true".</td> + </tr> + <tr> + <td valign="top">classpath</td> + <td valign="top"> + The classpath to pass into the script. + </td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">classpathref</td> + <td valign="top">The classpath to use, given as a + <a href="../using.html#references">reference</a> to a path defined elsewhere. + <td align="center" valign="top">No</td> + </tr> +</table> + <p> + This filter can take a nested <classpath> element. + See the <a href="../Tasks/script.html">script</a> task + on how to use this element. + </p> +<h4>Examples:</h4> + +Convert to uppercase: +<blockquote><pre> +<tokenfilter> + <scriptfilter language="javascript"> + self.setToken(self.getToken().toUpperCase()); + </scriptfilter> +</tokenfilter> +</pre></blockquote> + +Remove lines containing the string "bad" while +copying text files: + <blockquote> + <pre> +<copy todir="dist"> + <fileset dir="src" includes="**/*.txt"/> + <filterchain> + <scriptfilter language="beanshell"> + if (self.getToken().indexOf("bad") != -1) { + self.setToken(null); + } + </scriptfilter> + </filterchain> +</copy> + </pre> + </blockquote> + +<h4>Custom tokenizers and string filters</h4> + +Custom string filters and tokenizers may be plugged in by +extending the interfaces org.apache.tools.ant.filters.TokenFilter.Filter +and org.apache.tools.ant.util.Tokenizer respectly. + +They are defined the build file using <code><typedef/></code>. For +example a string filter that capitalizes words may be declared as: +<blockquote><pre> +package my.customant; +import org.apache.tools.ant.filters.TokenFilter; + +public class Capitalize + implements TokenFilter.Filter +{ + public String filter(String token) { + if (token.length() == 0) + return token; + return token.substring(0, 1).toUpperCase() + + token.substring(1); + } +} +</pre></blockquote> + +This may be used as follows: +<blockquote><pre> + <typedef name="capitalize" classname="my.customant.Capitalize" + classpath="my.customant.path"/> + <copy file="input" tofile="output"> + <filterchain> + <tokenfilter> + <stringtokenizer/> + <capitalize/> + </tokenfilter> + </filterchain> + </copy> +</pre></blockquote> + + +<h3><a name="sortfilter">SortFilter</a></h3> + <p><em>since Ant 1.8.0</em></p> + +<p>The sort filter reads all lines and sorts them. The sort order can + be reversed and it is possible to specify a custom implementation of + the <code>java.util.Comparator</code> interface to get even more + control.</p> + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Parameter Name</b></td> + <td vAlign=top><b>Parameter Value</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>reverse</td> + <td vAlign=top align="center">whether to reverse the sort order, + defaults to false. <b>Note:</b> this parameter is ignored if + the comparator parameter is present as well.</td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>comparator</td> + <td vAlign=top align="center">Class name of a class that + implements <code>java.util.Comparator</code> for Strings. This + class will be used to determine the sort order of lines.</td> + <td vAlign=top align="center">No</td> + </tr> +</table> + +<p>This filter is also available using the + name <code>sortfilter</code>. The <code>reverse</code> parameter + becomes an attribute, <code>comparator</code> can be specified by + using a nested element.</p> + +<h4>Examples:</h4> + +<blockquote><pre> + <copy todir="build"> + <fileset dir="input" includes="*.txt"/> + <filterchain> + <sortfilter/> + </filterchain> + </copy> +</pre></blockquote> + +<p> +Sort all files <code>*.txt</code> from <i>src</i> location +into <i>build</i> location. The lines of each file are sorted in +ascendant order comparing the lines via the +<code>String.compareTo(Object o)</code> method. +</p> + +<blockquote><pre> + <copy todir="build"> + <fileset dir="input" includes="*.txt"/> + <filterchain> + <sortfilter reverse="true"/> + </filterchain> + </copy> +</pre></blockquote> + +<p> +Sort all files <code>*.txt</code> from <i>src</i> location into reverse +order and copy them into <i>build</i> location. +</p> + +<blockquote><pre> + <copy todir="build"> + <fileset dir="input" includes="*.txt"/> + <filterchain> + <filterreader classname="org.apache.tools.ant.filters.SortFilter"> + <param name="comparator" value="org.apache.tools.ant.filters.EvenFirstCmp"/> + </filterreader> + </filterchain> + </copy> +</pre></blockquote> + +<p> +Sort all files <code>*.txt</code> from <i>src</i> location using as +sorting criterium <code>EvenFirstCmp</code> class, that sorts the file +lines putting even lines first then odd lines for example. The modified files +are copied into <i>build</i> location. The <code>EvenFirstCmp</code>, +has to an instanciable class via <code>Class.newInstance()</code>, +therefore in case of inner class has to be <em>static</em>. It also has to +implement <code>java.util.Comparator</code> interface, for example: +</p> + +<pre> + package org.apache.tools.ant.filters; + ...(omitted) + public final class EvenFirstCmp implements <b>Comparator</b> { + public int compare(Object o1, Object o2) { + ...(omitted) + } + } +</pre> + +<p>The example above is equivalent to:</p> + +<blockquote><pre> + <componentdef name="evenfirst" + classname="org.apache.tools.ant.filters.EvenFirstCmp"/> + <copy todir="build"> + <fileset dir="input" includes="*.txt"/> + <filterchain> + <sortfilter> + <evenfirst/> + </sortfilter> + </filterchain> + </copy> +</pre></blockquote> + +</body></html> diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/filterset.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/filterset.html new file mode 100644 index 00000000..8b0dfe18 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/filterset.html @@ -0,0 +1,200 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> + +<html> +<head> + <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>FilterSet Type</title> +</head> + +<body> +<h2><a name="filterset">FilterSet</a></h2> + +<p>FilterSets are groups of filters. Filters can be defined as token-value +pairs +or be read in from a file. FilterSets can appear inside tasks that support this +feature or at the same level as <code><target></code> - i.e., as +children of +<code><project></code>.</p> + +<p>FilterSets support the <code>id</code> and <code>refid</code> +attributes. You can define a FilterSet with an <code>id</code> +attribute and then refer to that definition from another FilterSet +with a <code>refid</code> attribute. It is also possible to nest +filtersets into filtersets to get a set union of the contained +filters.</p> + +<p>In addition, FilterSets can specify +<code>begintoken</code> and/or +<code>endtoken</code> attributes to define what to match.</p> +<p>Filtersets are used for doing +replacements in tasks such as <code><copy></code>, etc.</p> + +<p>Filters can also by specified by one or more nested propertysets, the + contents of which are applied when the filterset is created.</p> + +<p>If you specify multiple values for the same token, the last one + defined within a filterset will be used.</p> + +<p> +<strong>Note: </strong>When a filterset is used in an operation, the files are +processed in text mode and the filters applied line by line. This means that +the copy operations will typically corrupt binary files. When applying filters +you should ensure that the set of files being filtered are all text files. +</p> + +<h2>Filterset</h2> + +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top><b>Default</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>begintoken</td> + <td vAlign=top>The string marking the beginning of a token (eg., + <code>@DATE@</code>).</td> + <td vAlign=top>@</td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>endtoken</td> + <td vAlign=top>The string marking the end of a token (eg., + <code>@DATE@</code>).</td> + <td vAlign=top>@</td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>filtersfile</td> + <td vAlign=top>Specify a single filtersfile.</td> + <td vAlign=top><i>none</i></td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>recurse</td> + <td vAlign=top>Indicates whether the replacement text of tokens + should be searched for more tokens. <b>Since Ant 1.6.3</b></td> + <td vAlign=top><i>true</i></td> + <td vAlign=top align="center">No</td> + </tr> + <tr> + <td vAlign=top>onmissingfiltersfile</td> + <td vAlign=top>Indicate behavior when a nonexistent <i>filtersfile</i> + is specified. One of "fail", "warn", "ignore". <b>Since Ant 1.7</b></td> + <td vAlign=top>"fail"</td> + <td vAlign=top align="center">No</td> + </tr> +</table> + +<h2>Filter</h2> +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>token</td> + <td vAlign=top>The token to replace (eg., <code>@DATE@</code>)</td> + <td vAlign=top align="center">Yes</td> + </tr> + <tr> + <td vAlign=top>value</td> + <td vAlign=top>The value to replace it with + (eg., <code>Thursday, April 26, 2001</code>).</td> + <td vAlign=top align="center">Yes</td> + </tr> +</table> + +<h2>Filtersfile</h2> +<table cellSpacing=0 cellPadding=2 border=1> + <tr> + <td vAlign=top><b>Attribute</b></td> + <td vAlign=top><b>Description</b></td> + <td vAlign=top align="center"><b>Required</b></td> + </tr> + <tr> + <td vAlign=top>file</td> + <td vAlign=top>A properties file of + name-value pairs from which to load the tokens.</td> + <td vAlign=top align="center">Yes</td> + </tr> +</table> + +<h4>Examples</h4> + +<p>You are copying the <code>version.txt</code> file to the <code>dist</code> +directory from the <code>build</code> directory +but wish to replace the token <code>@DATE@</code> with today's date.</p> +<blockquote><pre> +<copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt"> + <filterset> + <filter token="DATE" value="${TODAY}"/> + </filterset> +</copy> +</pre></blockquote> + +<p>You are copying the <code>version.txt</code> file to the <code>dist</code> +directory from the build directory +but wish to replace the token <code>%DATE*</code> with today's date.</p> +<blockquote><pre> +<copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt"> + <filterset begintoken="%" endtoken="*"> + <filter token="DATE" value="${TODAY}"/> + </filterset> +</copy> +</pre></blockquote> + +<p>Copy all the docs but change all dates and appropriate notices as stored in a file.</p> +<blockquote><pre> +<copy toDir="${dist.dir}/docs"> + <fileset dir="${build.dir}/docs"> + <include name="**/*.html"> + </fileset> + <filterset begintoken="%" endtoken="*"> + <filtersfile file="${user.dir}/dist.properties"/> + </filterset> +</copy> +</pre></blockquote> + +<p>Define a FilterSet and reference it later.</p> +<blockquote><pre> +<filterset id="myFilterSet" begintoken="%" endtoken="*"> + <filter token="DATE" value="${TODAY}"/> +</filterset> + +<copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt"> + <filterset refid="myFilterSet"/> +</copy> +</pre></blockquote> + +<p>You are copying the <code>version.txt</code> file to the <code>dist</code> +directory from the <code>build</code> directory +but wish to replace the token <code>@project.date@</code> with the property of the same name.</p> +<blockquote><pre> +<copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt"> + <filterset> + <propertyset> + <propertyref name="project.date"/> + </propertyset> + </filterset> +</copy> +</pre></blockquote> +</body></html> diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/mapper.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/mapper.html new file mode 100644 index 00000000..5aff311e --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/mapper.html @@ -0,0 +1,972 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>Mapper Type</title> +</head> + +<body> + +<h2><a name="mapper">Mapping File Names</a></h2> +<p>Some tasks take source files and create target files. Depending on +the task, it may be quite obvious which name a target file will have +(using <a href="../Tasks/javac.html">javac</a>, you know there will be +<code>.class</code> files for your <code>.java</code> files) - in +other cases you may want to specify the target files, either to help +Apache Ant or to get an extra bit of functionality.</p> +<p>While source files are usually specified as <a +href="fileset.html">fileset</a>s, you don't specify target files directly - +instead, you tell Ant how to find the target file(s) for one source file. An +instance of <code>org.apache.tools.ant.util.FileNameMapper</code> is +responsible for this. It constructs target file names based on rules +that can be parameterized with <code>from</code> and <code>to</code> +attributes - the exact meaning of which is implementation-dependent.</p> +<p>These instances are defined in <code><mapper></code> elements +with the following attributes:</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">specifies one of the built-in implementations.</td> + <td rowspan="2" align="center" valign="middle">Exactly one of these</td> + </tr> + <tr> + <td valign="top">classname</td> + <td valign="top">specifies the implementation by class name.</td> + </tr> + <tr> + <td valign="top">classpath</td> + <td valign="top">the classpath to use when looking up + <code>classname</code>.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">classpathref</td> + <td valign="top">the classpath to use, given as <a + href="../using.html#references">reference</a> to a path defined elsewhere.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">from</td> + <td valign="top">the <code>from</code> attribute for the given + implementation.</td> + <td align="center" valign="top">Depends on implementation.</td> + </tr> + <tr> + <td valign="top">to</td> + <td valign="top">the <code>to</code> attribute for the given + implementation.</td> + <td align="center" valign="top">Depends on implementation.</td> + </tr> +</table> +<p>Note that Ant will not automatically convert / or \ characters in +the <code>to</code> and <code>from</code> attributes to the correct +directory separator of your current platform. If you need to specify +this separator, use <code>${file.separator}</code> instead. + For the regexpmapper, <code>${file.separator}</code> will not work, +as on windows it is the '\' character, and this is an escape character +for regular expressions, one should use the <code>handledirsep</code> attribute +instead. +</p> +<h3>Parameters specified as nested elements</h3> +<p>The classpath can be specified via a nested +<code><classpath></code>, as well - that is, +a <a href="../using.html#path">path</a>-like structure.</p> +<p><b>Since Ant 1.7.0,</b> nested File Mappers can +be supplied via either <CODE><mapper></CODE> elements or +<a href="../Tasks/typedef.html"><code><typedef></code></a>'d +implementations of <CODE>org.apache.tools.ant.util.FileNameMapper</CODE>. +If nested File Mappers are specified by either means, the mapper will be +implicitly configured as a <a href="#composite-mapper">composite mapper</a>. +</p> +<hr> +<h3>The built-in mapper types are:</h3> +<p>All built-in mappers are case-sensitive.</p> +<p><b>As of Ant 1.7.0,</b> each of the built-in mapper implementation + types is directly accessible using a specific tagname. This makes it + possible for filename mappers to support attributes in addition to + the generally available <i>to</i> and <i>from</i>.<br> + The <code><mapper type|classname="..."></code> usage + form remains valid for reasons of backward compatibility.</p> + + <!-- --> + <!-- Identity Mapper --> + <!-- --> + +<h4><a name="identity-mapper">identity</a></h4> +<p>The target file name is identical to the source file name. Both +<code>to</code> and <code>from</code> will be ignored.</p> +<b>Examples:</b> +<blockquote><pre> +<mapper type="identity"/> +<identitymapper/> +</pre></blockquote> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file name</b></td> + </tr> + <tr> + <td valign="top"><code>A.java</code></td> + <td valign="top"><code>A.java</code></td> + </tr> + <tr> + <td valign="top"><code>foo/bar/B.java</code></td> + <td valign="top"><code>foo/bar/B.java</code></td> + </tr> + <tr> + <td valign="top"><code>C.properties</code></td> + <td valign="top"><code>C.properties</code></td> + </tr> + <tr> + <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> + <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> + </tr> +</table> + + <!-- --> + <!-- Flatten Mapper --> + <!-- --> + +<h4><a name="flatten-mapper">flatten</a></h4> +<p>The target file name is identical to the source file name, with all +leading directory information stripped off. Both <code>to</code> and +<code>from</code> will be ignored.</p> +<b>Examples:</b> +<blockquote><pre> +<mapper type="flatten"/> +<flattenmapper/> +</pre></blockquote> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file name</b></td> + </tr> + <tr> + <td valign="top"><code>A.java</code></td> + <td valign="top"><code>A.java</code></td> + </tr> + <tr> + <td valign="top"><code>foo/bar/B.java</code></td> + <td valign="top"><code>B.java</code></td> + </tr> + <tr> + <td valign="top"><code>C.properties</code></td> + <td valign="top"><code>C.properties</code></td> + </tr> + <tr> + <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> + <td valign="top"><code>A.properties</code></td> + </tr> +</table> + + <!-- --> + <!-- Merge Mapper --> + <!-- --> + +<h4><a name="merge-mapper">merge</a></h4> +<p>The target file name will always be the same, as defined by +<code>to</code> - <code>from</code> will be ignored.</p> +<h5>Examples:</h5> +<blockquote><pre> +<mapper type="merge" to="archive.tar"/> +<mergemapper to="archive.tar"/> +</pre></blockquote> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file name</b></td> + </tr> + <tr> + <td valign="top"><code>A.java</code></td> + <td valign="top"><code>archive.tar</code></td> + </tr> + <tr> + <td valign="top"><code>foo/bar/B.java</code></td> + <td valign="top"><code>archive.tar</code></td> + </tr> + <tr> + <td valign="top"><code>C.properties</code></td> + <td valign="top"><code>archive.tar</code></td> + </tr> + <tr> + <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> + <td valign="top"><code>archive.tar</code></td> + </tr> +</table> + + <!-- --> + <!-- Glob Mapper --> + <!-- --> + +<h4><a name="glob-mapper">glob</a></h4> +<p>Both <code>to</code> and <code>from</code> are required and define patterns that may +contain at most one <code>*</code>. For each source file that matches +the <code>from</code> pattern, a target file name will be constructed +from the <code>to</code> pattern by substituting the <code>*</code> in +the <code>to</code> pattern with the text that matches the +<code>*</code> in the <code>from</code> pattern. Source file names +that don't match the <code>from</code> pattern will be ignored.</p> +<b>Examples:</b> +<blockquote><pre> +<mapper type="glob" from="*.java" to="*.java.bak"/> +<globmapper from="*.java" to="*.java.bak"/> +</pre></blockquote> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file name</b></td> + </tr> + <tr> + <td valign="top"><code>A.java</code></td> + <td valign="top"><code>A.java.bak</code></td> + </tr> + <tr> + <td valign="top"><code>foo/bar/B.java</code></td> + <td valign="top"><code>foo/bar/B.java.bak</code></td> + </tr> + <tr> + <td valign="top"><code>C.properties</code></td> + <td valign="top">ignored</td> + </tr> + <tr> + <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> + <td valign="top">ignored</td> + </tr> +</table> +<blockquote><pre> +<mapper type="glob" from="C*ies" to="Q*y"/> +<globmapper from="C*ies" to="Q*y"/> +</pre></blockquote> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file name</b></td> + </tr> + <tr> + <td valign="top"><code>A.java</code></td> + <td valign="top">ignored</td> + </tr> + <tr> + <td valign="top"><code>foo/bar/B.java</code></td> + <td valign="top">ignored</td> + </tr> + <tr> + <td valign="top"><code>C.properties</code></td> + <td valign="top"><code>Q.property</code></td> + </tr> + <tr> + <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> + <td valign="top"><code>Qlasses/dir/dir2/A.property</code></td> + </tr> +</table> + <p> + The globmapper mapper can take the following extra attributes. + </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">casesensitive</td> + <td valign="top"> + If this is false, the mapper will ignore case when matching the glob pattern. + This attribute can be true or false, the default is true. + <em>Since Ant 1.6.3.</em> + </td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">handledirsep</td> + <td valign="top"> + If this is specified, the mapper will ignore the difference between the normal + directory separator characters - \ and /. + This attribute can be true or false, the default is false. + This attribute is useful for cross-platform build files. + <em>Since Ant 1.6.3.</em> + <td align="center" valign="top">No</td> + </tr> + </table> + <p> + An example: + </p> + <pre> + <pathconvert property="x" targetos="unix"> + <path path="Aj.Java"/> + <mapper> + <chainedmapper> + <flattenmapper/> + <globmapper from="a*.java" to="*.java.bak" casesensitive="no"/> + </chainedmapper> + </mapper> + </pathconvert> + <echo>x is ${x}</echo> + </pre> + <p> + will output "x is j.java.bak". + </p> + <p> + and + </p> + <pre> + <pathconvert property="x" targetos="unix"> + <path path="d/e/f/j.java"/> + <mapper> + <globmapper from="${basedir}\d/e\*" to="*" handledirsep="yes"/> + </mapper> + </pathconvert> + <echo>x is ${x}</echo> + </pre> + <p> + will output "x is f/j.java". + </p> + + + <!-- --> + <!-- RegExp Mapper --> + <!-- --> + +<h4><a name="regexp-mapper">regexp</a></h4> + +<p>Both <code>to</code> and <code>from</code> are required and define +regular expressions. If the source file name (as a whole or in part) +matches the <code>from</code> pattern, the target file name will be +constructed from the +<code>to</code> pattern, using <code>\0</code> to <code>\9</code> as +back-references for the full match (<code>\0</code>) or the matches of +the subexpressions in parentheses. The <code>to</code> pattern +determines the <strong>whole</strong> file name, so if you wanted to +replace the extension of a file you should not use <code>from="\.old$" +to=".new"</code> but rather <code>from="(.*)\.old$" to="\1.new"</code> +(or rather use a glob mapper in this case).</p> + +<p>Source files not matching the <code>from</code> pattern will be +ignored.</p> + +<p>Note that you need to escape a dollar-sign (<code>$</code>) with +another dollar-sign in Ant.</p> + +<p>The regexp mapper needs a supporting library and an implementation +of <code>org.apache.tools.ant.util.regexp.RegexpMatcher</code> that + hides the specifics of the library. <em>Since Ant 1.8.0</em> Ant + requires Java 1.4 to run, so the implementation based on + the <code>java.util.regex</code> package will always be available. + You can still use the now retired Jakarta ORO or Jakarta Regex instead if your + provide the corresponding jar in your CLASSPATH.</p> + +<p>For information about using <a +href="http://www.cacas.org/~wes/java/" target="_top">gnu.regexp</a> or <a +href="http://www.crocodile.org/~sts/Rex/" target="_top">gnu.rex</a> with Ant, see <a +href="http://marc.theaimsgroup.com/?l=ant-dev&m=97550753813481&w=2" target="_top">this</a> +article.</p> + +<p>If you want to use one of the regular expression + libraries other than <code>java.util.regex</code> you need to also use + the corresponding <code>ant-[apache-oro, apache-regexp].jar</code> +from the Ant release you are using. +Make sure, both will be loaded from the same +classpath, that is either put them into your <code>CLASSPATH</code>, +<code>ANT_HOME/lib</code> directory or a nested +<code><classpath></code> element of the mapper - you cannot have +<code>ant-[apache-oro, apache-regexp].jar</code> in <code>ANT_HOME/lib</code> + and the library +in a nested <code><classpath></code>.</p> +<p>Ant will choose the regular-expression library based on the +following algorithm:</p> +<ul> +<li>If the system property +<code>ant.regexp.matcherimpl</code> has been set, it is taken as the +name of the class implementing +<code>org.apache.tools.ant.util.regexp.RegexpMatcher</code> that +should be used.</li> +<li>If it has not been set, uses the JDK 1.4 classes.</li> +</ul> + +<b>Examples:</b> +<blockquote><pre> +<mapper type="regexp" from="^(.*)\.java$$" to="\1.java.bak"/> +<regexpmapper from="^(.*)\.java$$" to="\1.java.bak"/> +</pre></blockquote> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file name</b></td> + </tr> + <tr> + <td valign="top"><code>A.java</code></td> + <td valign="top"><code>A.java.bak</code></td> + </tr> + <tr> + <td valign="top"><code>foo/bar/B.java</code></td> + <td valign="top"><code>foo/bar/B.java.bak</code></td> + </tr> + <tr> + <td valign="top"><code>C.properties</code></td> + <td valign="top">ignored</td> + </tr> + <tr> + <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> + <td valign="top">ignored</td> + </tr> +</table> +<blockquote><pre> +<mapper type="regexp" from="^(.*)/([^/]+)/([^/]*)$$" to="\1/\2/\2-\3"/> +<regexpmapper from="^(.*)/([^/]+)/([^/]*)$$" to="\1/\2/\2-\3"/> +</pre></blockquote> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file name</b></td> + </tr> + <tr> + <td valign="top"><code>A.java</code></td> + <td valign="top">ignored</td> + </tr> + <tr> + <td valign="top"><code>foo/bar/B.java</code></td> + <td valign="top"><code>foo/bar/bar-B.java</code></td> + </tr> + <tr> + <td valign="top"><code>C.properties</code></td> + <td valign="top">ignored</td> + </tr> + <tr> + <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> + <td valign="top"><code>Classes/dir/dir2/dir2-A.properties</code></td> + </tr> +</table> +<blockquote><pre> +<mapper type="regexp" from="^(.*)\.(.*)$$" to="\2.\1"/> +<regexpmapper from="^(.*)\.(.*)$$" to="\2.\1"/> +</pre></blockquote> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file name</b></td> + </tr> + <tr> + <td valign="top"><code>A.java</code></td> + <td valign="top"><code>java.A</code></td> + </tr> + <tr> + <td valign="top"><code>foo/bar/B.java</code></td> + <td valign="top"><code>java.foo/bar/B</code></td> + </tr> + <tr> + <td valign="top"><code>C.properties</code></td> + <td valign="top"><code>properties.C</code></td> + </tr> + <tr> + <td valign="top"><code>Classes/dir/dir2/A.properties</code></td> + <td valign="top"><code>properties.Classes/dir/dir2/A</code></td> + </tr> +</table> +<blockquote><pre> +<mapper type="regexp" from="^(.*?)(\$$[^/\\\.]*)?\.class$$" to="\1.java"/> +<regexpmapper from="^(.*?)(\$$[^/\\\.]*)?\.class$$" to="\1.java"/> +</pre></blockquote> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file name</b></td> + </tr> + <tr> + <td valign="top"><code>ClassLoader.class</code></td> + <td valign="top"><code>ClassLoader.java</code></td> + </tr> + <tr> + <td valign="top"><code>java/lang/ClassLoader.class</code></td> + <td valign="top"><code>java/lang/ClassLoader.java</code></td> + </tr> + <tr> + <td valign="top"><code>java\lang\ClassLoader$1.class</code></td> + <td valign="top"><code>java\lang\ClassLoader.java</code></td> + </tr> + <tr> + <td valign="top"><code>java/lang/ClassLoader$foo$1.class</code></td> + <td valign="top"><code>java/lang/ClassLoader.java</code></td> + </tr> +</table> + <p> + The regexpmapper mapper can take the following extra attributes. + </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">casesensitive</td> + <td valign="top"> + If this is false, the mapper will ignore case when matching the pattern. + This attribute can be true or false, the default is true. + <em>Since Ant 1.6.3.</em> + </td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">handledirsep</td> + <td valign="top"> + If this is specified, the mapper will treat a \ character in a filename + as a / for the purposes of matching. + This attribute can be true or false, the default is false. + This attribute is useful for cross-platform build files. + <em>Since Ant 1.6.3.</em> + <td align="center" valign="top">No</td> + </tr> + </table> + <p> + An example: + </p> + <pre> + <pathconvert property="x" targetos="unix"> + <path path="Aj.Java"/> + <chainedmapper> + <flattenmapper/> + <regexpmapper from="a(.*)\.java" to="\1.java.bak" casesensitive="no"/> + </chainedmapper> + </pathconvert> + <echo>x is ${x}</echo> + </pre> + <p> + will output "x is j.java.bak". + </p> + <p> + and + </p> + <pre> + <pathconvert property="hd.prop" targetos="windows"> + <path path="d\e/f\j.java"/> + <chainedmapper> + <regexpmapper from="${basedir}/d/e/(.*)" to="\1" handledirsep="yes"/> + </chainedmapper> + </pathconvert> + </pre> + <p> + will set <code>hd.prop</code> to "f\j.java". + </p> + + <!-- --> + <!-- Package Mapper --> + <!-- --> + +<h4><a name="package-mapper">package</a></h4> +<p>Sharing the same syntax as the <a href="#glob-mapper">glob mapper</a>, +the package mapper replaces +directory separators found in the matched source pattern with dots in the target +pattern placeholder. This mapper is particularly useful in combination +with <code><uptodate></code> and <code><junit></code> output.</p> +<p>The to and from attributes are both required.</p> +<b>Example:</b> +<blockquote><pre> +<mapper type="package" from="*Test.java" to="TEST-*Test.xml"/> +<packagemapper from="*Test.java" to="TEST-*Test.xml"/> +</pre></blockquote> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file name</b></td> + </tr> + <tr> + <td valign="top"><code>org/apache/tools/ant/util/PackageMapperTest.java</code></td> + <td valign="top"><code>TEST-org.apache.tools.ant.util.PackageMapperTest.xml</code></td> + </tr> + <tr> + <td valign="top"><code>org/apache/tools/ant/util/Helper.java</code></td> + <td valign="top">ignored</td> + </tr> +</table> + + <!-- --> + <!-- Unpackage Mapper --> + <!-- --> + +<h4><a name="unpackage-mapper">unpackage (since Ant 1.6.0)</a></h4> + <p>This mapper is the inverse of the <a href="#package-mapper">package</a> mapper. + It replaces the dots in a package name with directory separators. This + is useful for matching XML formatter results against their JUnit test + test cases. The mapper shares the sample syntax + as the <a href="#glob-mapper">glob mapper</a>. + </p> +<p>The to and from attributes are both required.</p> +<b>Example:</b> +<blockquote><pre> +<mapper type="unpackage" from="TEST-*Test.xml" to="${test.src.dir}/*Test.java"> +<unpackagemapper from="TEST-*Test.xml" to="${test.src.dir}/*Test.java"> +</pre></blockquote> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file name</b></td> + </tr> + <tr> + <td valign="top"><code>TEST-org.acme.AcmeTest.xml</code></td> + <td valign="top"><code>${test.src.dir}/org/acme/AcmeTest.java</code></td> + </tr> +</table> + + <!-- --> + <!-- Composite Mapper --> + <!-- --> + +<h4><a name="composite-mapper">composite (since Ant 1.7.0)</a></h4> + <p>This mapper implementation can contain multiple nested mappers. + File mapping is performed by passing the source filename to each nested + <code><mapper></code> in turn, returning all results. + The <i>to</i> and <i>from</i> attributes are ignored.</p> + <p>Starting with Ant 1.8.0 the order of the mapped results is the + same as the order of the nested mappers; prior to Ant 1.8.0 the + order has been undefined.</p> +<b>Examples:</b> +<blockquote><pre> +<compositemapper> + <identitymapper/> + <packagemapper from="*.java" to="*"/> +</compositemapper> +</pre></blockquote> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file names</b></td> + </tr> + <tr> + <td valign="center" rowspan="2"><code>foo/bar/A.java</code></td> + <td valign="top"><code>foo/bar/A.java</code></td> + </tr> + <tr> + <td valign="top"><code>foo.bar.A</code></td> + </tr> +</table> + <p>The composite mapper has no corresponding + <code><mapper <b>type</b>></code> attribute. + </p> + + <!-- --> + <!-- Chained Mapper --> + <!-- --> + +<h4><a name="chained-mapper">chained (since Ant 1.7.0)</a></h4> + <p>This mapper implementation can contain multiple nested mappers. + File mapping is performed by passing the source filename to the first + nested mapper, its results to the second, and so on. The target filenames + generated by the last nested mapper comprise the ultimate results of the + mapping operation. The <i>to</i> and <i>from</i> attributes are ignored.</p> +<b>Examples:</b> +<blockquote><pre> +<chainedmapper> + <flattenmapper/> + <globmapper from="*" to="new/path/*"/> + <mapper> + <globmapper from="*" to="*1"/> + <globmapper from="*" to="*2"/> + </mapper> +</chainedmapper> +</pre></blockquote> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file names</b></td> + </tr> + <tr> + <td valign="center" rowspan="2"><code>foo/bar/A.java</code></td> + <td valign="top"><code>new/path/A.java1</code></td> + </tr> + <tr> + <td valign="top"><code>new/path/A.java2</code></td> + </tr> + <tr> + <td valign="center" rowspan="2"><code>boo/far/B.java</code></td> + <td valign="top"><code>new/path/B.java1</code></td> + </tr> + <tr> + <td valign="top"><code>new/path/B.java2</code></td> + </tr> +</table> + <p>The chained mapper has no corresponding + <code><mapper <b>type</b>></code> attribute. + </p> + + <!-- --> + <!-- Filter Mapper --> + <!-- --> + +<h4><a name="filter-mapper">filtermapper (since Ant 1.6.3)</a></h4> + <p> + This mapper implementation applies a <a href="filterchain.html">filterchain</a> + to the source file name. + </p> +<b>Examples:</b> +<blockquote><pre> +<filtermapper> + <replacestring from="\" to="/"/> +</filtermapper> +</pre></blockquote> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file names</b></td> + </tr> + <tr> + <td valign="center"><code>foo\bar\A.java</code></td> + <td valign="top"><code>foo/bar/A.java</code></td> + </tr> +</table> +<blockquote><pre> +<filtermapper> + <scriptfilter language="beanshell"> + self.setToken(self.getToken().toUpperCase()); + </scriptfilter> +</filtermapper> +</pre></blockquote> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file names</b></td> + </tr> + <tr> + <td valign="center"><code>foo\bar\A.java</code></td> + <td valign="top"><code>FOO\BAR\A.JAVA</code></td> + </tr> +</table> + + <p>The filtermapper has no corresponding + <code><mapper <b>type</b>></code> attribute. + </p> + + <!-- --> + <!-- Script Mapper --> + <!-- --> + +<h4><a name="script-mapper">scriptmapper (since Ant 1.7)</a></h4> +<p> +This mapper executes a script written in <a href="http://jakarta.apache.org/bsf" target="_top">Apache BSF</a> +or + <a href="https://scripting.dev.java.net">JSR 223</a> +supported language, once per file to map.</p> +The script can be declared inline or in a specified file. +</p> +<p> +See the <a href="../Tasks/script.html">Script</a> task for +an explanation of scripts and dependencies. +</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">language</td> + <td valign="top"> + Scripting language + </td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">manager</td> + <td valign="top"> + The script engine manager to use. + See the <a href="../Tasks/script.html">script</a> task + for using this attribute. + </td> + <td valign="top" align="center">No - default is "auto"</td> + </tr> + <tr> + <td valign="top">src</td> + <td valign="top"> + File containing the script + </td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">setbeans</td> + <td valign="top">whether to have all properties, references and targets as + global variables in the script. <em>since Ant 1.8.0</em></td> + <td valign="top" align="center">No, default is "true".</td> + </tr> + <tr> + <td valign="top">classpath</td> + <td valign="top"> + The classpath to pass into the script. + </td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">classpathref</td> + <td valign="top">The classpath to use, given as a + <a href="../using.html#references">reference</a> to a path defined elsewhere. + <td align="center" valign="top">No</td> + </tr> + </table> + <p> + This filename mapper can take a nested <classpath> element. + See the <a href="../Tasks/script.html">script</a> task + on how to use this element. + </p> + +<p> + <b>Example:</b> +</p> +<blockquote><pre> +<scriptmapper language="javascript"> + self.addMappedName(source.toUpperCase()); + self.addMappedName(source.toLowerCase()); +</scriptmapper> +</pre></blockquote> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file names</b></td> + </tr> + <tr> + <td valign="center" rowspan="2"><code>foo\bar\A.java</code></td> + <td valign="top"><code>FOO\BAR\A.JAVA</code></td> + </tr> + <tr> + <td valign="top"><code>foo\bar\a.java</code></td> + </tr> +</table> + +<p> +To use this mapper, the scripts need access to the source file, +and the ability to return multiple mappings. Here are the relevant beans and +their methods. The script is called once for every source file, with the +list of mapped names reset after every invocation. + + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Script bean</b></td> + <td valign="top"><b>Description</b></td> + </tr> + <tr> + <td valign="top"><code>source: String</code></td> + <td valign="top"> + The file/path to map + </td> + </tr> + <tr> + <td valign="top"><code>self</code></td> + <td valign="top"> + the scriptmapper itself + </td> + </tr> + <tr> + <td valign="top"><code>self.addMappedName(String name)</code></td> + <td valign="top"> + Add a new mapping + </td> + </tr> + <tr> + <td valign="top"><code>self.clear()</code></td> + <td valign="top"> + Reset the list of files. + </td> + </tr> + </table> + + <p>The scriptmapper has no corresponding + <code><mapper <b>type</b>></code> attribute. + </p> + +<h4><a name="firstmatch-mapper">firstmatchmapper (since Ant 1.8.0)</a></h4> + <p> + This mapper supports an arbitrary number of nested mappers and + returns the results of the first mapper that matches. This is + different from <a href="#composite-mapper">composite mapper</a> + which collects the results of all matching children.</p> +<b>Examples:</b> +<blockquote><pre> +<firstmatchmapper> + <globmapper from="*.txt" to="*.bak"/> + <globmapper from="*A.*" to="*B.*"/> +</firstmatchmapper> +</pre></blockquote> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file names</b></td> + </tr> + <tr> + <td valign="center"><code>foo/bar/A.txt</code></td> + <td valign="top"><code>foo/bar/A.bak</code></td> + </tr> + <tr> + <td valign="center"><code>foo/bar/A.java</code></td> + <td valign="top"><code>foo/bar/B.java</code></td> + </tr> +</table> + + <p>The firstmatchmapper has no corresponding + <code><mapper <b>type</b>></code> attribute. + </p> + +<h4><a name="cutdirs-mapper">cutdirsmapper (since Ant 1.8.2)</a></h4> + +<p>This mapper strips a configured number of leading directories from + the source file name.</p> + +<b>Examples:</b> +<blockquote><pre> +<cutdirsmapper dirs="1"/> +</pre></blockquote> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Source file name</b></td> + <td valign="top"><b>Target file names</b></td> + </tr> + <tr> + <td valign="center"><code>foo/bar/A.txt</code></td> + <td valign="top"><code>bar/A.txt</code></td> + </tr> +</table> + +<p>The cutdirsmapper has no +corresponding <code><mapper <b>type</b>></code> attribute.</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">dirs</td> + <td valign="top"> + Number of directories to strip (must be a positive number). + </td> + <td align="center" valign="top">Yes</td> + </tr> + </table> + +</body> +</html> diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/multirootfileset.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/multirootfileset.html new file mode 100644 index 00000000..29a4f548 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/multirootfileset.html @@ -0,0 +1,173 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>MultiRootFileSet Type</title> +</head> + +<body> + +<h2><a name="multirootfileset">MultiRootFileSet</a></h2> + +<p><em>Since Ant 1.9.4</em></p> + +<p>A MultiRootFileSet is a group of files or directories. These files +or directories can be found in a directory forrest starting with a set +of base directories and are matched by patterns taken from a number of +<a href="patternset.html">PatternSets</a> and <a +href="selectors.html">Selectors</a>.</p> + +<p>MultiRootFileSet acts as a union of <a +href="fileset.html">FileSets</a> and <a href="dirset.html">DirSets</a> +that share the same patterns and selectors.</p> + +<p>MultiRootFileSet supports all attributes and nested elements of +FileSet and DirSet except for the "dir" attribute.</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">basedirs</td> + <td valign="top">Comma separated list of directories that build + the roots of the MultiRootFileSet.</td> + <td valign="top" align="center">No</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> + <tr> + <td valign="top">type</td> + <td valign="top">The type of file system entities which will be + included in this set. + Acceptable values are: + <ul> + <li>file - regular files</li> + <li>dir - directories</li> + <li>both - regular files and directories</li> + </ul> + </td> + <td valign="top" align="center">No, defaults to <i>file</i></td> + </tr> + <tr> + <td valign="top">includes</td> + <td valign="top">A comma- or space-separated list of patterns of directories that + must be included; all directories are included when omitted.</td> + <td valign="top" align="center">No</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> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">excludes</td> + <td valign="top">A comma- or space-separated list of patterns of directories that + must be excluded; no directories are excluded when omitted.</td> + <td valign="top" align="center">No</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> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">casesensitive</td> + <td valign="top">Specifies whether case-sensitivity should be applied + (<code>true</code>|<code>yes</code>|<code>on</code> or + <code>false</code>|<code>no</code>|<code>off</code>).</td> + <td valign="top" align="center">No; defaults to true.</td> + </tr> + <tr> + <td valign="top">followsymlinks</td> + <td valign="top">Shall symbolic links be followed? Defaults to + true. See <a href="fileset.html#symlink">fileset's documentation</a>.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">erroronmissingdir</td> + <td valign="top"> + Specify what happens if one of the base directories does not exist. + If true a build error will happen, if false, the subtree + will be ignored/empty. + Defaults to true. + </td> + <td valign="top" align="center">No</td> + </tr> +</table> + +<h3>Parameters specified as nested elements</h3> + +<p>PatternSets can be specified as nested +<code><patternset></code> elements. In addition, MultiRootFileSet holds +an implicit PatternSet and supports the nested +<code><include></code>, <code><includesfile></code>, +<code><exclude></code> and <code><excludesfile></code> +elements of <code><patternset></code> directly, as well as +<code><patternset></code>'s attributes.</p> + +<p>Selectors are available as nested elements within the +MultiRootFileSet. If any of the selectors within the MultiRootFileSet +do not select the file or directory, it is not considered part of the +MultiRootFileSet. This makes a MultiRootFileSet equivalent to +an <code><and></code> selector container.</p> + +<p>In addition basedirs for the MultiRootFileSet can be specified as + nested <code>basedir</code> elements that have a + single <code>file</code> attribute.</p> + + +<h4>Examples</h4> + +<blockquote><pre> +<multirootfileset basedirs="${build.dir},${other.project.dir}"> + <include name="apps/**/classes"/> + <exclude name="apps/**/*Test*"/> +</multirootfileset> +</pre></blockquote> +<p>Groups all files inside <code>classes</code> found under the +<code>apps</code> subdirectory of <code>${build.dir}</code> or +<code>${other.project.dir}</code>, except those that have the text +<code>Test</code> in their name.</p> + +<blockquote><pre> +<multirootfileset> + <basedir file="${build.dir}"/> + <basedir file="${other.project.dir}" + <include name="apps/**/classes"/> + <exclude name="apps/**/*Test*"/> +</multirootfileset> +</pre></blockquote> +<p>Is equivalent to the first example but used + nested <code>basedir</code> elements. The nested elements and + the <code>basedirs</code> attribute can be used at the same time and + the will be merged.</p> + +</body> +</html> + diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/namespace.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/namespace.html new file mode 100644 index 00000000..3adfa80c --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/namespace.html @@ -0,0 +1,224 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html><head><link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>XmlNamespaceSupport</title></head> + <body> + <h2><a name="namespace">XML Namespace Support</a></h2> + Apache Ant 1.6 introduces support for XML namespaces. + <h3>History</h3> + + <p> + All releases of Ant prior to Ant 1.6 do not support XML namespaces. + No support basically implies two things here: + </p> + <ul> + <li> Element names correspond to the "qname" of the tags, which is + usually the same as the local name. But if the build file writer uses + colons in names of defined tasks/types, those become part of the + element name. Turning on namespace support gives colon-separated + prefixes in tag names a special meaning, and thus build files using + colons in user-defined tasks and types will break. + </li> + <li> Attributes with the names 'xmlns' and 'xmlns:<code><prefix></code>' + are not treated specially, which means that custom tasks and types have + actually been able to use such attributes as parameter names. Again, + such tasks/types are going to break when namespace support is enabled + on the parser. + </li> + </ul> + <p>Use of colons in element names has been discouraged in the past, + and using any attribute starting with "xml" is actually strongly + discouraged by the XML spec to reserve such names for future use. + </p> + <h3>Motivation</h3> + + <p>In build files using a lot of custom and third-party tasks, it is + easy to get into name conflicts. When individual types are defined, the + build file writer can do some namespacing manually (for example, using + "tomcat-deploy" instead of just "deploy"). But when defining whole + libraries of types using the <code><typedef></code> 'resource' attribute, the + build file writer has no chance to override or even prefix the names + supplied by the library. </p> + <h3>Assigning Namespaces</h3> + + <p> + Adding a 'prefix' attribute to <code><typedef></code> might have been enough, + but XML already has a well-known method for namespacing. Thus, instead + of adding a 'prefix' attribute, the <code><typedef></code> and <code><taskdef></code> + tasks get a 'uri' attribute, which stores the URI of the XML namespace + with which the type should be associated: + </p><pre> <typedef resource="org/example/tasks.properties" uri="<a href="http://example.org/tasks">http://example.org/tasks</a>"/> + <my:task xmlns:my="<a href="http://example.org/tasks">http://example.org/tasks</a>"> + ... + </my:task> +</pre> + <p>As the above example demonstrates, the namespace URI needs to be + specified at least twice: one time as the value of the 'uri' attribute, + and another time to actually map the namespace to occurrences of + elements from that namespace, by using the 'xmlns' attribute. This + mapping can happen at any level in the build file: + </p><pre> <project name="test" xmlns:my="<a href="http://example.org/tasks">http://example.org/tasks</a>"> + <typedef resource="org/example/tasks.properties" uri="<a href="http://example.org/tasks">http://example.org/tasks</a>"/> + <my:task> + ... + </my:task> + </project> +</pre> + <p> + Use of a namespace prefix is of course optional. Therefore + the example could also look like this: + </p><pre> <project name="test"> + <typedef resource="org/example/tasks.properties" uri="<a href="http://example.org/tasks">http://example.org/tasks</a>"/> + <task xmlns="<a href="http://example.org/tasks">http://example.org/tasks</a>"> + ... + </task> + </project> +</pre> + <p> + Here, the namespace is set as the default namespace for the <code><task></code> + element and all its descendants. + </p> + <h3>Default namespace</h3> + <p> + The default namespace used by Ant is "antlib:org.apache.tools.ant". + </p> + <pre> +<typedef resource="org/example/tasks.properties" uri="antlib:org.apache.tools.ant"/> +<task> + .... +</task> + </pre> + + + + <h3>Namespaces and Nested Elements</h3> + + <p> + Almost always in Ant 1.6, elements nested inside a namespaced + element have the same namespace as their parent. So if 'task' in the + example above allowed a nested 'config' element, the build file snippet + would look like this: + </p><pre> <typedef resource="org/example/tasks.properties" uri="<a href="http://example.org/tasks">http://example.org/tasks</a>"/> + <my:task xmlns:my="<a href="http://example.org/tasks">http://example.org/tasks</a>"> + <my:config a="foo" b="bar"/> + ... + </my:task> +</pre> + <p>If the element allows or requires a lot of nested elements, the + prefix needs to be used for every nested element. Making the namespace + the default can reduce the verbosity of the script: + </p><pre> <typedef resource="org/example/tasks.properties" uri="<a href="http://example.org/tasks">http://example.org/tasks</a>"/> + <task xmlns="<a href="http://example.org/tasks">http://example.org/tasks</a>"> + <config a="foo" b="bar"/> + ... + </task> + </pre> + <p> + From Ant 1.6.2, elements nested inside a namespaced element may also be + in Ant's default namespace. This means that the following is now allowed: + </p> + </p><pre> <typedef resource="org/example/tasks.properties" + uri="<a href="http://example.org/tasks">http://example.org/tasks</a>"/> + <my:task xmlns:my="<a href="http://example.org/tasks">http://example.org/tasks</a>"> + <config a="foo" b="bar"/> + ... + </my:task> +</pre> + + <h3>Namespaces and Attributes</h3> + + <p> + Attributes are only used to configure the element they belong to if: + </p> + <ul> + <li> they have no namespace (note that the default namespace does *not* apply to attributes) + </li> + <li> they are in the same namespace as the element they belong to + </li> + </ul> + <p> + In Ant 1.9.1 two attribute namespaces <code>ant:if</code> and <code>ant:unless</code> were added + to allow you to insert elements conditionally. + </p> + <p> + Other attributes are simply ignored. + </p> + <p> + This means that both: + </p> + <p> + </p><pre> <my:task xmlns:my="<a href="http://example.org/tasks">http://example.org/tasks</a>"> + <my:config a="foo" b="bar"/> + ... + </my:task> +</pre> + <p> + and + </p> + <pre> <my:task xmlns:my="<a href="http://example.org/tasks">http://example.org/tasks</a>"> + <my:config my:a="foo" my:b="bar"/> + ... + </my:task> +</pre> + <p> + result in the parameters "a" and "b" being used as parameters to configure the nested "config" element. + </p> + <p>It also means that you can use attributes from other namespaces + to markup the build file with extra metadata, such as RDF and + XML-Schema (whether that's a good thing or not). The same is not true + for elements from unknown namespaces, which result in a error. + </p> + <h3>Mixing Elements from Different Namespaces</h3> + + <p>Now comes the difficult part: elements from different namespaces can + be woven together under certain circumstances. This has a lot to do + with the Ant 1.6 + <a href="../develop.html#nestedtype">add type introspection rules</a>: + Ant types and tasks are now free to accept arbitrary named types as + nested elements, as long as the concrete type implements the interface + expected by the task/type. The most obvious example for this is the + <code><condition></code> task, which supports various nested conditions, all + of which extend the interface <tt>Condition</tt>. To integrate a + custom condition in Ant, you can now simply <code><typedef></code> the + condition, and then use it anywhere nested conditions are allowed + (assuming the containing element has a generic <tt>add(Condition)</tt> or <tt>addConfigured(Condition)</tt> method): +</p><pre> <typedef resource="org/example/conditions.properties" uri="<a href="http://example.org/conditions">http://example.org/conditions</a>"/> + <condition property="prop" xmlns="<a href="http://example.org/conditions">http://example.org/conditions</a>"> + <and> + <available file="bla.txt"/> + <my:condition a="foo"/> + </and> + </condition> +</pre> + <p> + In Ant 1.6, this feature cannot be used as much as we'd all like to: a + lot of code has not yet been adapted to the new introspection rules, + and elements like Ant's built-in conditions and selectors are not + really types in 1.6. This is expected to change in Ant 1.7. + </p> + <h3>Namespaces and Antlib</h3> + + <p> + The new <a href="antlib.html">AntLib</a> + feature is also very much integrated with the namespace support in Ant + 1.6. Basically, you can "import" Antlibs simply by using a special + scheme for the namespace URI: the <tt>antlib</tt> scheme, which expects the package name in which a special <tt>antlib.xml</tt> file is located. + </p> + +</body> +</html> diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/patternset.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/patternset.html new file mode 100644 index 00000000..4ad433db --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/patternset.html @@ -0,0 +1,192 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>PatternSet Type</title> +</head> + +<body> + +<h2><a name="patternset">PatternSet</a></h2> +<p><a href="../dirtasks.html#patterns">Patterns</a> can be grouped to +sets and later be referenced by their <code>id</code> attribute. They +are defined via a <code>patternset</code> element, which can appear +nested into a <a href="fileset.html">FileSet</a> or a directory-based +task that constitutes an implicit FileSet. In addition, +<code>patternset</code>s can be defined as a stand alone element at +the same level as <code>target</code> — i.e., as children of +<code>project</code> as well as as children of +<code>target</code>.</p> <p>Patterns can be specified by nested +<code><include></code>, or <code><exclude></code> elements +or the following attributes.</p> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</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. All files are included when omitted.</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. You can specify more than one + include file by using a nested includesfile elements. + <b>Note:</b> if the file is empty and there are no other + patterns defined for the fileset, all files will be included. + </td> + </tr> + <tr> + <td valign="top">excludes</td> + <td valign="top">comma- or space-separated list of patterns of files that must be + excluded; no files (except default excludes) are excluded when omitted.</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. You can specify more than one + exclude file by using a nested excludesfile elements.</td> + </tr> +</table> +<h3>Parameters specified as nested elements</h3> +<h4><code>include</code> and <code>exclude</code></h4> +<p>Each such element defines a single pattern for files to include or +exclude.</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 <a href="../dirtasks.html#patterns">pattern</a> + to in/exclude.</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">if</td> + <td valign="top">Only use this pattern <a href="../properties.html#if+unless">if the named property is set</a>.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">unless</td> + <td valign="top">Only use this pattern <a href="../properties.html#if+unless">if the named property is + <b>not</b> set</a>.</td> + <td align="center" valign="top">No</td> + </tr> +</table> +<h4><code>includesfile</code> and <code>excludesfile</code></h4> +<p>If you want to list the files to include or exclude external to +your build file, you should use the includesfile/excludesfile +attributes or elements. Using the attribute, you can only specify a +single file of each type, while the nested elements can be specified +more than once - the nested elements also support if/unless attributes +you can use to test the existence of a property.</p> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">the name of the file holding the patterns to + in/exclude.</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">if</td> + <td valign="top">Only read this file <a href="../properties.html#if+unless">if the named property is set</a>.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">unless</td> + <td valign="top">Only read this file <a href="../properties.html#if+unless">if the named property is + <b>not</b> set</a>.</td> + <td align="center" valign="top">No</td> + </tr> +</table> +<h4><code>patternset</code></h4> +<p>Patternsets may be nested within one another, adding the nested +patterns to the parent patternset.</p> +<h4><code>invert</code></h4> +<p>A nested patternset can be inverted using the <code><invert></code> +element. <em>Since Apache Ant 1.7.1</em></p> +<h3>Examples</h3> +<blockquote><pre> +<patternset id="non.test.sources"> + <include name="**/*.java"/> + <exclude name="**/*Test*"/> +</patternset> +</pre></blockquote> +<p>Builds a set of patterns that matches all <code>.java</code> files +that do not contain the text <code>Test</code> in their name. This set +can be <a href="../using.html#references">referred</a> to via +<code><patternset refid="non.test.sources"/></code>, +by tasks that support this feature, or by FileSets.</p> +<p>Note that while the <code>includes</code> and +<code>excludes</code> attributes accept +multiple elements separated by commas or spaces, the nested +<code><include></code> and <code><exclude></code> elements expect their name +attribute to hold a single pattern.</p> +<p>The nested elements allow you to use if and unless arguments to +specify that the element should only be used if a property is set, or +that it should be used only if a property is not set.</p> +<p>For example</p> +<blockquote><pre> +<patternset id="sources"> + <include name="std/**/*.java"/> + <include name="prof/**/*.java" if="professional"/> + <exclude name="**/*Test*"/> +</patternset> +</pre></blockquote> +<p>will only include the files in the sub-directory <em>prof</em> if the property +<em>professional</em> is set to some value.</p> +<p>The two sets</p> +<blockquote><pre> +<patternset includesfile="some-file"/> +</pre></blockquote> +<p>and</p> +<blockquote><pre> +<patternset> + <includesfile name="some-file"/> +<patternset/> +</pre></blockquote> +<p>are identical. The include patterns will be read from the file +<code>some-file</code>, one pattern per line.</p> +<blockquote><pre> +<patternset> + <includesfile name="some-file"/> + <includesfile name="${some-other-file}" + if="some-other-file" + /> +<patternset/> +</pre></blockquote> +<p>will also read include patterns from the file the property +<code>some-other-file</code> points to, if a property of that name has +been defined.</p> + + +</body> +</html> + diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/permissions.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/permissions.html new file mode 100644 index 00000000..f7b90b78 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/permissions.html @@ -0,0 +1,164 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>Permissions type</title> +</head> + +<body> + +<h2><a name="permissions">Permissions</a></h2> +<p> +Permissions represents a set of security permissions granted or revoked to +a specific part code executed in the JVM where Apache Ant is running in. +The actual Permissions are specified via a set of nested permission items either +<code><grant></code>ed or <code><revoke></code>d.</p> +<p> +In the base situation a <a href="#baseset">base set</a> of permissions granted. +Extra permissions can be +granted. A granted permission can be overruled by revoking a permission. +The security manager installed by the permissions will throw an +<code>SecurityException</code> if +the code subject to these permissions try to use an permission that has not been +granted or that has been revoked.</p> +<h3>Nested elements</h3> +<h4>grant</h4> +<p> +Indicates a specific permission is always granted. Its attributes indicate which +permissions are granted.</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 fully qualified name of the Permission class.</td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name of the Permission. The actual contents depends on the + Permission class.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">actions</td> + <td valign="top">The actions allowed. The actual contents depend on the + Permission class and name.</td> + <td valign="top" align="center">No</td> + </tr> +</table> +<p> +Implied permissions are granted. +</p> +<p> +Please note that some Permission classes may actually need a name and / or actions in order to function properly. The name and actions are parsed by the actual +Permission class. +</p> +<h4>revoke</h4> +<p> +Indicates a specific permission is revoked.</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 fully qualified name of the Permission class.</td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name of the Permission. The actual contents depends on the + Permission class.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">actions</td> + <td valign="top">The actions allowed. The actual contents depend on the + Permission class and name.</td> + <td valign="top" align="center">No</td> + </tr> +</table> +<p> +Implied permissions are not resolved and therefore also not revoked. +</p> +<p> +The name can handle the * wildcard at the end of the name, in which case all +permissions of the specified class of which the name starts with the specified name +(excluding the *) are revoked. Note that the - wildcard often supported by the +granted properties is not supported. +If the name is left empty all names match, and are revoked. +If the actions are left empty all actions match, and are revoked. +</p> +<h3><a name="baseset">Base set</a></h3> +A permissions set implicitly contains the following permissions: +<blockquote><pre> +<grant class="java.net.SocketPermission" name="localhost:1024-" actions="listen"> +<grant class="java.util.PropertyPermission" name="java.version" actions="read"> +<grant class="java.util.PropertyPermission" name="java.vendor" actions="read"> +<grant class="java.util.PropertyPermission" name="java.vendor.url" actions="read"> +<grant class="java.util.PropertyPermission" name="java.class.version" actions="read"> +<grant class="java.util.PropertyPermission" name="os.name" actions="read"> +<grant class="java.util.PropertyPermission" name="os.version" actions="read"> +<grant class="java.util.PropertyPermission" name="os.arch" actions="read"> +<grant class="java.util.PropertyPermission" name="file.encoding" actions="read"> +<grant class="java.util.PropertyPermission" name="file.separator" actions="read"> +<grant class="java.util.PropertyPermission" name="path.separator" actions="read"> +<grant class="java.util.PropertyPermission" name="line.separator" actions="read"> +<grant class="java.util.PropertyPermission" name="java.specification.version" actions="read"> +<grant class="java.util.PropertyPermission" name="java.specification.vendor" actions="read"> +<grant class="java.util.PropertyPermission" name="java.specification.name" actions="read"> +<grant class="java.util.PropertyPermission" name="java.vm.specification.version" actions="read"> +<grant class="java.util.PropertyPermission" name="java.vm.specification.vendor" actions="read"> +<grant class="java.util.PropertyPermission" name="java.vm.specification.name" actions="read"> +<grant class="java.util.PropertyPermission" name="java.vm.version" actions="read"> +<grant class="java.util.PropertyPermission" name="java.vm.vendor" actions="read"> +<grant class="java.util.PropertyPermission" name="java.vm.name" actions="read"> +</blockquote></pre> +These permissions can be revoked via <code><revoke></code> elements if necessary. + +<h3>Examples</h3> +<blockquote><pre> +<permissions> + <grant class="java.security.AllPermission"/> + <revoke class="java.util.PropertyPermission"/> +</permissions> +</pre></blockquote> +<p> +Grants all permissions to the code except for those handling Properties. +</p> +<blockquote><pre> +<permissions> + <grant class="java.net.SocketPermission" name="foo.bar.com" action="connect"/> + <grant class="java.util.PropertyPermission" name="user.home" action="read,write"/> +</permissions> +</pre></blockquote> +<p> +Grants the base set of permissions with the addition of a SocketPermission to connect +to foo.bar.com and the permission to read and write the user.home system property. +</p> + +</body> +</html> diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/propertyset.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/propertyset.html new file mode 100644 index 00000000..81d491e0 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/propertyset.html @@ -0,0 +1,143 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>PropertySet Type</title> +</head> + +<body> + +<h2><a name="propertyset">PropertySet</a></h2> +<p><em>Since Apache Ant 1.6</em></p> + +<p>Groups a set of properties to be used by reference in a task that +supports this.</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">dynamic</td> + <td valign="top">Whether to reevaluate the set every time the set + is used. Default is "<code>true</code>".</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">negate</td> + <td valign="top">Whether to negate results. If + "<code>true</code>", all properties <i>not</i> + selected by nested elements will be returned. Default is + "<code>false</code>". <em>Since Ant 1.6.2</em> + </td> + <td valign="top" align="center">No</td> + </tr> +</table> +<h3>Parameters specified as nested elements</h3> + +<h4>propertyref</h4> + +<p>Selects properties from the current project to be included in the +set.</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">Select the property with the given name.</td> + <td align="center" valign="top" rowspan="4">Exactly one of these.</td> + </tr> + <tr> + <td valign="top">prefix</td> + <td valign="top">Select the properties whose name starts with the + given string.</td> + </tr> + <tr> + <td valign="top">regex</td> + <td valign="top">Select the properties that match the given + regular expression. Similar to <a + href="mapper.html#regexp-mapper">regexp type mappers</a>, this + requires a supported regular expression library.</td> + </tr> + <tr> + <td valign="top">builtin</td> + <td valign="top">Selects a builtin set of properties. Valid + values for this attribute are <code>all</code> for all Ant + properties, <code>system</code> for the system properties and + <code>commandline</code> for all properties specified on the + command line when invoking Ant (plus a number of special + internal Ant properties).</td> + </tr> +</table> + +<h4>propertyset</h4> + +<p>A <code>propertyset</code> can be used as the set union of more +<code>propertyset</code>s.</p> + +<p>For example:</p> + +<blockquote><pre> +<propertyset id="properties-starting-with-foo"> + <propertyref prefix="foo"/> +</propertyset> +<propertyset id="properties-starting-with-bar"> + <propertyref prefix="bar"/> +</propertyset> +<propertyset id="my-set"> + <propertyset refid="properties-starting-with-foo"/> + <propertyset refid="properties-starting-with-bar"/> +</propertyset> +</pre></blockquote> + +<p>collects all properties whose name starts with either +"foo" or "bar" in the set named +"my-set".</p> + +<h4>mapper</h4> + +<p>A <a href="mapper.html">mapper</a> - at maximum one mapper can be +specified. The mapper is used to change the names of the property +keys, for example: + +<blockquote><pre> +<propertyset id="properties-starting-with-foo"> + <propertyref prefix="foo"/> + <mapper type="glob" from="foo*" to="bar*"/> +</propertyset> +</pre></blockquote> + +<p>collects all properties whose name starts with "foo", but +changes the names to start with "bar" instead.</p> + +<p>If supplied, the nested mapper will be applied +subsequent to any negation of matched properties.</p> + + + +</body> +</html> + diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/redirector.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/redirector.html new file mode 100644 index 00000000..d0e36838 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/redirector.html @@ -0,0 +1,193 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>Redirector Type</title> +</head> + +<body> + +<h2><a name="redirector">I/O redirection</a></h2> +<p>For many tasks, input and output can be defined in a fairly +straightforward fashion. The <a href="../Tasks/exec.html">exec</a> +task, used to execute an external process, stands as a very +basic example. The executed process may accept input, produce +output, or do either or both depending upon various circumstances. +Output may be classified as "output" or as "error +output." The <code><redirector></code> type provides a concrete means +of redirecting input and output featuring the use of +<a href="./mapper.html">File Mapper</a>s to specify +source (input) and destination (output/error) files. <em>Since Apache Ant 1.6.2</em> +<p>The <code><redirector></code> element accepts the following attributes:</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">output</td> + <td valign="top">Name of a file to which output should be written. + If the error stream is not also redirected to a file or property, + it will appear in this output.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">error</td> + <td valign="top">The file to which the standard error of the + command should be redirected.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">logError</td> + <td valign="top">This attribute is used when you wish to see + error output in Ant's log and you are redirecting output to + a file/property. The error output will not be included in + the output file/property. If you redirect error with the + <i>error</i> or <i>errorProperty</i> attributes, this will + have no effect.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">append</td> + <td valign="top">Whether output and error files should be + appended to rather than overwritten. Defaults to + <code>false</code>.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">createemptyfiles</td> + <td valign="top">Whether output and error files should be + created even when empty. Defaults to <code>true</code>.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">outputproperty</td> + <td valign="top">The name of a property in which the output of the + command should be stored. Unless the error stream is redirected + to a separate file or stream, this property will include the + error output.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">errorproperty</td> + <td valign="top">The name of a property in which the standard error + of the command should be stored.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">input</td> + <td valign="top">A file from which the executed command's standard input + is taken. This attribute is mutually exclusive with the + <i>inputstring</i> attribute.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">inputstring</td> + <td valign="top">A string which serves as the input stream for the + executed command. This attribute is mutually exclusive with the + <i>input</i> attribute.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">inputencoding</td> + <td valign="top">The input encoding.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">outputencoding</td> + <td valign="top">The output encoding.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">errorencoding</td> + <td valign="top">The error encoding.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">alwayslog</td> + <td valign="top">Always send to the log in addition to + any other destination. <i>Since Ant 1.6.3</i>. + </td> + <td align="center" valign="top">No, default is <code>false</code></td> + </tr> + <tr> + <td valign="top">loginputstring</td> + <td valign="top">Controls the display of <i>inputstring</i>'s value in + log messages. Set to <code>false</code> when sending sensitive data + (e.g. passwords) to external processes. <i>Since Ant 1.6.3</i>. + </td> + <td align="center" valign="top">No, default is <code>true</code></td> + </tr> + <tr> + <td valign="top">binaryOutput</td> + <td valign="top">When set to true Ant will not try to split the + output into lines - which it will usually do in order to separate + error from normal output. This setting will not prevent binary + output from getting corrupted if you also specify filter chains. + <i>Since Ant 1.9.4</i>. + </td> + <td align="center" valign="top">No, default is <code>false</code></td> + </tr> +</table> +<h3>Parameters specified as nested elements</h3> +<h4>inputmapper</h4> +<p>A single <a href="./mapper.html">File Mapper</a> used to redirect process +input. Multiple mapping results should concatenate all mapped files as input. +Mapping will ordinarily be performed on a task-specified sourcefile; +consult the documentation of the individual task for more details. +A nested <code><inputmapper></code> is not compatible with either of the +<i>input</i> or <i>inputstring</i> attributes.</p> +<h4>outputmapper</h4> +<p>A single <a href="./mapper.html">File Mapper</a> used to redirect process +output. Mapping will ordinarily be performed on a task-specified sourcefile; +consult the documentation of the individual task for more details. +A nested <code><outputmapper></code> is not compatible with the +<i>output</i> attribute.</p> +<h4>errormapper</h4> +<p>A single <a href="./mapper.html">File Mapper</a> used to redirect error +output. Mapping will ordinarily be performed on a task-specified sourcefile; +consult the documentation of the individual task for more details. +A nested <code><errormapper></code> is not compatible with the +<i>error</i> attribute.</p> +<h4>inputfilterchain</h4> +<p>A <a href="./filterchain.html">FilterChain</a> can be +applied to the process input.</p> +<h4>outputfilterchain</h4> +<p>A <a href="./filterchain.html">FilterChain</a> can be +applied to the process output.</p> +<h4>errorfilterchain</h4> +<p>A <a href="./filterchain.html">FilterChain</a> can be +applied to the error output.</p> +<h3>Usage</h3> +Tasks known to support I/O redirection: +<ul> +<li><a href="../Tasks/exec.html">Exec</a></li> +<li><a href="../Tasks/apply.html">Apply</a></li> +<li><a href="../Tasks/java.html">Java</a></li> +</ul> +<p>The expected behavior of a <code><redirector></code> is to a great degree +dependent on the supporting task. Any possible points of confusion +should be noted at the task level.</p> + + +</body> +</html> + diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/regexp.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/regexp.html new file mode 100644 index 00000000..0628bb9b --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/regexp.html @@ -0,0 +1,116 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>Regexp Type</title> +</head> + +<body> + +<h2><a name="regexp">Regexp</a></h2> +<p> +Regexp represents a regular expression. +<h3>Parameters</h3> +<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">pattern</td> + <td valign="top">regular expression pattern</td> + <td valign="top" align="center">Yes</td> + </tr> +</table> + +<h3>Examples</h3> +<blockquote><pre> + <regexp id="myregexp" pattern="alpha(.+)beta"/><br> +</pre></blockquote> +<p> +Defines a regular expression for later use with id myregexp. +</p> +<blockquote><pre> + <regexp refid="myregexp"/><br> +</pre></blockquote> +<p> +Use the regular expression with id myregexp. +</p> +<h3><a name="implementation">Choice of regular expression implementation</a></h3> +<p> +Apache Ant comes with +wrappers for +<a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/package-summary.html" target="_top">the java.util.regex package</a>, +<a href="http://attic.apache.org/projects/jakarta-regexp.html" target="_top">jakarta-regexp</a> +and <a href="http://attic.apache.org/projects/jakarta-oro.html" target="_top">jakarta-ORO</a>, +See <a href="../install.html#librarydependencies">installation dependencies</a> + concerning the supporting libraries.</p> +<p> +The property <code>ant.regexp.regexpimpl</code> governs which regular expression implementation will be chosen. +Possible values for this property are : +<ul> +<li> +org.apache.tools.ant.util.regexp.Jdk14RegexpRegexp +</li> +<li> +org.apache.tools.ant.util.regexp.JakartaOroRegexp +</li> +<li> +org.apache.tools.ant.util.regexp.JakartaRegexpRegexp +</li> +</ul> +It can also be another implementation of the interface <code>org.apache.tools.ant.util.regexp.Regexp</code>. +If <code>ant.regexp.regexpimpl</code> is not defined, Ant uses Jdk14Regexp as this is always available.</p> +<p> +There are cross-platform issues for matches related to line terminator. +For example if you use $ to anchor your regular expression on the end of a line +the results might be very different depending on both your platform and the regular +expression library you use. It is 'highly recommended' that you test your pattern on +both Unix and Windows platforms before you rely on it. +<ul> + <li>Jakarta Oro defines a line terminator as '\n' and is consistent with Perl.</li> + <li>Jakarta RegExp uses a system-dependent line terminator.</li> + <li>JDK 1.4 uses '\n', '\r\n', '\u0085', '\u2028', '\u2029' as a default + but is configured in the wrapper to use only '\n' (UNIX_LINE)</li> +</ul> +<em>We used to recommend that you use Jakarta ORO but since its + development has been retired Java's built-in regex package is likely + the best choice going forward.</em> +</p> +<h3>Usage</h3> +The following tasks and types use the Regexp type : +<ul> +<li><a href="../Tasks/replaceregexp.html">ReplaceRegExp task</a></li> +<li><a href="filterchain.html#linecontainsregexp">LineContainsRegexp filter</a></li> +</ul> +<p> +These string filters also use the mechanism of regexp to choose a regular expression implementation : +</p> +<ul> +<li><a href="filterchain.html#containsregex">ContainsRegex string filter</a></li> +<li><a href="filterchain.html#replaceregex">ReplaceRegex string filter</a></li> +<li><a href="selectors.html#filenameselect">filename selector</a></li> +<li><a href="resources.html#rsel.name">name resource selector</a></li> +<li><a href="selectors.html#regexpselect">containsregexp selector</a></li> +</ul> + +</body> +</html> diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/resources.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/resources.html new file mode 100644 index 00000000..58cefde1 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/resources.html @@ -0,0 +1,1380 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>Resources and Resource Collections</title> +</head> + +<body> + +<h2><a name="resource">Resources</a></h2> +<p> +A file-like entity can be abstracted to the concept of a <i>resource</i>. +In addition to providing access to file-like attributes, a resource +implementation should, when possible, provide the means to read content +from and/or write content to the underlying entity. Although the resource +concept was introduced in <i>Apache Ant 1.5.2</i>, resources are available for +explicit use beginning in <b>Ant 1.7</b>. +</p> + +<h3>The built-in resource types are:</h3> + +<ul> + <li><a href="#basic">resource</a> - a basic resource.</li> + <li><a href="#bzip2resource">bzip2resource</a> - a BZip2 compressed resource.</li> + <li><a href="#file">file</a> - a file.</li> + <li><a href="#gzipresource">gzipresource</a> - a GZip compressed resource.</li> + <li><a href="#javaresource">javaresource</a> - a resource loadable + via a Java classloader.</li> + <li><a href="#javaconstant">javaconstant</a> - a constant in a class loadable + via a Java classloader.</li> + <li><a href="#propertyresource">propertyresource</a> - an Ant property.</li> + <li><a href="#string">string</a> - a text string.</li> + <li><a href="#tarentry">tarentry</a> - an entry in a tar file.</li> + <li><a href="#url">url</a> - a URL.</li> + <li><a href="#zipentry">zipentry</a> - an entry in a zip file.</li> +</ul> + +<h4><a name="basic">resource</a></h4> + +<p>A basic resource. Other resource types derive from this basic +type; as such all its attributes are available, though in most cases +irrelevant attributes will be ignored. This and all resource +implementations are also usable as single-element +<a href="#collection">Resource Collections</a>. +</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name of this resource</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">exists</td> + <td valign="top">Whether this resource exists</td> + <td align="center" valign="top">No, default <i>true</i></td> + </tr> + <tr> + <td valign="top">lastmodified</td> + <td valign="top">The last modification time of this resource</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">directory</td> + <td valign="top">Whether this resource is directory-like</td> + <td align="center" valign="top">No, default <i>false</i></td> + </tr> + <tr> + <td valign="top">size</td> + <td valign="top">The size of this resource</td> + <td align="center" valign="top">No</td> + </tr> +</table> + +<h4><a name="file">file</a></h4> + +<p>Represents a file accessible via local filesystem conventions.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">file</td> + <td valign="top">The file represented by this resource</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">basedir</td> + <td valign="top">The base directory of this resource. When this + attribute is set, attempts to access the name of the resource + will yield a path relative to this location.</td> + <td align="center" valign="top">No</td> + </tr> +</table> + +<h4><a name="javaresource">javaresource</a></h4> + +<p>Represents a resource loadable via a Java classloader.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name of the resource.</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">classpath</td> + <td valign="top">the classpath to use when looking up a resource.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">classpathref</td> + <td valign="top">the classpath to use when looking up a resource, + given as <a href="../using.html#references">reference</a> + to a <code><path></code> defined elsewhere..</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">loaderRef</td> + <td valign="top">the name of the loader that is + used to load the resource, constructed from the specified classpath.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">parentFirst</td> + <td valign="top">Whether to consult the parent classloader first - + the parent classloader most likely is the system classloader - + when using a nested classpath. Defaults + to <code>true</code>.<br/> + <em>Since Ant 1.8.0</em></td> + <td align="center" valign="top">No</td> + </tr> +</table> + +<p>The classpath can also be specified as nested classpath element, +where <b><classpath></b> is a <a +href="../using.html#path">path-like structure</a>.</p> + + +<h4><a name="javaconstant">javaconstant</a></h4> +<p>Loads the value of a java constant. As a specialisation of +<a href="#javaresource">javaresource</a> all of its attributes and nested elements are +supported. A constant must be specified as <tt>public static</tt> otherwise it could not be loaded.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name of the resource. Must be specified as full qualified + field name. + </td> + <td align="center" valign="top">Yes</td> + </tr> +</table> +<h5>Examples</h5> +This loads the value of the constant <tt>VERSION</tt> of the <tt>org.acme.Main</tt> class +into the <tt>version</tt>-property. The classpath for finding that class is provided via +nested classpath element. +<pre><code><loadresource property="version"> + <javaconstant name="org.acme.Main.VERSION"> + <classpath> + <pathelement location="${acme.lib.dir}"/> + </classpath> + </javaconstant> + </loadresource> +</code></pre> + +Create a new file <tt>c:/temp/org.apache.tools.ant.Main.DEFAULT_BUILD_FILENAME</tt> with the content +of that constant (<tt>build.xml</tt>). +<pre><code><copy todir="c:/temp"> + <javaconstant name="org.apache.tools.ant.Main.DEFAULT_BUILD_FILENAME"/> +</copy></code></pre> + + +<h4><a name="zipentry">zipentry</a></h4> + +<p>Represents an entry in a ZIP archive. The archive can be specified +using the archive attribute or a nested single-element resource +collection. <code>zipentry</code> only supports file system resources +as nested elements.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">zipfile or its alias name archive</td> + <td valign="top">The zip file containing this resource</td> + <td align="center" valign="top">Yes, unless a nested resource + collection has been specified.</td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name of the archived resource</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">encoding</td> + <td valign="top">The encoding of the zipfile</td> + <td align="center" valign="top">No; + platform default used if unspecified</td> + </tr> +</table> + +<h4><a name="tarentry">tarentry</a></h4> + +<p>Represents an entry in a TAR archive. The archive can be specified +using the archive attribute or a nested single-element resource +collection.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">archive</td> + <td valign="top">The tar archive containing this resource</td> + <td align="center" valign="top">Yes, unless a nested resource + collection has been specified.</td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name of the archived resource</td> + <td align="center" valign="top">Yes</td> + </tr> +</table> + +<h4><a name="gzipresource">gzipresource</a></h4> + +<p>This is not a stand-alone resource, but a wrapper around another +resource providing compression of the resource's contents on the fly. +A single element resource collection must be specified as a nested +element.</p> + +<h4><a name="bzip2resource">bzip2resource</a></h4> + +<p>This is not a stand-alone resource, but a wrapper around another +resource providing compression of the resource's contents on the fly. +A single element resource collection must be specified as a nested +element.</p> + +<h4><a name="url">url</a></h4> + +<p>Represents a URL.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">url</td> + <td valign="top">The url to expose</td> + <td rowspan="3" align="center" valign="middle">Exactly one of these</td> + </tr> + <tr> + <td valign="top">file</td> + <td valign="top">The file to expose as a file: url</td> + </tr> + <tr> + <td valign="top">baseUrl</td> + <td valign="top">The base URL which must be combined with relativePath</td> + </tr> + <tr> + <td valign="top">relativePath</td> + <td valign="top">Relative path that defines the url combined with + baseUrl</td> + <td align="center" valign="top">If using baseUrl</td> + </tr> +</table> + +<h4><a name="string">string</a></h4> + +<p>Represents a Java String. It can be written to, but only once, after which +it will be an error to write to again.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">value</td> + <td valign="top">The value of this resource</td> + <td align="center" valign="top">No</td> + </tr> +</table> + +<p>The resource also supports nested text, which can only be supplied if the <code>value</code> attribute is unset: + </p> +<pre> + <string> + self.log("Ant version =${ant.version}"); + </string> +</pre> + +</p> + +<h4><a name="propertyresource">propertyresource</a></h4> + +<p>Represents an Ant property.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The property name</td> + <td align="center" valign="top">Yes</td> + </tr> +</table> + +<hr> +<h2><a name="collection">Resource Collections</a></h2> +<p> +A Resource Collection is an abstraction of an entity that groups +together a number of <a href="#resource">resources</a>. Several of +Ant's "legacy" datatypes have been modified to behave as Resource Collections: +<ul> + <li><a href="fileset.html">fileset</a>, + <a href="dirset.html">dirset</a>, + <a href="multirootfileset.html">multirootfileset</a>, + <a href="filelist.html">filelist</a>, and + <a href="../using.html#path">path</a> + (and derivative types) expose <a href="#file">file</a> resources + </li> + <li><a href="tarfileset.html">tarfileset</a> + can expose <a href="#file">file</a> or <a href="#tarentry">tarentry</a> + resources depending on configuration + </li> + <li><a href="zipfileset.html">zipfileset</a> + can expose <a href="#file">file</a> or <a href="#zipentry">zipentry</a> + resources depending on configuration + </li> + <li><a href="propertyset.html">propertyset</a> + exposes <a href="#propertyresource">property</a> resources + </li> +</ul> +</p> +<p>Strangely, some tasks can even legitimately behave as resource collections: +<ul> + <li><a href="../Tasks/concat.html">concat</a> + exposes a concatenated resource, and adds e.g. + <a href="filterchain.html">filtering</a> + to Ant's resource-related capabilities. + </li> +</ul> +</p> +<h3>The additional built-in resource collections are:</h3> +<ul> + <li><a href="#resources">resources</a> - generic resource collection</li> + <li><a href="#files">files</a> - collection of files similar to + <a href="fileset.html">fileset</a></li> + <li><a href="#restrict">restrict</a> - restrict a resource collection + to include only resources meeting specified criteria</li> + <li><a href="#sort">sort</a> - sorted resource collection</li> + <li><a href="#first">first</a> - first <i>n</i> resources from a + nested collection</li> + <li><a href="#last">last</a> - last <i>n</i> resources from a + nested collection</li> + <li><a href="#allbutfirst">allbutfirst</a> - all except the + first <i>n</i> resources from a nested collection</li> + <li><a href="#allbutlast">allbutlast</a> - all except the last <i>n</i> + resources from a nested collection</li> + <li><a href="#tokens">tokens</a> - <a href="#string">string</a> tokens + gathered from a nested collection</li> + <li><a href="#union">union</a> - set union of nested resource collections</li> + <li><a href="#intersect">intersect</a> - set intersection + of nested resource collections</li> + <li><a href="#difference">difference</a> - set difference + of nested resource collections</li> + <li><a href="#mappedresources">mappedresources</a> - generic + resource collection wrapper that maps the names of the nested + resources using a <a href="mapper.html">mapper</a>.</li> + <li><a href="#archives">archives</a> - wraps around different + resource collections and treats the nested resources as ZIP or TAR + archives that will be extracted on the fly.</li> + <li><a href="#resourcelist">resourcelist</a> - a collection of + resources whose names have been read from another resource.</li> +</ul> +<h4><a name="resources">resources</a></h4> +<p>A generic resource collection, designed for use with + <a href="../using.html#references">references</a>. + For example, if a third-party Ant task generates a Resource Collection + of an unknown type, it can still be accessed via a + <code><resources></code> collection. The secondary use of this + collection type is as a container of other resource collections, + preserving the order of nested collections as well as + duplicate resources (contrast with <a href="#union">union</a>). +</p> +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results. <em>since Ant 1.8.0</em></td> + <td valign="top" align="center">No, default <i>false</i></td> + </tr> + </table> +</blockquote> + +<h4><a name="files">files</a></h4> +<p>A group of files. These files are matched by <b>absolute</b> patterns + taken from a number of <a href="patternset.html">PatternSets</a>. + These can be specified as nested <code><patternset></code> + elements. In addition, <code><files></code> holds an implicit + PatternSet and supports the nested <code><include></code>, + <code><includesfile></code>, <code><exclude></code> + and <code><excludesfile></code> elements of PatternSet directly, + as well as PatternSet's attributes. +</p> +<p><a href="selectors.html">File Selectors</a> are available as nested + elements. A file must be selected by all selectors in order to be included; + <code><files></code> is thus equivalent to an + <code><and></code> file selector container. +</p> +<p><b>More simply put</b>, this type is equivalent to a + <a href="fileset.html">fileset</a> with no base directory. + <b>Please note</b> that without a base directory, + filesystem scanning is based entirely on include and exclude patterns. + A <a href="selectors.html#filenameselect">filename</a> (or any) + selector can <i>only</i> influence the scanning process <i>after</i> + the file has been included based on pattern-based selection. +</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">includes</td> + <td valign="top">comma- or space-separated list of patterns + of files that must be included</td> + <td rowspan="2" valign="middle" align="center">At least one of these</td> + </tr> + <tr> + <td valign="top">includesfile</td> + <td valign="top">the name of a file; each line of this file is + taken to be an include pattern.</td> + </tr> + <tr> + <td valign="top">excludes</td> + <td valign="top">comma- or space-separated list of patterns + of files that must be excluded</td> + <td rowspan="2" valign="top" align="center">No, default none + (except default excludes when true)</td> + </tr> + <tr> + <td valign="top">excludesfile</td> + <td valign="top">the name of a file; each line of this file is + taken to be an exclude pattern.</td> + </tr> + <tr> + <td valign="top">defaultexcludes</td> + <td valign="top">Whether + <a href="../dirtasks.html#defaultexcludes">default excludes</a> + should be used</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + <tr> + <td valign="top">casesensitive</td> + <td valign="top">Whether patterns are case-sensitive</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + <tr> + <td valign="top">followsymlinks</td> + <td valign="top">Whether to follow symbolic links + (see note <a href="#symlink">below</a>)</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> +</table> + +<p><a name="symlink"><b>Note</b></a>: All files/directories for which +the canonical path is different from its path are considered symbolic +links. On Unix systems this usually means the file really is a +symbolic link but it may lead to false results on other +platforms. +</p> + +<h4><a name="restrict">restrict</a></h4> +<p>Restricts a nested resource collection using resource selectors: +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; disabling + may seriously impact performance</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + </table> + <h4>Parameters specified as nested elements</h4> + <p>A single resource collection is required.</p> + <p>Nested resource selectors are used to "narrow down" the included + resources, combined via a logical <i>AND</i>. These are patterned + after <a href="selectors.html">file selectors</a> but are, + unsurprisingly, targeted to resources. + Several built-in resource selectors are available in the internal + <a href="antlib.html">antlib</a> + <code>org.apache.tools.ant.types.resources.selectors</code>: + </p> + + <ul> + <li><a href="#rsel.name">name</a> - select resources by name.</li> + <li><a href="#rsel.exists">exists</a> - select existing resources.</li> + <li><a href="#rsel.date">date</a> - select resources by date.</li> + <li><a href="#rsel.type">type</a> - select resources by type.</li> + <li><a href="#rsel.size">size</a> - select resources by size.</li> + <li><a href="#rsel.instanceof">instanceof</a> + - select resources by class or Ant datatype.</li> + <li><a href="#rsel.and">and</a> - "and" nested resource selectors.</li> + <li><a href="#rsel.or">or</a> - "or" nested resource selectors.</li> + <li><a href="#rsel.not">not</a> - "not" a nested resource selector.</li> + <li><a href="#rsel.none">none</a> + - select resources selected by no nested resource selectors.</li> + <li><a href="#rsel.majority">majority</a> - select resources selected + by a majority of nested resource selectors.</li> + <li><a href="selectors.html#modified">modified</a> - select resources which + content has changed.</li> + <li><a href="selectors.html#containsselect">contains</a> - select resources + containing a particular text string.</li> + <li><a href="selectors.html#regexpselect">containsregexp</a> - select + resources whose contents match a particular regular expression.</li> + <li><a href="#rsel.compare">compare</a> - select resources + based on comparison to other resources.</li> + <li><a href="selectors.html#readable">readable</a> - + Select files (resources must be files) if they are readable.</li> + <li><a href="selectors.html#writable">writable</a> - + Select files (resources must be files) if they are writable.</li> + </ul> + + <h4><a name="rsel.name">name</a></h4> + <p>Selects resources by name.</p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name pattern to test using standard Ant + patterns.</td> + <td valign="top" align="center" rowspan="2">Exactly one of + the two</td> + </tr> + <tr> + <td valign="top">regex</td> + <td valign="top">The regular expression matching files to select.</td> + </tr> + <tr> + <td valign="top">casesensitive</td> + <td valign="top">Whether name comparisons are case-sensitive</td> + <td align="center" valign="top">No, default <i>true</i></td> + </tr> + <tr> + <td valign="top">handledirsep</td> + <td valign="top"> + If this is specified, the mapper will treat a \ character in a + resource name or name attribute as a / for the purposes of + matching. This attribute can be true or false, the default is + false. + <em>Since Ant 1.8.0.</em> + <td align="center" valign="top">No</td> + </tr> + </table> + + <h4><a name="rsel.exists">exists</a></h4> + <p>Selects existing resources.</p> + + <h4><a name="rsel.date">date</a></h4> + <p>Selects resources by date.</p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">millis</td> + <td valign="top">The comparison date/time in ms since January 1, 1970</td> + <td rowspan="2" align="center" valign="middle">One of these</td> + </tr> + <tr> + <td valign="top">datetime</td> + <td valign="top">The formatted comparison date/time</td> + </tr> + <tr> + <td valign="top">pattern</td> + <td valign="top">SimpleDateFormat-compatible pattern + for use with the <code>datetime</code> attribute</td> + <td align="center" valign="top"> + No, default is "MM/DD/YYYY HH:MM AM_or_PM"</td> + </tr> + <tr> + <td valign="top">granularity</td> + <td valign="top">The number of milliseconds leeway to use when + comparing file modification times. This is needed because not + every file system supports tracking the last modified time to + the millisecond level.</td> + <td align="center" valign="top">No; default varies by platform: + FAT filesystems = 2 sec; Unix = 1 sec; NTFS = 1 ms.</td> + </tr> + <tr> + <td valign="top">when</td> + <td valign="top">One of "before", "after", "equal"</td> + <td align="center" valign="top">No, default "equal"</td> + </tr> + </table> + + <h4><a name="rsel.type">type</a></h4> + <p>Selects resources by type (file or directory).</p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">type</td> + <td valign="top">One of "file", "dir", "any" (since Ant 1.8)</td> + <td align="center" valign="top">Yes</td> + </tr> + </table> + + <h4><a name="rsel.size">size</a></h4> + <p>Selects resources by size.</p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">size</td> + <td valign="top">The size to compare</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">when</td> + <td valign="top">One of "equal", "eq", "greater", "gt", "less", "lt", + "ge" (greater or equal), "ne" (not equal), "le" (less or equal)</td> + <td align="center" valign="top">No, default "equal"</td> + </tr> + </table> + + <h4><a name="rsel.instanceof">instanceof</a></h4> + <p>Selects resources by type.</p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">class</td> + <td valign="top">The class of which the resource must be an instance</td> + <td rowspan="2" align="center" valign="middle">One of these</td> + </tr> + <tr> + <td valign="top">type</td> + <td valign="top">The Ant type that must + be assignable from the resource</td> + </tr> + <tr> + <td valign="top">uri</td> + <td valign="top">The uri in which <i>type</i> must be defined</td> + <td valign="top">No</td> + </tr> + </table> + + <h4><a name="rsel.and">and</a></h4> + <p>Selects a resource if it is selected by all nested resource selectors.</p> + + <h4><a name="rsel.or">or</a></h4> + <p>Selects a resource if it is selected + by at least one nested resource selector.</p> + + <h4><a name="rsel.not">not</a></h4> + <p>Negates the selection result of the single + nested resource selector allowed.</p> + + <h4><a name="rsel.none">none</a></h4> + <p>Selects a resource if it is selected + by no nested resource selectors.</p> + + <h4><a name="rsel.majority">majority</a></h4> + <p>Selects a resource if it is selected + by the majority of nested resource selectors.</p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">allowtie</td> + <td valign="top">Whether a tie (when there is an even number + of nested resource selectors) is considered a majority</td> + <td valign="top">No, default <i>true</i></td> + </tr> + </table> + + <h4><a name="rsel.compare">compare</a></h4> + <p>Selects a resource based on its comparison to one or more "control" + resources using nested <a href="#rcmp">resource comparators</a>.</p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">when</td> + <td valign="top">Comparison ("equal"/"eq", "greater"/"gt", "less"/"lt", + "le" (less or equal), "ge" (greater or equal), "ne" (not equal).</td> + <td valign="top">No, default "equal"</td> + </tr> + <tr> + <td valign="top">against</td> + <td valign="top">Quantifier ("all"/"each"/"every", "any"/"some", + (exactly) "one", "most"/"majority", "none".</td> + <td valign="top">No, default "all"</td> + </tr> + </table> + <h4>Parameters specified as nested elements</h4> + <p>The resources against which comparisons will be made must be specified + using the nested <control> element, which denotes a + <a href="#resources">resources</a> collection.</p> + <h4>Examples</h4> + <p>Assuming the namespace settings +<pre><code> rsel="antlib:org.apache.tools.ant.types.resources.selectors" + rcmp="antlib:org.apache.tools.ant.types.resources.comparators" +</code></pre></p> + <pre> +<restrict> + <fileset dir="src" includes="a,b,c,d,e,f,g" /> + <rsel:compare when="le" against="all"> + <control> + <resource name="d" /> + </control> + <rcmp:name /> + </rsel:compare> +</restrict> + </pre> + <p>Selects files a, b, c, and d.</p> + <pre> + <project rsel="antlib:org.apache.tools.ant.types.resources.selectors"> + <macrodef name="copyFromPath"> + <attribute name="todir"/> + <attribute name="refid"/> + <element name="nested-resource-selectors" optional="yes" implicit="true"/> + <sequential> + <mkdir dir="@{todir}" taskname="copyFromPath"/> + <copy todir="@{todir}" taskname="copyFromPath"> + <restrict> + <path refid="@{refid}"/> + <rsel:or> + <nested-resource-selectors/> + </rsel:or> + </restrict> + <flattenmapper/> + </copy> + </sequential> + </macrodef> + <copyFromPath refid="classpath" todir="todir"> + <rsel:name name="log4j.properties"/> + <rsel:name name="default.properties"/> + </copyFromPath> + </project> + </pre> + <p>Creates the <tt>todir</tt> directory and copies (if present) the + files <tt>log4j.properties</tt> and <tt>default.properties</tt> + from the Classpath (already used while compiling). + </p> + + <pre> + <project> + <filelist id="allfiles" dir="${ant.home}/bin" files="ant.cmd,foo.txt,ant.bat,bar.txt,ant"/> + <restrict id="missingfiles"> + <filelist refid="allfiles"/> + <rsel:not xmlns:rsel="antlib:org.apache.tools.ant.types.resources.selectors"> + <rsel:exists/> + </rsel:not> + </restrict> + <echo>These files are missed: ${toString:missingfiles}</echo> + </project> + </pre> + <p>The resource collection <i>allfiles</i> defines a list of files which are expected. The restrict + <i>missingfiles</i> uses the <tt><not><exists></tt> selector for getting all files + which are not present. Finally we use the <i>toString:</i> <a href="../using.html#pathshortcut">pathshortcut</a> for + getting them in a readable form: <tt>[echo] These files are missed: ....foo.txt;....bar.txt</tt></p> + +</blockquote> + +<h4><a name="sort">sort</a></h4> + +<p>Sorts a nested resource collection according to the resources' + natural order, or by one or more nested <a href="#rcmp">resource + comparators</a>:</p> +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; disabling + may seriously impact performance</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + </table> + <h4>Parameters specified as nested elements</h4> + <p>A single resource collection is required.</p> + <p>The sort can be controlled and customized by specifying one or more + resource comparators. Resources can be sorted according to multiple + criteria; the first specified is the "outermost", while the last + specified is the "innermost". Several built-in resource comparators + are available in the internal <a href="antlib.html">antlib</a> + <code>org.apache.tools.ant.types.resources.comparators</code>: + </p> + <h4><a name="rcmp">Resource Comparators:</a></h4> + <ul> + <li><a href="#rcmp.name">name</a> - sort resources by name</li> + <li><a href="#rcmp.exists">exists</a> - sort resources by existence</li> + <li><a href="#rcmp.date">date</a> - sort resources by date</li> + <li><a href="#rcmp.type">type</a> - sort resources by type</li> + <li><a href="#rcmp.size">size</a> - sort resources by size</li> + <li><a href="#rcmp.content">content</a> - sort resources by content</li> + <li><a href="#rcmp.reverse">reverse</a> - reverse the natural sort order, + or that of a single nested resource comparator</li> + </ul> + + <h4><a name="rcmp.name">name</a></h4> + <p>Sort resources by name.</p> + + <h4><a name="rcmp.exists">exists</a></h4> + <p>Sort resources by existence. + Not existing is considered "less than" existing.</p> + + <h4><a name="rcmp.date">date</a></h4> + <p>Sort resources by date.</p> + + <h4><a name="rcmp.type">type</a></h4> + <p>Sort resources by type (file or directory). + Because directories contain files, they are considered "greater".</p> + + <h4><a name="rcmp.size">size</a></h4> + <p>Sort resources by size.</p> + + <h4><a name="rcmp.content">content</a></h4> + <p>Sort resources by content.</p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">binary</td> + <td valign="top">Whether content should be compared in binary mode. + If <i>false<i>, content will be compared without regard to + platform-specific line-ending conventions.</td> + <td valign="top">No, default <i>true</i></td> + </tr> + </table> + + <h4><a name="rcmp.reverse">reverse</a></h4> + <p>Reverse the natural sort order, or that of a single nested comparator.</p> + + <h4>Examples</h4> + <pre> + <property name="eol" value="${line.separator}" /> + <pathconvert property="sorted" pathsep="${eol}"> + <sort> + <tokens> + <string value="foo bar etc baz" /> + <stringtokenizer /> + </tokens> + </sort> + </pathconvert></pre> + <p>The resource of type string "foo bar etc baz" is split into four tokens by + the stringtokenizer. These tokens are sorted and there <i>sorted</i> gets the value + of "bar baz etc foo".</p> + + <pre> + <sort> + <fileset dir="foo" /> + <reverse xmlns="antlib:org.apache.tools.ant.types.resources.comparators"> + <date /> + </reverse> + </sort></pre> + <p>This takes all files from <i>foo</i> + and sorts them by modification date in reverse order. + Because the resource comparators used (<code><reverse></code> + and <code><date></code>) are in an internal antlib + their namespace must be set explicitly. + </p> + +</blockquote> + +<h4><a name="first">first</a></h4> +<p>Includes the first <i>count</i> resources from a nested resource collection. +This can be used in conjunction with the <a href="#sort">sort</a> collection, +for example, to select the first few oldest, largest, etc. resources from a +larger collection.</p> +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">count</td> + <td valign="top">The number of resources to include</td> + <td valign="top" align="center">No, default 1</td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; disabling + may seriously impact performance</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + </table> + <h4>Parameters specified as nested elements</h4> + <p>A single resource collection is required.</p> +</blockquote> + +<h4><a name="last">last</a></h4> +<p>Includes the last <i>count</i> resources from a nested resource collection. +This can be used in conjunction with the <a href="#sort">sort</a> collection, +for example, to select the last few oldest, largest, etc. resources from a +larger collection. <strong>Since Ant 1.7.1</strong>.</p> +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">count</td> + <td valign="top">The number of resources to include</td> + <td valign="top" align="center">No, default 1</td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; disabling + may seriously impact performance</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + </table> + <h4>Parameters specified as nested elements</h4> + <p>A single resource collection is required.</p> +</blockquote> + +<h4><a name="allbutfirst">allbutfirst</a></h4> +<p>Includes all elements except for the first <i>count</i> resources +from a nested resource collection. This can be used in conjunction +with the <a href="#sort">sort</a> collection, for example, to select +all but the first few oldest, largest, etc. resources from a larger +collection. <strong>Since Ant 1.9.5</strong>.</p> +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">count</td> + <td valign="top">The number of resources to exclude</td> + <td valign="top" align="center">No, default 1</td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; disabling + may seriously impact performance</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + </table> + <h4>Parameters specified as nested elements</h4> + <p>A single resource collection is required.</p> +</blockquote> + +<h4><a name="allbutlast">allbutlast</a></h4> +<p>Includes all elements except for the last <i>count</i> resources +from a nested resource collection. This can be used in conjunction +with the <a href="#sort">sort</a> collection, for example, to select +all but the last few oldest, largest, etc. resources from a larger +collection. <strong>Since Ant 1.9.5</strong>.</p> +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">count</td> + <td valign="top">The number of resources to exclude</td> + <td valign="top" align="center">No, default 1</td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; disabling + may seriously impact performance</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + </table> + <h4>Parameters specified as nested elements</h4> + <p>A single resource collection is required.</p> +</blockquote> + +<h4><a name="tokens">tokens</a></h4> +<p>Includes the <a href="#string">string</a> tokens gathered from a nested + resource collection. Uses the same tokenizers supported by the +<a href="filterchain.html#tokenfilter">TokenFilter</a>. Imaginative + use of this resource collection can implement equivalents for such Unix + functions as <code>sort</code>, <code>grep -c</code>, <code>wc</code> and + <code>wc -l</code>.</p> +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">encoding</td> + <td valign="top">The encoding of the nested resources</td> + <td valign="top" align="center">No, default is platform default</td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; disabling + may seriously impact performance</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + </table> + <h4>Parameters specified as nested elements</h4> + <ul> + <li>A single resource collection is required.</li> + <li>One nested tokenizer may be specified. If omitted, a + <a href="filterchain.html#linetokenizer">LineTokenizer</a> will be used. + </li> + </ul> + <h4>Examples</h4> + <pre><concat> + <union> + <sort> + <tokens> + <resources refid="input" /> + <linetokenizer includedelims="true" /> + </tokens> + </sort> + </union> +</concat> + </pre> + <p>Implements Unix <i>sort -u</i> against resource collection <i>input</i>.</p> +</blockquote> + +<h4><a name="setlogic">Set operations</a></h4> +<blockquote> + <p>The following resource collections implement set operations:</p> + <ul> + <li><a href="#union">union</a></li> + <li><a href="#intersect">intersect</a></li> + <li><a href="#difference">difference</a></li> + </ul> + + <h4><a name="union">union</a></h4> + <p>Union of nested resource collections.</p> + + <h4><a name="intersect">intersect</a></h4> + <p>Intersection of nested resource collections.</p> + + <h4><a name="difference">difference</a></h4> + <p>Difference of nested resource collections.</p> + + <p>The following attributes apply to all set-operation resource collections: + </p> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; disabling + may seriously impact performance</td> + <td valign="top" align="center">No, default <i>true</i></td> + </tr> + </table> + + <h4>Examples</h4> + <pre> + <resources id="A"> + <string value="a"/> + <string value="b"/> + </resources> + <resources id="B"> + <string value="b"/> + <string value="c"/> + </resources> + <union id="union"><resources refid="A"/><resources refid="B"/></union> + <intersect id="intersect"><resources refid="A"/><resources refid="B"/></intersect> + <difference id="difference"><resources refid="A"/><resources refid="B"/></difference> + <echo> + A: ${toString:A} = a;b + B: ${toString:B} = b;c + + union : ${toString:union} = a;b;c + intersect : ${toString:intersect} = b + difference: ${toString:difference} = a;c + </echo> + </pre> +</blockquote> + +<h4><a name="mappedresources">mappedresources</a></h4> + +<p><em>Since Ant 1.8.0</em></p> + +<p>Wraps another resource collection and maps the names of the nested + resources using a <a href="mapper.html">mapper</a>.</p> + +<p>Even if <em>mappedresources</em> wraps a resource collection that + consists of file-system based resources, <em>mappedresources</em> + will not appear to be file-system based. This means you can't + use <em>mappedresources</em> with tasks that only allow file-system + based resources.</p> + +<blockquote> + <h4>Parameters specified as attributes</h4> + + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache results; enabling + may improve performance. <em>Since Ant 1.8.1</em></td> + <td valign="top" align="center">No, default <i>false</i></td> + </tr> + <tr> + <td valign="top">enablemultiplemappings</td> + <td valign="top"> + If true the the collection will use all the mappings for a + given source path. If false the it will only process the first + resource. + <em>since Ant 1.8.1</em>.</td> + <td align="center">No - defaults to false.</td> + </tr> + </table> + + <h4>Parameters specified as nested elements</h4> + <p>A single resource collection is required.</p> + <p>A single <a href="mapper.html">mapper</a> can be used to map + names. If no mapper has been given (which doesn't make any sense, + honestly), an identity mapper will be used.</p> + + <h4>Examples</h4> + + <p>Copies all files from a given directory to a target directory + adding ".bak" as an extension. Note this could be done with a + <em>mapper</em> nested into <em>copy</em> directly as well.</p> + + <pre> + <copy todir="${target}"> + <mappedresources> + <fileset dir="${src}"/> + <globmapper from="*" to="*.bak"/> + </mappedresources> + </copy> + </pre> + + <p>Creates a WAR archive adding all CLASSPATH entries that are files + to the <code>WEB-INF/lib</code> directory without keeping their + files-system structure.</p> + + <pre> + <war destfile="${output}"> + <mappedresources> + <restrict> + <path path="${java.class.path}"/> + <type type="file"/> + </restrict> + <chainedmapper> + <flattenmapper/> + <globmapper from="*" to="WEB-INF/lib/*"/> + </chainedmapper> + </mappedresources> + </war> + </pre> +</blockquote> + +<h4><a name="archives">archives</a></h4> + +<p><em>Since Ant 1.8.0</em></p> + +<p>This resource collection accepts an arbitrary number of nested + resources and assumes that all those resources must be either ZIP or + TAR archives. The resources returned + by <code><archives></code> are the contents of the nested + archives.</p> + +<p>This resource collection is a generalization + of <a href="../Tasks/zip.html#zipgroupfileset">zipgroupfileset</a> + which is only supported by the zip family of tasks.</p> + +<p><em>archives</em> doesn't support any attributes.</p> + +<blockquote> + <h4>Parameters specified as nested elements</h4> + + <p><code><archives></code> has two nested + elements <code><zips></code> and + <code><tars></code> that are <a href="#union">unions</a> + themselves, i.e. they accept arbitrary many resource(collection)s + as nested elements.</p> + + <p>The nested resources of <zips> are treated as ZIP archives, + the nested resources of <tars> as TAR archives.</p> + + <h4>Examples</h4> + + <p>Copies all files from all jars that are on the classpath + to <code>${target}</code>.</p> + + <pre> + <copy todir="${target}"> + <archives> + <zips> + <restrict> + <path path="${java.class.path}"/> + <name name="*.jar"/> + </restrict> + </zips> + </archives> + </copy> + </pre> +</blockquote> + +<h4><a name="resourcelist">resourcelist</a></h4> + +<p><em>Since Ant 1.8.0</em></p> + +<p>This resource collection accepts an arbitrary number of nested + resources, reads those resources and returns a resource for each + line read.</p> + +<p>If the line contains a colon, Ant will try to use it as an URL and + if that fails (or the line doesn't contain a colon) will return a + file resource with the line's content as its name.</p> + +<p>Properties will be expanded for each line. If the property + expansion yields a resource object rather than a string (for example + because of custom property helpers), the resources will be returned + directly.</p> + +<p><code><resourcelist></code> is a generalization + of <a href="filelist.html"><code><filelist></code></a>.</p> + +<blockquote> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">encoding</td> + <td valign="top">The encoding of the nested resources</td> + <td valign="top" align="center">No, default is platform default</td> + </tr> + </table> +</blockquote> + +<blockquote> + <h4>Parameters specified as nested elements</h4> + + <p><code><resourcelist></code> accepts arbitrary many + resource(collection)s as nested elements.</p> + + <p>In addition <code><resourcelist></code> supports + nested <code><filterchain></code> elements that can be used + to filter/modify the read resources before their lines get + expanded. Such a nested element corresponds to + a <a href="filterchain.html">filterchain</a>.</p> + + <h4>Examples</h4> + + <p>The following example copies a file from the first URL of + several alternatives that can actually be reached. It assumes + that the file mirrors.txt looks like</p> + + <pre> + mirrors.txt: +http://best.mirror.example.org/ +http://second.best.mirror.example.org/mirror/of/best/ +https://yet.another.mirror/ +http://the.original.site/ + </pre> + + <pre> + <copy todir="${target}"> + <first> + <restrict> + <resourcelist> + <file file="mirrors.txt"/> + </resourcelist> + <exists/> + </restrict> + </first> + </copy> + </pre> +</blockquote> + +</body> +</html> diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/selectors-program.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/selectors-program.html new file mode 100644 index 00000000..074a5426 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/selectors-program.html @@ -0,0 +1,244 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + <head> + <meta http-equiv="Content-Language" content="en-us"> + <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>Programming Selectors in Apache Ant</title> + </head> + + <body> + <h2>Programming your own Selectors</h2> + + <h3>Selector Programming API</h3> + + <p>Want to define your own selectors? It's easy!</p> + + <p>First, pick the type of selector that you want to define. There + are three types, and a recipe for each one follows. Chances are + you'll want to work with the first one, Custom Selectors.</p> + + <ol> + <li>Custom Selectors + + <p>This is the category that Apache Ant provides specifically for you to + define your own Selectors. Anywhere you want to use your selector + you use the <code><custom></code> element and specify + the class name of your selector within it. See the + <a href="selectors.html#customselect">Custom Selectors</a> + section of the Selector page for details. The + <code><custom></code> element can be used anywhere + the core selectors can be used. It can be contained within + <a href="selectors.html#selectcontainers">Selector Containers</a>, + for example.</p> + + <p>To create a new Custom Selector, you have to create a class that + implements + <code>org.apache.tools.ant.types.selectors.ExtendFileSelector</code>. + The easiest way to do that is through the convenience base class + <code>org.apache.tools.ant.types.selectors.BaseExtendSelector</code>, + which provides all of the methods for supporting + <code><param></code> tags. First, override the + <code>isSelected()</code> method, and optionally the + <code>verifySettings()</code> method. If your custom + selector requires parameters to be set, you can also override + the <code>setParameters()</code> method and interpret the + parameters that are passed in any way you like. Several of the + core selectors demonstrate how to do that because they can + also be used as custom selectors.</p> + + <li>Core Selectors + + <p>These are the selectors used by Ant itself. To implement one of + these, you will have to alter some of the classes contained within + Ant.</p> + + <ul> + <li><p>First, create a class that implements + <code>org.apache.tools.ant.types.selectors.FileSelector</code>. + You can either choose to implement all methods yourself from + scratch, or you can extend + <code>org.apache.tools.ant.types.selectors.BaseSelector</code> + instead, a convenience class that provides reasonable default + behaviour for many methods.</p> + + <p>There is only one method required. + <code>public boolean isSelected(File basedir, String filename, + File file)</code> + is the real purpose of the whole exercise. It returns true + or false depending on whether the given file should be + selected from the list or not.</p> + + <p>If you are using + <code>org.apache.tools.ant.types.selectors.BaseSelector</code> + there are also some predefined behaviours you can take advantage + of. Any time you encounter a problem when setting attributes or + adding tags, you can call setError(String errmsg) and the class + will know that there is a problem. Then, at the top of your + <code>isSelected()</code> method call <code>validate()</code> and + a BuildException will be thrown with the contents of your error + message. The <code>validate()</code> method also gives you a + last chance to check your settings for consistency because it + calls <code>verifySettings()</code>. Override this method and + call <code>setError()</code> within it if you detect any + problems in how your selector is set up.</p> + + <p>You may also want to override <code>toString()</code>.</p> + + <li><p>Put an <code>add</code> method for your selector in + <code>org.apache.tools.ant.types.selectors.SelectorContainer</code>. + This is an interface, so you will also have to add an implementation + for the method in the classes which implement it, namely + <code>org.apache.tools.ant.types.AbstractFileSet</code>, + <code>org.apache.tools.ant.taskdefs.MatchingTask</code> and + <code>org.apache.tools.ant.types.selectors.BaseSelectorContainer</code>. + Once it is in there, it will be available everywhere that core + selectors are appropriate.</p> + </ul> + + <li>Selector Containers + <p>Got an idea for a new Selector Container? Creating a new one is + no problem:</p> + <ul> + <li><p>Create a new class that implements + <code>org.apache.tools.ant.types.selectors.SelectorContainer</code>. + This will ensure that your new + Container can access any new selectors that come along. Again, there + is a convenience class available for you called + <code>org.apache.tools.ant.types.selectors.BaseSelectorContainer</code>. + </p> + <li><p>Implement the + <code>public boolean isSelected(String filename, File file)</code> + method to do the right thing. Chances are you'll want to iterate + over the selectors under you, so use + <code>selectorElements()</code> to get an iterator that will do + that.</p> + <li><p>Again, put an <code>add</code> method for your container in + <code>org.apache.tools.ant.types.selectors.SelectorContainer</code> + and its implementations + <code>org.apache.tools.ant.types.AbstractFileSet</code> and + <code>org.apache.tools.ant.types.selectors.BaseSelectorContainer</code>. + </p> + </ul> + </ol> + + <h3>Testing Selectors</h3> + + <p>For a robust component (and selectors are (Project)Components) tests are + necessary. For testing Tasks we use JUnit TestCases - more specific + <tt>org.apache.tools.ant.BuildFileRule extends org.junit.rules.ExternalResource</tt>. + Some of its features like configure the (test) project by reading its buildfile and + execute targets we need for selector tests also. Therefore we use that BuildFileRule. + But testing selectors requires some more work: having a set of files, instantiate + and configure the selector, check the selection work and more. Because we usually + extend <tt>BaseExtendSelector</tt> its features have to be tested also (e.g. setError()). + </p> + + <p>That's why we have a test rule for doing our selector tests: + <tt>org.apache.tools.ant.types.selectors.BaseSelectorRule</tt>.</p> + + <p>This class extends ExternalResource and therefore can included in the set of Ant's + unit tests. It holds an instance of preconfigured BuildFileRule. Configuration + is done by parsing the src/etc/testcases/types/selectors.xml. BaseSelectorRule + then gives us helper methods for handling multiple selections. </p> + + <p>Because the term "testcase" or "testenvironment" are so often used, this + special testenvironment got a new name: <i>bed</i>. The setup and cleanup of + the bed is all handled by the BaseSelectorRule so any test only has to handle + the actual test scenarios</p> + + <p>A usual test scenario is:</p> + <ol> + <li>instantiate the selector</li> + <li>configure the selector</li> + <li>let the selector do some work</li> + <li>verify the work</li> + </ol> + + + + <p>An example test would be:<pre> +package org.apache.tools.ant.types.selectors; + +public class MySelectorTest { + + @Rule + public final BaseSelectorRule selectorRule = new BaseSelectorRule(); + + @Test + public void testCase1() { + + + // Configure the selector + MySelector s = new MySelector(); + s.addParam("key1", "value1"); + s.addParam("key2", "value2"); + s.setXX(true); + s.setYY("a value"); + + // do the tests + assertEquals("FTTTTTTTT", selectorRule.selectionString(s)); + } +} + </pre> + As an example of an error JUnit could log<pre> + [junit] FAILED + [junit] Error for files: <font color=blue>.;copy.filterset.filtered;tar/gz/asf-logo.gif.tar.gz</font> + [junit] expected:<<font color=blue>FTTTFTTTF...</font>> but was:<TTTTTTTTT...> + [junit] junit.framework.ComparisonFailure: Error for files: .;copy.filterset.filtered;tar/gz/asf-logo.gif.tar.gz + [junit] expected:<FTTTFTTTF...> but was:<TTTTTTTTT...> + [junit] at junit.framework.Assert.assertEquals(Assert.java:81) + [junit] at org.apache.tools.ant.types.selectors.BaseSelectorTest.performTest(BaseSelectorTest.java:194) + </pre></p> + + <p>Described above the test class should provide a <tt>getInstance()</tt> + method. But that isn't used here. The used <tt>getSelector()</tt> method is + implemented in the base class and gives an instance of an Ant Project to + the selector. This is usually done inside normal build file runs, but not + inside this special environment, so this method gives the selector the + ability to use its own Project object (<tt>getProject()</tt>), for example + for logging.</p> + + + <h3>Logging</h3> + + <p>During development and maybe later you sometimes need the output of information. + Therefore Logging is needed. Because the selector extends BaseExtendSelector or directly + BaseSelector it is an Ant <tt>DataType</tt> and therefore a <tt>ProjectComponent</tt>. <br> + That means that you have access to the project object and its logging capability. + <tt>ProjectComponent</tt> itself provides <i>log</i> methods which will do the + access to the project instance. Logging is therefore done simply with: + <pre> + log( "message" ); + </pre> + or + <pre> + log( "message" , loglevel ); + </pre> + where the <tt>loglevel</tt> is one of the values <ul> + <li> org.apache.tools.ant.Project.MSG_ERR </li> + <li> org.apache.tools.ant.Project.MSG_WARN </li> + <li> org.apache.tools.ant.Project.MSG_INFO (= default) </li> + <li> org.apache.tools.ant.Project.MSG_VERBOSE </li> + <li> org.apache.tools.ant.Project.MSG_DEBUG </li> + </ul> + </p> + + + </body> + +</html> diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/selectors.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/selectors.html new file mode 100644 index 00000000..560b416c --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/selectors.html @@ -0,0 +1,1566 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + <head> + <meta http-equiv="Content-Language" content="en-us"> + <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> + <title>Selectors in Apache Ant</title> + </head> + + <body> + <h2>Selectors</h2> + + <p>Selectors are a mechanism whereby the files that make up a + <code><fileset></code> can be selected based on criteria + other than filename as provided by the <code><include></code> + and <code><exclude></code> tags.</p> + + <h3>How to use a Selector</h3> + + <p>A selector is an element of FileSet, and appears within it. It can + also be defined outside of any target by using the <code><selector></code> tag + and then using it as a reference. + </p> + + <p>Different selectors have different attributes. Some selectors can + contain other selectors, and these are called + <a href="#selectcontainers"><code>Selector Containers</code></a>. + There is also a category of selectors that allow + user-defined extensions, called + <a href="#customselect"><code>Custom Selectors</code></a>. + The ones built in to Apache Ant are called + <a href="#coreselect"><code>Core Selectors</code></a>. + </p> + + <h3><a name="coreselect">Core Selectors</a></h3> + + <p>Core selectors are the ones that come standard + with Ant. They can be used within a fileset and can be contained + within Selector Containers.</p> + + <p>The core selectors are:</p> + + <ul> + <li><a href="#containsselect"><code><contains></code></a> - Select + files that contain a particular text string</li> + <li><a href="#dateselect"><code><date></code></a> - Select files + that have been modified either before or after a particular date + and time</li> + <li><a href="#dependselect"><code><depend></code></a> - Select files + that have been modified more recently than equivalent files + elsewhere</li> + <li><a href="#depthselect"><code><depth></code></a> - Select files + that appear so many directories down in a directory tree</li> + <li><a href="#differentselect"><code><different></code></a> - Select files + that are different from those elsewhere</li> + <li><a href="#filenameselect"><code><filename></code></a> - Select + files whose name matches a particular pattern. Equivalent to + the include and exclude elements of a patternset.</li> + <li><a href="#presentselect"><code><present></code></a> - Select + files that either do or do not exist in some other location</li> + <li><a href="#regexpselect"><code><containsregexp></code></a> - Select + files that match a regular expression</li> + <li><a href="#sizeselect"><code><size></code></a> - Select files + that are larger or smaller than a particular number of bytes.</li> + <li><a href="#typeselect"><code><type></code></a> - Select files + that are either regular files or directories.</li> + <li><a href="#modified"><code><modified></code></a> - Select files if + the return value of the configured algorithm is different from that + stored in a cache.</li> + <li><a href="#signedselector"><code><signedselector></code></a> - Select files if + they are signed, and optionally if they have a signature of a certain name. + </li> + <li><a href="#scriptselector"><code><scriptselector></code></a> - + Use a BSF or JSR 223 scripting language to create + your own selector + </li> + <li><a href="#readable"><code><readable></code></a> - + Select files if they are readable.</li> + <li><a href="#writable"><code><writable></code></a> - + Select files if they are writable.</li> + </ul> + + <h4><a name="containsselect">Contains Selector</a></h4> + + <p>The <code><contains></code> tag in a FileSet limits + the files defined by that fileset to only those which contain the + string specified by the <code>text</code> attribute. + .</p> + <p>The <code><contains></code> selector can be used as a + ResourceSelector (see the + <a href="resources.html#restrict"><restrict></a> + ResourceCollection).</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">text</td> + <td valign="top">Specifies the text that every file must contain + </td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">casesensitive</td> + <td valign="top">Whether to pay attention to case when looking + for the string in the <code>text</code> attribute. Default is + true. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">ignorewhitespace</td> + <td valign="top">Whether to eliminate whitespace before checking + for the string in the <code>text</code> attribute. Default is + false. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">encoding</td> + <td valign="top">Encoding of the resources being selected. + Required in practice if the encoding of the files being + selected is different from the default encoding of the JVM + where Ant is running. + Since Ant 1.9.0 + </td> + <td valign="top" align="center">No</td> + </tr> + </table> + + <p>Here is an example of how to use the Contains Selector:</p> + + <blockquote><pre> +<fileset dir="${doc.path}" includes="**/*.html"> + <contains text="script" casesensitive="no"/> +</fileset> +</pre></blockquote> + + <p>Selects all the HTML files that contain the string + <code>script</code>.</p> + + + <h4><a name="dateselect">Date Selector</a></h4> + + <p>The <code><date></code> tag in a FileSet will put + a limit on the files specified by the include tag, so that tags + whose last modified date does not meet the date limits specified + by the selector will not end up being selected.</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">datetime</td> + <td valign="top">Specifies the date and time to test for. + Should be in the format MM/DD/YYYY HH:MM AM_or_PM, or + an alternative pattern specified via the <i>pattern</i> + attribute. + </td> + <td valign="top" align="center" rowspan="2">At least one of the two.</td> + </tr> + <tr> + <td valign="top">millis</td> + <td valign="top">The number of milliseconds since 1970 that should + be tested for. It is usually much easier to use the datetime + attribute. + </td> + </tr> + <tr> + <td valign="top">when</td> + <td valign="top">Indicates how to interpret the date, whether + the files to be selected are those whose last modified times should + be before, after, or equal to the specified value. Acceptable + values for this attribute are: + <ul> + <li>before - select files whose last modified date is before the indicated date + <li>after - select files whose last modified date is after the indicated date + <li>equal - select files whose last modified date is this exact date + </ul> + The default is equal. + <td valign="top" align="center">No</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. Default is 0 milliseconds, or 2 seconds on DOS systems. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">pattern</td> + <td valign="top">The <CODE>SimpleDateFormat</CODE>-compatible pattern + to use when interpreting the <i>datetime</i> attribute. + <i>Since Ant 1.6.2</i> + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">checkdirs</td> + <td valign="top"> + Indicates whether or not to check dates on directories. + </td> + <td valign="top" align="center">No, defaults to <i>false</i></td> + </tr> + </table> + + <p>Here is an example of how to use the Date Selector:</p> + + <blockquote><pre> +<fileset dir="${jar.path}" includes="**/*.jar"> + <date datetime="01/01/2001 12:00 AM" when="before"/> +</fileset> +</pre></blockquote> + + <p>Selects all JAR files which were last modified before midnight + January 1, 2001.</p> + + + <h4><a name="dependselect">Depend Selector</a></h4> + + <p>The <code><depend></code> tag selects files + whose last modified date is later than another, equivalent file in + another location.</p> + + <p>The <code><depend></code> tag supports the use of a + contained <a href="mapper.html"><code><mapper></code></a> element + to define the location of the file to be compared against. If no + <code><mapper></code> element is specified, the + <code>identity</code> type mapper is used.</p> + + <p>The <code><depend></code> selector is case-sensitive.</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">targetdir</td> + <td valign="top">The base directory to look for the files to compare + against. The precise location depends on a combination of this + attribute and the <code><mapper></code> element, if any. + </td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">granularity</td> + <td valign="top">The number of milliseconds leeway to give before + deciding a file is out of date. This is needed because not every + file system supports tracking the last modified time to the + millisecond level. Default is 0 milliseconds, or 2 seconds on DOS systems. + </td> + <td valign="top" align="center">No</td> + </tr> + </table> + + <p>Here is an example of how to use the Depend Selector:</p> + + <blockquote><pre> +<fileset dir="${ant.1.5}/src/main" includes="**/*.java"> + <depend targetdir="${ant.1.4.1}/src/main"/> +</fileset> +</pre></blockquote> + + <p>Selects all the Java source files which were modified in the + 1.5 release. + </p> + + + <h4><a name="depthselect">Depth Selector</a></h4> + + <p>The <code><depth></code> tag selects files based on + how many directory levels deep they are in relation to the base + directory of the fileset. + </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">min</td> + <td valign="top">The minimum number of directory levels below + the base directory that a file must be in order to be selected. + Default is no limit. + </td> + <td valign="top" align="center" rowspan="2">At least one of the two.</td> + </tr> + <tr> + <td valign="top">max</td> + <td valign="top">The maximum number of directory levels below + the base directory that a file can be and still be selected. + Default is no limit. + </td> + </tr> + </table> + + <p>Here is an example of how to use the Depth Selector:</p> + + <blockquote><pre> +<fileset dir="${doc.path}" includes="**/*"> + <depth max="1"/> +</fileset> +</pre></blockquote> + + <p>Selects all files in the base directory and one directory below + that.</p> + + + <h4><a name="differentselect">Different Selector</a></h4> + + <p>The <code><different></code> selector will select a file + if it is deemed to be 'different' from an equivalent file in + another location. The rules for determining difference between + the two files are as follows: + <ol> + <li>If a file is only present in the resource collection you apply + the selector to but not in targetdir (or after applying the + mapper) the file is selected. + <li>If a file is only present in targetdir (or after applying the + mapper) it is ignored. + <li> Files with different lengths are different. + <li> If <tt>ignoreFileTimes</tt> is turned off, then differing file + timestamps will cause files to be regarded as different. + <li> Unless <tt>ignoreContents</tt> is set to true, + a byte-for-byte check is run against the two files. + </ol> + + 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 just a timestamp. For example: anything fetched from a web site, + or the output of some program. To reduce the amount of checking, when using + this task inside a <code><copy></code> task, set + <tt>preservelastmodified</tt> to <i>true</i> to propagate the timestamp + from the source file to the destination file.<p> + + The <code><different></code> selector supports the use of a + contained <a href="mapper.html"><code><mapper></code></a> element + to define the location of the file to be compared against. If no + <code><mapper></code> element is specified, the + <code>identity</code> type mapper is used.</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">targetdir</td> + <td valign="top">The base directory to look for the files to compare + against. The precise location depends on a combination of this + attribute and the <code><mapper></code> element, if any. + </td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">ignoreFileTimes</td> + <td valign="top">Whether to use file times in the comparison or not. + Default is true (time differences are ignored). + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">ignoreContents</td> + <td valign="top">Whether to do a byte per byte compare. + Default is false (contents are compared). + Since Ant 1.6.3 + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">granularity</td> + <td valign="top">The number of milliseconds leeway to give before + deciding a file is out of date. This is needed because not every + file system supports tracking the last modified time to the + millisecond level. Default is 0 milliseconds, or 2 seconds on DOS systems. + </td> + <td valign="top" align="center">No</td> + </tr> + </table> + + <p>Here is an example of how to use the Different Selector:</p> + + <blockquote><pre> +<fileset dir="${ant.1.5}/src/main" includes="**/*.java"> + <different targetdir="${ant.1.4.1}/src/main" + ignoreFileTimes="true"/> +</fileset> +</pre></blockquote> + + <p>Compares all the Java source files between the 1.4.1 and the 1.5 release + and selects those who are different, disregarding file times. + </p> + + <h4><a name="filenameselect">Filename Selector</a></h4> + + <p>The <code><filename></code> tag acts like the + <code><include></code> and <code><exclude></code> + tags within a fileset. By using a selector instead, however, + one can combine it with all the other selectors using whatever + <a href="#selectcontainers">selector container</a> is desired. + </p> + + <p>The <code><filename></code> selector is + case-sensitive.</p> + + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">The name of files to select. The name parameter + can contain the standard Ant wildcard characters. + </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 to pay attention to case when looking + at file names. Default is "true". + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">negate</td> + <td valign="top">Whether to reverse the effects of this filename + selection, therefore emulating an exclude rather than include + tag. Default is "false". + </td> + <td valign="top" align="center">No</td> + </tr> + </table> + + <p>Here is an example of how to use the Filename Selector:</p> + + <blockquote><pre> +<fileset dir="${doc.path}" includes="**/*"> + <filename name="**/*.css"/> +</fileset> +</pre></blockquote> + + <p>Selects all the cascading style sheet files.</p> + + + <h4><a name="presentselect">Present Selector</a></h4> + + <p>The <code><present></code> tag selects files + that have an equivalent file in another directory tree.</p> + + <p>The <code><present></code> tag supports the use of a + contained <a href="mapper.html"><code><mapper></code></a> element + to define the location of the file to be tested against. If no + <code><mapper></code> element is specified, the + <code>identity</code> type mapper is used.</p> + + <p>The <code><present></code> selector is case-sensitive.</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">targetdir</td> + <td valign="top">The base directory to look for the files to compare + against. The precise location depends on a combination of this + attribute and the <code><mapper></code> element, if any. + </td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">present</td> + <td valign="top">Whether we are requiring that a file is present in + the src directory tree only, or in both the src and the target + directory tree. Valid values are: + <ul> + <li>srconly - select files only if they are in the src + directory tree but not in the target directory tree + <li>both - select files only if they are present both in the + src and target directory trees + </ul> + Default is both. Setting this attribute to "srconly" + is equivalent to wrapping the selector in the <code><not></code> + selector container. + </td> + <td valign="top" align="center">No</td> + </tr> + </table> + + <p>Here is an example of how to use the Present Selector:</p> + + <blockquote><pre> +<fileset dir="${ant.1.5}/src/main" includes="**/*.java"> + <present present="srconly" targetdir="${ant.1.4.1}/src/main"/> +</fileset> +</pre></blockquote> + + <p>Selects all the Java source files which are new in the + 1.5 release. + </p> + + <h4><a name="regexpselect">Regular Expression Selector</a></h4> + + <p>The <code><containsregexp></code> tag in a FileSet limits + the files defined by that fileset to only those which contents contain a + match to the regular expression specified by the <code>expression</code> attribute. + </p> + <p>The <code><containsregexp></code> selector can be used as a + ResourceSelector (see the + <a href="resources.html#restrict"><restrict></a> + ResourceCollection).</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">expression</td> + <td valign="top">Specifies the regular expression that must + match true in every file</td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">casesensitive</td> + <td valign="top">Perform a case sensitive match. Default is + true. <em>since Ant 1.8.2</em></td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">multiline</td> + <td valign="top"> + Perform a multi line match. + Default is false. <em>since Ant 1.8.2</em></td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">singleline</td> + <td valign="top"> + This allows '.' to match new lines. + SingleLine is not to be confused with multiline, SingleLine is a perl + regex term, it corresponds to dotall in java regex. + Default is false. <em>since Ant 1.8.2</em></td> + <td valign="top" align="center">No</td> + </tr> + </table> + + <p>Here is an example of how to use the regular expression Selector:</p> + + <blockquote><pre> +<fileset dir="${doc.path}" includes="*.txt"> + <containsregexp expression="[4-6]\.[0-9]"/> +</fileset> +</pre></blockquote> + + <p>Selects all the text files that match the regular expression + (have a 4,5 or 6 followed by a period and a number from 0 to 9). + + + <h4><a name="sizeselect">Size Selector</a></h4> + + <p>The <code><size></code> tag in a FileSet will put + a limit on the files specified by the include tag, so that tags + which do not meet the size limits specified by the selector will not + end up being selected.</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 size of the file which should be tested for. + </td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">units</td> + <td valign="top">The units that the <code>value</code> attribute + is expressed in. When using the standard single letter SI + designations, such as "k","M", or + "G", multiples of 1000 are used. If you want to use + power of 2 units, use the IEC standard: "Ki" for 1024, + "Mi" for 1048576, and so on. The default is no units, + which means the <code>value</code> attribute expresses the exact + number of bytes. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">when</td> + <td valign="top">Indicates how to interpret the size, whether + the files to be selected should be larger, smaller, or equal to + that value. Acceptable values for this attribute are: + <ul> + <li>less - select files less than the indicated size + <li>more - select files greater than the indicated size + <li>equal - select files this exact size + </ul> + The default is equal. + <td valign="top" align="center">No</td> + </tr> + </table> + + <p>Here is an example of how to use the Size Selector:</p> + + <blockquote><pre> +<fileset dir="${jar.path}"> + <patternset> + <include name="**/*.jar"/> + </patternset> + <size value="4" units="Ki" when="more"/> +</fileset> +</pre></blockquote> + + <p>Selects all JAR files that are larger than 4096 bytes.</p> + + <h4><a name="typeselect">Type Selector</a></h4> + + <p>The <code><type></code> tag selects files of a certain type: + directory or regular.</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">The type of file which should be tested for. + Acceptable values are: + <ul> + <li>file - regular files</li> + <li>dir - directories</li> + </ul> + </td> + <td valign="top" align="center">Yes</td> + </tr> + </table> + + <p>Here is an example of how to use the Type Selector to select only + directories in <code>${src}</code></p> + + <blockquote><pre> +<fileset dir="${src}"> + <type type="dir"/> +</fileset> +</pre></blockquote> + + <p>The Type Selector is often used in conjunction with other selectors. + For example, to select files that also exist in a <code>template</code> + directory, but avoid selecting empty directories, use: + +<blockquote><pre> +<fileset dir="${src}"> + <and> + <present targetdir="template"/> + <type type="file"/> + </and> +</fileset> +</pre></blockquote> + + + <h4><a name="modified">Modified Selector</a></h4> + <p>The <code><modified></code> selector computes a value for a file, compares that + to the value stored in a cache and select the file, if these two values + differ.</p> + <p>Because this selector is highly configurable the order in which the selection is done + is: <ol> + <li> get the absolute path for the file </li> + <li> get the cached value from the configured cache (absolute path as key) </li> + <li> get the new value from the configured algorithm </li> + <li> compare these two values with the configured comparator </li> + <li> update the cache if needed and requested </li> + <li> do the selection according to the comparison result </li> + </ol> + <p>The comparison, computing of the hashvalue and the store is done by implementation + of special interfaces. Therefore they may provide additional parameters.</p> + + <p>The <code><modified></code> selector can be used as a + ResourceSelector (see the + <a href="resources.html#restrict"><restrict></a> + ResourceCollection). + In that case it maps simple file resources to files and does its job. If the + resource is from another type, the <code><modified></code> selector tries + to (<b>attention!</b>) copy the content into a local file for computing the + hashvalue.</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"> algorithm </td> + <td valign="top"> The type of algorithm should be used. + Acceptable values are (further information see later): + <ul> + <li> hashvalue - HashvalueAlgorithm </li> + <li> digest - DigestAlgorithm </li> + <li> checksum - ChecksumAlgorithm </li> + </ul> + </td> + <td valign="top" align="center"> No, defaults to <i>digest</i> </td> + </tr> + <tr> + <td valign="top"> cache </td> + <td valign="top"> The type of cache should be used. + Acceptable values are (further information see later): + <ul> + <li> propertyfile - PropertyfileCache </li> + </ul> + </td> + <td valign="top" align="center"> No, defaults to <i>propertyfile</i> </td> + </tr> + <tr> + <td valign="top"> comparator </td> + <td valign="top"> The type of comparator should be used. + Acceptable values are (further information see later): + <ul> + <li> equal - EqualComparator </li> + <li> rule - java.text.RuleBasedCollator + <!-- NOTE --> + <i>(see <a href="#ModSelNote">note</a> for restrictions)</i> + </li> + </ul> + </td> + <td valign="top" align="center"> No, defaults to <i>equal</i> </td> + </tr> + <tr> + <td valign="top"> algorithmclass </td> + <td valign="top"> Classname of custom algorithm implementation. Lower + priority than <i>algorithm</i>. </td> + <td valign="top" align="center"> No </td> + </tr> + <tr> + <td valign="top"> cacheclass </td> + <td valign="top"> Classname of custom cache implementation. Lower + priority than <i>cache</i>. </td> + <td valign="top" align="center"> No </td> + </tr> + <tr> + <td valign="top"> comparatorclass </td> + <td valign="top"> Classname of custom comparator implementation. Lower + priority than <i>comparator</i>. </td> + <td valign="top" align="center"> No </td> + </tr> + <tr> + <td valign="top"> update </td> + <td valign="top"> Should the cache be updated when values differ? (boolean) </td> + <td valign="top" align="center"> No, defaults to <i>true</i> </td> + </tr> + <tr> + <td valign="top"> seldirs </td> + <td valign="top"> Should directories be selected? (boolean) </td> + <td valign="top" align="center"> No, defaults to <i>true</i> </td> + </tr> + <tr> + <td valign="top"> selres </td> + <td valign="top"> Should Resources without an InputStream, and + therefore without checking, be selected? (boolean) </td> + <td valign="top" align="center"> No, defaults to <i>true</i>. Only relevant + when used as ResourceSelector. </td> + </tr> + <tr> + <td valign="top"> delayupdate </td> + <td valign="top"> If set to <i>true</i>, the storage of the cache will be delayed until the + next finished BuildEvent; task finished, target finished or build finished, + whichever comes first. This is provided for increased performance. If set + to <i>false</i>, the storage of the cache will happen with each change. This + attribute depends upon the <i>update</i> attribute. (boolean)</td> + <td valign="top" align="center"> No, defaults to <i>true</i> </td> + </tr> + </table> + + <p>These attributes can be set with nested <code><param/></code> tags. With <code><param/></code> + tags you can set other values too - as long as they are named according to + the following rules: <ul> + <li> <b> algorithm </b>: same as attribute algorithm </li> + <li> <b> cache </b>: same as attribute cache </li> + <li> <b> comparator </b>: same as attribute comparator </li> + <li> <b> algorithmclass </b>: same as attribute algorithmclass </li> + <li> <b> cacheclass </b>: same as attribute cacheclass </li> + <li> <b> comparatorclass </b>: same as attribute comparatorclass </li> + <li> <b> update </b>: same as attribute update </li> + <li> <b> seldirs </b>: same as attribute seldirs </li> + <li> <b> algorithm.* </b>: Value is transferred to the algorithm via its + <i>set</i>XX-methods </li> + <li> <b> cache.* </b>: Value is transferred to the cache via its + <i>set</i>XX-methods </li> + <li> <b> comparator.* </b>: Value is transferred to the comparator via its + <i>set</i>XX-methods </li> + </ul> + + <table border="1" cellpadding="2" cellspacing="0"> + <tr><td colspan="2"><font size="+1"><b> Algorithm options</b></font></td></tr> + <tr> + <td valign="top"><b>Name</b></td> + <td valign="top"><b>Description</b></td> + </tr> + <tr> + <td valign="top"> hashvalue </td> + <td valign="top"> Reads the content of a file into a java.lang.String + and use thats hashValue(). No additional configuration required. + </td> + </tr> + <tr> + <td valign="top"> digest </td> + <td valign="top"> Uses java.security.MessageDigest. This Algorithm supports + the following attributes: + <ul> + <li><i>algorithm.algorithm</i> (optional): Name of the Digest algorithm + (e.g. 'MD5' or 'SHA', default = <i>MD5</i>) </li> + <li><i>algorithm.provider</i> (optional): Name of the Digest provider + (default = <i>null</i>) </li> + </ul> + </td> + </tr> + <tr> + <td valign="top"> checksum </td> + <td valign="top"> Uses java.util.zip.Checksum. This Algorithm supports + the following attributes: + <ul> + <li><i>algorithm.algorithm</i> (optional): Name of the algorithm + (e.g. 'CRC' or 'ADLER', default = <i>CRC</i>) </li> + </ul> + </td> + </tr> + <tr><td colspan="2"><font size="+1"><b> Cache options </b></font></td></tr> + <tr> + <td valign="top"> propertyfile </td> + <td valign="top"> Use the java.util.Properties class and its possibility + to load and store to file. + This Cache implementation supports the following attributes: + <ul> + <li><i>cache.cachefile</i> (optional): Name of the properties-file + (default = <i>cache.properties</i>) </li> + </ul> + </td> + </tr> + <tr><td colspan="2"><font size="+1"><b> Comparator options</b></font></td></tr> + <tr> + <td valign="top"> equal </td> + <td valign="top"> Very simple object comparison. </td> + </tr> + <tr> + <td valign="top"> rule </td> + <td valign="top"> Uses <i>java.text.RuleBasedCollator</i> for Object + comparison. + <!-- NOTE --> + <i>(see <a href="#ModSelNote">note</a> for restrictions)</i> + </td> + </tr> + </table> + + <p>The <code><modified></code> selector supports a nested + <code><classpath></code> element that represents a <a href="../using.html#path"> + PATH like structure</a> for finding custom interface implementations. </p> + + <p>Here are some examples of how to use the Modified Selector:</p> + + <blockquote><pre> + <copy todir="dest"> + <fileset dir="src"> + <modified/> + </fileset> + </copy> + </pre></blockquote> + <p>This will copy all files from <i>src</i> to <i>dest</i> which content has changed. + Using an updating PropertyfileCache with cache.properties and + MD5-DigestAlgorithm.</p> + + <blockquote><pre> + <copy todir="dest"> + <fileset dir="src"> + <modified update="true" + seldirs="true" + cache="propertyfile" + algorithm="digest" + comparator="equal"> + <param name="cache.cachefile" value="cache.properties"/> + <param name="algorithm.algorithm" value="MD5"/> + </modified> + </fileset> + </copy> + </pre></blockquote> + <p>This is the same example rewritten as CoreSelector with setting the all the values + (same as defaults are).</p> + + <blockquote><pre> + <copy todir="dest"> + <fileset dir="src"> + <custom class="org.apache.tools.ant.types.selectors.modifiedselector.ModifiedSelector"> + <param name="update" value="true"/> + <param name="seldirs" value="true"/> + <param name="cache" value="propertyfile"/> + <param name="algorithm" value="digest"/> + <param name="comparator" value="equal"/> + <param name="cache.cachefile" value="cache.properties"/> + <param name="algorithm.algorithm" value="MD5"/> + </custom> + </fileset> + </copy> + </pre></blockquote> + <p>And this is the same rewritten as CustomSelector.</p> + + <blockquote><pre> + <target name="generate-and-upload-site"> + <echo> generate the site using forrest </echo> + <antcall target="site"/> + + <echo> upload the changed file </echo> + <ftp server="${ftp.server}" userid="${ftp.user}" password="${ftp.pwd}"> + <fileset dir="htdocs/manual"> + <modified/> + </fileset> + </ftp> + </target> + </pre></blockquote> + <p>A useful scenario for this selector inside a build environment + for homepage generation (e.g. with <a href="http://xml.apache.org/forrest/"> + Apache Forrest</a>). Here all <b>changed</b> files are uploaded to the server. The + CacheSelector saves therefore much upload time.</p> + + <blockquote><pre> + <modified cacheclassname="com.mycompany.MyCache"> + <classpath> + <pathelement location="lib/mycompany-antutil.jar"/> + </classpath> + </modified> + </pre></blockquote> + <p>Uses <tt>com.mycompany.MyCache</tt> from a jar outside of Ants own classpath + as cache implementation</p> + + <h4><a name="ModSelNote">Note on RuleBasedCollator</a></h4> + <p>The RuleBasedCollator needs a format for its work, but its needed while + instantiation. There is a problem in the initialization algorithm for this + case. Therefore you should not use this (or tell me the workaround :-).</p> + + <h4><a name="signedselector">Signed Selector</a></h4> + + <p> + The <code><signedselector></code> tag selects signed files and optionally + signed with a certain name. + </p> + <p> + This selector has been added in Apache Ant 1.7. + </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 signature name to check for.</td> + <td valign="top" align="center">no</td> + </tr> + </table> + + <h4><a name="readable">Readable Selector</a></h4> + + <p>The <code><readable></code> selector selects only files + that are readable. Ant only invokes + <code>java.io.File#canRead</code> so if a file is unreadable + but the Java VM cannot detect this state, this selector will + still select the file.</p> + + <h4><a name="writable">Writable Selector</a></h4> + + <p>The <code><writable></code> selector selects only files + that are writable. Ant only invokes + <code>java.io.File#canWrite</code> so if a file is unwritable + but the Java VM cannot detect this state, this selector will + still select the file.</p> + + <h4><a name="scriptselector">Script Selector</a></h4> + + <p> + The <code><scriptselector></code> element enables you + to write a complex selection algorithm in any + <a href="http://jakarta.apache.org/bsf" target="_top">Apache BSF</a> + or + <a href="https://scripting.dev.java.net">JSR 223</a> + supported language. + See the <a href="../Tasks/script.html">Script</a> task for + an explanation of scripts and dependencies. + </p> + <p> + This selector was added in Apache Ant 1.7. + </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">language</td> + <td valign="top">language of the script.</td> + <td valign="top" align="center">yes</td> + </tr> + <tr> + <td valign="top">manager</td> + <td valign="top"> + The script engine manager to use. + See the <a href="../Tasks/script.html">script</a> task + for using this attribute. + </td> + <td valign="top" align="center">No - default is "auto"</td> + </tr> + <tr> + <td valign="top">src</td> + <td valign="top">filename of the script</td> + <td valign="top" align="center">no</td> + </tr> + <tr> + <td valign="top">setbeans</td> + <td valign="top">whether to have all properties, references and targets as + global variables in the script.</td> + <td valign="top" align="center">No, default is "true".</td> + </tr> + <tr> + <td valign="top">classpath</td> + <td valign="top"> + The classpath to pass into the script. + </td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">classpathref</td> + <td valign="top">The classpath to use, given as a + <a href="../using.html#references">reference</a> to a path defined elsewhere. + <td align="center" valign="top">No</td> + </tr> + </table> + <p> + This selector can take a nested <classpath> element. + See the <a href="../Tasks/script.html">script</a> task + on how to use this element. + </p> + <p> + If no <code>src</code> attribute is supplied, the script must be nested + inside the selector declaration. + </p> + <p>The embedded script is invoked for every test, with + the bean <code>self</code> + is bound to the selector. It has an attribute <code>selected</code> + must can be set using <code>setSelected(boolean)</code> to select that + file. + + <p> + + The following beans are configured for every script, alongside + the classic set of project, properties, and targets. + + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Bean</b></td> + <td valign="top"><b>Description</b></td> + <td valign="top"><b>Type</b></td> + </tr> + <tr> + <td valign="top">self</td> + <td valign="top">selector instance</td> + <td valign="top">org.apache.tools.ant.types.optional</td> + </tr> + <tr> + <td valign="top">filename</td> + <td valign="top">filename of the selection</td> + <td valign="top" >String</td> + </tr> + <tr> + <td valign="top">file</td> + <td valign="top">file of the selection</td> + <td valign="top" >java.io.File</td> + </tr> + <tr> + <td valign="top">basedir</td> + <td valign="top">Fileset base directory</td> + <td valign="top" >java.io.File</td> + </tr> + + </table> + <p> + The <code>self</code> bean maps to the selector, which has the following + attributes. Only the <code>selected</code> flag is writable, the rest + are read only via their getter methods. + + <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>Type</b></td> + </tr> + <tr> + <td valign="top">selected</td> + <td valign="top">writeable flag to select this file</td> + <td valign="top" align="center">boolean</td> + </tr> + <tr> + <td valign="top">filename</td> + <td valign="top">filename of the selection</td> + <td valign="top" >String</td> + </tr> + <tr> + <td valign="top">file</td> + <td valign="top">file of the selection</td> + <td valign="top" >java.io.File</td> + </tr> + <tr> + <td valign="top">basedir</td> + <td valign="top">Fileset base directory</td> + <td valign="top" >java.io.File</td> + </tr> + </table> + + <p> + Example + </p> +<pre> + <scriptselector language="javascript"> + self.setSelected(true); + </scriptselector> +</pre> + <p> + Selects every file. + </p> + +<pre> + <scriptselector language="javascript"> + self.setSelected((filename.length%2)==0); + </scriptselector> +</pre> +Select files whose filename length is even. + + <h3><a name="selectcontainers">Selector Containers</a></h3> + + <p>To create more complex selections, a variety of selectors that + contain other selectors are available for your use. They combine the + selections of their child selectors in various ways.</p> + + <p>The selector containers are:</p> + + <ul> + <li><a href="#andselect"><code><and></code></a> - select a file only if all + the contained selectors select it. + <li><a href="#majorityselect"><code><majority></code></a> - select a file + if a majority of its selectors select it. + <li><a href="#noneselect"><code><none></code></a> - select a file only if + none of the contained selectors select it. + <li><a href="#notselect"><code><not></code></a> - can contain only one + selector, and reverses what it selects and doesn't select. + <li><a href="#orselect"><code><or></code></a> - selects a file if any one + of the contained selectors selects it. + <li><a href="#selectorselect"><code><selector></code></a> - contains only one + selector and forwards all requests to it without alteration, provided + that any <code>"if"</code> or + <code>"unless"</code> conditions are met. This + is the selector to use if you want to define a reference. It is + usable as an element of <code><project></code>. It is also + the one to use if you want selection of files to be dependent on + Ant property settings. + </ul> + + <p>All selector containers can contain any other selector, including + other containers, as an element. Using containers, the selector tags + can be arbitrarily deep. Here is a complete list of allowable + selector elements within a container:</p> + + <ul> + <li><code><and></code></li> + <li><code><contains></code></li> + <li><code><custom></code></li> + <li><code><date></code></li> + <li><code><depend></code></li> + <li><code><depth></code></li> + <li><code><filename></code></li> + <li><code><majority></code></li> + <li><code><none></code></li> + <li><code><not></code></li> + <li><code><or></code></li> + <li><code><present></code></li> + <li><code><selector></code></li> + <li><code><size></code></li> + </ul> + + <h4><a name="andselect">And Selector</a></h4> + + <p>The <code><and></code> tag selects files that are + selected by all of the elements it contains. It returns as + soon as it finds a selector that does not select the file, + so it is not guaranteed to check every selector. + </p> + + <p>Here is an example of how to use the And Selector:</p> + + <blockquote><pre> +<fileset dir="${dist}" includes="**/*.jar"> + <and> + <size value="4" units="Ki" when="more"/> + <date datetime="01/01/2001 12:00 AM" when="before"/> + </and> +</fileset> +</pre></blockquote> + + <p>Selects all the JAR file larger than 4096 bytes which haven't been update + since the last millennium. + </p> + + + <h4><a name="majorityselect">Majority Selector</a></h4> + + <p>The <code><majority></code> tag selects files provided + that a majority of the contained elements also select it. Ties are + dealt with as specified by the <code>allowtie</code> attribute. + </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 files should be selected if there + are an even number of selectors selecting them as are + not selecting them. Default is true. + </td> + <td valign="top" align="center">No</td> + </tr> + </table> + + + <p>Here is an example of how to use the Majority Selector:</p> + + <blockquote><pre> +<fileset dir="${docs}" includes="**/*.html"> + <majority> + <contains text="project" casesensitive="false"/> + <contains text="taskdef" casesensitive="false"/> + <contains text="IntrospectionHelper" casesensitive="true"/> + </majority> +</fileset> +</pre></blockquote> + + <p>Selects all the HTML files which contain at least two of the three + phrases "project", "taskdef", and "IntrospectionHelper" (this last phrase must + match case exactly). + </p> + + + <h4><a name="noneselect">None Selector</a></h4> + + <p>The <code><none></code> tag selects files that are + not selected by any of the elements it contains. It returns as + soon as it finds a selector that selects the file, + so it is not guaranteed to check every selector. + </p> + + <p>Here is an example of how to use the None Selector:</p> + + <blockquote><pre> +<fileset dir="${src}" includes="**/*.java"> + <none> + <present targetdir="${dest}"/> + <present targetdir="${dest}"> + <mapper type="glob" from="*.java" to="*.class"/> + </present> + </none> +</fileset> +</pre></blockquote> + + <p>Selects only Java files which do not have equivalent java or + class files in the dest directory. + </p> + + + <h4><a name="notselect">Not Selector</a></h4> + + <p>The <code><not></code> tag reverses the meaning of the + single selector it contains. + </p> + + <p>Here is an example of how to use the Not Selector:</p> + + <blockquote><pre> +<fileset dir="${src}" includes="**/*.java"> + <not> + <contains text="test"/> + </not> +</fileset> +</pre></blockquote> + + <p>Selects all the files in the src directory that do not contain the + string "test". + </p> + + + <h4><a name="orselect">Or Selector</a></h4> + + <p>The <code><or></code> tag selects files that are + selected by any one of the elements it contains. It returns as + soon as it finds a selector that selects the file, + so it is not guaranteed to check every selector. + </p> + + <p>Here is an example of how to use the Or Selector:</p> + + <blockquote><pre> +<fileset dir="${basedir}"> + <or> + <depth max="0"/> + <filename name="*.png"/> + <filename name="*.gif"/> + <filename name="*.jpg"/> + </or> +</fileset> +</pre></blockquote> + + <p>Selects all the files in the top directory along with all the + image files below it. + </p> + + + <h4><a name="selectorselect">Selector Reference</a></h4> + + <p>The <code><selector></code> tag is used to create selectors + that can be reused through references. It is the only selector which can + be used outside of + any target, as an element of the <code><project></code> tag. It + can contain only one other selector, but of course that selector can + be a container. + </p> + + <p>The <code><selector></code> tag can also be used to select + files conditionally based on whether an Ant property exists or not. + This functionality is realized using the <code>"if"</code> and + <code>"unless"</code> attributes in exactly the same way they + are used on targets or on the <code><include></code> and + <code><exclude></code> tags within a + <code><patternset></code>.</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">if</td> + <td valign="top">Allow files to be selected only <a href="../properties.html#if+unless">if the named + property is set</a>. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">unless</td> + <td valign="top">Allow files to be selected only <a href="../properties.html#if+unless">if the named + property is <b>not</b> set</a>. + </td> + <td valign="top" align="center">No</td> + </tr> + </table> + + <p>Here is an example of how to use the Selector Reference:</p> + + <blockquote><pre> +<project default="all" basedir="./ant"> + + <selector id="completed"> + <none> + <depend targetdir="build/classes"> + <mapper type="glob" from="*.java" to="*.class"/> + </depend> + <depend targetdir="docs/manual/api"> + <mapper type="glob" from="*.java" to="*.html"/> + </depend> + </none> + </selector> + + <target> + <zip> + <fileset dir="src/main" includes="**/*.java"> + <selector refid="completed"/> + </fileset> + </zip> + </target> + +</project> +</pre></blockquote> + + <p>Zips up all the Java files which have an up-to-date equivalent + class file and javadoc file associated with them. + </p> + + <p>And an example of selecting files conditionally, based on whether + properties are set:</p> + + <blockquote><pre> +<fileset dir="${working.copy}"> + <or> + <selector if="include.tests"> + <filename name="**/*Test.class"> + </selector> + <selector if="include.source"> + <and> + <filename name="**/*.java"> + <not> + <selector unless="include.tests"> + <filename name="**/*Test.java"> + </selector> + </not> + </and> + </selector> + </or> +</fileset> +</pre></blockquote> + + <p>A fileset that conditionally contains Java source files and Test + source and class files.</p> + + <h3><a name="customselect">Custom Selectors</a></h3> + + <p>You can write your own selectors and use them within the selector + containers by specifying them within the <code><custom></code> tag.</p> + + <p>First, you have to write your selector class in Java. The only + requirement it must meet in order to be a selector is that it implements + the <code>org.apache.tools.ant.types.selectors.FileSelector</code> + interface, which contains a single method. See + <a href="selectors-program.html">Programming Selectors in Ant</a> for + more information.</p> + + <p>Once that is written, you include it in your build file by using + the <code><custom></code> tag. + </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">classname</td> + <td valign="top">The name of your class that implements + <code>org.apache.tools.ant.types.selectors.FileSelector</code>. + </td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">classpath</td> + <td valign="top">The classpath to use in order to load the + custom selector class. If neither this classpath nor the + classpathref are specified, the class will be + loaded from the classpath that Ant uses. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">classpathref</td> + <td valign="top">A reference to a classpath previously + defined. If neither this reference nor the + classpath above are specified, the class will be + loaded from the classpath that Ant uses. + </td> + <td valign="top" align="center">No</td> + </tr> + </table> + + <p>Here is how you use <code><custom></code> to + use your class as a selector: + </p> + + <blockquote><pre> +<fileset dir="${mydir}" includes="**/*"> + <custom classname="com.mydomain.MySelector"> + <param name="myattribute" value="myvalue"/> + </custom> +</fileset> +</pre></blockquote> + + <p>A number of core selectors can also be used as custom selectors + by specifying their attributes using <code><param></code> elements. These + are</p> + + <ul> + <li><a href="#containsselect">Contains Selector</a> with + classname <code>org.apache.tools.ant.types.selectors.ContainsSelector</code> + <li><a href="#dateselect">Date Selector</a> with + classname <code>org.apache.tools.ant.types.selectors.DateSelector</code> + <li><a href="#depthselect">Depth Selector</a> with + classname <code>org.apache.tools.ant.types.selectors.DepthSelector</code> + <li><a href="#filenameselect">Filename Selector</a> with + classname <code>org.apache.tools.ant.types.selectors.FilenameSelector</code> + <li><a href="#sizeselect">Size Selector</a> with + classname <code>org.apache.tools.ant.types.selectors.SizeSelector</code> + </ul> + + <p>Here is the example from the Depth Selector section rewritten + to use the selector through <code><custom></code>.</p> + + <blockquote><pre> +<fileset dir="${doc.path}" includes="**/*"> + <custom classname="org.apache.tools.ant.types.selectors.DepthSelector"> + <param name="max" value="1"/> + </custom> +</fileset> +</pre></blockquote> + + <p>Selects all files in the base directory and one directory below + that.</p> + + <p>For more details concerning writing your own selectors, consult + <a href="selectors-program.html">Programming Selectors in Ant</a>.</p> + + + + </body> + +</html> diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/tarfileset.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/tarfileset.html new file mode 100644 index 00000000..499ed798 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/tarfileset.html @@ -0,0 +1,182 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <meta http-equiv="Content-Language" content="en-us"> + <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>TarFileSet Type</title> +</head> +<body> +<h2><a name="fileset">TarFileSet</a></h2> + +<p><em>TarFileSet</em> has been added as a stand-alone type in Apache Ant +1.7.</p> + +<p>A <code><tarfileset></code> is a special form of a <code><<a + href="fileset.html">fileset</a>></code> which can behave in 2 +different ways : <br> +</p> +<ul> + <li>When the <span style="font-style: italic;">src</span> attribute + is used - or a nested resource collection has been specified, the + tarfileset is populated with tar entries found in the file <span + style="font-style: italic;">src</span>.<br> + </li> + <li>When the <span style="font-style: italic;">dir</span> attribute +is used, the tarfileset is populated with filesystem files found under <span + style="font-style: italic;">dir</span>.<br> + </li> +</ul> +<p><code><tarfileset></code> supports all attributes of <code><<a + href="fileset.html">fileset</a>></code> + in addition to those listed below. Note that tar archives in general + don't contain entries with leading slashes so you shouldn't use + include/exclude patterns that start with slashes either. +</p> +<p>A tarfileset can be defined with the <span style="font-style: +italic;">id </span>attribute and referred to with the <span +style="font-style: italic;">refid</span> attribute. This is also true +for tarfileset which has been added in Ant 1.7.<br> +</p> +<h3>Parameters</h3> +<table border="1" cellpadding="2" cellspacing="0"> + <tbody> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td valign="top" align="center"><b>Required</b></td> + </tr> + <tr> + <td valign="top">prefix</td> + <td valign="top">all files in the fileset are prefixed with that +path in the archive.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">fullpath</td> + <td valign="top">the file described by the fileset is placed at +that exact location in the archive.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">src</td> + <td valign="top">may be used in place of the <i>dir</i> attribute + to specify a tar file whose contents will be extracted and included +in the archive.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">filemode</td> + <td valign="top">A 3 digit octal string, specify the user, group +and other modes in the standard Unix fashion. Only applies to +plain files. Default is 644.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">dirmode</td> + <td valign="top">A 3 digit octal string, specify the user, group +and other modes in the standard Unix fashion. Only applies to +directories. Default is 755.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">username</td> + <td valign="top">The username for the tar entry. This is not the same as the UID. + </td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">group</td> + <td valign="top">The groupname for the tar entry. This is not the same as the GID. + </td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">uid</td> + <td valign="top">The user identifier (UID) for the tar entry. This is an integer value + and is not the same as the username. + </td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">gid</td> + <td valign="top">The group identifier (GID) for the tar entry. + </td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">erroronmissingarchive</td> + <td valign="top"> + Specify what happens if the archive does not exist. + If true, a build error will happen; if false, the fileset + will be ignored/empty. + Defaults to true. + <em>Since Ant 1.8.0</em> + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">encoding</td> + <td valign="top">The character encoding to use for filenames + inside the zip file. For a list of possible values see the <a + href="http://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html">Supported Encodings</a>. + Defaults to the platform's default character encoding. + <em>Since Ant 1.9.5</em> + <td align="center" valign="top">No</td> + </tr> + </tbody> +</table> +<p>The <i>fullpath</i> attribute can only be set for filesets that +represent a single file. The <i>prefix</i> and <i>fullpath</i> +attributes cannot both be set on the same fileset.</p> +<p>When using the <i>src</i> attribute, include and exclude patterns +may be used to specify a subset of the archive for inclusion in the +archive as with the <i>dir</i> attribute.</p> + +<p>Please note that currently only the <a +href="../Tasks/tar.html">tar</a> task uses the permission and +ownership attributes.</p> + +<h3>Parameters specified as nested elements</h3> + +<h4>any <a href="resources.html">resource</a> or single element +resource collection</h4> + +<p>The specified resource will be used as src.</p> + +<h4>Examples</h4> +<blockquote> +<pre> + <copy todir="some-dir"> + <tarfileset includes="lib/**"> + <bzip2resource> + <url url="http://example.org/dist/some-archive.tar.bz2"/> + </bzip2resource> + </tarfileset> + </copy> + </pre></blockquote> + +<p>downloads the archive some-archive.tar.bz2, uncompresses and +extracts it on the fly, copies the contents of the lib directory into +some-dir and discards the rest of the archive. File timestamps will +be compared between the archive's entries and files inside the target +directory, no files get overwritten unless they are out-of-date.</p> + + +</body> +</html> diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/xmlcatalog.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/xmlcatalog.html new file mode 100644 index 00000000..a0ddafc0 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/xmlcatalog.html @@ -0,0 +1,306 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>XMLCatalog Type</title> +</head> + +<body> + +<h2><a name="XMLCatalog">XMLCatalog</a></h2> + +<p>An XMLCatalog is a catalog of public resources such as DTDs or +entities that are referenced in an XML document. Catalogs are +typically used to make web references to resources point to a locally +cached copy of the resource.</p> + +<p>This allows the XML Parser, XSLT Processor or other consumer of XML +documents +to efficiently allow a local substitution for a resource available on the +web. +</p> +<p><b>Note:</b> This task <em>uses, but does not depend on</em> external +libraries not included in the Apache Ant distribution. See <a + href="../install.html#librarydependencies">Library Dependencies</a> for more +information.</p> +<p>This data type provides a catalog of resource locations based +on the <a +href="http://oasis-open.org/committees/entity/spec-2001-08-06.html"> +OASIS "Open Catalog" standard</a>. The catalog entries are used +both for Entity resolution and URI resolution, in accordance with +the <code>org.xml.sax.EntityResolver</code> and <code> +javax.xml.transform.URIResolver</code> interfaces as defined +in the <a href="https://jaxp.dev.java.net/">Java API for XML +Processing (JAXP) Specification</a>.</p> +<p>For example, in a <code>web.xml</code> file, the DTD is referenced as: +<pre> +<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" + "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"> +</pre> +The XML processor, without XMLCatalog support, would need to retrieve the +DTD from +the URL specified whenever validation of the document was required. +</p> +<p>This can be very time consuming during the build process, +especially where network throughput is limited. Alternatively, you +can do the following: +<ol> +<li>Copy <code>web-app_2_2.dtd</code> onto your local disk somewhere (either in the +filesystem or even embedded inside a jar or zip file on the classpath).</li> +<li>Create an <code><xmlcatalog></code> with a <code><dtd></code> +element whose <code>location</code> attribute points to the file.</li> +<li>Success! The XML processor will now use the local copy instead of calling out +to the internet.</li> +</ol> +</p> +<p>XMLCatalogs can appear inside tasks +that support this feature or at the same level as <code>target</code> +- i.e., as children of <code>project</code> for reuse across different +tasks, +e.g. XML Validation and XSLT Transformation. The XML Validate task +uses XMLCatalogs for entity resolution. The XSLT Transformation +task uses XMLCatalogs for both entity and URI resolution.</p> +<p>XMLCatalogs are specified as either a reference to another +XMLCatalog, defined previously in a build file, or as a list of +<code>dtd</code> or <code>entity</code> locations. In addition, +external catalog files may be specified in a nested <code>catalogpath</code> , +but they will be ignored unless the resolver library from +xml-commons is available in the system classpath. <b>Due to backwards +incompatible changes in the resolver code after the release of +resolver 1.0, Ant will not support resolver.jar in version 1.0 - we +expect a resolver release 1.1 to happen before Ant 1.6 gets +released.</b> A separate classpath for entity resolution may be +specified inline via nested <code>classpath</code> elements; otherwise +the system classpath is used for this as well.</p> +<p>XMLCatalogs can also be nested inside other XMLCatalogs. For +example, a "superset" XMLCatalog could be made by including several +nested XMLCatalogs that referred to other, previously defined +XMLCatalogs.</p> +<p>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 path. External catalog files may be either <a +href="http://oasis-open.org/committees/entity/background/9401.html"> +plain text format</a> or <a +href="http://www.oasis-open.org/committees/entity/spec-2001-08-06.html"> +XML format</a>. If the xml-commons resolver library is not found in the +classpath, external catalog files, specified in <code>catalogpath</code>, +will be ignored and a warning +will be logged. In this case, however, processing of inline entries will +proceed normally.</p> +<p>Currently, only <code><dtd></code> and +<code><entity></code> elements may be specified inline; these +roughly correspond to OASIS catalog entry types <code>PUBLIC</code> and +<code>URI</code> respectively. By contrast, external catalog files +may use any of the entry types defined in the +<a href="http://oasis-open.org/committees/entity/spec-2001-08-06.html"> ++OASIS specification</a>.</p> +<h3><a name="ResolverAlgorithm">Entity/DTD/URI Resolution Algorithm</a></h3> + +When an entity, DTD, or URI is looked up by the XML processor, the +XMLCatalog searches its list of entries to see if any match. That is, +it attempts to match the <code>publicId</code> attribute of each entry +with the PublicID or URI of the entity to be resolved. Assuming a +matching entry is found, XMLCatalog then executes the following steps: + +<h4>1. Filesystem lookup</h4> + +<p>The <code>location</code> is first looked up in the filesystem. If +the <code>location</code> is a relative path, the ant project basedir +attribute is used as the base directory. If the <code>location</code> +specifies an absolute path, it is used as is. Once we have an +absolute path in hand, we check to see if a valid and readable file +exists at that path. If so, we are done. If not, we proceed to the +next step.</p> + +<h4>2. Classpath lookup</h4> + +<p>The <code>location</code> is next looked up in the classpath. +Recall that jar files are merely fancy zip files. For classpath +lookup, the <code>location</code> is used as is (no base is +prepended). We use a Classloader to attempt to load the resource from +the classpath. For example, if hello.jar is in the classpath and it +contains <code>foo/bar/blat.dtd</code> it will resolve an entity whose +<code>location</code> is <code>foo/bar/blat.dtd</code>. Of course, it +will <em>not</em> resolve an entity whose <code>location</code> is +<code>blat.dtd</code>. + + +<h4>3a. Apache xml-commons resolver lookup</h4> + +<p>What happens next depends on whether the resolver library from +xml-commons is available on the classpath. If so, we defer all +further attempts at resolving to it. The resolver library supports +extremely sophisticated functionality like URL rewriting and so on, +which can be accessed by making the appropriate entries in external +catalog files (XMLCatalog does not yet provide inline support for all +of the entries defined in the <a +href="http://oasis-open.org/committees/entity/spec-2001-08-06.html">OASIS +standard</a>).</p> + +<h4>3. URL-space lookup</h4> + +<p>Finally, we attempt to make a URL out of the <code>location</code>. +At first this may seem like this would defeat the purpose of +XMLCatalogs -- why go back out to the internet? But in fact, this can +be used to (in a sense) implement HTTP redirects, substituting one URL +for another. The mapped-to URL might also be served by a local web +server. If the URL resolves to a valid and readable resource, we are +done. Otherwise, we give up. In this case, the XML processor will +perform its normal resolution algorithm. Depending on the processor +configuration, further resolution failures may or may not result in +fatal (i.e. build-ending) errors.</p> + +<h3>XMLCatalog attributes</h3> +<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">id</td> + <td valign="top">a unique name for an XMLCatalog, used for referencing +the + XMLCatalog's contents from another XMLCatalog</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">refid</td> + <td valign="top">the <code>id</code> of another XMLCatalog whose +contents + you would like to be used for this XMLCatalog</td> + <td valign="top" align="center">No</td> + </tr> +</table> + +<h3>XMLCatalog nested elements</h3> +<h4>dtd/entity</h4> +<p>The <code>dtd</code> and <code>entity</code> elements used to specify +XMLCatalogs are identical in their structure</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">publicId</td> + <td valign="top">The public identifier used when defining a dtd or +entity, + e.g. <code>"-//Sun Microsystems, Inc.//DTD Web Application +2.2//EN"</code> + </td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">location</td> + <td valign="top">The location of the local replacement to be used for +the public identifier specified. This may be specified as a file name, +resource name found on the classpath, or a URL. Relative paths will +be resolved according to the base, which by default is the Ant project +basedir. + </td> + <td valign="top" align="center">Yes</td> + </tr> +</table> +<h4>classpath</h4> +<p>The classpath to use for <a href="#ResolverAlgorithm">entity +resolution</a>. The nested <code><classpath></code> is a +<a href="../using.html#path">path</a>-like structure.</p> +<h4>catalogpath</h4> +<p> +The nested <code>catalogpath</code> element is a <a +href="../using.html#path">path</a>-like structure listing catalog files to +search. All files in this path are assumed to be OASIS catalog files, in +either +<a href="http://oasis-open.org/committees/entity/background/9401.html"> +plain text format</a> or <a +href="http://www.oasis-open.org/committees/entity/spec-2001-08-06.html"> +XML format</a>. Entries specifying nonexistent files will be ignored. If the +resolver library from xml-commons is not available in the classpath, all +<code>catalogpaths</code> will be ignored and a warning will be logged. +</p> +<h3>Examples</h3> +<p>Set up an XMLCatalog with a single dtd referenced locally in a user's +home +directory:</p> +<blockquote><pre> + <xmlcatalog> + <dtd + publicId="-//OASIS//DTD DocBook XML V4.1.2//EN" + location="/home/dion/downloads/docbook/docbookx.dtd"/> + </xmlcatalog> +</pre></blockquote> +<p>Set up an XMLCatalog with a multiple dtds to be found either in the +filesystem (relative to the Ant project basedir) or in the classpath: +</p> +<blockquote><pre> + <xmlcatalog id="commonDTDs"> + <dtd + publicId="-//OASIS//DTD DocBook XML V4.1.2//EN" + location="docbook/docbookx.dtd"/> + <dtd + publicId="-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" + location="web-app_2_2.dtd"/> + </xmlcatalog> +</pre></blockquote> + +<p>Set up an XMLCatalog with a combination of DTDs and entities as +well as a nested XMLCatalog and external catalog files in both +formats:</p> + +<blockquote><pre> + <xmlcatalog id="allcatalogs"> + <dtd + publicId="-//ArielPartners//DTD XML Article V1.0//EN" + location="com/arielpartners/knowledgebase/dtd/article.dtd"/> + <entity + publicId="LargeLogo" + location="com/arielpartners/images/ariel-logo-large.gif"/> + <xmlcatalog refid="commonDTDs"/> + <catalogpath> + <pathelement location="/etc/sgml/catalog"/> + <fileset + dir="/anetwork/drive" + includes="**/catalog"/> + <fileset + dir="/my/catalogs" + includes="**/catalog.xml"/> + </catalogpath> + </xmlcatalog> + </xmlcatalog> +</pre></blockquote> +<p>To reference the above XMLCatalog in an <code>xslt</code> task:<p> +<blockquote><pre> + <xslt basedir="${source.doc}" + destdir="${dest.xdocs}" + extension=".xml" + style="${source.xsl.converter.docbook}" + includes="**/*.xml" + force="true"> + <xmlcatalog refid="allcatalogs"/> + </xslt> +</pre></blockquote> + + + +</body> +</html> diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Types/zipfileset.html b/framework/src/ant/apache-ant-1.9.6/manual/Types/zipfileset.html new file mode 100644 index 00000000..955e2718 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Types/zipfileset.html @@ -0,0 +1,148 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <meta http-equiv="Content-Language" content="en-us"> + <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> +<title>ZipFileSet Type</title> +</head> +<body> +<h2><a name="fileset">ZipFileSet</a></h2> + +<p>A <code><zipfileset></code> is a special form of a <code><<a + href="fileset.html">fileset</a>></code> which can behave in 2 +different ways : <br> +</p> +<ul> + <li>When the <span style="font-style: italic;">src</span> attribute + is used - or a nested resource collection has been specified + (<em>since Apache Ant 1.7</em>), the zipfileset is populated with + zip entries found in the file <span style="font-style: + italic;">src</span>.<br> + </li> + <li>When the <span style="font-style: italic;">dir</span> attribute +is used, the zipfileset is populated with filesystem files found under <span + style="font-style: italic;">dir</span>.<br> + </li> +</ul> +<p><code><zipfileset></code> supports all attributes of <code><<a + href="fileset.html">fileset</a>></code> + in addition to those listed below. Note that zip archives in general + don't contain entries with leading slashes so you shouldn't use + include/exclude patterns that start with slashes either.</p> + +<p>Since Ant 1.6, a zipfileset can be defined with the <span + style="font-style: italic;">id </span>attribute and referred to with +the <span style="font-style: italic;">refid</span> attribute.<br> +</p> +<h3>Parameters</h3> +<table border="1" cellpadding="2" cellspacing="0"> + <tbody> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td valign="top" align="center"><b>Required</b></td> + </tr> + <tr> + <td valign="top">prefix</td> + <td valign="top">all files in the fileset are prefixed with that +path in the archive.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">fullpath</td> + <td valign="top">the file described by the fileset is placed at +that exact location in the archive.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">src</td> + <td valign="top">may be used in place of the <i>dir</i> attribute + to specify a zip file whose contents will be extracted and included +in the archive.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">filemode</td> + <td valign="top">A 3 digit octal string, specify the user, group +and other modes in the standard Unix fashion. Only applies to +plain files. Default is 644. <em>since Ant 1.5.2</em>.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">dirmode</td> + <td valign="top">A 3 digit octal string, specify the user, group +and other modes in the standard Unix fashion. Only applies to +directories. Default is 755. <em>since Ant 1.5.2</em>.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">encoding</td> + <td valign="top">The character encoding to use for filenames + inside the zip file. For a list of possible values see the <a + href="http://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html">Supported Encodings</a>. + Defaults to the platform's default character encoding. + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">erroronmissingarchive</td> + <td valign="top"> + Specify what happens if the archive does not exist. + If true, a build error will happen; if false, the fileset + will be ignored/empty. + Defaults to true. + <em>Since Ant 1.8.0</em> + </td> + <td valign="top" align="center">No</td> + </tr> + </tbody> +</table> +<p>The <i>fullpath</i> attribute can only be set for filesets that +represent a single file. The <i>prefix</i> and <i>fullpath</i> +attributes cannot both be set on the same fileset.</p> +<p>When using the <i>src</i> attribute, include and exclude patterns +may be used to specify a subset of the archive for inclusion in the +archive as with the <i>dir</i> attribute.</p> + +<p>Please note that currently only the <a +href="../Tasks/tar.html">tar</a> and <a +href="../Tasks/zip.html">zip</a> tasks use the permission.</p> + +<h3>Parameters specified as nested elements</h3> + +<h4>any file system based <a href="resources.html">resource</a> or +single element resource collection</h4> + +<p>The specified resource will be used as src.</p> + +<h4>Examples</h4> +<blockquote> + <pre> <zip destfile="${dist}/manual.zip"><br> <zipfileset dir="htdocs/manual" prefix="docs/user-guide"/><br> <zipfileset dir="." includes="ChangeLog27.txt" fullpath="docs/ChangeLog.txt"/><br> <zipfileset src="examples.zip" includes="**/*.html" prefix="docs/examples"/><br> </zip><br></pre> + <p>zips all files in the <code>htdocs/manual</code> directory into +the <code>docs/user-guide</code> directory in the archive, adds the +file <code>ChangeLog27.txt</code> in the current directory as <code>docs/ChangeLog.txt</code>, +and includes all the html files in <code>examples.zip</code> under <code>docs/examples</code>. +The archive might end up containing the files:</p> + <code> docs/user-guide/html/index.html<br> +docs/ChangeLog.txt<br> +docs/examples/index.html<br> + </code></blockquote> + + +</body> +</html> |