Developing with Ant

Writing Your Own Task

It is very easy to write your own task:

1. Create a Java class that extends org.apache.tools.ant.Task.
2. For each attribute, write a setter method. The setter method must be a public void method that takes a single argument. The name of the method must begin with set, followed by the attribute name, with the first character of the name in uppercase, and the rest in lowercase. The type of the attribute can be:
   • String
   • any primitive type (they are converted for you from their String-representation in the buildfile)
   • boolean - your method will be passed the value true if the value specified in the buildfile is one of true, yes, or on)
   • Class
   • File (in which case the value of the attribute is interpreted relative to the project's basedir)
   • any other type that has a constructor with a single String argument
3. If your task has enumerated attributes, you should consider using a subclass of org.apache.tools.ant.types.EnumeratedAttribute as an argument to your setter method. See org/apache/tools/ant/taskdefs/FixCRLF.java for an example.
4. If the task should support character data, write a public void addText(String) method.
5. For each nested element, write a create or add method. A create method must be a public method that takes no arguments and returns an Object type. The name of the create method must begin with create, followed by the element name. An add method must be a public void method that takes a single argument of an Object type with a no-argument constructor. The name of the add method must begin with add, followed by the element name.
6. Write a public void execute method, with no arguments, that throws a BuildException. This method implements the task itself.

The Life-cycle of a Task

1. The task gets instantiated using a no-argument constructor, at parser time. This means even tasks that are never executed get instantiated.
2. The task gets references to its project and location inside the buildfile via its inherited project and location variables.
3. If the user specified an id attribute to this task, the project registers a reference to this newly created task, at parser time.
4. The task gets a reference to the target it belongs to via its inherited target variable.
5. init() is called at parser time.
6. All child elements of the XML element corresponding to this task are created via this task's createXXX() methods or instantiated and added to this task via its addXXX() methods, at parser time.
7. All attributes of this task get set via their corresponding setXXX methods, at runtime.
8. The content character data sections inside the XML element corresponding to this task is added to the task via its addText method, at runtime.
9. All attributes of all child elements get set via their corresponding setXXX methods, at runtime.
10. execute() is called at runtime. While the above initialization steps only occur once, the execute() method may be called more than once, if the task is invoked more than once. For example, if target1 and target2 both depend on target3, then running 'ant target1 target2' will run all tasks in target3 twice.

Example

Let's write our own task, which prints a message on the System.out stream. The task has one attribute, called message.

package com.mydomain;

import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.Task;

public class MyVeryOwnTask extends Task {
  private String msg;

  // The method executing the task
  public void execute() throws BuildException {
    System.out.println(msg);
  }

  // The setter for the "message" attribute
  public void setMessage(String msg) {
    this.msg = msg;
  }
}

It's really this simple ;-)

Adding your task to the system is rather simple too:

1. Make sure the class that implements your task is in the classpath when starting Ant.
2. Add a <taskdef> element to your project. This actually adds your task to the system.
3. Use your task in the rest of the buildfile.

Example

<?xml version="1.0"?>

<project name="OwnTaskExample" default="main" basedir=".">
  <taskdef name="mytask" classname="com.mydomain.MyVeryOwnTask"/>

  <target name="main">
    <mytask message="Hello World! MyVeryOwnTask works!"/>
  </target>
</project>

Another way to add a task (more permanently), is to add the task name and implementing class name to the default.properties file in the org.apache.tools.ant.taskdefs package. Then you can use it as if it were a built-in task.

Build Events

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.

To use build events you need to create an ant Project object. You can then call the addBuildListener method to add your listener to the project. Your listener must implement the org.apache.tools.antBuildListener interface. The listener will receive BuildEvents for the following events

• Build started
• Build finished
• Target started
• Target finished
• Task started
• Task finished
• Message logged

If you wish to attach a listener from the command line you may use the -listener option. For example:

ant -listener org.apache.tools.ant.XmlLogger

will run Ant with a listener that generates an XML representation of the build progress. This listener is included with Ant, as is the default listener, which generates the logging to standard output.

Copyright © 2000,2001 Apache Software Foundation. All rights Reserved.