mirror of
https://github.com/apache/ant.git
synced 2025-05-17 21:45:12 +00:00
203 lines
9.2 KiB
HTML
203 lines
9.2 KiB
HTML
<!DOCTYPE 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
|
|
|
|
https://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 lang="en">
|
|
|
|
<head>
|
|
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
|
<title>Typedef Task</title>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<h2 id="typedef">Typedef</h2>
|
|
<h3>Description</h3>
|
|
<p>Adds a task or a data type definition to the current project such that this new type or task can
|
|
be used in the current project.</p>
|
|
<p>A Task is any class that extends <code class="code">org.apache.tools.ant.Task</code> or can be adapted
|
|
as a Task using an adapter class.</p>
|
|
<p>Data types are things like <a href="../using.html#path">paths</a>
|
|
or <a href="../Types/fileset.html">filesets</a> that can be defined at the project level and
|
|
referenced via their <var>id</var> attribute. Custom data types usually need custom tasks to put
|
|
them to good use.</p>
|
|
<p>Two attributes are needed to make a definition: the name that identifies this data type uniquely,
|
|
and the full name of the class (including its package name) that implements this type.</p>
|
|
<p>You can also define a group of definitions at once using the file or resource attributes. These
|
|
attributes point to files in the format of Java property files or an xml format.</p>
|
|
<p>For property files each line defines a single data type in the format:</p>
|
|
<pre>typename=fully.qualified.java.classname</pre>
|
|
<p>The xml format is described in the <a href="../Types/antlib.html">Antlib</a> section.</p>
|
|
|
|
<p>If you are defining tasks or types that share the same classpath with
|
|
multiple <code>taskdef</code> or <code>typedef</code> tasks, the corresponding classes will be
|
|
loaded by different
|
|
Java <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/ClassLoader.html"
|
|
target="_top">ClassLoaders</a>. Two classes with the same name loaded via different ClassLoaders
|
|
are not the same class from the point of view of JVM, they don't share static variables and
|
|
instances of these classes can't access private methods or attributes of instances defined by "the
|
|
other class" of the same name. They don't even belong to the same Java package and can't access
|
|
package private code, either.</p>
|
|
|
|
<p>The best way to load several tasks/types that are supposed to cooperate with each other via
|
|
shared Java code is to use the <var>resource</var> attribute and an <code>antlib</code> descriptor.
|
|
If this is not possible, the second best option is to use the <var>loaderref</var> attribute and
|
|
specify the same name for each and every <code>typedef</code>/<code>taskdef</code>—this way
|
|
the classes will share the same <code>ClassLoader</code>. Note that
|
|
the <code>typedef</code>/<code>taskdef</code> tasks must use identical classpath definitions (this
|
|
includes the order of path components) for the <var>loaderref</var> attribute to work.</p>
|
|
|
|
<h3>Parameters</h3>
|
|
<table class="attr">
|
|
<tr>
|
|
<th scope="col">Attribute</th>
|
|
<th scope="col">Description</th>
|
|
<th scope="col">Required</th>
|
|
</tr>
|
|
<tr>
|
|
<td>name</td>
|
|
<td>the name of the data type</td>
|
|
<td rowspan="2">Yes, unless <var>file</var> or <var>resource</var> attributes have been
|
|
specified.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>classname</td>
|
|
<td class="left">the full class name implementing the data type</td>
|
|
</tr>
|
|
<tr>
|
|
<td>file</td>
|
|
<td>Name of the file to load definitions from.</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>resource</td>
|
|
<td>Name of the resource to load definitions from. If multiple resources by this name are found
|
|
along the classpath, and <var>format</var> is <q>properties</q>, the first resource will be
|
|
loaded; otherwise all such resources will be loaded.</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>format</td>
|
|
<td>The format of the file or resource. The values are <q>properties</q>" or <q>xml</q>. If the
|
|
value is <q>properties</q> the file/resource is a property file contains name-classname
|
|
pairs. If the value is <q>xml</q>, the file/resource is an XML file/resource structured
|
|
according to <a href="../Types/antlib.html">Antlib</a>. The default is <q>properties</q>
|
|
unless the file/resource name ends with <samp>.xml</samp>, in which case the <var>format</var>
|
|
attribute will have the value <q>xml</q>. <em>Since Ant 1.6</em></td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>classpath</td>
|
|
<td>the classpath to use when looking up <var>classname</var>.</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>classpathref</td>
|
|
<td>a reference to a classpath to use when looking up <var>classname</var>.</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>loaderRef</td>
|
|
<td>the name of the loader that is used to load the class, constructed from the specified
|
|
classpath. Use this to allow multiple tasks/types to be loaded with the same loader, so they
|
|
can call each other. <em>Since Ant 1.5</em></td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>onerror</td>
|
|
<td>The action to take if there was a failure in defining the type. The values are <q>fail</q>:
|
|
cause a build exception; <q>report</q>: output a warning, but continue; <q>ignore</q>: do
|
|
nothing. <em>Since Ant 1.6</em>, an additional value is <q>failall</q>: cause all behavior of
|
|
fail, as well as a build exception for the resource or file attribute if the resource or file
|
|
is not found.</td>
|
|
<td>No; default is <q>fail</q> (<em>since Ant 1.7</em>)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>adapter</td>
|
|
<td>A class that is used to adapt the defined class to another interface/class. The adapter
|
|
class must implement the interface <code>org.apache.tools.ant.TypeAdapter</code>. The adapter
|
|
class will be used to wrap the defined class unless the defined class implements/extends the
|
|
class defined by the attribute <q>adaptto</q>. If <q>adaptto</q> is not set, the defined
|
|
class will always be wrapped. <em>Since Ant 1.6</em></td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>adaptto</td>
|
|
<td>This attribute is used in conjunction with the adapter attribute. If the defined class does
|
|
not implement/extend the interface/class specified by this attribute, the adaptor class will
|
|
be used to wrap the class. <em>Since Ant 1.6</em></td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>uri</td>
|
|
<td>The uri that this definition should live in. <em>Since Ant 1.6</em></td>
|
|
<td>No</td>
|
|
</tr>
|
|
</table>
|
|
<h3>Parameters specified as nested elements</h3>
|
|
<h4>classpath</h4>
|
|
<p><code>Typedef</code>'s <var>classpath</var> attribute is a <a href="../using.html#path">path-like
|
|
structure</a> and can also be set via a nested <code>classpath</code> element.</p>
|
|
|
|
<h3>Examples</h3>
|
|
<p>The following fragment defines define a type called <code>urlset</code>.</p>
|
|
<pre><typedef name="urlset" classname="com.mydomain.URLSet"/></pre>
|
|
<p>The data type is now available to Ant. The class <code>com.mydomain.URLSet</code> implements this
|
|
type.</p>
|
|
|
|
<p>Assuming a class <code>org.acme.ant.RunnableAdapter</code> that
|
|
extends <code class="code">Task</code> and
|
|
implements <code class="code">org.apache.tools.ant.TypeAdapter</code>, and in
|
|
the <code class="code">execute()</code> method invokes <code class="code">run()</code> on the
|
|
proxied object, one may use a <code class="code">Runnable</code> class as an Ant task. The following
|
|
fragment defines a task called <code>runclock</code>.</p>
|
|
<pre>
|
|
<typedef name="runclock"
|
|
classname="com.acme.ant.RunClock"
|
|
adapter="org.acme.ant.RunnableAdapter"/></pre>
|
|
|
|
<p>The following fragment shows the use of the <var>classpathref</var> and <var>loaderref</var> to
|
|
load up two definitions.</p>
|
|
<pre>
|
|
<path id="lib.path">
|
|
<fileset dir="lib" includes="lib/*.jar"/>
|
|
</path>
|
|
|
|
<typedef name="filter1"
|
|
classname="org.acme.filters.Filter1"
|
|
classpathref="lib.path"
|
|
loaderref="lib.path.loader"/>
|
|
<typedef name="filter2"
|
|
classname="org.acme.filters.Filter2"
|
|
loaderref="lib.path.loader"/></pre>
|
|
|
|
<p>If you want to load an antlib into a special XML namespace, the <var>uri</var> attribute is
|
|
important:</p>
|
|
<pre>
|
|
<project xmlns:antcontrib="antlib:net.sf.antcontrib">
|
|
<taskdef uri="antlib:net.sf.antcontrib"
|
|
resource="net/sf/antcontrib/antlib.xml"
|
|
classpath="path/to/ant-contrib.jar"/></pre>
|
|
|
|
<p>Here the namespace declaration <code>xmlns:antcontrib="antlib:net.sf.antcontrib"</code> allows
|
|
tasks and types of the Ant-Contrib Antlib to be used with the <samp>antcontrib</samp> prefix
|
|
like <code><antcontrib:if></code>. The normal rules of XML namespaces apply and you can
|
|
declare the prefix at any element to make it usable for the element it is declared on as well as all
|
|
its child elements.</p>
|
|
|
|
</body>
|
|
</html>
|