leafcutter
Project home

• A way of integrating Ant tasks into existing Java programs.
  
• A wholesale alternative to standard Ant for process automation. We'll look at reasons for doing this in a moment.

Leafcutter example

Ant users write XML buildfiles. These define a number of targets which contain sequences of configured tasks. Dependencies between targets can be specified, along with simple conditions for task execution.

For example, when the backup task below is executed, Ant will first execute the init target because of the dependency. If the backup.enabled property is set, Ant will then execute the property and copy tasks in sequence.

<target name="backup" depends="init" if="backup.enabled">
   <property name="source.dir" value="src/main"/>
   <copy todir="home/backups" verbose=true>
      <fileset dir=${source.dir}" includes="**/*.txt"/>
   </copy>
</target>

This Java code does the same job using the Leafcutter API:

public void backup(boolean enabled){
   init();
   if (enabled){
      File sourceDir = new File("src/main");
      TaskRunner.run("copy todir=home/backups verbose=true (fileset dir=${1} includes=**/*.txt)", sourceDir);
   }
}

Why use Leafcutter?

In the example above, the buildfile code and the Java code which uses Leafcutter are pretty similar. What's the point of using Leafcutter at all?

Firstly, Ant's buildfiles are declarative - in other words, they're more like configuration files than programs. Ant is based on the assumption that all the procedural logic you'll need is predefined by the tasks and the target execution rules.

This isn't a problem for simple "one-off" processes; the predefined procedural logic usually caters for your needs. However, you soon find yourself wanting to write process-specific procedural logic, for example:

• Execute a task or a set of tasks in a loop (there's no support for looping in buildfiles)
• Use non-trivial conditional logic (buildfiles only allow simple conditionals which are cumbersome to use)
• Handle errors robustly (standard Ant tends to "bomb out" at the first sign of trouble)
• Dynamically derive the task arguments (not possible in buildfiles - a major cause of inflexibility)

Leafcutter allows you to conveniently embed Ant tasks within a Java program. This gives you complete freedom to implement any kind of logic you like!

You can also use Java’s object oriented nature to make your automated process more flexible and reusable. Leafcutter has a track record of replacing large, rigid Ant buildfiles (thousands of lines of XML) with Java programs which are much smaller and more maintainable.

In general, Java programs are much easier to work with than large buildfiles. Although some tool support exists for Ant (e.g. in the Eclipse IDE), it will never match the tool support for Java. Using Leafcutter, you can use your favourite Java IDE to navigate, edit, test, debug, and refactor your scripts in ways that just aren't possible with standard Ant.

Documentation

The Leafcutter User Guide contains all the information you need to get going.

An FAQ is also available.

For more details about the public API, see the javadocs.

Download

The latest binary Leafcutter distribution is available here. A JAR containing source code is available here.

(The latest minimal binary Leafcutter distribution without ant or log4j is available here. You can use this if you want to use your own version of ant or log4j or junit with leafcutter rather than the bundled versions.)

News

27th Jan 2005 Tiny Tool of the week!

Leafcutter has been selected as the "Tiny Tool of the week" by the JavaTools community at java.net.

25th Jan 2005 BETA1-1 released

Fixed bug in processing nested elements which have the same name as tasks, e.g. the "test" nested element of the junit task.

Feedback

Your feedback would be greatly appreciated! Please use the discussion forums.

Help and support

Please take a look at the FAQ first.

If you need further help, please use the discussion groups (see links to the left of this page).

Last updated $Date: 2006/03/31 00:27:19 $