October 30, 2014
Hot Topics:
RSS RSS feed Download our iPhone app

Introduction to Custom Ant Tasks

  • September 7, 2006
  • By Rob Lybarger
  • Send Email »
  • More Articles »

Example Two: Optional Attributes Support

I will now expand on the previous example by adding an attribute to your task. Consider that you desire to have an optional attribute for your task. The value of this attribute will be a person's name, such as Bob, and you will say "Hello, Bob!" instead of "Hello, World!" if this attribute is set. (If the name attribute is omitted, you'll fall back to the original message.)

You provide attribute support by adding the necessary instance variable in your class and providing a corresponding getter/setter method for it. The name of the attribute should match the name of your instance variable so that Ant can most easily determine which getter/setter method is involved as it is processing your custom task. (Chalk it up to some reflection magic.) In other words, if you decide you want an optional "name" attribute in your custom task, you need to create a "name" instance variable and a standard getName/setName method pair. For a build.xml file that looks like this...

<project name="demo" basedir="." default="demo">

   <taskdef resource="MyAntTasks.properties" classpath="mytasks.jar"/>

   <target name="demo">
      <helloworld name="Bob"/>
   </target>

</project>

...you provide the following Java code:

package org.roblybarger.ant.taskdefs;
import org.apache.tools.ant.Task;
import org.apache.tools.ant.Project;

public class HelloWorld extends Task {

   private String name=null;

   public void setName(String name) {
      this.name = name;
   }

   public String getName() {
      return name;
   }

   public void execute() {
      if (name != null && name.length() > 0) {
         log("Hello, " + name + "!", Project.MSG_INFO);
      }
      else {
         log("Hello, World!", Project.MSG_INFO);
      }
   }

}

Recompile and update your jar file. Run Ant both with and without the additional attribute present. For the sample build.xml file I showed at the beginning of this section, you should get:

Buildfile: build.xml

demo:
<helloworld> Hello, Bob!

BUILD SUCCESSFUL
Total time: 0 seconds

Property References in Attributes

You may refer to properties defined elsewhere in the build.xml file when you set the value of an attribute for your custom task—Ant automatically will expand the property before it calls the setter method in your code. In other words, name="${first} ${last}" would work fine without your needing to detect, parse, and replace the values on your own.

Case-Insensitivity

The exact case for your attribute name does not need to exactly match that of the instance variable in your Java class. In general, attribute names can also be entirely in lower case. In other words, if your instance variable is called "intValue", it is fine for the attribute to be named "intvalue" in the build.xml file.

Type Conversions to Non-String Variables

Ant does provide some automatic type conversions as necessary, so the instance variables in your Java code can be primitive types such as int or boolean or object types such as File.

To see any of the above comments illustrated, view the downloadable files for this example.

Example Three: Required Attributes and Conditionally Failing the Build

Now, consider the case where you insist the name attribute to be given, meaning it is no longer an optional attribute. Where, in Example Two, you were checking for a null (or zero length) value and emitting the default message, you now will cause the Ant output to say "BUILD FAILED" and halt operation. This is done by throwing an org.apache.tools.ant.BuildException object.

Note: I am showing only an updated execute method here.
public void execute() throws BuildException {
   if (name != null && name.length() > 0) {
      log("Hello, " + name + "!", Project.MSG_INFO);
   }
   else {
      throw new BuildException("name attribute is required.");
   }
}

Now, update the build.xml file to use this both with and without the required attribute to see the effect:

<project name="demo" basedir="." default="demo">

   <taskdef resource="MyAntTasks.properties" classpath="mytasks.jar"/>

   <target name="demo">
      <helloworld name="Bob"/>
       <helloworld/>
   </target>

</project>

Running this without the name attribute in the build.xml file should result in this:

Buildfile: build.xml

demo:
[helloworld] Hello, Bob!

BUILD FAILED
/Users/rob/Projects/Articles/Article1/ex3_files/build.xml:7:
   name attribute is required.

Total time: 0 seconds

Reasons for you to do this might involve some critical file not being present (or readable), some required property not being set as expected, or whatever else might cause your business logic to go horribly awry. To address some problems ahead of time, you might be able to have some default values; however, I encourage you to emit a "WARNING" level log message that informs the user (which may be you, later, when you forgot how your task works) that a default value is being used.





Page 2 of 3



Comment and Contribute

 


(Maximum characters: 1200). You have characters left.

 

 


Sitemap | Contact Us

Rocket Fuel