wangwei
/
antliscence
forked from youys/ant

<!--
   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 Ant frontend: ProjectHelper</title>
</head>

<body>
<h1>The Ant frontend: ProjectHelper</h1>

<h2><a name="definition">What is a ProjectHelper?</a></h2>

<p>
The <code>ProjectHelper</code> 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.
</p>
<p>
So in Ant there is a default <code>ProjectHelper</code>
(<code>org.apache.tools.ant.helper.ProjectHelper2</code>) 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.
</p>

<p>
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).
</p>

<h2><a name="repository">How is Ant is selecting the proper ProjectHelper</a></h2>

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

<p>So Ant at startup will list the found implementations and will keep it
ordered as it finds them 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 error while trying to instanciate a <code>ProjectHelper</code>, Ant
will log an error but still won't stop. If you want further debugging
info about the <code>ProjectHelper</code> internal 'repository', use the system
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>
Then when Ant is expected to parse a file, it will ask the
<code>ProjectHelper</code> 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 <code>true</code> to
<code>supportsBuildFile(File buildFile)</code> will be selected.
</p>

<p>
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 <code>ProjectHelper</code>
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>
Then 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>
</ul>
</p>

<p>
Now that you have your implementation ready, you have to declare it to Ant. Two
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>
</ul>
</p>

</body>
</html>