Writing Custom Ant Tasks

What I think can do the job is to take a more considered approach to using a scripting tool inside an ant build. Rather than just create a mishmash of scripts that are called from exec or script tasks, I suggest that we write custom ant build tasks in a high level scripting language – in this case, Jython.

Writing custom ant tasks allows a build manager to leverage the huge number of already written tasks in their builds while writing what naturally belongs in a more flexible tool in custom ant tasks that can themselves then be reused, are as cross platform as java itself, and wholly integrated into Ant. Because Ant uses java introspection to determine the capabilities of custom tasks, Jython is the perfect tool to accomplish this. All we need to do is ensure that the methods that Ant expects are present in the Jython classes and Ant won't notice the difference.

What we will implement is the perennial SimpleTask which is nothing more than a hello world for ant. It should be sufficient to demonstrate the key steps.

<DOS>
set CLASSPATH=c:\path\to\ant\lib\ant.jar

<UNIX>
export CLASSPATH=/path/to/ant/lib/ant.jar

from org.apache.tools.ant import Task

class SimpleTask(Task): 

  message = ""

  def execute(self):
     """@sig public void execute()"""
     Task.log(self, "Message: " + self.message)

  def setMessage(this, aMessage):
     """@sig public void setMessage(java.lang.String str)"""
     this.message = aMessage

jythonc -a -c -d -j myTasks.jar SimpleTask.py

<project name="ant jython demo" default="testit" basedir=".">

  <!-- Define the tasks we are building -->
  <taskdef name="Simple" classname="SimpleTask" />

  <!-- Test Case starts here -->
  <target name="testit"> 
     <Simple message="Hello World!" />
  </target>

</project>

A Task Container Task

All right, that is a pretty simple task. What else can we do? Well, the sky is the limit really. Here is an example of a task container. In this case, the task holds references to a set of other tasks (SimpleTask tasks in this case):

from org.apache.tools.ant import Task
from org.apache.tools.ant import TaskContainer

class SimpleContainer(TaskContainer): 

  subtasks = []

  def execute(this):
     """@sig public void execute()"""
     
     for task in this.subtasks:
         task.perform()        
     
  def createSimpleTask(self):
     """@sig public java.lang.Object createSimpleTask()"""   

     task = SimpleTask()
     self.subtasks.append(task)
     return task

class SimpleTask(Task): 

  message = ""

  def execute(self):
     """@sig public void execute()"""
     Task.log(self, "Message: " + self.message)

  def setMessage(this, aMessage):
     """@sig public void setMessage(java.lang.String str)"""
     this.message = aMessage

The SimpleContainer extends the TaskContainer java class. Its createSimpleTask method creates a SimpleTask object and returns it to Ant so its properties can be set. Then when all the tasks have been added to the container and their properties set, the execute method on the SimpleContainer class is called which in turn calls the perform method on each of the contained tasks. Note that the perform method is inherited from the Task superclass and it in turn calls the the execute method which we have overriden.

<project name="ant jython demo" default="testit" basedir=".">

  <!-- Define the tasks we are building -->
  <taskdef name="Container" classname="SimpleContainer" />

  <!-- Test Case starts here -->
  <target name="testit"> 

     <Container> 

         <SimpleTask message="hello" />
         <SimpleTask message="there" />

     </Container>

  </target>

</project>    

Things To Look Out For

As I learned this technique I discovered that the magic doc strings are really necessary to force Jython to put the right methods in the generated java classes. For example:

"""@sig public void execute()"""

This is primarily due to Ant's introspection that looks for those specific methods and signatures. These docstrings are required or Ant won't recognize the classes as Ant tasks.

I also learned that for Jython to extend a java class, it must specifically import the java classes using this syntax:

from org.apache.tools.ant import Task
from org.apache.tools.ant import TaskContainer

class MyTask(Task):
   ...

You can not use this syntax:

import org.apache.tools.ant.Task
import org.apache.tools.ant.TaskContainer

 class MyTask(org.apache.tools.ant.Task):
    ...

This is because, for some reason, Jython doesn't figure out that MyTask is extending this java class and so doesn't generate the right Java wrapper classes. You will know that this working right when you see output like the following when you run the jythonc compiler:

processing SimpleTask

Required packages:
  org.apache.tools.ant

Creating adapters:

Creating .java files:
  SimpleTask module
    SimpleTask extends org.apache.tools.ant.Task <<<

What About Groovy

Groovy is a scripting language specifically targeting java developers. It is gathering steam in the java world now that it has been accepted as JSR 241 in Sun's community java process although that seems to be a little controversial. It also can be compiled to java byte code like Jython.

Here is an example of the SimpleTask done above in Groovy:

import org.apache.tools.ant.Task;
import java.lang.String

public class GroovySimpleTask extends Task {

  private String myMessage = ""

  public void execute() {
      this.log(myMessage)
  }

  public void setMessage(String aMessage) {
     myMessage = aMessage
  }

}

Its pretty easy to get this into ant. Here are the steps I followed:

groovyc GroovySimpleTask.groovy
jar cvf Groovy.jar GroovySimpleTask.class
copy Groovy.jar c:\tools\ant\lib

I also had to copy over to ant's lib directory, the groovy support jar files.

copy %GROOVY_HOME%\lib\groovy-1.0-beta-4.jar c:\tools\ant\lib
copy %GROOVY_HOME%\lib\*asm*.jar c:\tools\ant\lib

The advantage of Groovy is that you don't have to have the magic doc strings to force the method signatures to be what Ant expects. It took me a little while to figure out that you call the super class methods using the magic this object though. That is fairly indicative of what my experience with Groovy has been so far ... its pretty neat and contains lots of the same very high level language features that python perl and ruby do and then some, but the language is still changing and the documentation is poor. If the example is any indicator, there isn't much difference in the size of groovy vs jython, although after working with Jython for a while, I found it tiresome to have to constantly worry about the braces for marking blocks of code again. Groovy is certainly a language to keep an eye on though.

For now, Jython is mature, has a tons of third party modules, and is a documented way of doing this and is my first choice for writing custom ant tasks.

Summary

So there you have it. Here is a quick summary then of why this is a helpful technique.

First, it is a lot faster to write ant tasks that integrate with third party tools and systems using a glue language and python/jython is excellent at that. That is really my prime motivation for trying out this technique.

Secondly, Jython has the advantage over other scripting languages (which could be run using Ant's exec or script tasks) because it can be tightly integrated with Ant (i.e. use the same logging methods, same settings, etc). This makes it easier to build a standardized build environment.

Finally, and related to the last point, Jython can be compiled to java byte code which runs like any java class file. This means you don't have to have jython installed to use the custom tasks and your custom task, if written well, can run on a wide variety of platforms.

I think this is a reasonable way to add flexibility and additional integration points to Ant builds.

Resources

Jython Home Page

Ant Home Page

Bruce Eckel on Build Tools

Bill de hÓra - Heart of darkness - what's wrong with Ant

Martin Fowler - BuildLanguage

Jonathan Simon - Scripting with Jython Instead of XML

Ken Arnold - What is wrong with Ant

Ken Arnold - The Sum of Ant

Mike Spille - ANT's Finally a Real Build Tool

Groovy Home Page

Footnotes