4
<meta http-equiv="Content-Language" content="en-us">
5
<title>Ant User Manual</title>
9
<h1>Developing with Ant</h1>
11
<h2><a name="writingowntask">Writing Your Own Task</a></h2>
12
<p>It is very easy to write your own task:</p>
14
<li>Create a Java class that extends <code>org.apache.tools.ant.Task</code>.</li>
15
<li>For each attribute, write a <i>setter</i> method. The setter method must be a
16
<code>public void</code> method that takes a single argument. The
17
name of the method must begin with <code>set</code>, followed by the
18
attribute name, with the first character of the name in uppercase, and the rest in
19
lowercase. The type of the attribute can be:
25
any primitive type (they are converted for you from their String-representation
29
boolean - your method will be passed the value
30
<i>true</i> if the value specified in the buildfile is one of <code>true</code>,
31
<code>yes</code>, or <code>on</code>)
38
(in which case the value of the attribute is interpreted relative to the
42
any other type that has a constructor with a single
43
<code>String</code> argument
47
<li>If your task has enumerated attributes, you should consider using
48
a subclass of <code>org.apache.tools.ant.types.EnumeratedAttribute</code>
50
to your setter method. See
51
<code>org/apache/tools/ant/taskdefs/FixCRLF.java</code> for
53
<li>If the task should support character data, write a <code>public void
54
addText(String)</code> method.</li>
55
<li>For each nested element, write a <i>create</i> or <i>add</i> method.
57
must be a <code>public</code> method that takes no arguments and returns
58
an <code>Object</code> type. The name of the create method must begin with
59
<code>create</code>, followed by the element name. An add method must be
60
a <code>public void</code> method that takes a single argument of an
61
<code>Object</code> type with a no-argument constructor.
62
The name of the add method
63
must begin with <code>add</code>, followed by the element name.</li>
64
<li>Write a <code>public void execute</code> method, with no arguments, that
65
throws a <code>BuildException</code>. This method implements the task
69
<h3>The Life-cycle of a Task</h3>
71
<li>The task gets instantiated using a no-argument constructor, at parser
72
time. This means even tasks that are never executed get
75
<li>The task gets references to its project and location inside the
76
buildfile via its inherited <code>project</code> and
77
<code>location</code> variables.</li>
79
<li>If the user specified an <code>id</code> attribute to this task,
81
registers a reference to this newly created task, at parser
84
<li>The task gets a reference to the target it belongs to via its
85
inherited <code>target</code> variable.</li>
87
<li><code>init()</code> is called at parser time.</li>
89
<li>All child elements of the XML element corresponding to this task
90
are created via this task's <code>createXXX()</code> methods or
91
instantiated and added to this task via its <code>addXXX()</code>
92
methods, at parser time.</li>
94
<li>All attributes of this task get set via their corresponding
95
<code>setXXX</code> methods, at runtime.</li>
97
<li>The content character data sections inside the XML element
98
corresponding to this task is added to the task via its
99
<code>addText</code> method, at runtime.</li>
101
<li>All attributes of all child elements get set via their corresponding
102
<code>setXXX</code> methods, at runtime.</li>
104
<li><code>execute()</code> is called at runtime. While the above initialization
105
steps only occur once, the execute() method may be
106
called more than once, if the task is invoked more than once. For example,
107
if <code>target1</code> and <code>target2</code> both depend
108
on <code>target3</code>, then running
109
<code>'ant target1 target2'</code> will run all tasks in
110
<code>target3</code> twice.</li>
114
<p>Let's write our own task, which prints a message on the
115
<code>System.out</code> stream.
117
task has one attribute, called <code>message</code>.</p>
120
package com.mydomain;
122
import org.apache.tools.ant.BuildException;
123
import org.apache.tools.ant.Task;
125
public class MyVeryOwnTask extends Task {
128
// The method executing the task
129
public void execute() throws BuildException {
130
System.out.println(msg);
133
// The setter for the "message" attribute
134
public void setMessage(String msg) {
140
<p>It's really this simple ;-)</p>
141
<p>Adding your task to the system is rather simple too:</p>
143
<li>Make sure the class that implements your task is in the classpath when
145
<li>Add a <code><taskdef></code> element to your project.
146
This actually adds your task to the system.</li>
147
<li>Use your task in the rest of the buildfile.</li>
153
<?xml version="1.0"?>
155
<project name="OwnTaskExample" default="main" basedir=".">
156
<taskdef name="mytask" classname="com.mydomain.MyVeryOwnTask"/>
158
<target name="main">
159
<mytask message="Hello World! MyVeryOwnTask works!"/>
164
<p>Another way to add a task (more permanently), is to add the task name and
165
implementing class name to the <code>default.properties</code> file in the
166
<code>org.apache.tools.ant.taskdefs</code>
167
package. Then you can use it as if it were a built-in task.</p>
170
<h2><a name="buildevents">Build Events</a></h2>
171
<P>Ant is capable of generating build events as it performs the tasks necessary to build a project.
172
Listeners can be attached to Ant to receive these events. This capability could be used, for example,
173
to connect Ant to a GUI or to integrate Ant with an IDE.
175
<p>To use build events you need to create an ant <code>Project</code> object. You can then call the
176
<code>addBuildListener</code> method to add your listener to the project. Your listener must implement
177
the <code>org.apache.tools.antBuildListener</code> interface. The listener will receive BuildEvents
178
for the following events</P>
180
<li>Build started</li>
181
<li>Build finished</li>
182
<li>Target started</li>
183
<li>Target finished</li>
184
<li>Task started</li>
185
<li>Task finished</li>
186
<li>Message logged</li>
190
If you wish to attach a listener from the command line you may use the
191
<code>-listener</code> option. For example:</p>
193
<pre>ant -listener org.apache.tools.ant.XmlLogger</pre>
195
<p>will run Ant with a listener that generates an XML representation of the build progress. This
196
listener is included with Ant, as is the default listener, which generates the logging to standard output.</p>
199
<p align="center">Copyright © 2000,2001 Apache Software Foundation. All rights
added
removed
docs/manual/develop.html
