|
|
|
@@ -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> |
Gintas Grigelionis
7 years ago