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