You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.

tutorial-writing-tasks.html 25 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759
  1. <html>
  2. <head>
  3. <title>Tutorial: Writing Tasks</title>
  4. <meta name="author" content="Jan Mat�rne">
  5. <style type="text/css">
  6. <!--
  7. .code { background: #EFEFEF; margin-top: }
  8. .output { color: #FFFFFF; background: #837A67; }
  9. -->
  10. </style>
  11. </head>
  12. <body>
  13. <h1>Tutorial: Writing Tasks</h1>
  14. <p>This document provides a step by step tutorial for writing
  15. tasks.</p>
  16. <h2>Content</h2>
  17. <p><ul>
  18. <li><a href="#buildenvironment">Set up the build environment</a></li>
  19. <li><a href="#write1">Write the Task</a></li>
  20. <li><a href="#use1">Use the Task</a></li>
  21. <li><a href="#TaskAdapter">Integration with TaskAdapter</a></li>
  22. <li><a href="#derivingFromTask">Deriving from Ant's Task</a></li>
  23. <li><a href="#attributes">Attributes</a></li>
  24. <li><a href="#NestedText">Nested Text</a></li>
  25. <li><a href="#NestedElements">Nested Elements</a></li>
  26. <li><a href="#complex">Our task in a little more complex version</a></li>
  27. <li><a href="#TestingTasks">Test the Task</a></li>
  28. <li><a href="#resources">Resources</a></li>
  29. </ul></p>
  30. <a name="buildenvironment"></a>
  31. <h2>Set up the build environment</h2>
  32. <p>Ant builds itself, we are using Ant too (why we would write
  33. a task if not? :-) therefore we should use Ant for our build.<p>
  34. <p>We choose a directory as root directory. All things will be done
  35. here if I say nothing different. I will reference this directory
  36. as <i>root-directory</i> of our project. In this root-directory we
  37. create a text file names <i>build.xml</i>. What should Ant do for us?
  38. <ul>
  39. <li>compiles my stuff</li>
  40. <li>make the jar, so that I can deploy it</li>
  41. <li>clean up everything</li>
  42. </ul>
  43. So the buildfile contains three targets.
  44. <pre class="code">
  45. &lt;?xml version="1.0" encoding="ISO-8859-1"?>
  46. &lt;project name="MyTask" basedir="." default="jar">
  47. &lt;target name="clean" description="Delete all generated files">
  48. &lt;delete dir="classes"/>
  49. &lt;delete file="MyTasks.jar"/>
  50. &lt;/target>
  51. &lt;target name="compile" description="Compiles the Task">
  52. &lt;javac srcdir="src" destdir="classes"/>
  53. &lt;/target>
  54. &lt;target name="jar" description="JARs the Task">
  55. &lt;jar destfile="MyTask.jar" basedir="classes"/>
  56. &lt;/target>
  57. &lt;/project>
  58. </pre>
  59. This buildfile uses often the same value (src, classes, MyTask.jar), so we should rewrite that
  60. using &lt;property>s. On second there are some handicaps: &lt;javac> requires that the destination
  61. directory exists; a call of "clean" with a non existing classes directory will fail; "jar" requires
  62. the execution of some steps bofore. So the refactored code is:
  63. <pre class="code">
  64. &lt;?xml version="1.0" encoding="ISO-8859-1"?>
  65. &lt;project name="MyTask" basedir="." default="jar">
  66. <b>&lt;property name="src.dir" value="src"/></b>
  67. <b>&lt;property name="classes.dir" value="classes"/></b>
  68. &lt;target name="clean" description="Delete all generated files">
  69. &lt;delete dir="<b>${classes.dir}</b>" <b>failonerror="false"</b>/>
  70. &lt;delete file="<b>${ant.project.name}.jar</b>"/>
  71. &lt;/target>
  72. &lt;target name="compile" description="Compiles the Task">
  73. <b>&lt;mkdir dir="${classes.dir}"/></b>
  74. &lt;javac srcdir="<b>${src.dir}</b>" destdir="${classes.dir}"/>
  75. &lt;/target>
  76. &lt;target name="jar" description="JARs the Task" <b>depends="compile"</b>>
  77. &lt;jar destfile="${ant.project.name}.jar" basedir="${classes.dir}"/>
  78. &lt;/target>
  79. &lt;/project>
  80. </pre>
  81. <i>ant.project.name</i> is one of the
  82. <a href="http://ant.apache.org/manual/using.html#built-in-props" target="_blank">
  83. build-in properties [1]</a> of Ant.
  84. <a name="write1"></a>
  85. <h2>Write the Task</h2>
  86. Now we write the simplest Task - a HelloWorld-Task (what else?). Create a text file
  87. <i>HelloWorld.java</i> in the src-directory with:
  88. <pre class="code">
  89. public class HelloWorld {
  90. public void execute() {
  91. System.out.println("Hello World");
  92. }
  93. }
  94. </pre>
  95. and we can compile and jar it with <tt>ant</tt> (default target is "jar" and via
  96. its <i>depends</i>-clause the "compile" is executed before).
  97. <a name="use1"></a>
  98. <h2>Use the Task</h2>
  99. <p>But after creating the jar we want to use our new Task. Therefore we need a
  100. new target "use". Before we can use our new task we have to declare it with
  101. <a href="http://ant.apache.org/manual/CoreTasks/taskdef.html" target="_blank">
  102. &lt;taskdef> [2]</a>. And for easier process we change the default clause:
  103. <pre class="code">
  104. &lt;?xml version="1.0" encoding="ISO-8859-1"?>
  105. &lt;project name="MyTask" basedir="." default="<b>use</b>">
  106. ...
  107. <b>&lt;target name="use" description="Use the Task" depends="jar">
  108. &lt;taskdef name="helloworld" classname="HelloWorld" classpath="${ant.project.name}.jar"/>
  109. &lt;helloworld/>
  110. &lt;/target></b>
  111. &lt;/project>
  112. </pre>
  113. Important is the <i>classpath</i>-attribute. Ant searches in its /lib directory for
  114. tasks and our task isn't there. So we have to provide the right location. </p>
  115. <p>Now we can type in <tt>ant</tt> and all should work ...
  116. <pre class="output">
  117. Buildfile: build.xml
  118. compile:
  119. [mkdir] Created dir: C:\tmp\anttests\MyFirstTask\classes
  120. [javac] Compiling 1 source file to C:\tmp\anttests\MyFirstTask\classes
  121. jar:
  122. [jar] Building jar: C:\tmp\anttests\MyFirstTask\MyTask.jar
  123. use:
  124. [helloworld] Hello World
  125. BUILD SUCCESSFUL
  126. Total time: 3 seconds
  127. </pre>
  128. <a name="TaskAdapter"></a>
  129. <h2>Integration with TaskAdapter</h2>
  130. <p>Our class has nothing to do with Ant. It extends no superclass and implements
  131. no interface. How does Ant know to integrate? Via name convention: our class provides
  132. a method with signature <tt>public void execute()</tt>. This class is wrapped by Ant's
  133. <tt>org.apache.tools.ant.TaskAdapter</tt> which is a task and uses reflection for
  134. setting a reference to the project and calling the <i>execute()</i> method.</p>
  135. <p><i>Setting a reference to the project</i>? Could be interesting. The Project class
  136. gives us some nice abilities: access to Ant's logging facilities getting and setting
  137. properties and much more. So we try to use that class:
  138. <pre class="code">
  139. import org.apache.tools.ant.Project;
  140. public class HelloWorld {
  141. private Project project;
  142. public void setProject(Project proj) {
  143. project = proj;
  144. }
  145. public void execute() {
  146. String message = project.getProperty("ant.project.name");
  147. project.log("Here is project '" + message + "'.", Project.MSG_INFO);
  148. }
  149. }
  150. </pre>
  151. and the execution with <tt>ant</tt> will show us the expected
  152. <pre class="output">
  153. use:
  154. Here is project 'MyTask'.
  155. </pre></p>
  156. <a name="derivingFromTask"></a>
  157. <h2>Deriving from Ant's Task</h2>
  158. <p>Ok, that works ... But usually you will extend <tt>org.apache.tools.ant.Task</tt>.
  159. That class is integrated in Ant, get's the project-reference, provides documentation
  160. fiels, provides easier access to the logging facility and (very useful) gives you
  161. the exact location where <i>in the buildfile</i> this task instance is used.</p>
  162. <p>Oki-doki - let's us use some of these:
  163. <pre class="code">
  164. import org.apache.tools.ant.Task;
  165. public class HelloWorld extends Task {
  166. public void execute() {
  167. // use of the reference to Project-instance
  168. String message = getProject().getProperty("ant.project.name");
  169. // Task's log method
  170. log("Here is project '" + message + "'.");
  171. // where this task is used?
  172. log("I am used in: " + getLocation() );
  173. }
  174. }
  175. </pre>
  176. which gives us when running
  177. <pre class="output">
  178. use:
  179. [helloworld] Here is project 'MyTask'.
  180. [helloworld] I am used in: C:\tmp\anttests\MyFirstTask\build.xml:23:
  181. </pre>
  182. <a name="attributes">
  183. <h2>Attributes</h2>
  184. <p>Now we want to specify the text of our message (it seems that we are
  185. rewriting the &lt;echo/> task :-). First we well do that with an attribute.
  186. It is very easy - for each attribute provide a <tt>public void set&lt;attributename>(&lt;type>
  187. newValue)</tt> method and Ant will do the rest via reflection.</p>
  188. <pre class="code">
  189. import org.apache.tools.ant.Task;
  190. import org.apache.tools.ant.BuildException;
  191. public class HelloWorld extends Task {
  192. String message;
  193. public void setMessage(String msg) {
  194. message = msg;
  195. }
  196. public void execute() {
  197. if (message==null) {
  198. throw new BuildException("No message set.");
  199. }
  200. log(message);
  201. }
  202. }
  203. </pre>
  204. <p>Oh, what's that in execute()? Throw a <i>BuildException</i>? Yes, that's the usual
  205. way to show Ant that something important is missed and complete build should fail. The
  206. string provided there is written as build-failes-message. Here it's necessary because
  207. the log() method can't handle a <i>null</i> value as parameter and throws a NullPointerException.
  208. (Of course you can initialize the <i>message</i> with a default string.)</p>
  209. <p>After that we have to modify our buildfile:
  210. <pre class="code">
  211. &lt;target name="use" description="Use the Task" depends="jar">
  212. &lt;taskdef name="helloworld"
  213. classname="HelloWorld"
  214. classpath="${ant.project.name}.jar"/>
  215. &lt;helloworld <b>message="Hello World"</b>/>
  216. &lt;/target>
  217. </pre>
  218. That's all.</p>
  219. <p>Some background for working with attributes: Ant supports any of these datatypes as
  220. arguments of the set-method:<ul>
  221. <li>elementary data type like <i>int</i>, <i>long</i>, ...</li>
  222. <li>its wrapper classes like <i>java.lang.Integer</i>, <i>java.lang.Long</i>, ...</li>
  223. <li><i>java.lang.String</i></li>
  224. <li>some more classes (e.g. <i>java.io.File</i>; see
  225. <a href="http://ant.apache.org/manual/develop.html#set-magic">Manual
  226. 'Writing Your Own Task' [3]</a>)</li>
  227. </ul>
  228. Before calling the set-method all properties are resolved. So a <tt>&lt;helloworld message="${msg}"/></tt>
  229. would not set the message string to "${msg}" if there is a property "msg" with a set value.
  230. <a name="NestedText"></a>
  231. <h2>Nested Text</h2>
  232. <p>Maybe you have used the &lt;echo> task in a way like <tt>&lt;echo>Hello World&lt;/echo></tt>.
  233. For that you have to provide a <tt>public void addText(String text)</tt> method.
  234. <pre class="code">
  235. ...
  236. public class HelloWorld extends Task {
  237. ...
  238. public void addText(String text) {
  239. message = text;
  240. }
  241. ...
  242. }
  243. </pre>
  244. But here properties are <b>not</b> resolved! For resolving properties we have to use
  245. Project's <tt>replaceProperties(String propname) : String</tt> method which takes the
  246. property name as argument and returns its value (or ${propname} if not set).</p>
  247. <a name="NestedElements"></a>
  248. <h2>Nested Elements</h2>
  249. <p>There are several ways for inserting the ability of handling nested elements. See
  250. the <a href="http://ant.apache.org/manual/develop.html#nested-elements">Manual [4]</a> for other.
  251. We use the first way of the three described ways. There are several steps for that:<ol>
  252. <li>We create a class for collecting all the infos the nested element should contain.
  253. This class is created by the same rules for attributes and nested elements
  254. as for the task (set&lt;attributename>() methods). </li>
  255. <li>The task holds multiple instances of this class in a list.</li>
  256. <li>A factory method instantiates an object, saves the reference in the list
  257. and returns it to Ant Core.</li>
  258. <li>The execute() method iterates over the list and evaluates its values.</li>
  259. </li></p>
  260. <pre class="code">
  261. import java.util.Vector;
  262. import java.util.Iterator;
  263. ...
  264. public void execute() {
  265. if (message!=null) log(message);
  266. for (Iterator it=messages.iterator(); it.hasNext(); ) { <b>// 4</b>
  267. Message msg = (Message)it.next();
  268. log(msg.getMsg());
  269. }
  270. }
  271. Vector messages = new Vector(); <b>// 2</b>
  272. public Message createMessage() { <b>// 3</b>
  273. Message msg = new Message();
  274. messages.add(msg);
  275. return msg;
  276. }
  277. public class Message { <b>// 1</b>
  278. public Message() {}
  279. String msg;
  280. public void setMsg(String msg) { this.msg = msg; }
  281. public String getMsg() { return msg; }
  282. }
  283. ...
  284. </pre>
  285. <p>Then we can use the new nested element. But where is xml-name for that defined?
  286. The mapping XML-name : classname is defined in the factory method:
  287. <tt>public <i>classname</i> create<i>XML-name</i>()</tt>. Therefore we write in
  288. the buildfile
  289. <pre class="code">
  290. &lt;helloworld>
  291. &lt;message msg="Nested Element 1"/>
  292. &lt;message msg="Nested Element 2"/>
  293. &lt;/helloworld>
  294. </pre>
  295. <a name="complex"></a>
  296. <h2>Our task in a little more complex version</h2>
  297. <p>For recapitulation now a little refactored buildfile:
  298. <pre class="code">
  299. &lt;?xml version="1.0" encoding="ISO-8859-1"?>
  300. &lt;project name="MyTask" basedir="." default="use">
  301. &lt;property name="src.dir" value="src"/>
  302. &lt;property name="classes.dir" value="classes"/>
  303. &lt;target name="clean" description="Delete all generated files">
  304. &lt;delete dir="${classes.dir}" failonerror="false"/>
  305. &lt;delete file="${ant.project.name}.jar"/>
  306. &lt;/target>
  307. &lt;target name="compile" description="Compiles the Task">
  308. &lt;mkdir dir="${classes.dir}"/>
  309. &lt;javac srcdir="${src.dir}" destdir="${classes.dir}"/>
  310. &lt;/target>
  311. &lt;target name="jar" description="JARs the Task" depends="compile">
  312. &lt;jar destfile="${ant.project.name}.jar" basedir="${classes.dir}"/>
  313. &lt;/target>
  314. &lt;target name="use.init"
  315. description="Taskdef the HelloWorld-Task"
  316. depends="jar">
  317. &lt;taskdef name="helloworld"
  318. classname="HelloWorld"
  319. classpath="${ant.project.name}.jar"/>
  320. &lt;/target>
  321. &lt;target name="use.without"
  322. description="Use without any"
  323. depends="use.init">
  324. &lt;helloworld/>
  325. &lt;/target>
  326. &lt;target name="use.message"
  327. description="Use with attribute 'message'"
  328. depends="use.init">
  329. &lt;helloworld message="attribute-text"/>
  330. &lt;/target>
  331. &lt;target name="use.fail"
  332. description="Use with attribute 'fail'"
  333. depends="use.init">
  334. &lt;helloworld fail="true"/>
  335. &lt;/target>
  336. &lt;target name="use.nestedText"
  337. description="Use with nested text"
  338. depends="use.init">
  339. &lt;helloworld>nested-text&lt;/helloworld>
  340. &lt;/target>
  341. &lt;target name="use.nestedElement"
  342. description="Use with nested 'message'"
  343. depends="use.init">
  344. &lt;helloworld>
  345. &lt;message msg="Nested Element 1"/>
  346. &lt;message msg="Nested Element 2"/>
  347. &lt;/helloworld>
  348. &lt;/target>
  349. &lt;target name="use"
  350. description="Try all (w/out use.fail)"
  351. depends="use.without,use.message,use.nestedText,use.nestedElement"
  352. />
  353. &lt;/project>
  354. </pre>
  355. And the code of the task:
  356. <pre class="code">
  357. import org.apache.tools.ant.Task;
  358. import org.apache.tools.ant.BuildException;
  359. import java.util.Vector;
  360. import java.util.Iterator;
  361. /**
  362. * The task of the tutorial.
  363. * Print a message or let the build fail.
  364. * @author Jan Mat�rne
  365. * @since 2003-08-19
  366. */
  367. public class HelloWorld extends Task {
  368. /** The message to print. As attribute. */
  369. String message;
  370. public void setMessage(String msg) {
  371. message = msg;
  372. }
  373. /** Should the build fail? Defaults to <i>false</i>. As attribute. */
  374. boolean fail = false;
  375. public void setFail(boolean b) {
  376. fail = b;
  377. }
  378. /** Support for nested text. */
  379. public void addText(String text) {
  380. message = text;
  381. }
  382. /** Do the work. */
  383. public void execute() {
  384. // handle attribute 'fail'
  385. if (fail) throw new BuildException("Fail requested.");
  386. // handle attribute 'message' and nested text
  387. if (message!=null) log(message);
  388. // handle nested elements
  389. for (Iterator it=messages.iterator(); it.hasNext(); ) {
  390. Message msg = (Message)it.next();
  391. log(msg.getMsg());
  392. }
  393. }
  394. /** Store nested 'message's. */
  395. Vector messages = new Vector();
  396. /** Factory method for creating nested 'message's. */
  397. public Message createMessage() {
  398. Message msg = new Message();
  399. messages.add(msg);
  400. return msg;
  401. }
  402. /** A nested 'message'. */
  403. public class Message {
  404. // Bean constructor
  405. public Message() {}
  406. /** Message to print. */
  407. String msg;
  408. public void setMsg(String msg) { this.msg = msg; }
  409. public String getMsg() { return msg; }
  410. }
  411. }
  412. </pre>
  413. And it works:
  414. <pre class="output">
  415. C:\tmp\anttests\MyFirstTask>ant
  416. Buildfile: build.xml
  417. compile:
  418. [mkdir] Created dir: C:\tmp\anttests\MyFirstTask\classes
  419. [javac] Compiling 1 source file to C:\tmp\anttests\MyFirstTask\classes
  420. jar:
  421. [jar] Building jar: C:\tmp\anttests\MyFirstTask\MyTask.jar
  422. use.init:
  423. use.without:
  424. use.message:
  425. [helloworld] attribute-text
  426. use.nestedText:
  427. [helloworld] nested-text
  428. use.nestedElement:
  429. [helloworld]
  430. [helloworld]
  431. [helloworld]
  432. [helloworld]
  433. [helloworld] Nested Element 1
  434. [helloworld] Nested Element 2
  435. use:
  436. BUILD SUCCESSFUL
  437. Total time: 3 seconds
  438. C:\tmp\anttests\MyFirstTask>ant use.fail
  439. Buildfile: build.xml
  440. compile:
  441. jar:
  442. use.init:
  443. use.fail:
  444. BUILD FAILED
  445. C:\tmp\anttests\MyFirstTask\build.xml:36: Fail requested.
  446. Total time: 1 second
  447. C:\tmp\anttests\MyFirstTask>
  448. </pre>
  449. Next step: test ...
  450. <a name="TestingTasks"></a>
  451. <h2>Test the Task</h2>
  452. <p>We have written a test already: the use.* tasks in the buildfile. But its
  453. difficult to test that automatically. Common (and in Ant) used is JUnit for
  454. that. For testing tasks Ant provides a baseclass <tt>org.apache.tools.ant.BuildFileTest</tt>.
  455. This class extends <tt>junit.framework.TestCase</tt> and can therefore be integrated
  456. into the unit tests. But this class provides some for testing tasks useful methods:
  457. initialize Ant, load a buildfile, execute targets,
  458. expecting BuildExceptions with a specified text, expect a special text
  459. in the output log ... </p>
  460. <p>In Ant it is usual that the testcase has the same name as the task with a prepending
  461. <i>Test</i>, therefore we will create a file <i>HelloWorldTest.java</i>. Because we
  462. have a very small project we can put this file into <i>src</i> directory (Ant's own
  463. testclasses are in /src/testcases/...). Because we have already written our tests
  464. for "hand-test" we can use that for automatic tests, too. But there is one little
  465. problem we have to solve: all test supporting classes are not part of the binary
  466. distribution of Ant. So you can build the special jar file from source distro with
  467. target "test-jar" or you can download a nightly build from
  468. <a href="http://gump.covalent.net/jars/latest/ant/ant-testutil.jar">
  469. http://gump.covalent.net/jars/latest/ant/ant-testutil.jar [5]</a>.</p>
  470. <p>For executing the test and creating a report we need the optional tasks &lt;junit>
  471. and &lt;junitreport>. So we add to the buildfile:
  472. <pre class="code">
  473. ...
  474. <font color="#9F9F9F">&lt;project name="MyTask" basedir="." </font>default="test"<font color="#9F9F9F">&gt;</font>
  475. ...
  476. &lt;property name="ant.test.lib" value="ant-testutil.jar"/>
  477. &lt;property name="report.dir" value="report"/>
  478. &lt;property name="junit.out.dir.xml" value="${report.dir}/junit/xml"/>
  479. &lt;property name="junit.out.dir.html" value="${report.dir}/junit/html"/>
  480. &lt;path id="classpath.run">
  481. &lt;path path="${java.class.path}"/>
  482. &lt;path location="${ant.project.name}.jar"/>
  483. &lt;/path>
  484. &lt;path id="classpath.test">
  485. &lt;path refid="classpath.run"/>
  486. &lt;path location="${ant.test.lib}"/>
  487. &lt;/path>
  488. &lt;target name="clean" description="Delete all generated files">
  489. &lt;delete failonerror="false" includeEmptyDirs="true">
  490. &lt;fileset dir="." includes="${ant.project.name}.jar"/>
  491. &lt;fileset dir="${classes.dir}"/>
  492. &lt;fileset dir="${report.dir}"/>
  493. &lt;/delete>
  494. &lt;/target>
  495. <font color="#9F9F9F">&lt;target name="compile" description="Compiles the Task">
  496. &lt;mkdir dir="${classes.dir}"/>
  497. &lt;javac srcdir="${src.dir}" destdir="${classes.dir}" </font>classpath="${ant.test.lib}"<font color="#9F9F9F">/>
  498. &lt;/target></font>
  499. ...
  500. &lt;target name="junit" description="Runs the unit tests" depends="jar">
  501. &lt;delete dir="${junit.out.dir.xml}" />
  502. &lt;mkdir dir="${junit.out.dir.xml}" />
  503. &lt;junit printsummary="yes" haltonfailure="no">
  504. &lt;classpath refid="classpath.test"/>
  505. &lt;formatter type="xml"/>
  506. &lt;batchtest fork="yes" todir="${junit.out.dir.xml}">
  507. &lt;fileset dir="${src.dir}" includes="**/*Test.java"/>
  508. &lt;/batchtest>
  509. &lt;/junit>
  510. &lt;/target>
  511. &lt;target name="junitreport" description="Create a report for the rest result">
  512. &lt;mkdir dir="${junit.out.dir.html}" />
  513. &lt;junitreport todir="${junit.out.dir.html}">
  514. &lt;fileset dir="${junit.out.dir.xml}">
  515. &lt;include name="*.xml"/>
  516. &lt;/fileset>
  517. &lt;report format="frames" todir="${junit.out.dir.html}"/>
  518. &lt;/junitreport>
  519. &lt;/target>
  520. &lt;target name="test"
  521. depends="junit,junitreport"
  522. description="Runs unit tests and creates a report"
  523. />
  524. ...
  525. </pre></p>
  526. <p>Back to the <i>src/HelloWorldTest.java</i>. We create a class extending
  527. <i>BuildFileTest</i> with String-constructor (JUnit-standard), a <i>setUp()</i>
  528. method initializing Ant and for each testcase (targets use.*) a <i>testXX()</i>
  529. method invoking that target.
  530. <pre class="code">
  531. import org.apache.tools.ant.BuildFileTest;
  532. public class HelloWorldTest extends BuildFileTest {
  533. public HelloWorldTest(String s) {
  534. super(s);
  535. }
  536. public void setUp() {
  537. // initialize Ant
  538. configureProject("build.xml");
  539. }
  540. public void testWithout() {
  541. executeTarget("use.without");
  542. assertEquals("Message was logged but should not.", getLog(), "");
  543. }
  544. public void testMessage() {
  545. // execute target 'use.nestedText' and expect a message
  546. // 'attribute-text' in the log
  547. expectLog("use.message", "attribute-text");
  548. }
  549. public void testFail() {
  550. // execute target 'use.fail' and expect a BuildException
  551. // with text 'Fail requested.'
  552. expectBuildException("use.fail", "Fail requested.");
  553. }
  554. public void testNestedText() {
  555. expectLog("use.nestedText", "nested-text");
  556. }
  557. public void testNestedElement() {
  558. executeTarget("use.nestedElement");
  559. assertLogContaining("Nested Element 1");
  560. assertLogContaining("Nested Element 2");
  561. }
  562. }
  563. </pre></p>
  564. <p>When starting <tt>ant</tt> we'll get a short message to STDOUT and
  565. a nice HTML-report.
  566. <pre class="output">
  567. C:\tmp\anttests\MyFirstTask>ant
  568. Buildfile: build.xml
  569. compile:
  570. [mkdir] Created dir: C:\tmp\anttests\MyFirstTask\classes
  571. [javac] Compiling 2 source files to C:\tmp\anttests\MyFirstTask\classes
  572. jar:
  573. [jar] Building jar: C:\tmp\anttests\MyFirstTask\MyTask.jar
  574. junit:
  575. [mkdir] Created dir: C:\tmp\anttests\MyFirstTask\report\junit\xml
  576. [junit] Running HelloWorldTest
  577. [junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 2,334 sec
  578. junitreport:
  579. [mkdir] Created dir: C:\tmp\anttests\MyFirstTask\report\junit\html
  580. [junitreport] Using Xalan version: Xalan Java 2.4.1
  581. [junitreport] Transform time: 661ms
  582. test:
  583. BUILD SUCCESSFUL
  584. Total time: 7 seconds
  585. C:\tmp\anttests\MyFirstTask>
  586. </pre></p>
  587. <a name="resources"></a>
  588. <h2>Resources</h2>
  589. <p>This tutorial and its resources are available via
  590. <a href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=22570">BugZilla [6]</a>.
  591. The ZIP provided there contains<ul>
  592. <li>this tutorial</li>
  593. <li>the buildfile (last version)</li>
  594. <li>the source of the task (last version)</li>
  595. <li>the source of the unit test (last version)</li>
  596. <li>the ant-testutil.jar (nightly build of 2003-08-18)</li>
  597. <li>generated classes</li>
  598. <li>generated jar</li>
  599. <li>generated reports</li>
  600. </ul>
  601. The last sources and the buildfile are also available
  602. <a href="tutorial-writing-tasks-src.zip">here [7]</a> inside the manual.
  603. </p>
  604. Used Links:<br>
  605. &nbsp;&nbsp;[1] <a href="http://ant.apache.org/manual/using.html#built-in-props">http://ant.apache.org/manual/using.html#built-in-props</a><br>
  606. &nbsp;&nbsp;[2] <a href="http://ant.apache.org/manual/CoreTasks/taskdef.html">http://ant.apache.org/manual/CoreTasks/taskdef.html</a><br>
  607. &nbsp;&nbsp;[3] <a href="http://ant.apache.org/manual/develop.html#set-magic">http://ant.apache.org/manual/develop.html#set-magic</a><br>
  608. &nbsp;&nbsp;[4] <a href="http://ant.apache.org/manual/develop.html#nested-elements">http://ant.apache.org/manual/develop.html#nested-elements</a><br>
  609. &nbsp;&nbsp;[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>
  610. &nbsp;&nbsp;[6] <a href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=22570">http://nagoya.apache.org/bugzilla/show_bug.cgi?id=22570</a><br>
  611. &nbsp;&nbsp;[7] <a href="tutorial-writing-tasks-src.zip">tutorial-writing-tasks-src.zip</a><br>
  612. <hr>
  613. <p align="center">Copyright &copy; 2003-2004 The Apache Software Foundation. All rights
  614. Reserved.</p>
  615. </body>
  616. </html>