| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <link rel="stylesheet" type="text/css" href="stylesheets/style.css"> |
| <title>The Apache Ant frontend: ProjectHelper</title> |
| </head> |
| |
| <body> |
| <h1>The Apache Ant frontend: ProjectHelper</h1> |
| |
| <h2><a name="definition">What is a ProjectHelper?</a></h2> |
| |
| <p> |
| The <code>ProjectHelper</code> 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. |
| </p> |
| |
| <p> |
| Ant' default <code>ProjectHelper</code> |
| (<code>org.apache.tools.ant.helper.ProjectHelper2</code>) 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 <code>build.xml</code>. |
| </p> |
| |
| <p> |
| 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). |
| </p> |
| |
| <p>Since Ant 1.8.2, the <a href="Tasks/import.html">import</a> 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. |
| </p> |
| |
| <h2><a name="repository">How is Ant is selecting the proper ProjectHelper</a></h2> |
| |
| <p> |
| Ant knows about several implementations of <code>ProjectHelper</code> |
| and has to decide which to use for each build file. |
| </p> |
| |
| <p>At startup Ant lists the all implementations found and keeps them |
| in the same order they've been found in an internal 'repository': |
| <ul> |
| <li>the first to be searched for is the one declared by the system property |
| <code>org.apache.tools.ant.ProjectHelper</code> (see |
| <a href="running.html#sysprops">Java System Properties</a>);</li> |
| <li>then it searches with its class loader for a <code>ProjectHelper</code> |
| service declarations in the META-INF: it searches in the classpath for a |
| file <code>META-INF/services/org.apache.tools.ant.ProjectHelper</code>. |
| This file will just contain the fully qualified name of the |
| implementation of <code>ProjectHelper</code> to instanciate;</li> |
| <li>it will also search with the system class loader for |
| <code>ProjectHelper</code> service declarations in the META-INF;</li> |
| <li>last but not least it will add its default <code>ProjectHelper</code> |
| that can parse classical build.xml files.</li> |
| </ul> |
| In case of an error while trying to instanciate a <code>ProjectHelper</code>, Ant |
| will log an error but won't stop. If you want further debugging |
| info about the <code>ProjectHelper</code> internal 'repository', use the <b>system</b> |
| property <code>ant.project-helper-repo.debug</code> and set it to |
| <code>true</code>; the full stack trace will then also be printed. |
| </p> |
| |
| <p> |
| When Ant is expected to parse a file, it will ask the |
| <code>ProjectHelper</code> 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 <code>true</code> to |
| <code>supportsBuildFile(File buildFile)</code> will be selected. |
| </p> |
| |
| <p> |
| 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 <code>ProjectHelper</code>s |
| and will select the first one that expects a default file that actually exist. |
| </p> |
| |
| <h2><a name="writing">Writing your own ProjectHelper</a></h2> |
| |
| <p> |
| The class <code>org.apache.tools.ant.ProjectHelper</code> is the API expected to |
| be implemented. So write your own <code>ProjectHelper</code> by extending that |
| abstract class. You are then expected to implement at least the function |
| <code>parse(Project project, Object source)</code>. Note also that your |
| implementation will be instanciated by Ant, and it is expecting a default |
| constructor with no arguments. |
| </p> |
| |
| <p> |
| There are some functions that will help you define what your helper is |
| capable of and what is is expecting: |
| <ul> |
| <li><code>getDefaultBuildFile()</code>: defines which file name is expected if |
| none provided</li> |
| <li><code>supportsBuildFile(File buildFile)</code>: defines if your parser |
| can parse the input file</li> |
| |
| <li><code>canParseAntlibDescriptor(URL url)</code>: whether your |
| implementation is capable of parsing a given Antlib |
| descriptor. The base class returns <code>false</code></li> |
| <li><code>parseAntlibDescriptor(Project containingProject, URL |
| source)</code>: invoked to actually parse the Antlib |
| descriptor if your implementation returned <code>true</code> |
| for the previous method.</li> |
| </ul> |
| </p> |
| |
| <p> |
| Now that you have your implementation ready, you have to declare it to Ant. Three |
| solutions here: |
| <ul> |
| <li>use the system property <code>org.apache.tools.ant.ProjectHelper</code> |
| (see also the <a href="running.html#sysprops">Java System Properties</a>);</li> |
| <li>use the service file in META-INF: in the jar you will build with your |
| implementation, add a file |
| <code>META-INF/services/org.apache.tools.ant.ProjectHelper</code>. |
| And then in this file just put the fully qualified name of your |
| implementation</li> |
| <li>use the <a href="Tasks/projecthelper.html">projecthelper</a> task (since |
| Ant 1.8.2) which will install dynamically an helper in the internal helper |
| 'repository'. Then your helper can be used on the next call to the |
| <a href="Tasks/import.html">import</a> task.</li> |
| </ul> |
| </p> |
| |
| </body> |
| </html> |
| |