The Ant frontend: ProjectHelper

What is a ProjectHelper?

The ProjectHelper in Ant is responsible to parse the build file and create java instances representing the build workflow. It also declares which kind of file it can parse, and which file name it expects as default input file.

So in Ant there is a default ProjectHelper (org.apache.tools.ant.helper.ProjectHelper2) which will parse the usual build.xml files. And if no build file is specified on the command line, it will expect to find a build.xml file.

The immediate benefit of a such abstraction it that it is possible to make Ant understand other kind of descriptive language than XML. Some experiment have been done around a pure java frontend, and a groovy one too (ask the dev mailing list for further info about these).

How is Ant is selecting the proper ProjectHelper

Ant can now know about several implementations of ProjectHelper and have to decide which to use for each build file.

So Ant at startup will list the found implementations and will keep it ordered as it finds them in an internal 'repository':

the first to be searched for is the one declared by the system property org.apache.tools.ant.ProjectHelper (see Java System Properties);
then it searches with its class loader for a ProjectHelper service declarations in the META-INF: it searches in the classpath for a file META-INF/services/org.apache.tools.ant.ProjectHelper. This file will just contain the fully qualified name of the implementation of ProjectHelper to instanciate;
it will also search with the system class loader for ProjectHelper service declarations in the META-INF;
last but not least it will add its default ProjectHelper that can parse classical build.xml files.

In case of error while trying to instanciate a ProjectHelper, Ant will log an error but still won't stop. If you want further debugging info about the ProjectHelper internal 'repository', use the system property ant.project-helper-repo.debug and set it to true; the full stack trace will then also be printed.

Then when Ant is expected to parse a file, it will ask the ProjectHelper repository to found an implementation that will be able to parse the input file. Actually it will just iterate on the ordered list and the first implementation that returns true to supportsBuildFile(File buildFile) will be selected.

And when Ant is launching and there is no input file specified, it will search for a default input file. It will iterate on the list of ProjectHelper and will select the first one that expects a default file that actually exist.

Writing your own ProjectHelper

The class org.apache.tools.ant.ProjectHelper is the API expected to be implemented. So write your own ProjectHelper by extending that abstract class. You are then expected to implement at least the function parse(Project project, Object source). Note also that your implementation will be instanciated by Ant, and it is expecting a default constructor with no arguments.

Then there are some functions that will help you define what your helper is capable of and what is is expecting:

getDefaultBuildFile(): defines which file name is expected if none provided
supportsBuildFile(File buildFile): defines if your parser can parse the input file

Now that you have your implementation ready, you have to declare it to Ant. Two solutions here:

use the system property org.apache.tools.ant.ProjectHelper (see also the Java System Properties);
use the service file in META-INF: in the jar you will build with your implementation, add a file META-INF/services/org.apache.tools.ant.ProjectHelper. And then in this file just put the fully qualified name of your implementation