You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ant.apache.org by bo...@apache.org on 2010/10/22 17:27:05 UTC
svn commit: r1026374 -
/ant/core/trunk/docs/manual/tutorial-writing-tasks.html
Author: bodewig
Date: Fri Oct 22 15:27:04 2010
New Revision: 1026374
URL: http://svn.apache.org/viewvc?rev=1026374&view=rev
Log:
found two non-closed tags (were missing the > sign). Had to make it well-formed XML so Emacs' nXML mode could assist me.
Modified:
ant/core/trunk/docs/manual/tutorial-writing-tasks.html
Modified: ant/core/trunk/docs/manual/tutorial-writing-tasks.html
URL: http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/tutorial-writing-tasks.html?rev=1026374&r1=1026373&r2=1026374&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/tutorial-writing-tasks.html (original)
+++ ant/core/trunk/docs/manual/tutorial-writing-tasks.html Fri Oct 22 15:27:04 2010
@@ -18,6 +18,7 @@
<head>
<title>Tutorial: Writing Tasks</title>
<link rel="stylesheet" type="text/css" href="stylesheets/style.css">
+ </link>
</head>
<body>
<h1>Tutorial: Writing Tasks</h1>
@@ -25,7 +26,7 @@
<p>This document provides a step by step tutorial for writing
tasks.</p>
<h2>Content</h2>
-<p><ul>
+<ul>
<li><a href="#buildenvironment">Set up the build environment</a></li>
<li><a href="#write1">Write the Task</a></li>
<li><a href="#use1">Use the Task</a></li>
@@ -39,16 +40,16 @@ tasks.</p>
<li><a href="#TestingTasks">Test the Task</a></li>
<li><a href="#Debugging">Debugging</a></li>
<li><a href="#resources">Resources</a></li>
-</ul></p>
+</ul>
<a name="buildenvironment"></a>
<h2>Set up the build environment</h2>
<p>Ant builds itself, we are using Ant too (why we would write
-a task if not? :-) therefore we should use Ant for our build.<p>
+a task if not? :-) therefore we should use Ant for our build.</p>
<p>We choose a directory as root directory. All things will be done
here if I say nothing different. I will reference this directory
as <i>root-directory</i> of our project. In this root-directory we
-create a text file names <i>build.xml</i>. What should Ant do for us?
+create a text file names <i>build.xml</i>. What should Ant do for us?</p>
<ul>
<li>compiles my stuff</li>
<li>make the jar, so that I can deploy it</li>
@@ -130,7 +131,7 @@ its <i>depends</i>-clause the "compile"
<p>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
<a href="http://ant.apache.org/manual/Tasks/taskdef.html" target="_blank">
-<code><taskdef></code> [2]</a>. And for easier process we change the default clause:
+<code><taskdef></code> [2]</a>. And for easier process we change the default clause:</p>
<pre class="code">
<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="MyTask" basedir="." default="<b>use</b>">
@@ -145,10 +146,10 @@ new target "use". Before we can use our
</project>
</pre>
-Important is the <i>classpath</i>-attribute. Ant searches in its /lib directory for
+<p>Important is the <i>classpath</i>-attribute. Ant searches in its /lib directory for
tasks and our task isn't there. So we have to provide the right location. </p>
-<p>Now we can type in <tt>ant</tt> and all should work ...
+<p>Now we can type in <tt>ant</tt> and all should work ...</p>
<pre class="output">
Buildfile: build.xml
@@ -178,7 +179,7 @@ setting a reference to the project and c
<p><i>Setting a reference to the project</i>? 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:</p>
<pre class="code">
import org.apache.tools.ant.Project;
@@ -200,7 +201,7 @@ and the execution with <tt>ant</tt> will
<pre class="output">
use:
Here is project 'MyTask'.
-</pre></p>
+</pre>
<a name="derivingFromTask"></a>
@@ -210,7 +211,7 @@ That class is integrated in Ant, get's t
fiels, provides easier access to the logging facility and (very useful) gives you
the exact location where <i>in the buildfile</i> this task instance is used.</p>
-<p>Oki-doki - let's us use some of these:
+<p>Oki-doki - let's us use some of these:</p>
<pre class="code">
import org.apache.tools.ant.Task;
@@ -227,27 +228,27 @@ public class HelloWorld extends Task {
}
}
</pre>
-which gives us when running
+<p>which gives us when running</p>
<pre class="output">
use:
[helloworld] Here is project 'MyTask'.
[helloworld] I am used in: C:\tmp\anttests\MyFirstTask\build.xml:23:
</pre>
-<a name="accessTaskProject">
+<a name="accessTaskProject"></a>
<h2>Accessing the Task's Project</h2>
<p>The parent project of your custom task may be accessed through method <code>getProject()</code>. 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 <code>execute()</code> is called, the Project object is available.</p>
-<p>Here are two useful methods from class Project:
+<p>Here are two useful methods from class Project:</p>
<ul>
<li><code>String getProperty(String propertyName)</code></li>
<li>
<code>String replaceProperties(String value)</code>
</li>
-</ul
-</p>
+</ul>
+
<p>The method <code>replaceProperties()</code> is discussed further in section <a href="#NestedText">Nested Text</a>.</p>
-<a name="attributes">
+<a name="attributes"></a>
<h2>Attributes</h2>
<p>Now we want to specify the text of our message (it seems that we are
rewriting the <code><echo/></code> task :-). First we well do that with an attribute.
@@ -279,7 +280,7 @@ string provided there is written as buil
the log() method can't handle a <i>null</i> value as parameter and throws a NullPointerException.
(Of course you can initialize the <i>message</i> with a default string.)</p>
-<p>After that we have to modify our buildfile:
+<p>After that we have to modify our buildfile:</p>
<pre class="code">
<target name="use" description="Use the Task" depends="jar">
<taskdef name="helloworld"
@@ -288,10 +289,10 @@ the log() method can't handle a <i>null<
<helloworld <b>message="Hello World"</b>/>
</target>
</pre>
-That's all.</p>
+<p>That's all.</p>
<p>Some background for working with attributes: Ant supports any of these datatypes as
-arguments of the set-method:<ul>
+arguments of the set-method:</p><ul>
<li>elementary data type like <i>int</i>, <i>long</i>, ...</li>
<li>its wrapper classes like <i>java.lang.Integer</i>, <i>java.lang.Long</i>, ...</li>
<li><i>java.lang.String</i></li>
@@ -308,7 +309,7 @@ would not set the message string to "${m
<a name="NestedText"></a>
<h2>Nested Text</h2>
<p>Maybe you have used the <code><echo></code> task in a way like <tt><echo>Hello World</echo></tt>.
-For that you have to provide a <tt>public void addText(String text)</tt> method.
+For that you have to provide a <tt>public void addText(String text)</tt> method.</p>
<pre class="code">
...
public class HelloWorld extends Task {
@@ -320,7 +321,7 @@ public class HelloWorld extends Task {
...
}
</pre>
-But here properties are <b>not</b> resolved! For resolving properties we have to use
+<p>But here properties are <b>not</b> resolved! For resolving properties we have to use
Project's <tt>replaceProperties(String propname) : String</tt> method which takes the
property name as argument and returns its value (or ${propname} if not set).</p>
<p>Thus, to replace properties in the nested node text, our method <code>addText()</code> can be written as:</p>
@@ -335,7 +336,7 @@ property name as argument and returns it
<h2>Nested Elements</h2>
<p>There are several ways for inserting the ability of handling nested elements. See
the <a href="http://ant.apache.org/manual/develop.html#nested-elements">Manual [4]</a> for other.
-We use the first way of the three described ways. There are several steps for that:<ol>
+We use the first way of the three described ways. There are several steps for that:</p><ol>
<li>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 (<code>set<attributename></code>() methods). </li>
@@ -343,7 +344,7 @@ We use the first way of the three descri
<li>A factory method instantiates an object, saves the reference in the list
and returns it to Ant Core.</li>
<li>The execute() method iterates over the list and evaluates its values.</li>
-</ol></p>
+</ol>
<pre class="code">
import java.util.Vector;
import java.util.Iterator;
@@ -377,7 +378,7 @@ import java.util.Iterator;
<p>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:
<tt>public <i>classname</i> create<i>XML-name</i>()</tt>. Therefore we write in
-the buildfile
+the buildfile</p>
<pre class="code">
<helloworld>
<message msg="Nested Element 1"/>
@@ -385,11 +386,11 @@ the buildfile
</helloworld>
</pre>
<p>Note that if you choose to use methods 2 or 3, the class that represents the nested
-element must be declared as <pre>static</pre></p>
+element must be declared as <code>static</code></p>
<a name="complex"></a>
<h2>Our task in a little more complex version</h2>
-<p>For recapitulation now a little refactored buildfile:
+<p>For recapitulation now a little refactored buildfile:</p>
<pre class="code">
<?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
http://gump.covalent.net/jars/latest/ant/ant-testutil.jar [5]</a>.</p>
<p>For executing the test and creating a report we need the optional tasks <code><junit></code>
-and <code><junitreport></code>. So we add to the buildfile:
+and <code><junitreport></code>. So we add to the buildfile:</p>
<pre class="code">
...
<font color="#9F9F9F"><project name="MyTask" basedir="." </font>default="test"<font color="#9F9F9F">></font>
@@ -674,12 +675,12 @@ and <code><junitreport></code>. So
description="Runs unit tests and creates a report"
/>
...
-</pre></p>
+</pre>
<p>Back to the <i>src/HelloWorldTest.java</i>. We create a class extending
<i>BuildFileTest</i> with String-constructor (JUnit-standard), a <i>setUp()</i>
method initializing Ant and for each testcase (targets use.*) a <i>testXX()</i>
-method invoking that target.
+method invoking that target.</p>
<pre class="code">
import org.apache.tools.ant.BuildFileTest;
@@ -721,10 +722,10 @@ public class HelloWorldTest extends Buil
assertLogContaining("Nested Element 2");
}
}
-</pre></p>
+</pre>
<p>When starting <tt>ant</tt> we'll get a short message to STDOUT and
-a nice HTML-report.
+a nice HTML-report.</p>
<pre class="output">
C:\tmp\anttests\MyFirstTask>ant
Buildfile: build.xml
@@ -753,20 +754,20 @@ test:
BUILD SUCCESSFUL
Total time: 7 seconds
C:\tmp\anttests\MyFirstTask>
-</pre></p>
+</pre>
-<a name="Debugging"></a
+<a name="Debugging"></a>
<h2>Debugging</h2>
<p>Try running Ant with the flag <code>-verbose</code>. For more information, try flag <code>-debug</code>.</p>
<p>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.</p>
-<p>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:
+<p>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:</p>
<ul>
<li>Initial <code>main()</code> function: <code>com.apache.tools.ant.launch.Launcher.main()</code></li>
<li>Task entry point: <code>com.apache.tools.ant.UnknownElement.execute()</code></li>
</ul>
-</p>
+
<p>If you need to debug when a task attribute or the text is set, begin by debugging into method <code>execute()</code> of your custom task. Then set breakpoints in other methods. This will ensure the class byte-code has been loaded by the Java VM.</p>
@@ -775,8 +776,8 @@ C:\tmp\anttests\MyFirstTask>
<h2>Resources</h2>
<p>This tutorial and its resources are available via
<a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=22570">BugZilla [6]</a>.
-The ZIP provided there contains<ul>
-<li>this tutorial</li>
+The ZIP provided there contains</p><ul>
+<li>this initial version of this tutorial</li>
<li>the buildfile (last version)</li>
<li>the source of the task (last version)</li>
<li>the source of the unit test (last version)</li>
@@ -785,21 +786,19 @@ The ZIP provided there contains<ul>
<li>generated jar</li>
<li>generated reports</li>
</ul>
-The last sources and the buildfile are also available
+<p>The last sources and the buildfile are also available
<a href="tutorial-writing-tasks-src.zip">here [7]</a> inside the manual.
</p>
-
-Used Links:<br>
- [1] <a href="http://ant.apache.org/manual/properties.html#built-in-props">http://ant.apache.org/manual/properties.html#built-in-props</a><br>
- [2] <a href="http://ant.apache.org/manual/Tasks/taskdef.html">http://ant.apache.org/manual/Tasks/taskdef.html</a><br>
- [3] <a href="http://ant.apache.org/manual/develop.html#set-magic">http://ant.apache.org/manual/develop.html#set-magic</a><br>
- [4] <a href="http://ant.apache.org/manual/develop.html#nested-elements">http://ant.apache.org/manual/develop.html#nested-elements</a><br>
- [5] <a href="http://gump.covalent.net/jars/latest/ant/ant-testutil.jar">http://gump.covalent.net/jars/latest/ant/ant-testutil.jar</a><br>
- [6] <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=22570">http://issues.apache.org/bugzilla/show_bug.cgi?id=22570</a><br>
- [7] <a href="tutorial-writing-tasks-src.zip">tutorial-writing-tasks-src.zip</a><br>
-
-
+<p>Used Links:<br></br>
+ [1] <a href="http://ant.apache.org/manual/properties.html#built-in-props">http://ant.apache.org/manual/properties.html#built-in-props</a><br></br>
+ [2] <a href="http://ant.apache.org/manual/Tasks/taskdef.html">http://ant.apache.org/manual/Tasks/taskdef.html</a><br></br>
+ [3] <a href="http://ant.apache.org/manual/develop.html#set-magic">http://ant.apache.org/manual/develop.html#set-magic</a><br></br>
+ [4] <a href="http://ant.apache.org/manual/develop.html#nested-elements">http://ant.apache.org/manual/develop.html#nested-elements</a><br></br>
+ [5] <a href="http://gump.covalent.net/jars/latest/ant/ant-testutil.jar">http://gump.covalent.net/jars/latest/ant/ant-testutil.jar</a><br></br>
+ [6] <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=22570">http://issues.apache.org/bugzilla/show_bug.cgi?id=22570</a><br></br>
+ [7] <a href="tutorial-writing-tasks-src.zip">tutorial-writing-tasks-src.zip</a><br></br>
+</p>
</body>
</html>