ProjectHelper in Apache Ant is responsible for parsing the build file
and creating java instances representing the build workflow. It also signals which
kind of file it can parse, and which file name it expects as default input file.
org.apache.tools.ant.helper.ProjectHelper2) parses the
usual build.xml files. And if no build file is specified on the command line, it
will expect to find a file named
The immediate benefit of a such abstraction it that it is possible to make Ant understand other kind of descriptive languages than XML. Some experiments have been done around a pure java frontend, and a groovy one too (ask the dev mailing list for further info about these).
Since Ant 1.8.2, the import task will also try to use the proper helper to parse the imported file. So it is possible to write different build files in different languages and have them import each other.
Ant knows about several implementations of
and has to decide which to use for each build file.
At startup Ant lists the all implementations found and keeps them in the same order they've been found in an internal 'repository':
org.apache.tools.ant.ProjectHelper(see Java System Properties);
ProjectHelperservice 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
ProjectHelperservice declarations in the META-INF;
ProjectHelperthat can parse classical build.xml files.
ProjectHelper, Ant will log an error but won't stop. If you want further debugging info about the
ProjectHelperinternal 'repository', use the system property
ant.project-helper-repo.debugand set it to
true; the full stack trace will then also be printed.
When Ant is expected to parse a file, it will ask the
ProjectHelper repository to find an implementation that will be
able to parse the input file. Actually it will just iterate over the ordered list
and the first implementation that returns
supportsBuildFile(File buildFile) will be selected.
When Ant is started and no input file has been specified, it will search for
a default input file. It will iterate over list of
and will select the first one that expects a default file that actually exist.
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 instantiated by Ant, and it is expecting a default
constructor with no arguments.
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
canParseAntlibDescriptor(URL url): whether your implementation is capable of parsing a given Antlib descriptor. The base class returns
parseAntlibDescriptor(Project containingProject, URL source): invoked to actually parse the Antlib descriptor if your implementation returned
truefor the previous method.
Now that you have your implementation ready, you have to declare it to Ant. Three solutions here:
org.apache.tools.ant.ProjectHelper(see also the Java System Properties);
META-INF/services/org.apache.tools.ant.ProjectHelper. And then in this file just put the fully qualified name of your implementation