diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Tasks/typedef.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/Tasks/typedef.html | 269 |
1 files changed, 269 insertions, 0 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/typedef.html b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/typedef.html new file mode 100644 index 00000000..bdd58a7f --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/typedef.html @@ -0,0 +1,269 @@ +<!-- + 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>Typedef Task</title> +</head> + +<body> + +<h2><a name="typedef">Typedef</a></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 org.apache.tools.ant.Task 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 ID 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 taskdef or typedef tasks, the corresponding classes + will be loaded by different + Java <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/ClassLoader.html">ClassLoaders</a>. + Two classes with the same name loaded via different ClassLoaders + are not the same class from the point of view of the Java VM, 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 + 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.</p> + +<h3>Parameters</h3> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">the name of the data type</td> + <td valign="top" align="center">Yes, unless the file or resource type + attributes have been specified.</td> + </tr> + <tr> + <td valign="top">classname</td> + <td valign="top">the full class name implementing the data type</td> + <td valign="top" align="center">Yes, unless file or resource + have been specified.</td> + </tr> + <tr> + <td valign="top">file</td> + <td valign="top">Name of the file to load definitions from.</td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">resource</td> + <td valign="top"> + Name of the resource to load definitions from. + If multiple resources by this name are found along the classpath, + and the format is "properties", the first resource will be loaded; + otherwise all such resources will be loaded. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">format</td> + <td valign="top">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 to classname pairs. If the value + is "xml", the file/resource is an xml file/resource structured according + to <a href="../Types/antlib.html">Antlib</a>. + The default is "properties" unless the file/resource name ends with + ".xml", in which case the format attribute will have the value "xml". + <b>since Apache Ant 1.6</b> + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">classpath</td> <td valign="top">the classpath to + use when looking up <code>classname</code>.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">classpathref</td> + <td valign="top"> + a reference to a classpath to use when looking up <code>classname</code>. + </td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">loaderRef</td> + <td valign="top">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. <b>since Ant 1.5</b> </td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">onerror</td> + <td valign="top">The action to take if there was a failure in defining the + type. The values are <i>fail</i>: cause a build exception; <i>report</i>: + output a warning, but continue; <i>ignore</i>: do nothing. + <b>since Ant 1.6</b> + An additional value is <i>failall</i>: 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. <b>since Ant 1.7</b> + The default is <i>fail</i>. + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">adapter</td> + <td valign="top">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. + <b>since Ant 1.6</b> + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">adaptto</td> + <td valign="top">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. <b>since Ant 1.6</b> + </td> + <td valign="top" align="center">No</td> + </tr> + <tr> + <td valign="top">uri</td> + <td valign="top"> + The uri that this definition should live in. + <b>since Ant 1.6</b> + </td> + <td valign="top" align="center">No</td> + </tr> +</table> + <h3>Parameters specified as nested elements</h3> + <h4>classpath</h4> + <p><code>Typedef</code>'s <i>classpath</i> attribute is a + <a href="../using.html#path">path-like structure</a> and can also be set + via a nested <i>classpath</i> element.</p> + +<h3>Examples</h3> + The following fragment defines define a type called <i>urlset</i>. + <pre> + <typedef name="urlset" classname="com.mydomain.URLSet"/> </pre> + The data type is now available to Ant. The + class <code>com.mydomain.URLSet</code> implements this type.</p> + + + <p> + Assuming a class <i>org.acme.ant.RunnableAdapter</i> that + extends Task and implements <i>org.apache.tools.ant.TypeAdapter</i>, + and in the execute method invokes <i>run</i> on the proxied object, + one may use a Runnable class as an Ant task. The following fragment + defines a task called <i>runclock</i>. + </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 classpathref and + loaderref 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 <tt>uri</tt> 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 AntContrib Antlib to be used with the + <code>antcontrib</code> 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> + |