diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/projecthelper.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/projecthelper.html | 150 |
1 files changed, 150 insertions, 0 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/projecthelper.html b/framework/src/ant/apache-ant-1.9.6/manual/projecthelper.html new file mode 100644 index 00000000..fa07aea4 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/projecthelper.html @@ -0,0 +1,150 @@ +<!-- + 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> + |