From 753a6c60f47f3ac4f270005b65e9d6481de8eb68 Mon Sep 17 00:00:00 2001 From: Ashlee Young Date: Fri, 23 Oct 2015 10:00:02 -0700 Subject: Adding maven and ant source trees Change-Id: I0a39b9add833a31b9c3f98d193983ae2f3a5a445 Signed-off-by: Ashlee Young --- .../manual/tutorial-writing-tasks.html | 819 +++++++++++++++++++++ 1 file changed, 819 insertions(+) create mode 100644 framework/src/ant/apache-ant-1.9.6/manual/tutorial-writing-tasks.html (limited to 'framework/src/ant/apache-ant-1.9.6/manual/tutorial-writing-tasks.html') diff --git a/framework/src/ant/apache-ant-1.9.6/manual/tutorial-writing-tasks.html b/framework/src/ant/apache-ant-1.9.6/manual/tutorial-writing-tasks.html new file mode 100644 index 00000000..c3b8a6a8 --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/tutorial-writing-tasks.html @@ -0,0 +1,819 @@ + + + + Tutorial: Writing Tasks + + + +

Tutorial: Writing Tasks

+ +

This document provides a step by step tutorial for writing +tasks.

+

Content

+ + + +

Set up the build environment

+

Apache Ant builds itself, we are using Ant too (why we would write +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?

+ +So the buildfile contains three targets. +
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<project name="MyTask" basedir="." default="jar">
+
+    <target name="clean" description="Delete all generated files">
+        <delete dir="classes"/>
+        <delete file="MyTasks.jar"/>
+    </target>
+
+    <target name="compile" description="Compiles the Task">
+        <javac srcdir="src" destdir="classes"/>
+    </target>
+
+    <target name="jar" description="JARs the Task">
+        <jar destfile="MyTask.jar" basedir="classes"/>
+    </target>
+
+</project>
+
+ +This buildfile uses often the same value (src, classes, MyTask.jar), so we should rewrite that +using <property>s. On second there are some handicaps: <javac> requires that the destination +directory exists; a call of "clean" with a non existing classes directory will fail; "jar" requires +the execution of some steps before. So the refactored code is: + +
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<project name="MyTask" basedir="." default="jar">
+
+    <property name="src.dir" value="src"/>
+    <property name="classes.dir" value="classes"/>
+
+    <target name="clean" description="Delete all generated files">
+        <delete dir="${classes.dir}" failonerror="false"/>
+        <delete file="${ant.project.name}.jar"/>
+    </target>
+
+    <target name="compile" description="Compiles the Task">
+        <mkdir dir="${classes.dir}"/>
+        <javac srcdir="${src.dir}" destdir="${classes.dir}"/>
+    </target>
+
+    <target name="jar" description="JARs the Task" depends="compile">
+        <jar destfile="${ant.project.name}.jar" basedir="${classes.dir}"/>
+    </target>
+
+</project>
+
+ant.project.name is one of the + +build-in properties [1] of Ant. + + + +

Write the Task

+ +Now we write the simplest Task - a HelloWorld-Task (what else?). Create a text file +HelloWorld.java in the src-directory with: +
+public class HelloWorld {
+    public void execute() {
+        System.out.println("Hello World");
+    }
+}
+
+and we can compile and jar it with ant (default target is "jar" and via +its depends-clause the "compile" is executed before). + + + + +

Use the Task

+

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:

+
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<project name="MyTask" basedir="." default="use">
+
+    ...
+
+    <target name="use" description="Use the Task" depends="jar">
+        <taskdef name="helloworld" classname="HelloWorld" classpath="${ant.project.name}.jar"/>
+        <helloworld/>
+    </target>
+
+</project>
+
+ +

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 ...

+
+Buildfile: build.xml
+
+compile:
+    [mkdir] Created dir: C:\tmp\anttests\MyFirstTask\classes
+    [javac] Compiling 1 source file to C:\tmp\anttests\MyFirstTask\classes
+
+jar:
+      [jar] Building jar: C:\tmp\anttests\MyFirstTask\MyTask.jar
+
+use:
+[helloworld] Hello World
+
+BUILD SUCCESSFUL
+Total time: 3 seconds
+
+ + + + +

Integration with TaskAdapter

+

Our class has nothing to do with Ant. It extends no superclass and implements +no interface. How does Ant know to integrate? Via name convention: our class provides +a method with signature public void execute(). This class is wrapped by Ant's +org.apache.tools.ant.TaskAdapter which is a task and uses reflection for +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:

+
+import org.apache.tools.ant.Project;
+
+public class HelloWorld {
+
+    private Project project;
+
+    public void setProject(Project proj) {
+        project = proj;
+    }
+
+    public void execute() {
+        String message = project.getProperty("ant.project.name");
+        project.log("Here is project '" + message + "'.", Project.MSG_INFO);
+    }
+}
+
+and the execution with ant will show us the expected +
+use:
+Here is project 'MyTask'.
+
+ + + +

Deriving from Ant's Task

+

Ok, that works ... But usually you will extend org.apache.tools.ant.Task. +That class is integrated in Ant, get's the project-reference, provides documentation +fields, provides easier access to the logging facility and (very useful) gives you +the exact location where in the buildfile this task instance is used.

+ +

Oki-doki - let's us use some of these:

+
+import org.apache.tools.ant.Task;
+
+public class HelloWorld extends Task {
+    public void execute() {
+        // use of the reference to Project-instance
+        String message = getProject().getProperty("ant.project.name");
+
+        // Task's log method
+        log("Here is project '" + message + "'.");
+
+        // where this task is used?
+        log("I am used in: " +  getLocation() );
+    }
+}
+
+

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 method execute() is called, the Project object is available.

+

Here are two useful methods from class Project:

+ + +

The method replaceProperties() is discussed further in section Nested Text.

+ + +

Attributes

+

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. +It is very easy - for each attribute provide a public void set<attributename>(<type> +newValue) method and Ant will do the rest via reflection.

+
+import org.apache.tools.ant.Task;
+import org.apache.tools.ant.BuildException;
+
+public class HelloWorld extends Task {
+
+    String message;
+    public void setMessage(String msg) {
+        message = msg;
+    }
+
+    public void execute() {
+        if (message==null) {
+            throw new BuildException("No message set.");
+        }
+        log(message);
+    }
+
+}
+
+

Oh, what's that in execute()? Throw a BuildException? Yes, that's the usual +way to show Ant that something important is missed and complete build should fail. The +string provided there is written as build-failes-message. Here it's necessary because +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:

+
+    <target name="use" description="Use the Task" depends="jar">
+        <taskdef name="helloworld"
+                 classname="HelloWorld"
+                 classpath="${ant.project.name}.jar"/>
+        <helloworld message="Hello World"/>
+    </target>
+
+

That's all.

+ +

Some background for working with attributes: Ant supports any of these datatypes as +arguments of the set-method:

+Before calling the set-method all properties are resolved. So a <helloworld message="${msg}"/> +would not set the message string to "${msg}" if there is a property "msg" with a set value. + + + +

Nested Text

+

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.

+
+...
+public class HelloWorld extends Task {
+    private String message;
+    ...
+    public void addText(String text) {
+        message = text;
+    }
+    ...
+}
+
+

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:

+
+    public void addText(String text) {
+        message = getProject().replaceProperties(text);
+    }
+
+ + + +

Nested Elements

+

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:

    +
  1. We create a class for collecting all the info the nested element should contain. + This class is created by the same rules for attributes and nested elements + as for the task (set<attributename>() methods).
    2. +
  2. The task holds multiple instances of this class in a list.
    3. +
  3. A factory method instantiates an object, saves the reference in the list + and returns it to Ant Core.
    4. +
  4. The execute() method iterates over the list and evaluates its values.
    5. +
+
+import java.util.Vector;
+import java.util.Iterator;
+...
+    public void execute() {
+        if (message!=null) log(message);
+        for (Iterator it=messages.iterator(); it.hasNext(); ) {      // 4
+            Message msg = (Message)it.next();
+            log(msg.getMsg());
+        }
+    }
+
+
+    Vector messages = new Vector();                                  // 2
+
+    public Message createMessage() {                                 // 3
+        Message msg = new Message();
+        messages.add(msg);
+        return msg;
+    }
+
+    public class Message {                                           // 1
+        public Message() {}
+
+        String msg;
+        public void setMsg(String msg) { this.msg = msg; }
+        public String getMsg() { return msg; }
+    }
+...
+
+

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

+
+        <helloworld>
+            <message msg="Nested Element 1"/>
+            <message msg="Nested Element 2"/>
+        </helloworld>
+
+

Note that if you choose to use methods 2 or 3, the class that represents the nested +element must be declared as static

+ + +

Our task in a little more complex version

+

For recapitulation now a little refactored buildfile:

+
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<project name="MyTask" basedir="." default="use">
+
+    <property name="src.dir" value="src"/>
+    <property name="classes.dir" value="classes"/>
+
+    <target name="clean" description="Delete all generated files">
+        <delete dir="${classes.dir}" failonerror="false"/>
+        <delete file="${ant.project.name}.jar"/>
+    </target>
+
+    <target name="compile" description="Compiles the Task">
+        <mkdir dir="${classes.dir}"/>
+        <javac srcdir="${src.dir}" destdir="${classes.dir}"/>
+    </target>
+
+    <target name="jar" description="JARs the Task" depends="compile">
+        <jar destfile="${ant.project.name}.jar" basedir="${classes.dir}"/>
+    </target>
+
+
+    <target name="use.init"
+            description="Taskdef the HelloWorld-Task"
+            depends="jar">
+        <taskdef name="helloworld"
+                 classname="HelloWorld"
+                 classpath="${ant.project.name}.jar"/>
+    </target>
+
+
+    <target name="use.without"
+            description="Use without any"
+            depends="use.init">
+        <helloworld/>
+    </target>
+
+    <target name="use.message"
+            description="Use with attribute 'message'"
+            depends="use.init">
+        <helloworld message="attribute-text"/>
+    </target>
+
+    <target name="use.fail"
+            description="Use with attribute 'fail'"
+            depends="use.init">
+        <helloworld fail="true"/>
+    </target>
+
+    <target name="use.nestedText"
+            description="Use with nested text"
+            depends="use.init">
+        <helloworld>nested-text</helloworld>
+    </target>
+
+    <target name="use.nestedElement"
+            description="Use with nested 'message'"
+            depends="use.init">
+        <helloworld>
+            <message msg="Nested Element 1"/>
+            <message msg="Nested Element 2"/>
+        </helloworld>
+    </target>
+
+
+    <target name="use"
+            description="Try all (w/out use.fail)"
+            depends="use.without,use.message,use.nestedText,use.nestedElement"
+    />
+
+</project>
+
+ +And the code of the task: +
+import org.apache.tools.ant.Task;
+import org.apache.tools.ant.BuildException;
+import java.util.Vector;
+import java.util.Iterator;
+
+/**
+ * The task of the tutorial.
+ * Print a message or let the build fail.
+ * @since 2003-08-19
+ */
+public class HelloWorld extends Task {
+
+
+    /** The message to print. As attribute. */
+    String message;
+    public void setMessage(String msg) {
+        message = msg;
+    }
+
+    /** Should the build fail? Defaults to false. As attribute. */
+    boolean fail = false;
+    public void setFail(boolean b) {
+        fail = b;
+    }
+
+    /** Support for nested text. */
+    public void addText(String text) {
+        message = text;
+    }
+
+
+    /** Do the work. */
+    public void execute() {
+        // handle attribute 'fail'
+        if (fail) throw new BuildException("Fail requested.");
+
+        // handle attribute 'message' and nested text
+        if (message!=null) log(message);
+
+        // handle nested elements
+        for (Iterator it=messages.iterator(); it.hasNext(); ) {
+            Message msg = (Message)it.next();
+            log(msg.getMsg());
+        }
+    }
+
+
+    /** Store nested 'message's. */
+    Vector messages = new Vector();
+
+    /** Factory method for creating nested 'message's. */
+    public Message createMessage() {
+        Message msg = new Message();
+        messages.add(msg);
+        return msg;
+    }
+
+    /** A nested 'message'. */
+    public class Message {
+        // Bean constructor
+        public Message() {}
+
+        /** Message to print. */
+        String msg;
+        public void setMsg(String msg) { this.msg = msg; }
+        public String getMsg() { return msg; }
+    }
+
+}
+
+ +And it works: +
+C:\tmp\anttests\MyFirstTask>ant
+Buildfile: build.xml
+
+compile:
+    [mkdir] Created dir: C:\tmp\anttests\MyFirstTask\classes
+    [javac] Compiling 1 source file to C:\tmp\anttests\MyFirstTask\classes
+
+jar:
+      [jar] Building jar: C:\tmp\anttests\MyFirstTask\MyTask.jar
+
+use.init:
+
+use.without:
+
+use.message:
+[helloworld] attribute-text
+
+use.nestedText:
+[helloworld] nested-text
+
+use.nestedElement:
+[helloworld]
+[helloworld]
+[helloworld]
+[helloworld]
+[helloworld] Nested Element 1
+[helloworld] Nested Element 2
+
+use:
+
+BUILD SUCCESSFUL
+Total time: 3 seconds
+C:\tmp\anttests\MyFirstTask>ant use.fail
+Buildfile: build.xml
+
+compile:
+
+jar:
+
+use.init:
+
+use.fail:
+
+BUILD FAILED
+C:\tmp\anttests\MyFirstTask\build.xml:36: Fail requested.
+
+Total time: 1 second
+C:\tmp\anttests\MyFirstTask>
+
+Next step: test ... + + + + +

Test the Task

+

We have written a test already: the use.* tasks in the buildfile. But its +difficult to test that automatically. Common (and in Ant) used is JUnit for +that. For testing tasks Ant provides a JUnit Rule org.apache.tools.ant.BuildFileRule. +This class provides some for testing tasks useful methods: +initialize Ant, load a buildfile, execute targets, capturing debug and run logs ...

+ +

In Ant it is usual that the testcase has the same name as the task with a prepending +Test, therefore we will create a file HelloWorldTest.java. Because we +have a very small project we can put this file into src directory (Ant's own +testclasses are in /src/testcases/...). Because we have already written our tests +for "hand-test" we can use that for automatic tests, too. But there is one little +problem we have to solve: all test supporting classes are not part of the binary +distribution of Ant. So you can build the special jar file from source distro with +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:

+
+...
+<project name="MyTask" basedir="." default="test">
+...
+    <property name="ant.test.lib" value="ant-testutil.jar"/>
+    <property name="report.dir"   value="report"/>
+    <property name="junit.out.dir.xml"  value="${report.dir}/junit/xml"/>
+    <property name="junit.out.dir.html" value="${report.dir}/junit/html"/>
+
+    <path id="classpath.run">
+        <path path="${java.class.path}"/>
+        <path location="${ant.project.name}.jar"/>
+    </path>
+
+    <path id="classpath.test">
+        <path refid="classpath.run"/>
+        <path location="${ant.test.lib}"/>
+    </path>
+
+    <target name="clean" description="Delete all generated files">
+        <delete failonerror="false" includeEmptyDirs="true">
+            <fileset dir="." includes="${ant.project.name}.jar"/>
+            <fileset dir="${classes.dir}"/>
+            <fileset dir="${report.dir}"/>
+        </delete>
+    </target>
+
+    <target name="compile" description="Compiles the Task">
+        <mkdir dir="${classes.dir}"/>
+        <javac srcdir="${src.dir}" destdir="${classes.dir}" classpath="${ant.test.lib}"/>
+    </target>
+...
+    <target name="junit" description="Runs the unit tests" depends="jar">
+        <delete dir="${junit.out.dir.xml}"/>
+        <mkdir  dir="${junit.out.dir.xml}"/>
+        <junit printsummary="yes" haltonfailure="no">
+            <classpath refid="classpath.test"/>
+            <formatter type="xml"/>
+            <batchtest fork="yes" todir="${junit.out.dir.xml}">
+                <fileset dir="${src.dir}" includes="**/*Test.java"/>
+            </batchtest>
+        </junit>
+    </target>
+
+    <target name="junitreport" description="Create a report for the rest result">
+        <mkdir dir="${junit.out.dir.html}"/>
+        <junitreport todir="${junit.out.dir.html}">
+            <fileset dir="${junit.out.dir.xml}">
+                <include name="*.xml"/>
+            </fileset>
+            <report format="frames" todir="${junit.out.dir.html}"/>
+        </junitreport>
+    </target>
+
+    <target name="test"
+            depends="junit,junitreport"
+            description="Runs unit tests and creates a report"
+    />
+...
+
+ +

Back to the src/HelloWorldTest.java. We create a class with a public +BuildFileRule field annotated with JUnit's @Rule annotation. As per +conventional JUnit4 tests, this class should have no constructors, or a default no-args +constructor, setup methods should be annotated with @Before, tear down methods +annotated with @After and any test method annotated with @Test. +

+import org.apache.tools.ant.BuildFileRule;
+import org.junit.Assert;
+import org.junit.Test;
+import org.junit.Before;
+import org.junit.Rule;
+import org.apache.tools.ant.AntAssert;
+import org.apache.tools.ant.BuildException;
+
+public class HelloWorldTest {
+
+    @Rule
+    public final BuildFileRule buildRule = new BuildFileRule();
+
+    @Before
+    public void setUp() {
+        // initialize Ant
+        buildRule.configureProject("build.xml");
+    }
+
+    @Test
+    public void testWithout() {
+        buildRule.executeTarget("use.without");
+        assertEquals("Message was logged but should not.", buildRule.getLog(), "");
+    }
+
+    public void testMessage() {
+        // execute target 'use.nestedText' and expect a message
+        // 'attribute-text' in the log
+        buildRule.executeTarget("use.message");
+        Assert.assertEquals("attribute-text", buildRule.getLog());
+    }
+
+    @Test
+    public void testFail() {
+        // execute target 'use.fail' and expect a BuildException
+        // with text 'Fail requested.'
+        try {
+           buildRule.executeTarget("use.fail");
+           fail("BuildException should have been thrown as task was set to fail");
+        } catch (BuildException ex) {
+            Assert.assertEquals("fail requested", ex.getMessage());
+        }
+
+    }
+
+    @Test
+    public void testNestedText() {
+        buildRule.executeTarget("use.nestedText");
+        Assert.assertEquals("nested-text", buildRule.getLog());
+    }
+
+    @Test
+    public void testNestedElement() {
+        buildRule.executeTarget("use.nestedElement");
+        AntAssert.assertContains("Nested Element 1", buildRule.getLog());
+        AntAssert.assertContains("Nested Element 2", buildRule.getLog());
+    }
+}
+
+ +

When starting ant we'll get a short message to STDOUT and +a nice HTML-report.

+
+C:\tmp\anttests\MyFirstTask>ant
+Buildfile: build.xml
+
+compile:
+    [mkdir] Created dir: C:\tmp\anttests\MyFirstTask\classes
+    [javac] Compiling 2 source files to C:\tmp\anttests\MyFirstTask\classes
+
+jar:
+      [jar] Building jar: C:\tmp\anttests\MyFirstTask\MyTask.jar
+
+junit:
+    [mkdir] Created dir: C:\tmp\anttests\MyFirstTask\report\junit\xml
+    [junit] Running HelloWorldTest
+    [junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 2,334 sec
+
+
+
+junitreport:
+    [mkdir] Created dir: C:\tmp\anttests\MyFirstTask\report\junit\html
+[junitreport] Using Xalan version: Xalan Java 2.4.1
+[junitreport] Transform time: 661ms
+
+test:
+
+BUILD SUCCESSFUL
+Total time: 7 seconds
+C:\tmp\anttests\MyFirstTask>
+
+ + + +

Debugging

+ +

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:

+ + +

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.

+ + + + +

Resources

+

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:
+  [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
+

+ + + -- cgit 1.2.3-korg