@@ -30,43 +30,43 @@
<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>For each attribute, write a <i>setter</i> 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 end 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 <i>create</i>, <i>add</i> or
<i>addConfigured</i> 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>
<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 end 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 <i>create</i>, <i>add</i> or
<i>addConfigured</i> 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>
@@ -261,7 +261,7 @@ handled.</p>
the methods will be called, but we don't know which, this depends on
the implementation of your Java virtual machine.</p>
<h3><a name="nestedtype">Nested Types</a></h3>
<h3><a name="nestedtype">Nested Types</a></h3>
If your task needs to nest an arbitrary type that has been defined
using <code><typedef></code> you have two options.
<ol>
@@ -361,6 +361,7 @@ public class Sample {
</copy>
</blockquote>
</pre>
<h3><a name="taskcontainer">TaskContainer</a></h3>
<p>The <code>TaskContainer</code> consists of a single method,
@@ -382,8 +383,7 @@ invoke <code>perform</code> on these instances instead of
<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>
The task has one attribute, called <code>message</code>.</p>
<blockquote>
<pre>
package com.mydomain;
@@ -430,6 +430,7 @@ public class MyVeryOwnTask extends Task {
</project>
</pre>
</blockquote>
<h3>Example 2</h3>
To use a task directly from the buildfile which created it, place the
<code><taskdef></code> declaration inside a target
@@ -467,42 +468,41 @@ package. Then you can use it as if it were a built-in task.</p>
<hr>
<h2><a name="buildevents">Build Events</a></h2>
<P >Ant is capable of generating build events as it performs the tasks necessary to build a project.
<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 >
<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 >
for the following events</p >
<ul>
<li>Build started</li>
<li>Build finished</li>
<li>Target started</li>
<li>Target finished</li>
<li>Task started</li>
<li>Task finished</li>
<li>Message logged</li>
<li>Build started</li>
<li>Build finished</li>
<li>Target started</li>
<li>Target finished</li>
<li>Task started</li>
<li>Task finished</li>
<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
<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. Ant 1.6.2
introduces an extension of the BuildListener interface named
SubBuildListener that will receive two new events for</p>
<ul>
<li>SubBuild started</li>
<li>SubBuild finished</li>
<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 wish to attach a listener from the command line you may use the
<p>If you wish to attach a listener from the command line you may use the
<code>-listener</code> option. For example:</p>
<blockquote>
<pre>ant -listener org.apache.tools.ant.XmlLogger</pre>
@@ -515,8 +515,7 @@ these streams is redirected by Ant's core to the build event system. Accessing t
streams can cause an infinite loop in Ant. Depending on the version of Ant, this will
either cause the build to terminate or the Java VM 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>
been configured.</p>
<p><b>Note2:</b> All methods of a BuildListener except for the "Build
Started" and "Build Finished" events may occur on several threads
@@ -526,20 +525,19 @@ been configured.
<hr>
<h2><a name="integration">Source code integration</a></h2>
The other way to extend Ant through Java is to make changes to existing tasks, which is positively encouraged.
<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>
benefits all users and spreads the maintenance load around.</p>
Please consult the
<a href="http://jakarta.apache.org/site/getinvolved.html">Getting Involved</a> pages on the Jakarta web site
<p> Please consult the
<a href="http://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>
Ant also has some
source tree.</p>
<p> Ant also has some
<a href="http://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.
keep your tasks to yourself, you should still read this as it should be informative.</p>
</body>
</html>
Jan Matrne