Typedef Task

Typedef

Description

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.

A Task is any class that extends org.apache.tools.ant.Task or can be adapted as a Task using an adapter class.

Data types are things like paths or filesets that can be defined at the project level and referenced via their id attribute. Custom data types usually need custom tasks to put them to good use.

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.

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.

For property files each line defines a single data type in the format:

typename=fully.qualified.java.classname

The xml format is described in the Antlib section.

If you are defining tasks or types that share the same classpath with multiple taskdef or typedef tasks, the corresponding classes will be loaded by different Java ClassLoaders. 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.

The best way to load several tasks/types that are supposed to cooperate with each other via shared Java code is to use the resource attribute and an antlib descriptor. If this is not possible, the second best option is to use the loaderref attribute and specify the same name for each and every typedef/taskdef—this way the classes will share the same ClassLoader. Note that the typedef/taskdef tasks must use identical classpath definitions (this includes the order of path components) for the loaderref attribute to work.

Parameters

Attribute	Description	Required
name	the name of the data type	Yes, unless `file` or `resource` attributes have been specified.
classname	the full class name implementing the data type
file	Name of the file to load definitions from.	No
resource	Name of the resource to load definitions from. If multiple resources by this name are found along the classpath, and `format` is properties, the first resource will be loaded; otherwise all such resources will be loaded.	No
format	The format of the file or resource. The values are properties" or xml. If the value is properties the file/resource is a property file contains name-classname pairs. If the value is xml, the file/resource is an XML file/resource structured according to Antlib. The default is properties unless the file/resource name ends with `.xml`, in which case the `format` attribute will have the value xml. Since Ant 1.6	No
classpath	the classpath to use when looking up `classname`.	No
classpathref	a reference to a classpath to use when looking up `classname`.	No
loaderRef	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. Since Ant 1.5	No
onerror	The action to take if there was a failure in defining the type. The values are fail: cause a build exception; report: output a warning, but continue; ignore: do nothing. Since Ant 1.6, an additional value is failall: 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.	No; default is fail (since Ant 1.7)
adapter	A class that is used to adapt the defined class to another interface/class. The adapter class must implement the interface `org.apache.tools.ant.TypeAdapter`. The adapter class will be used to wrap the defined class unless the defined class implements/extends the class defined by the attribute adaptto. If adaptto is not set, the defined class will always be wrapped. Since Ant 1.6	No
adaptto	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. Since Ant 1.6	No
uri	The uri that this definition should live in. Since Ant 1.6	No

Parameters specified as nested elements

classpath

Typedef's classpath attribute is a path-like structure and can also be set via a nested classpath element.

Examples

The following fragment defines define a type called urlset.

<typedef name="urlset" classname="com.mydomain.URLSet"/>

The data type is now available to Ant. The class com.mydomain.URLSet implements this type.

Assuming a class org.acme.ant.RunnableAdapter that extends Task and implements org.apache.tools.ant.TypeAdapter, and in the execute() method invokes run() on the proxied object, one may use a Runnable class as an Ant task. The following fragment defines a task called runclock.

<typedef name="runclock"
         classname="com.acme.ant.RunClock"
         adapter="org.acme.ant.RunnableAdapter"/>

The following fragment shows the use of the classpathref and loaderref to load up two definitions.

<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"/>

If you want to load an antlib into a special XML namespace, the uri attribute is important:

<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"/>

Here the namespace declaration xmlns:antcontrib="antlib:net.sf.antcontrib" allows tasks and types of the Ant-Contrib Antlib to be used with the antcontrib prefix like <antcontrib:if>. 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.