| @@ -30,43 +30,43 @@ | |||||
| <ol> | <ol> | ||||
| <li>Create a Java class that extends <code>org.apache.tools.ant.Task</code> | <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> | 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 | <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 | <code>public void</code> method that takes a single argument. The | ||||
| name of the method must begin with <code>set</code>, followed by 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 | 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 | 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>. | <code>file</code> you create a method <code>setFile</code>. | ||||
| Depending on the type of the argument, Ant will perform some | Depending on the type of the argument, Ant will perform some | ||||
| conversions for you, see <a href="#set-magic">below</a>.</li> | conversions for you, see <a href="#set-magic">below</a>.</li> | ||||
| <li>If your task shall contain other tasks as nested elements (like | <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> | </ol> | ||||
| <hr> | <hr> | ||||
| @@ -261,7 +261,7 @@ handled.</p> | |||||
| the methods will be called, but we don't know which, this depends on | the methods will be called, but we don't know which, this depends on | ||||
| the implementation of your Java virtual machine.</p> | 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 | If your task needs to nest an arbitrary type that has been defined | ||||
| using <code><typedef></code> you have two options. | using <code><typedef></code> you have two options. | ||||
| <ol> | <ol> | ||||
| @@ -361,6 +361,7 @@ public class Sample { | |||||
| </copy> | </copy> | ||||
| </blockquote> | </blockquote> | ||||
| </pre> | </pre> | ||||
| <h3><a name="taskcontainer">TaskContainer</a></h3> | <h3><a name="taskcontainer">TaskContainer</a></h3> | ||||
| <p>The <code>TaskContainer</code> consists of a single method, | <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> | <h3>Example</h3> | ||||
| <p>Let's write our own task, which prints a message on the | <p>Let's write our own task, which prints a message on the | ||||
| <code>System.out</code> stream. | <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> | <blockquote> | ||||
| <pre> | <pre> | ||||
| package com.mydomain; | package com.mydomain; | ||||
| @@ -430,6 +430,7 @@ public class MyVeryOwnTask extends Task { | |||||
| </project> | </project> | ||||
| </pre> | </pre> | ||||
| </blockquote> | </blockquote> | ||||
| <h3>Example 2</h3> | <h3>Example 2</h3> | ||||
| To use a task directly from the buildfile which created it, place the | To use a task directly from the buildfile which created it, place the | ||||
| <code><taskdef></code> declaration inside a target | <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> | <hr> | ||||
| <h2><a name="buildevents">Build Events</a></h2> | <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, | 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. | 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 | <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 | <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 | the <code>org.apache.tools.antBuildListener</code> interface. The listener will receive BuildEvents | ||||
| for the following events</P> | |||||
| for the following events</p> | |||||
| <ul> | <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> | </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 | 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 | own but never sends build started/finished events. Ant 1.6.2 | ||||
| introduces an extension of the BuildListener interface named | introduces an extension of the BuildListener interface named | ||||
| SubBuildListener that will receive two new events for</p> | SubBuildListener that will receive two new events for</p> | ||||
| <ul> | <ul> | ||||
| <li>SubBuild started</li> | |||||
| <li>SubBuild finished</li> | |||||
| <li>SubBuild started</li> | |||||
| <li>SubBuild finished</li> | |||||
| </ul> | </ul> | ||||
| <p>If you are interested in those events, all you need to do is to | <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 | implement the new interface instead of BuildListener (and register the | ||||
| listener, of course).</p> | 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> | <code>-listener</code> option. For example:</p> | ||||
| <blockquote> | <blockquote> | ||||
| <pre>ant -listener org.apache.tools.ant.XmlLogger</pre> | <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 | 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 | 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 | 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 | <p><b>Note2:</b> All methods of a BuildListener except for the "Build | ||||
| Started" and "Build Finished" events may occur on several threads | Started" and "Build Finished" events may occur on several threads | ||||
| @@ -526,20 +525,19 @@ been configured. | |||||
| <hr> | <hr> | ||||
| <h2><a name="integration">Source code integration</a></h2> | <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 | 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 | 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> | <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 | 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> | </body> | ||||
| </html> | </html> | ||||