manual/projecthelper.html - ant - Git at Google

 <!--
    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 instantiate;</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 instantiate 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 instantiated 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>
	<!--
	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 instantiate;</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 instantiate 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 instantiated 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>