From 0ce95ee95e9e4f99930845d67d6789d23a8bf5fd Mon Sep 17 00:00:00 2001
From: Stefan Bodewig This document provides a step by step tutorial for writing
tasks.Tutorial: Writing Tasks
@@ -25,7 +26,7 @@
Content
-
+
Ant builds itself, we are using Ant too (why we would write -a task if not? :-) therefore we should use Ant for our build.
+a task if not? :-) therefore we should use Ant for our build.
We choose a directory as root directory. All things will be done here if I say nothing different. I will reference this directory as root-directory of our project. In this root-directory we -create a text file names build.xml. What should Ant do for us? +create a text file names build.xml. What should Ant do for us?
But after creating the jar we want to use our new Task. Therefore we need a
new target "use". Before we can use our new task we have to declare it with
-<taskdef>
[2]. And for easier process we change the default clause:
+<taskdef>
[2]. And for easier process we change the default clause:
<?xml version="1.0" encoding="ISO-8859-1"?> <project name="MyTask" basedir="." default="use"> @@ -145,10 +146,10 @@ new target "use". Before we can use our new task we have to declare it with </project>-Important is the classpath-attribute. Ant searches in its /lib directory for +
Important is the classpath-attribute. Ant searches in its /lib directory for tasks and our task isn't there. So we have to provide the right location.
-Now we can type in ant and all should work ... +
Now we can type in ant and all should work ...
Buildfile: build.xml @@ -178,7 +179,7 @@ setting a reference to the project and calling the execute() method.Setting a reference to the project? Could be interesting. The Project class gives us some nice abilities: access to Ant's logging facilities getting and setting -properties and much more. So we try to use that class: +properties and much more. So we try to use that class:
import org.apache.tools.ant.Project; @@ -200,7 +201,7 @@ and the execution with ant will show us the expected@@ -210,7 +211,7 @@ That class is integrated in Ant, get's the project-reference, provides documenta fiels, provides easier access to the logging facility and (very useful) gives you the exact location where in the buildfile this task instance is used. -use: Here is project 'MyTask'. -+Oki-doki - let's us use some of these: +
Oki-doki - let's us use some of these:
import org.apache.tools.ant.Task; @@ -227,27 +228,27 @@ public class HelloWorld extends Task { } }-which gives us when running +which gives us when running
use: [helloworld] Here is project 'MyTask'. [helloworld] I am used in: C:\tmp\anttests\MyFirstTask\build.xml:23:- +Accessing the Task's Project
The parent project of your custom task may be accessed through method
-getProject()
. However, do not call this from the custom task constructor, as the return value will be null. Later, when node attributes or text are set, or methodexecute()
is called, the Project object is available.Here are two useful methods from class Project: +
Here are two useful methods from class Project:
String getProperty(String propertyName)
String replaceProperties(String value)
The method replaceProperties()
is discussed further in section Nested Text.
Now we want to specify the text of our message (it seems that we are
rewriting the <echo/>
task :-). First we well do that with an attribute.
@@ -279,7 +280,7 @@ string provided there is written as build-failes-message. Here it's necessary be
the log() method can't handle a null value as parameter and throws a NullPointerException.
(Of course you can initialize the message with a default string.)
After that we have to modify our buildfile: +
After that we have to modify our buildfile:
<target name="use" description="Use the Task" depends="jar"> <taskdef name="helloworld" @@ -288,10 +289,10 @@ the log() method can't handle a null value as parameter and throws a Null <helloworld message="Hello World"/> </target>-That's all. +
That's all.
Some background for working with attributes: Ant supports any of these datatypes as -arguments of the set-method:
Maybe you have used the <echo>
task in a way like <echo>Hello World</echo>.
-For that you have to provide a public void addText(String text) method.
+For that you have to provide a public void addText(String text) method.
... public class HelloWorld extends Task { @@ -320,7 +321,7 @@ public class HelloWorld extends Task { ... }-But here properties are not resolved! For resolving properties we have to use +
But here properties are not resolved! For resolving properties we have to use Project's replaceProperties(String propname) : String method which takes the property name as argument and returns its value (or ${propname} if not set).
Thus, to replace properties in the nested node text, our method addText()
can be written as:
There are several ways for inserting the ability of handling nested elements. See the Manual [4] for other. -We use the first way of the three described ways. There are several steps for that:
set<attributename>
() methods). import java.util.Vector; import java.util.Iterator; @@ -377,7 +378,7 @@ import java.util.Iterator;Then we can use the new nested element. But where is xml-name for that defined? The mapping XML-name : classname is defined in the factory method: public classname createXML-name(). Therefore we write in -the buildfile +the buildfile
<helloworld> <message msg="Nested Element 1"/> @@ -385,11 +386,11 @@ the buildfile </helloworld>Note that if you choose to use methods 2 or 3, the class that represents the nested -element must be declared as
static+element must be declared asstatic
Our task in a little more complex version
-For recapitulation now a little refactored buildfile: +
For recapitulation now a little refactored buildfile:
<?xml version="1.0" encoding="ISO-8859-1"?> <project name="MyTask" basedir="." default="use"> @@ -614,7 +615,7 @@ target "test-jar" or you can download a nightly build from http://gump.covalent.net/jars/latest/ant/ant-testutil.jar [5].For executing the test and creating a report we need the optional tasks
<junit>
-and<junitreport>
. So we add to the buildfile: +and<junitreport>
. So we add to the buildfile:... <project name="MyTask" basedir="." default="test"> @@ -674,12 +675,12 @@ and+<junitreport>
. So we add to the buildfile: description="Runs unit tests and creates a report" /> ... -Back to the src/HelloWorldTest.java. We create a class extending BuildFileTest with String-constructor (JUnit-standard), a setUp() method initializing Ant and for each testcase (targets use.*) a testXX() -method invoking that target. +method invoking that target.
import org.apache.tools.ant.BuildFileTest; @@ -721,10 +722,10 @@ public class HelloWorldTest extends BuildFileTest { assertLogContaining("Nested Element 2"); } } -+
When starting ant we'll get a short message to STDOUT and -a nice HTML-report. +a nice HTML-report.
C:\tmp\anttests\MyFirstTask>ant Buildfile: build.xml @@ -753,20 +754,20 @@ test: BUILD SUCCESSFUL Total time: 7 seconds C:\tmp\anttests\MyFirstTask> -+ -
Try running Ant with the flag -verbose
. For more information, try flag -debug
.
For deeper issues, you may need to run the custom task code in a Java debugger. First, get the source for Ant and build it with debugging information.
-Since Ant is a large project, it can be a little tricky to set the right breakpoints. Here are two important breakpoints for version 1.8: +
Since Ant is a large project, it can be a little tricky to set the right breakpoints. Here are two important breakpoints for version 1.8:
main()
function: com.apache.tools.ant.launch.Launcher.main()
com.apache.tools.ant.UnknownElement.execute()
If you need to debug when a task attribute or the text is set, begin by debugging into method execute()
of your custom task. Then set breakpoints in other methods. This will ensure the class byte-code has been loaded by the Java VM.
This tutorial and its resources are available via BugZilla [6]. -The ZIP provided there contains
The last sources and the buildfile are also available here [7] inside the manual.
- -Used Links:Used Links:
+ [1] http://ant.apache.org/manual/properties.html#built-in-props
+ [2] http://ant.apache.org/manual/Tasks/taskdef.html
+ [3] http://ant.apache.org/manual/develop.html#set-magic
+ [4] http://ant.apache.org/manual/develop.html#nested-elements
+ [5] http://gump.covalent.net/jars/latest/ant/ant-testutil.jar
+ [6] http://issues.apache.org/bugzilla/show_bug.cgi?id=22570
+ [7] tutorial-writing-tasks-src.zip
+