public void method that takes a single argument. The
name of the method must begin with set, followed by the
attribute name, with the first character of the name in uppercase, and the rest in
- lowercase. The type of the attribute can be:
-String
-true,
-yes, or on)
-Class
-File
-(in which case the value of the attribute is interpreted relative to the
-project's basedir)
-String argument
-org.apache.tools.ant.types.EnumeratedAttribute
-as an argument
-to your setter method. See
-org/apache/tools/ant/taskdefs/FixCRLF.java for
-an example.public void
-addText(String) method.public method that takes no arguments and returns
-an Object type. The name of the create method must begin with
-create, followed by the element name. An add method must be
-a public void method that takes a single argument of an
-Object type with a no-argument constructor.
-The name of the add method
-must begin with add, followed by the element name.file you create a method setFile.
+ Depending on the type of the argument, Ant will perform some
+ conversions for you, see below.
+
+ parallel), your
+ class must implement the interface
+ org.apache.tools.ant.TaskContainer. If you do so, your
+ task can not support any other nested elements. See
+ below.public void addText(String)
+method. Note that Ant does not expand properties on
+the text it passes to the task.public method that takes no arguments and returns an
+Object type. The name of the create method must begin
+with create, followed by the element name. An add (or
+addConfigured) method must be a public void method that
+takes a single argument of an Object type with a
+no-argument constructor. The name of the add (addConfigured) method
+must begin with add (addConfigured),
+followed by the element name. For a more complete discussion see
+below.public void execute method, with no arguments, that
throws a BuildException. This method implements the task
itself.setXXX methods, at runtime.execute() is called at runtime. While the above initialization
+ execute() is called at runtime. While the above initialization
steps only occur once, the execute() method may be
called more than once, if the task is invoked more than once. For example,
if target1 and target2 both depend
@@ -110,6 +95,129 @@ itself.target3 twice.
+Ant will always expand properties before it passes the value of an +attribute to the corresponding setter method.
+ +The most common way to write an attribute setter is to use a
+java.lang.String argument. In this case Ant will pass
+the literal value (after property expansion) to your task. But there
+is more! If the argument of you setter method is
boolean, your method will be passed the value
+ true if the value specified in the build file is one of
+ true, yes, or on and
+ false otherwise.char or java.lang.Character, your
+ method will be passed the first character of the value specified in
+ the build file.int, short
+ and so on), Ant will convert the value of the attribute into this
+ type, thus making sure that you'll never receive input that is not a
+ number for that attribute.java.io.File, Ant will first determine whether the
+ value given in the build file represents an absolute path name. If
+ not, Ant will interpret the value as a path name relative to the
+ project's basedir.org.apache.tools.ant.types.Path, Ant will tokenize
+ the value specified in the build file, accepting : and
+ ; as path separators. Relative path names will be
+ interpreted as relative to the project's basedir.java.lang.Class, Ant will interpret the value
+ given in the build file as a Java class name and load the named
+ class from the system class loader.String argument, Ant will use this constructor to
+ create a new instance from the value given in the build file.org.apache.tools.ant.types.EnumeratedAttribute, Ant
+ will invoke this classes setValue method. Use this if
+ your task should support enumerated attributes (attributes with
+ values that must be part of a predefined set of values). See
+ org/apache/tools/ant/taskdefs/FixCRLF.java and the
+ inner AddAsisRemove class used in setCr
+ for an example.What happens if more than one setter method is present for a given
+attribute? A method taking a String argument will always
+lose against the more specific methods. If there are still more
+setters Ant could chose from, only one of them will be called, but we
+don't know which, this depends on the implementation of your Java
+virtual machine.
Let's assume your task shall support nested elements with the name
+inner. First of all, you need a class that represents
+this nested element. Often you simply want to use one of Ant's
+classes like org.apache.tools.ant.types.FileSet to
+support nested fileset elements.
Attributes of the nested elements or nested child elements of them +will be handled using the same mechanism used for tasks (i.e. setter +methods for attributes, addText for nested text and +create/add/addConfigured methods for child elements).
+ +Now you have a class NestedElement that is supposed to
+be used for your nested <inner> elements, you have
+three options:
public NestedElement createInner()public void addInner(NestedElement anInner)public void addConfiguredInner(NestedElement anInner)What is the difference?
+ +Option 1 makes the task create the instance of
+NestedElement, there are no restrictions on the type.
+For the options 2 and 3, Ant has to create an instance of
+NestedInner before it can pass it to the task, this
+means, NestedInner must have a public no-arg
+constructor. This is the only difference between options 1 and 2.
The difference between 2 and 3 is what Ant has done to the object
+before it passes it to the method. addInner will receive
+an object directly after the constructor has been called, while
+addConstructedInner gets the object after the
+attributes and nested children for this new object have been
+handled.
What happens if you use more than one of the options? Only one of +the methods will be called, but we don't know which, this depends on +the implementation of your Java virtual machine.
+ +The TaskContainer consists of a single method,
+addTask that basically is the same as an add method for nested elements. The task
+instances will be configured (their attributes and nested elements
+have been handled) when your task's execute method gets
+invoked, but not before that.
When we said execute would be
+called, we lied ;-). In fact, Ant will call the perform
+method in org.apache.tools.ant.Task, which in turn calls
+execute. This method makes sure that Build Events will be triggered. If you
+execute the task instances nested into your task, you should also
+invoke perform on these instances instead of
+execute.
Let's write our own task, which prints a message on the
System.out stream.
@@ -123,17 +231,17 @@ import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.Task;
public class MyVeryOwnTask extends Task {
- private String msg;
+ private String msg;
- // The method executing the task
- public void execute() throws BuildException {
- System.out.println(msg);
- }
+ // The method executing the task
+ public void execute() throws BuildException {
+ System.out.println(msg);
+ }
- // The setter for the "message" attribute
- public void setMessage(String msg) {
- this.msg = msg;
- }
+ // The setter for the "message" attribute
+ public void setMessage(String msg) {
+ this.msg = msg;
+ }
}