|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140 |
- <!--
- 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 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>
-
- <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. 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>
-
|