You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ant.apache.org by gi...@apache.org on 2018/03/03 20:27:06 UTC
ant git commit: Style corrections, in particular regarding footnotes
Repository: ant
Updated Branches:
refs/heads/master 0cd8f773d -> 63d1abc7c
Style corrections, in particular regarding footnotes
Project: http://git-wip-us.apache.org/repos/asf/ant/repo
Commit: http://git-wip-us.apache.org/repos/asf/ant/commit/63d1abc7
Tree: http://git-wip-us.apache.org/repos/asf/ant/tree/63d1abc7
Diff: http://git-wip-us.apache.org/repos/asf/ant/diff/63d1abc7
Branch: refs/heads/master
Commit: 63d1abc7c081429ad0083ae30d418f44977accf1
Parents: 0cd8f77
Author: Gintas Grigelionis <gi...@apache.org>
Authored: Sat Mar 3 21:26:50 2018 +0100
Committer: Gintas Grigelionis <gi...@apache.org>
Committed: Sat Mar 3 21:26:50 2018 +0100
----------------------------------------------------------------------
manual/Tasks/copy.html | 2 +-
manual/Tasks/filter.html | 19 +-
manual/Tasks/java.html | 4 +-
manual/Tasks/jjtree.html | 18 +-
manual/Tasks/rmic.html | 4 +-
manual/Types/resources.html | 10 +-
manual/develop.html | 501 +++++++++++++++++----------------------
7 files changed, 241 insertions(+), 317 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/ant/blob/63d1abc7/manual/Tasks/copy.html
----------------------------------------------------------------------
diff --git a/manual/Tasks/copy.html b/manual/Tasks/copy.html
index 69219f3..9c2cc90 100644
--- a/manual/Tasks/copy.html
+++ b/manual/Tasks/copy.html
@@ -72,7 +72,7 @@ note</a></em>.</p>
</tr>
<tr>
<td>todir</td>
- <td>The directory to copy to.</td>
+ <td class="left">The directory to copy to.</td>
</tr>
<tr>
<td>overwrite</td>
http://git-wip-us.apache.org/repos/asf/ant/blob/63d1abc7/manual/Tasks/filter.html
----------------------------------------------------------------------
diff --git a/manual/Tasks/filter.html b/manual/Tasks/filter.html
index 09c263b..3525756 100644
--- a/manual/Tasks/filter.html
+++ b/manual/Tasks/filter.html
@@ -30,9 +30,8 @@
these as filters. Token filters are used by all tasks that perform file copying operations through
the Project commodity methods. See the warning <a href="../using.html#filters"><em>here</em></a>
before using.</p>
-<p>Note 1: the token string must not contain the separators chars (<q>@</q>).<br/>Note 2:
-Either <var>token</var> and <var>value</var> attributes must be provided, or only
-the <var>filtersfile</var> attribute.</p>
+<p>The task uses <q>@</q> as token separator. Token strings cannot contain separator characters;
+incorrect tokens are ignored.</p>
<h3>Parameters</h3>
<table class="attr">
@@ -43,22 +42,20 @@ the <var>filtersfile</var> attribute.</p>
</tr>
<tr>
<td>token</td>
- <td>the token string without <q>@</q></td>
- <td>Yes<sup>*</sup></td>
+ <td>the token string without the separator chars (<q>@</q>)</td>
+ <td rowspan="3">Yes; either both <var>token</var> and <var>value</var>, or
+ only <var>filtersfile</var></td>
</tr>
<tr>
<td>value</td>
- <td>the string that should be put to replace the token when the file is copied</td>
- <td>Yes<sup>*</sup></td>
+ <td class="left">the string that should be put to replace the token when the file is copied</td>
</tr>
<tr>
<td>filtersfile</td>
- <td>The file from which the filters must be read. This file must be a formatted as a property
- file.</td>
- <td>Yes<sup>*</sup></td>
+ <td class="left">The file from which the filters must be read. This file must be a formatted as
+ a property file.</td>
</tr>
</table>
-<p>* see Note 1 and 2 above parameters table.</p>
<h3>Examples</h3>
<pre>
<filter token="year" value="2000"/>
http://git-wip-us.apache.org/repos/asf/ant/blob/63d1abc7/manual/Tasks/java.html
----------------------------------------------------------------------
diff --git a/manual/Tasks/java.html b/manual/Tasks/java.html
index 3883b6d..01b3759 100644
--- a/manual/Tasks/java.html
+++ b/manual/Tasks/java.html
@@ -56,7 +56,7 @@ because it tries to read from the standard input.</p>
<td>jar</td>
<td class="left">the location of the jar file to execute (must have a <code>Main-Class</code>
entry in the manifest). <var>fork</var> must be set to <q>true</q> if this option is selected.
- See notes below for more details.
+ See notes <a href="#jar-execute">below</a> for more details.
</td>
</tr>
<tr>
@@ -302,7 +302,7 @@ structure</a> and can also be set via a nested <code>modulepath</code> element.<
<p>The location of modules that replace upgradeable modules in the runtime image can be specified
using this <a href="../using.html#path">path-like structure</a>.</p>
-<h3>JAR file execution</h3>
+<h3 id="jar-execute">JAR file execution</h3>
<p>The parameter of the <var>jar</var> attribute is of type <code>File</code>; that is, the
parameter is resolved to an absolute file relative to the base directory of the
http://git-wip-us.apache.org/repos/asf/ant/blob/63d1abc7/manual/Tasks/jjtree.html
----------------------------------------------------------------------
diff --git a/manual/Tasks/jjtree.html b/manual/Tasks/jjtree.html
index 0757856..0c6fc93 100644
--- a/manual/Tasks/jjtree.html
+++ b/manual/Tasks/jjtree.html
@@ -418,13 +418,13 @@ versions</h3>
<td>Not Supported</td>
<td>Same</td>
</tr>
-<tr>
+<tr id="footnote-1-back">
<td><pre><b>jjtree -OUTPUT_FILE:<i>D:</i>/tmp/subdir/output.jj grammar.jjt</b>
/tmp/subdir/output.jj
/tmp/<generated>.java</pre>
</td>
<td>Not Supported</td>
- <td>Not Supported *)</td>
+ <td>Not Supported<a href="#footnote-1"><sup>*</sup></a></td>
</tr>
<tr>
<td><pre><b>jjtree -OUTPUT_FILE:<i>D:</i>/tmp/subdir/output.jj relative/grammar.jjt</b>
@@ -432,7 +432,7 @@ versions</h3>
/tmp/<generated>.java</pre>
</td>
<td>Not Supported</td>
- <td>Not Supported *)</td>
+ <td>Not Supported<a href="#footnote-1"><sup>*</sup></a></td>
</tr>
<tr>
<td><pre><b>jjtree -OUTPUT_FILE:<i>D:</i>/tmp/subdir/output.jj /tmp/absolute/grammar.jjt</b>
@@ -440,7 +440,7 @@ versions</h3>
/tmp/<generated>.java</pre>
</td>
<td>Not Supported</td>
- <td>Not Supported *)</td>
+ <td>Not Supported<a href="#footnote-1"><sup>*</sup></a></td>
</tr>
<tr>
<td><pre><b>jjtree -OUTPUT_FILE:/tmp/subdir/output.jj -OUTPUT_DIRECTORY:relative grammar.jjt</b>
@@ -493,11 +493,11 @@ versions</h3>
</tbody>
</table>
-<p>*) <strong>Footnote</strong>: When running JJTree with the Ant <code>taskdef jjtree</code> the
-option <code>-OUTPUT_DIRECTORY</code> must always be set, because the project's <var>basedir</var>
-and the Ant working directory might differ. So even if you don't specify
-the <var>outputdirectory</var> for <code>taskdef jjtree</code>, JJTree will be called with
-the <code>-OUTPUT_DIRECTORY</code> set to the project's <var>basedir</var>. But when
+<p id="footnote-1"><a href="#footnote-1-back"><strong>Note</strong></a>: When running JJTree with
+the Ant <code>taskdef jjtree</code> the option <code>-OUTPUT_DIRECTORY</code> must always be set,
+because the project's <var>basedir</var> and the Ant working directory might differ. So even if you
+don't specify the <var>outputdirectory</var> for <code>taskdef jjtree</code>, JJTree will be called
+with the <code>-OUTPUT_DIRECTORY</code> set to the project's <var>basedir</var>. But when
the <code>-OUTPUT_DIRECTORY</code> is set, the <code>-OUTPUT_FILE</code> setting is handled as if
relative to this <code>-OUTPUT_DIRECTORY</code>. Thus when the <code>-OUTPUT_FILE</code> is absolute
or contains a drive letter we have a problem. Therefore absolute <var>outputfile</var>s (when
http://git-wip-us.apache.org/repos/asf/ant/blob/63d1abc7/manual/Tasks/rmic.html
----------------------------------------------------------------------
diff --git a/manual/Tasks/rmic.html b/manual/Tasks/rmic.html
index 5af1a7e..86992f4 100644
--- a/manual/Tasks/rmic.html
+++ b/manual/Tasks/rmic.html
@@ -77,7 +77,7 @@ documentation to learn how to use it.</p>
<th>Description</th>
<th>Required</th>
</tr>
- <tr id="1">
+ <tr id="footnote-1-back">
<td>base</td>
<td>the location to store the compiled files. Also serves as the parent directory for any
non-Fileset includes, etc. (This functionality has remained unchanged.)</td>
@@ -214,7 +214,7 @@ documentation to learn how to use it.</p>
</tr>
</table>
-<p id="footnote-1"><a href="#1">Note</a>:</p>
+<p id="footnote-1"><a href="#footnote-1-back">Note</a>:</p>
<ul>
<li>Maintaining compatibility, <var>base</var>, when specified by itself, serves as both the
parent directory for any source files AND the output directory.</li>
http://git-wip-us.apache.org/repos/asf/ant/blob/63d1abc7/manual/Types/resources.html
----------------------------------------------------------------------
diff --git a/manual/Types/resources.html b/manual/Types/resources.html
index f27524d..f8dfda8 100644
--- a/manual/Types/resources.html
+++ b/manual/Types/resources.html
@@ -503,17 +503,17 @@ selection.
<td>Whether patterns are case-sensitive</td>
<td>No; default <q>true</q></td>
</tr>
- <tr>
+ <tr id="followsymlinks">
<td>followsymlinks</td>
<td>Whether to follow symbolic links (see note <a href="#symlink">below</a>)</td>
<td>No; default <q>true</q></td>
</tr>
</table>
-<p id="symlink"><strong>Note</strong>: 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>
+<p id="symlink"><a href="#followsymlinks"><strong>Note</strong></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 id="restrict">restrict</h4>
<p>Restricts a nested resource collection using resource selectors:</p>
http://git-wip-us.apache.org/repos/asf/ant/blob/63d1abc7/manual/develop.html
----------------------------------------------------------------------
diff --git a/manual/develop.html b/manual/develop.html
index 01f3d7f..424e54c 100644
--- a/manual/develop.html
+++ b/manual/develop.html
@@ -29,207 +29,164 @@
<p>It is very easy to write your own task:</p>
<ol>
<li>Create a Java class that extends <code>org.apache.tools.ant.Task</code>
- or <a href="base_task_classes.html">another class</a> that was designed to be extended.</li>
-
- <li id="footnote-1-back">For each attribute, write a <em>setter</em> method. The setter method must be a
- <code>public void</code> method that takes a single argument. The
- name of the method must begin with <code>set</code>, followed by the
- attribute name, with the first character of the name in uppercase, and the rest in
- lowercase<a href="#footnote-1"><sup>*</sup></a>. That is, to support an attribute named
- <code>file</code> you create a method <code>setFile</code>.
- Depending on the type of the argument, Ant will perform some
- conversions for you, see <a href="#set-magic">below</a>.</li>
-
- <li>If your task shall contain other tasks as nested elements (like
- <a href="Tasks/parallel.html"><code>parallel</code></a>), your
- class must implement the interface
- <code>org.apache.tools.ant.TaskContainer</code>. If you do so, your
- task can not support any other nested elements. See
- <a href="#taskcontainer">below</a>.</li>
-
- <li>If the task should support character data (text nested between the
- start and end tags), write a <code>public void addText(String)</code>
- method. Note that Ant does <strong>not</strong> expand properties on
- the text it passes to the task.</li>
-
- <li>For each nested element, write a <em>create</em>, <em>add</em> or
- <em>addConfigured</em> method. A create method must be a
- <code>public</code> method that takes no arguments and returns an
- <code>Object</code> type. The name of the create method must begin
- with <code>create</code>, followed by the element name. An add (or
- addConfigured) method must be a <code>public void</code> method that
- takes a single argument of an <code>Object</code> type with a
- no-argument constructor. The name of the add (addConfigured) method
- must begin with <code>add</code> (<code>addConfigured</code>),
- followed by the element name. For a more complete discussion see
- <a href="#nested-elements">below</a>.</li>
-
- <li>Write a <code>public void execute</code> method, with no arguments, that
- throws a <code>BuildException</code>. This method implements the task
- itself.</li>
+ or <a href="base_task_classes.html">another class</a> that was designed to be extended.</li>
+
+ <li id="footnote-1-back">For each attribute, write a <em>setter</em> method. The setter method
+ must be a <code>public void</code> method that takes a single argument. The name of the method
+ must begin with <code>set</code>, followed by the attribute name, with the first character of
+ the name in uppercase, and the rest in lowercase<a href="#footnote-1"><sup>*</sup></a>. That
+ is, to support an attribute named <code>file</code> you create a method <code>setFile</code>.
+ Depending on the type of the argument, Ant will perform some conversions for you,
+ see <a href="#set-magic">below</a>.</li>
+
+ <li>If your task shall contain other tasks as nested elements
+ (like <a href="Tasks/parallel.html"><code>parallel</code></a>), your class must implement the
+ interface <code>org.apache.tools.ant.TaskContainer</code>. If you do so, your task can not
+ support any other nested elements. See <a href="#taskcontainer">below</a>.</li>
+
+ <li>If the task should support character data (text nested between the start and end tags), write
+ a <code>public void addText(String)</code> method. Note that Ant does <strong>not</strong>
+ expand properties on the text it passes to the task.</li>
+
+ <li>For each nested element, write a <em>create</em>, <em>add</em> or <em>addConfigured</em>
+ method. A create method must be a <code>public</code> method that takes no arguments and returns
+ an <code>Object</code> type. The name of the create method must begin with <code>create</code>,
+ followed by the element name. An add (or addConfigured) method must be a <code>public void</code>
+ method that takes a single argument of an <code>Object</code> type with a no-argument constructor.
+ The name of the add (addConfigured) method must begin with <code>add</code>
+ (<code>addConfigured</code>), followed by the element name. For a more complete discussion
+ see <a href="#nested-elements">below</a>.</li>
+
+ <li>Write a <code>public void execute</code> method, with no arguments, that throws
+ a <code>BuildException</code>. This method implements the task itself.</li>
</ol>
<hr>
-<p id="footnote-1"><a href="#footnote-1-back">*</a> Actually the case of the letters after
-the first one doesn't really matter to Ant, using all lower case is a
-good convention, though.</p>
+<p id="footnote-1"><a href="#footnote-1-back">*</a> Actually the case of the letters after the first
+one doesn't really matter to Ant, using all lower case is a good convention, though.</p>
<h3>The Life-cycle of a Task</h3>
<ol>
- <li>
- The xml element that contains the tag corresponding to the
- task gets converted to an <code>UnknownElement</code> at parse time.
- This <code>UnknownElement</code> gets placed in a list within a target
- object, or recursively within another <code>UnknownElement</code>.
+ <li>The xml element that contains the tag corresponding to the task gets converted to
+ an <code>UnknownElement</code> at parse time. This <code>UnknownElement</code> gets placed in a
+ list within a target object, or recursively within another <code>UnknownElement</code>.
</li>
- <li>
- When the target is executed, each <code>UnknownElement</code> is invoked
- using an <code>perform()</code> method. This instantiates
- the task. This means that tasks only gets
+
+ <li>When the target is executed, each <code>UnknownElement</code> is invoked using
+ an <code>perform()</code> method. This instantiates the task. This means that tasks only gets
instantiated at run time.
</li>
- <li>The task gets references to its project and location inside the
- buildfile via its inherited <code>project</code> and
- <code>location</code> variables.</li>
+ <li>The task gets references to its project and location inside the buildfile via its
+ inherited <code>project</code> and <code>location</code> variables.</li>
- <li>If the user specified an <var>id</var> attribute to this task,
- the project registers a reference to this newly created task, at run
- time.</li>
+ <li>If the user specified an <var>id</var> attribute to this task, the project registers a
+ reference to this newly created task, at run time.</li>
- <li>The task gets a reference to the target it belongs to via its
- inherited <code>target</code> variable.</li>
+ <li>The task gets a reference to the target it belongs to via its inherited <code>target</code>
+ variable.</li>
<li><code>init()</code> is called at run time.</li>
- <li>All child elements of the XML element corresponding to this task
- are created via this task's <code>createXXX()</code> methods or
- instantiated and added to this task via its <code>addXXX()</code>
- methods, at run time. Child elements corresponding
- to <code>addConfiguredXXX()</code> are created at this point but
- the actual <code>addConfigured</code> method is not called.</li>
+ <li>All child elements of the XML element corresponding to this task are created via this
+ task's <code>createXXX()</code> methods or instantiated and added to this task via
+ its <code>addXXX()</code> methods, at run time. Child elements corresponding
+ to <code>addConfiguredXXX()</code> are created at this point but the
+ actual <code>addConfigured</code> method is not called.</li>
- <li>All attributes of this task get set via their corresponding
- <code>setXXX</code> methods, at runtime.</li>
+ <li>All attributes of this task get set via their corresponding <code>setXXX</code> methods, at
+ runtime.</li>
- <li>The content character data sections inside the XML element
- corresponding to this task is added to the task via its
- <code>addText</code> method, at runtime.</li>
+ <li>The content character data sections inside the XML element corresponding to this task is added
+ to the task via its <code>addText</code> method, at runtime.</li>
- <li>All attributes of all child elements get set via their corresponding
- <code>setXXX</code> methods, at runtime.</li>
+ <li>All attributes of all child elements get set via their corresponding <code>setXXX</code>
+ methods, at runtime.</li>
- <li>If child elements of the XML element corresponding to this task
- have been created for <code>addConfiguredXXX()</code> methods,
- those methods get invoked now.</li>
+ <li>If child elements of the XML element corresponding to this task have been created
+ for <code>addConfiguredXXX()</code> methods, those methods get invoked now.</li>
- <li id="execute"><code>execute()</code> is called at runtime.
- If <code>target1</code> and <code>target2</code> both depend
- on <code>target3</code>, then running
- <code>'ant target1 target2'</code> will run all tasks in
- <code>target3</code> twice.</li>
+ <li id="execute"><code>execute()</code> is called at runtime. If <q>target1</q>
+ and <q>target2</q> both depend on <q>target3</q>, then running <code>'ant target1
+ target2'</code> will run all tasks in <q>target3</code> twice.</li>
</ol>
<h3 id="set-magic">Conversions Ant will perform for attributes</h3>
-<p>Ant will always expand properties before it passes the value of an
-attribute to the corresponding setter method. <em>Since Ant 1.8</em>, it is
-possible to <a href="Tasks/propertyhelper.html">extend Ant's property handling</a>
-such that a non-string Object may be the result of the evaluation of a string
-containing a single property reference. These will be assigned directly via
-setter methods of matching type. Since it requires some beyond-the-basics
-intervention to enable this behavior, it may be a good idea to flag attributes
-intended to permit this usage paradigm.
-</p>
-
-<p>The most common way to write an attribute setter is to use a
-<code>java.lang.String</code> argument. In this case Ant will pass
-the literal value (after property expansion) to your task. But there
-is more! If the argument of you setter method is</p>
-
-<ul>
-
- <li><code>boolean</code>, your method will be passed the value
- <code>true</code> if the value specified in the build file is one of
- <code>true</code>, <code>yes</code>, or <code>on</code> and
- <code>false</code> otherwise.</li>
-
- <li><code>char</code> or <code>java.lang.Character</code>, your
- method will be passed the first character of the value specified in
- the build file.</li>
-
- <li>any other primitive type (<code>int</code>, <code>short</code>
- and so on), Ant will convert the value of the attribute into this
- type, thus making sure that you'll never receive input that is not a
- number for that attribute.</li>
-
- <li><code>java.io.File</code>, Ant will first determine whether the
- value given in the build file represents an absolute path name. If
- not, Ant will interpret the value as a path name relative to the
- project's basedir.</li>
-
- <li><code>org.apache.tools.ant.types.Resource</code>, Ant will
- resolve the string as a <code>java.io.File</code> as above, then
- pass in as a <code>org.apache.tools.ant.types.resources.FileResource</code>.
- <em>Since Ant 1.8</em>
- </li>
+<p>Ant will always expand properties before it passes the value of an attribute to the corresponding
+setter method. <em>Since Ant 1.8</em>, it is possible to <a href="Tasks/propertyhelper.html">extend
+Ant's property handling</a> such that a non-string Object may be the result of the evaluation of a
+string containing a single property reference. These will be assigned directly via setter methods of
+matching type. Since it requires some beyond-the-basics intervention to enable this behavior, it may
+be a good idea to flag attributes intended to permit this usage paradigm.</p>
- <li><code>org.apache.tools.ant.types.Path</code>, Ant will tokenize
- the value specified in the build file, accepting <q>:</q> and
- <q>;</q> as path separators. Relative path names will be
- interpreted as relative to the project's <var>basedir</var>.</li>
-
- <li><code>java.lang.Class</code>, Ant will interpret the value
- given in the build file as a Java class name and load the named
- class from the system class loader.</li>
-
- <li>any other type that has a constructor with a single
- <code>String</code> argument, Ant will use this constructor to
- create a new instance from the value given in the build file.</li>
-
- <li>A subclass of
- <code>org.apache.tools.ant.types.EnumeratedAttribute</code>, Ant
- will invoke this classes <code>setValue</code> method. Use this if
- your task should support enumerated attributes (attributes with
- values that must be part of a predefined set of values). See
- <code>org/apache/tools/ant/taskdefs/FixCRLF.java</code> and the
- inner <code>AddAsisRemove</code> class used in <code>setCr</code>
- for an example.</li>
-
- <li>A (Java 5) enumeration, Ant will call the setter with the enum constant
- matching the value given in the build file. This is easier than using
- <code>EnumeratedAttribute</code> and can result in cleaner code, but of course
- your task will not run on JDK 1.4 or earlier. Note that any override of
- <code>toString()</code> in the enumeration is ignored; the build file must use
- the declared name (see <code>Enum.getName()</code>). You may wish to use lowercase
- enum constant names, in contrast to usual Java style, to look better in build files.
- <em>Since Ant 1.7.0</em></li>
+<p>The most common way to write an attribute setter is to use a <code>java.lang.String</code>
+argument. In this case Ant will pass the literal value (after property expansion) to your task.
+But there is more! If the argument of you setter method is</p>
+<ul>
+ <li><code>boolean</code>, your method will be passed the value <code>true</code> if the value
+ specified in the build file is one of <code>true</code>, <code>yes</code>, or <code>on</code>
+ and <code>false</code> otherwise.</li>
+
+ <li><code>char</code> or <code>java.lang.Character</code>, your method will be passed the first
+ character of the value specified in the build file.</li>
+
+ <li>any other primitive type (<code>int</code>, <code>short</code> and so on), Ant will convert
+ the value of the attribute into this type, thus making sure that you'll never receive input that
+ is not a number for that attribute.</li>
+
+ <li><code>java.io.File</code>, Ant will first determine whether the value given in the build file
+ represents an absolute path name. If not, Ant will interpret the value as a path name relative
+ to the project's basedir.</li>
+
+ <li><code>org.apache.tools.ant.types.Resource</code>, Ant will resolve the string as
+ a <code>java.io.File</code> as above, then pass in as
+ a <code>org.apache.tools.ant.types.resources.FileResource</code>. <em>Since Ant 1.8</em></li>
+
+ <li><code>org.apache.tools.ant.types.Path</code>, Ant will tokenize the value specified in the
+ build file, accepting <q>:</q> and <q>;</q> as path separators. Relative path names will be
+ interpreted as relative to the project's <var>basedir</var>.</li>
+
+ <li><code>java.lang.Class</code>, Ant will interpret the value given in the build file as a Java
+ class name and load the named class from the system class loader.</li>
+
+ <li>any other type that has a constructor with a single <code>String</code> argument, Ant will use
+ this constructor to create a new instance from the value given in the build file.</li>
+
+ <li>A subclass of <code>org.apache.tools.ant.types.EnumeratedAttribute</code>, Ant will invoke
+ this classes <code>setValue</code> method. Use this if your task should support enumerated
+ attributes (attributes with values that must be part of a predefined set of values).
+ See <code>org/apache/tools/ant/taskdefs/FixCRLF.java</code> and the
+ inner <code>AddAsisRemove</code> class used in <code>setCr</code> for an example.</li>
+
+ <li>A (Java 5) enumeration, Ant will call the setter with the enum constant matching the value
+ given in the build file. This is easier than using <code>EnumeratedAttribute</code> and can
+ result in cleaner code, but of course your task will not run on JDK 1.4 or earlier. Note that
+ any override of <code>toString()</code> in the enumeration is ignored; the build file must use
+ the declared name (see <code>Enum.getName()</code>). You may wish to use lowercase enum constant
+ names, in contrast to usual Java style, to look better in build files. <em>Since Ant
+ 1.7.0</em></li>
</ul>
-<p>What happens if more than one setter method is present for a given
-attribute? A method taking a <code>String</code> argument will always
-lose against the more specific methods. If there are still more
-setters Ant could chose from, only one of them will be called, but we
-don't know which, this depends on the implementation of your Java
-virtual machine.</p>
+<p>What happens if more than one setter method is present for a given attribute? A method taking
+a <code>String</code> argument will always lose against the more specific methods. If there are
+still more setters Ant could chose from, only one of them will be called, but we don't know which,
+this depends on the implementation of your Java virtual machine.</p>
<h3 id="nested-elements">Supporting nested elements</h3>
-<p>Let's assume your task shall support nested elements with the name
-<code>inner</code>. First of all, you need a class that represents
-this nested element. Often you simply want to use one of Ant's
-classes like <code>org.apache.tools.ant.types.FileSet</code> to
-support nested <code>fileset</code> elements.</p>
+<p>Let's assume your task shall support nested elements with the name <code>inner</code>. First of
+all, you need a class that represents this nested element. Often you simply want to use one of
+Ant's classes like <code>org.apache.tools.ant.types.FileSet</code> to support
+nested <code>fileset</code> elements.</p>
-<p>Attributes of the nested elements or nested child elements of them
-will be handled using the same mechanism used for tasks (i.e. setter
-methods for attributes, addText for nested text and
+<p>Attributes of the nested elements or nested child elements of them will be handled using the same
+mechanism used for tasks (i.e. setter methods for attributes, addText for nested text and
create/add/addConfigured methods for child elements).</p>
-<p>Now you have a class <code>NestedElement</code> that is supposed to
-be used for your nested <code><inner></code> elements, you have
-three options:</p>
+<p>Now you have a class <code>NestedElement</code> that is supposed to be used for your
+nested <code><inner></code> elements, you have three options:</p>
<ol>
<li><code>public NestedElement createInner()</code></li>
@@ -239,41 +196,32 @@ three options:</p>
<p>What is the difference?</p>
-<p>Option 1 makes the task create the instance of
-<code>NestedElement</code>, there are no restrictions on the type.
-For the options 2 and 3, Ant has to create an instance of
-<code>NestedInner</code> before it can pass it to the task, this
-means, <code>NestedInner</code> must have a <code>public</code> no-arg
- constructor or a <code>public</code> one-arg constructor
- taking a <code>Project</code> class as a parameter.
-This is the only difference between options 1 and 2.</p>
-
-<p>The difference between 2 and 3 is what Ant has done to the object
-before it passes it to the method. <code>addInner</code> will receive
-an object directly after the constructor has been called, while
-<code>addConfiguredInner</code> gets the object <em>after</em> the
-attributes and nested children for this new object have been
-handled.</p>
-
-<p>What happens if you use more than one of the options? Only one of
-the methods will be called, but we don't know which, this depends on
-the implementation of your JVM.</p>
+<p>Option 1 makes the task create the instance of <code>NestedElement</code>, there are no
+restrictions on the type. For the options 2 and 3, Ant has to create an instance
+of <code>NestedInner</code> before it can pass it to the task, this means, <code>NestedInner</code>
+must have a <code>public</code> no-arg constructor or a <code>public</code> one-arg constructor
+taking a <code>Project</code> class as a parameter. This is the only difference between options 1
+and 2.</p>
+
+<p>The difference between 2 and 3 is what Ant has done to the object before it passes it to the
+method. <code>addInner</code> will receive an object directly after the constructor has been
+called, while <code>addConfiguredInner</code> gets the object <em>after</em> the attributes and
+nested children for this new object have been handled.</p>
+
+<p>What happens if you use more than one of the options? Only one of the methods will be called,
+but we don't know which, this depends on the implementation of your JVM.</p>
<h3 id="nestedtype">Nested Types</h3>
-If your task needs to nest an arbitrary type that has been defined
-using <code><typedef></code> you have two options.
- <ol>
- <li><code>public void add(Type type)</code></li>
- <li><code>public void addConfigured(Type type)</code></li>
- </ol>
- The difference between 1 and 2 is the same as between 2 and 3 in the
- previous section.
- <p>
- For example suppose one wanted to handle objects object of type
- <code>org.apache.tools.ant.taskdefs.condition.Condition</code>, one may
- have a class:
- </p>
- <pre>
+<p>If your task needs to nest an arbitrary type that has been defined
+using <code><typedef></code> you have two options.</p>
+<ol>
+ <li><code>public void add(Type type)</code></li>
+ <li><code>public void addConfigured(Type type)</code></li>
+</ol>
+<p>The difference between 1 and 2 is the same as between 2 and 3 in the previous section.</p>
+<p>For example suppose one wanted to handle objects object of
+type <code>org.apache.tools.ant.taskdefs.condition.Condition</code>, one may have a class:</p>
+<pre>
public class MyTask extends Task {
private List conditions = new ArrayList();
public void add(Condition c) {
@@ -283,9 +231,7 @@ public class MyTask extends Task {
// iterator over the conditions
}
}</pre>
- <p>
- One may define and use this class like this:
- </p>
+<p>One may define and use this class like this:</p>
<pre>
<taskdef name="mytask" classname="MyTask" classpath="classes"/>
<typedef name="condition.equals"
@@ -293,9 +239,7 @@ public class MyTask extends Task {
<mytask>
<condition.equals arg1="${debug}" arg2="true"/>
</mytask></pre>
- <p>
- A more complicated example follows:
- </p>
+<p>A more complicated example follows:</p>
<pre>
public class Sample {
public static class MyFileSelector implements FileSelector {
@@ -325,11 +269,9 @@ public class Sample {
public void setCount(int c) {}
}
}</pre>
- <p>
- This class defines a number of static classes that implement/extend
- <code>Path</code>, <code>MyFileSelector</code> and <code>MyInterface</code>. These may be defined and used
- as follows:
- </p>
+<p>This class defines a number of static classes that
+implement/extend <code>Path</code>, <code>MyFileSelector</code> and <code>MyInterface</code>. These
+may be defined and used as follows:</p>
<pre>
<typedef name="myfileselector" classname="Sample$MyFileSelector"
classpath="classes" loaderref="classes"/>
@@ -350,26 +292,21 @@ public class Sample {
<h3 id="taskcontainer">TaskContainer</h3>
-<p>The <code>TaskContainer</code> consists of a single method,
-<code>addTask</code> that basically is the same as an <a
-href="#nested-elements">add method</a> for nested elements. The task
-instances will be configured (their attributes and nested elements
-have been handled) when your task's <code>execute</code> method gets
-invoked, but not before that.</p>
-
-<p>When we <a href="#execute">said</a> <code>execute</code> would be
-called, we lied ;-). In fact, Ant will call the <code>perform</code>
-method in <code>org.apache.tools.ant.Task</code>, which in turn calls
-<code>execute</code>. This method makes sure that <a
-href="#buildevents">Build Events</a> will be triggered. If you
-execute the task instances nested into your task, you should also
-invoke <code>perform</code> on these instances instead of
+<p>The <code>TaskContainer</code> consists of a single method, <code>addTask</code> that basically
+is the same as an <a href="#nested-elements">add method</a> for nested elements. The task instances
+will be configured (their attributes and nested elements have been handled) when your
+task's <code>execute</code> method gets invoked, but not before that.</p>
+
+<p>When we <a href="#execute">said</a> <code>execute</code> would be called, we lied ;-). In fact,
+Ant will call the <code>perform</code> method in <code>org.apache.tools.ant.Task</code>, which in
+turn calls <code>execute</code>. This method makes sure that <a href="#buildevents">Build
+Events</a> will be triggered. If you execute the task instances nested into your task, you should
+also invoke <code>perform</code> on these instances instead of
<code>execute</code>.</p>
<h3>Example</h3>
-<p>Let's write our own task, which prints a message on the
-<code>System.out</code> stream.
-The task has one attribute, called <code>message</code>.</p>
+<p>Let's write our own task, which prints a message on the <code>System.out</code> stream. The task
+has one attribute, called <code>message</code>.</p>
<pre>
package com.mydomain;
@@ -394,10 +331,9 @@ public class MyVeryOwnTask extends Task {
<p>It's really this simple ;-)</p>
<p>Adding your task to the system is rather simple too:</p>
<ol>
- <li>Make sure the class that implements your task is in the classpath when
- starting Ant.</li>
- <li>Add a <code><taskdef></code> element to your project.
- This actually adds your task to the system.</li>
+ <li>Make sure the class that implements your task is in the classpath when starting Ant.</li>
+ <li>Add a <code><taskdef></code> element to your project. This actually adds your task to
+ the system.</li>
<li>Use your task in the rest of the buildfile.</li>
</ol>
@@ -415,11 +351,10 @@ public class MyVeryOwnTask extends Task {
</project></pre>
<h3>Example 2</h3>
-To use a task directly from the buildfile which created it, place the
-<code><taskdef></code> declaration inside a target
-<em>after the compilation</em>. Use the <var>classpath</var> attribute of
-<code><taskdef></code> to point to where the code has just been
-compiled.
+<p>To use a task directly from the buildfile which created it, place
+the <code><taskdef></code> declaration inside a target <em>after the compilation</em>. Use
+the <var>classpath</var> attribute of <code><taskdef></code> to point to where the code has
+just been compiled.</p>
<pre>
<?xml version="1.0"?>
@@ -442,21 +377,19 @@ compiled.
</target>
</project></pre>
-<p>Another way to add a task (more permanently) is to add the task name and
-implementing class name to the <samp>default.properties</samp> file in the
-<code>org.apache.tools.ant.taskdefs</code>
+<p>Another way to add a task (more permanently) is to add the task name and implementing class name
+to the <samp>default.properties</samp> file in the <code>org.apache.tools.ant.taskdefs</code>
package. Then you can use it as if it were a built-in task.</p>
<hr>
<h2 id="buildevents">Build Events</h2>
<p>Ant is capable of generating build events as it performs the tasks necessary to build a project.
-Listeners can be attached to Ant to receive these events. This capability could be used, for example,
-to connect Ant to a GUI or to integrate Ant with an IDE.
-</p>
-<p>To use build events you need to create an ant <code>Project</code> object. You can then call the
-<code>addBuildListener</code> method to add your listener to the project. Your listener must implement
-the <code>org.apache.tools.antBuildListener</code> interface. The listener will receive BuildEvents
-for the following events</p>
+Listeners can be attached to Ant to receive these events. This capability could be used, for
+example, to connect Ant to a GUI or to integrate Ant with an IDE.</p>
+<p>To use build events you need to create an ant <code>Project</code> object. You can then call
+the <code>addBuildListener</code> method to add your listener to the project. Your listener must
+implement the <code>org.apache.tools.antBuildListener</code> interface. The listener will receive
+BuildEvents for the following events</p>
<ul>
<li>Build started</li>
<li>Build finished</li>
@@ -467,49 +400,45 @@ for the following events</p>
<li>Message logged</li>
</ul>
-<p>If the build file invokes another build file via
-<a href="Tasks/ant.html"><code><ant></code></a> or
-<a href="Tasks/subant.html"><code><subant></code></a> or uses
-<a href="Tasks/antcall.html"><code><antcall></code></a>, you are creating a
-new Ant "project" that will send target and task level events of its
-own but never sends build started/finished events. <em>Since Ant 1.6.2</em>,
-BuildListener interface has an extension named
+<p>If the build file invokes another build file
+via <a href="Tasks/ant.html"><code><ant></code></a>
+or <a href="Tasks/subant.html"><code><subant></code></a> or
+uses <a href="Tasks/antcall.html"><code><antcall></code></a>, you are creating a new Ant
+"project" that will send target and task level events of its own but never sends build
+started/finished events. <em>Since Ant 1.6.2</em>, BuildListener interface has an extension named
SubBuildListener that will receive two new events for</p>
<ul>
<li>SubBuild started</li>
<li>SubBuild finished</li>
</ul>
-<p>If you are interested in those events, all you need to do is to
-implement the new interface instead of BuildListener (and register the
-listener, of course).</p>
+<p>If you are interested in those events, all you need to do is to implement the new interface
+instead of BuildListener (and register the listener, of course).</p>
-<p>If you wish to attach a listener from the command line you may use the
-<code>-listener</code> option. For example:</p>
+<p>If you wish to attach a listener from the command line you may use the <code>-listener</code>
+option. For example:</p>
<pre>ant -listener org.apache.tools.ant.XmlLogger</pre>
<p>will run Ant with a listener that generates an XML representation of the build progress. This
-listener is included with Ant, as is the default listener, which generates the logging to standard output.</p>
+listener is included with Ant, as is the default listener, which generates the logging to standard
+output.</p>
-<p><strong>Note</strong>: A listener must not access <code>System.out</code> and <code>System.err</code> directly since output on
-these streams is redirected by Ant's core to the build event system. Accessing these
-streams can cause an infinite loop in Ant. Depending on the version of Ant, this will
-either cause the build to terminate or the JVM to run out of Stack space. A logger, also, may
-not access System.out and System.err directly. It must use the streams with which it has
-been configured.</p>
+<p><strong>Note</strong>: A listener must not access <code>System.out</code>
+and <code>System.err</code> directly since output on these streams is redirected by Ant's core to
+the build event system. Accessing these streams can cause an infinite loop in Ant. Depending on the
+version of Ant, this will either cause the build to terminate or the JVM to run out of Stack
+space. A logger, also, may not access <code>System.out</code> and <code>System.err</code>
+directly. It must use the streams with which it has been configured.</p>
-<p><strong>Note</strong>: All methods of a BuildListener except for the "Build
- Started" and "Build Finished" events may occur on several threads
- simultaneously—for example while Ant is executing
- a <code><parallel></code> task.</p>
+<p><strong>Note</strong>: All methods of a BuildListener except for the "Build Started" and "Build
+Finished" events may occur on several threads simultaneously—for example while Ant is
+executing a <code><parallel></code> task.</p>
<h3>Example</h3>
-Writing an adapter to your favourite log library is very easy.
-Just implement the BuildListener interface, instantiate your logger and delegate
-the message to that instance.<br/>
-When starting your build provide your adapter class and the log library to the
-build classpath and activate your logger via <code>-listener</code> option as
-described above.
+<p>Writing an adapter to your favourite log library is very easy. Just implement the BuildListener
+interface, instantiate your logger and delegate the message to that instance.</p>
+<p>When starting your build provide your adapter class and the log library to the build classpath
+and activate your logger via <code>-listener</code> option as described above.</p>
<pre>
public class MyLogAdapter implements BuildListener {
@@ -540,19 +469,17 @@ public class MyLogAdapter implements BuildListener {
<hr>
<h2 id="integration">Source code integration</h2>
-<p>The other way to extend Ant through Java is to make changes to existing tasks, which is positively encouraged.
-Both changes to the existing source and new tasks can be incorporated back into the Ant codebase, which
-benefits all users and spreads the maintenance load around.</p>
+<p>The other way to extend Ant through Java is to make changes to existing tasks, which is
+positively encouraged. Both changes to the existing source and new tasks can be incorporated back
+into the Ant codebase, which benefits all users and spreads the maintenance load around.</p>
-<p>Please consult the
-<a href="https://www.apache.org/foundation/getinvolved.html">Getting Involved</a> pages on the Apache web site
-for details on how to fetch the latest source and how to submit changes for reincorporation into the
-source tree.</p>
+<p>Please consult the <a href="https://www.apache.org/foundation/getinvolved.html">Getting
+Involved</a> pages on the Apache web site for details on how to fetch the latest source and how to
+submit changes for reincorporation into the source tree.</p>
-<p>Ant also has some
-<a href="https://ant.apache.org/ant_task_guidelines.html">task guidelines</a>
-which provides some advice to people developing and testing tasks. Even if you intend to
-keep your tasks to yourself, you should still read this as it should be informative.</p>
+<p>Ant also has some <a href="https://ant.apache.org/ant_task_guidelines.html">task guidelines</a>
+which provides some advice to people developing and testing tasks. Even if you intend to keep your
+tasks to yourself, you should still read this as it should be informative.</p>
</body>
</html>