|
|
@@ -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> |
|
|
|