Menu
▾
▴
[Tm4j-commits] tm4j/lib/ant/apache-ant-1.7.0/docs/manual LICENSE, NONE, 1.1 antexternal.html, NONE, 1.1 anttaskslist.html, NONE, 1.1 base_task_classes.html, NONE, 1.1 clonevm.html, NONE, 1.1 conceptstypeslist.html, NONE, 1.1 coretasklist.html, NONE, 1.1 cover.html, NONE, 1.1 credits.html, NONE, 1.1 develop.html, NONE, 1.1 developlist.html, NONE, 1.1 dirtasks.html, NONE, 1.1 favicon.ico, NONE, 1.1 feedback.html, NONE, 1.1 ide.html, NONE, 1.1 index.html, NONE, 1.1 inputhandler.html, NONE, 1.1 install.html, NONE, 1.1 installlist.html, NONE, 1.1 intro.html, NONE, 1.1 javacprops.html, NONE, 1.1 listeners.html, NONE, 1.1 optionaltasklist.html, NONE, 1.1 platform.html, NONE, 1.1 proxy.html, NONE, 1.1 running.html, NONE, 1.1 runninglist.html, NONE, 1.1 sysclasspath.html, NONE, 1.1 tasksoverview.html, NONE, 1.1 toc.html, NONE, 1.1 tutorial-HelloWorldWithAnt.html, NONE, 1.1 tutorial-tasks-filesets-properties.html, NONE, 1.1 tutorial-tasks-filesets-properties.zip, NONE, 1.1 tutorial-writing-tasks-src.zip, NONE, 1.1 tutorial-writing-tasks.html, NONE, 1.1 tutorials.html, NONE, 1.1 using.html, NONE, 1.1 usinglist.html, NONE, 1.1
Update of /cvsroot/tm4j/tm4j/lib/ant/apache-ant-1.7.0/docs/manual In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv12860/lib/ant/apache-ant-1.7.0/docs/manual Added Files: LICENSE antexternal.html anttaskslist.html base_task_classes.html clonevm.html conceptstypeslist.html coretasklist.html cover.html credits.html develop.html developlist.html dirtasks.html favicon.ico feedback.html ide.html index.html inputhandler.html install.html installlist.html intro.html javacprops.html listeners.html optionaltasklist.html platform.html proxy.html running.html runninglist.html sysclasspath.html tasksoverview.html toc.html tutorial-HelloWorldWithAnt.html tutorial-tasks-filesets-properties.html tutorial-tasks-filesets-properties.zip tutorial-writing-tasks-src.zip tutorial-writing-tasks.html tutorials.html using.html usinglist.html Log Message: Update 4 years old ant. --- NEW FILE: inputhandler.html --- <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Language" content="en-us"> <link rel="stylesheet" type="text/css" href="stylesheets/style.css"> <title>InputHandler</title> </head> <body> <h1>InputHandler</h1> <h2>Overview</h2> <p>When a task wants to prompt a user for input, it doesn't simply read the input from the console as this would make it impossible to embed Ant in an IDE. Instead it asks an implementation of the <code>org.apache.tools.ant.input.InputHandler</code> interface to prompt the user and hand the user input back to the task.</p> <p>To do this, the task creates an <code>InputRequest</code> object and passes it to the <code>InputHandler</code> Such an <code>InputRequest</code> may know whether a given user input is valid and the <code>InputHandler</code> is supposed to reject all invalid input.</p> <p>Exactly one <code>InputHandler</code> instance is associated with every Ant process, users can specify the implementation using the <code>-inputhandler</code> command line switch.</p> <h2>InputHandler</h2> <p>The <code>InputHandler</code> interface contains exactly one method</p> <pre> void handleInput(InputRequest request) throws org.apache.tools.ant.BuildException; </pre> <p>with some pre- and postconditions. The main postcondition is that this method must not return unless the <code>request</code> considers the user input valid, it is allowed to throw an exception in this situation.</p> <p>Ant comes with three built-in implementations of this interface:</p> <h3><a name="defaulthandler">DefaultInputHandler</a></h3> <p>This is the implementation you get, when you don't use the <code>-inputhandler</code> command line switch at all. This implementation will print the prompt encapsulated in the <code>request</code> object to Ant's logging system and re-prompt for input until the user enters something that is considered valid input by the <code>request</code> object. Input will be read from the console and the user will need to press the Return key.</p> <h3>PropertyFileInputHandler</h3> <p>This implementation is useful if you want to run unattended build processes. It reads all input from a properties file and makes the build fail if it cannot find valid input in this file. The name of the properties file must be specified in the Java system property <code>ant.input.properties</code>.</p> <p>The prompt encapsulated in a <code>request</code> will be used as the key when looking up the input inside the properties file. If no input can be found, the input is considered invalid and an exception will be thrown.</p> <p><strong>Note</strong> that <code>ant.input.properties</code> must be a Java system property, not an Ant property. I.e. you cannot define it as a simple parameter to <code>ant</code>, but you can define it inside the <code>ANT_OPTS</code> environment variable.</p> <h3>GreedyInputHandler</h3> <p>Like the default implementation, this InputHandler reads from standard input. However, it consumes <i>all</i> available input. This behavior is useful for sending Ant input via an OS pipe. <b>Since Ant 1.7</b>.</p> <h2>InputRequest</h2> <p>Instances of <code>org.apache.tools.ant.input.InputRequest</code> encapsulate the information necessary to ask a user for input and validate this input.</p> <p>The instances of <code>InputRequest</code> itself will accept any input, but subclasses may use stricter validations. <code>org.apache.tools.ant.input.MultipleChoiceInputRequest</code> should be used if the user input must be part of a predefined set of choices.</p> </html> --- NEW FILE: tutorial-writing-tasks.html --- <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> <html> <head> <title>Tutorial: Writing Tasks</title> <meta name="author" content="Jan Matèrne"> <style type="text/css"> <!-- .code { background: #EFEFEF; margin-top: } .output { color: #FFFFFF; background: #837A67; } --> </style> </head> <body> <h1>Tutorial: Writing Tasks</h1> <p>This document provides a step by step tutorial for writing tasks.</p> <h2>Content</h2> <p><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> <li><a href="#TaskAdapter">Integration with TaskAdapter</a></li> <li><a href="#derivingFromTask">Deriving from Ant's Task</a></li> <li><a href="#attributes">Attributes</a></li> <li><a href="#NestedText">Nested Text</a></li> <li><a href="#NestedElements">Nested Elements</a></li> <li><a href="#complex">Our task in a little more complex version</a></li> <li><a href="#TestingTasks">Test the Task</a></li> <li><a href="#resources">Resources</a></li> </ul></p> <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> <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? <ul> <li>compiles my stuff</li> <li>make the jar, so that I can deploy it</li> <li>clean up everything</li> </ul> So the buildfile contains three targets. <pre class="code"> <?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> </pre> This buildfile uses often the same value (src, classes, MyTask.jar), so we should rewrite that using <code><property></code>s. On second there are some handicaps: <code><javac></code> 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 bofore. So the refactored code is: <pre class="code"> <?xml version="1.0" encoding="ISO-8859-1"?> <project name="MyTask" basedir="." default="jar"> <b><property name="src.dir" value="src"/></b> <b><property name="classes.dir" value="classes"/></b> <target name="clean" description="Delete all generated files"> <delete dir="<b>${classes.dir}</b>" <b>failonerror="false"</b>/> <delete file="<b>apache-ant.jar</b>"/> </target> <target name="compile" description="Compiles the Task"> <b><mkdir dir="${classes.dir}"/></b> <javac srcdir="<b>src</b>" destdir="${classes.dir}"/> </target> <target name="jar" description="JARs the Task" <b>depends="compile"</b>> <jar destfile="apache-ant.jar" basedir="${classes.dir}"/> </target> </project> </pre> <i>ant.project.name</i> is one of the <a href="http://ant.apache.org/manual/using.html#built-in-props" target="_blank"> build-in properties [1]</a> of Ant. <a name="write1"></a> <h2>Write the Task</h2> Now we write the simplest Task - a HelloWorld-Task (what else?). Create a text file <i>HelloWorld.java</i> in the src-directory with: <pre class="code"> public class HelloWorld { public void execute() { System.out.println("Hello World"); } } </pre> and we can compile and jar it with <tt>ant</tt> (default target is "jar" and via its <i>depends</i>-clause the "compile" is executed before). <a name="use1"></a> <h2>Use the Task</h2> <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/CoreTasks/taskdef.html" target="_blank"> <code><taskdef></code> [2]</a>. And for easier process we change the default clause: <pre class="code"> <?xml version="1.0" encoding="ISO-8859-1"?> <project name="MyTask" basedir="." default="<b>use</b>"> ... <b><target name="use" description="Use the Task" depends="jar"> <taskdef name="helloworld" classname="HelloWorld" classpath="apache-ant.jar"/> <helloworld/> </target></b> </project> </pre> 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 ... <pre class="output"> 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 </pre> <a name="TaskAdapter"></a> <h2>Integration with TaskAdapter</h2> <p>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 <tt>public void execute()</tt>. This class is wrapped by Ant's <tt>org.apache.tools.ant.TaskAdapter</tt> which is a task and uses reflection for setting a reference to the project and calling the <i>execute()</i> method.</p> <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: <pre class="code"> 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); } } </pre> and the execution with <tt>ant</tt> will show us the expected <pre class="output"> use: Here is project 'MyTask'. </pre></p> <a name="derivingFromTask"></a> <h2>Deriving from Ant's Task</h2> <p>Ok, that works ... But usually you will extend <tt>org.apache.tools.ant.Task</tt>. That class is integrated in Ant, get's the project-reference, provides documentation 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: <pre class="code"> 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() ); } } </pre> which gives us when running <pre class="output"> use: [helloworld] Here is project 'MyTask'. [helloworld] I am used in: C:\tmp\anttests\MyFirstTask\build.xml:23: </pre> <a name="attributes"> <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. It is very easy - for each attribute provide a <tt>public void set<code><attributename></code>(<code><type></code> newValue)</tt> method and Ant will do the rest via reflection.</p> <pre class="code"> 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); } } </pre> <p>Oh, what's that in execute()? Throw a <i>BuildException</i>? 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 <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: <pre class="code"> <target name="use" description="Use the Task" depends="jar"> <taskdef name="helloworld" classname="HelloWorld" classpath="apache-ant.jar"/> <helloworld <b>message="Hello World"</b>/> </target> </pre> That's all.</p> <p>Some background for working with attributes: Ant supports any of these datatypes as arguments of the set-method:<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> <li>some more classes (e.g. <i>java.io.File</i>; see <a href="http://ant.apache.org/manual/develop.html#set-magic">Manual 'Writing Your Own Task' [3]</a>)</li> </ul> Before calling the set-method all properties are resolved. So a <tt><helloworld message="${msg}"/></tt> would not set the message string to "${msg}" if there is a property "msg" with a set value. <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. <pre class="code"> ... public class HelloWorld extends Task { ... public void addText(String text) { message = text; } ... } </pre> 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> <a name="NestedElements"></a> <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> <li>We create a class for collecting all the infos 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> <li>The task holds multiple instances of this class in a list.</li> <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> </li></p> <pre class="code"> import java.util.Vector; import java.util.Iterator; ... public void execute() { if (message!=null) log(message); for (Iterator it=messages.iterator(); it.hasNext(); ) { <b>// 4</b> Message msg = (Message)it.next(); log(msg.getMsg()); } } Vector messages = new Vector(); <b>// 2</b> public Message createMessage() { <b>// 3</b> Message msg = new Message(); messages.add(msg); return msg; } public class Message { <b>// 1</b> public Message() {} String msg; public void setMsg(String msg) { this.msg = msg; } public String getMsg() { return msg; } } ... </pre> <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 <pre class="code"> <helloworld> <message msg="Nested Element 1"/> <message msg="Nested Element 2"/> </helloworld> </pre> <a name="complex"></a> <h2>Our task in a little more complex version</h2> <p>For recapitulation now a little refactored buildfile: <pre class="code"> <?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="apache-ant.jar"/> </target> <target name="compile" description="Compiles the Task"> <mkdir dir="${classes.dir}"/> <javac srcdir="src" destdir="${classes.dir}"/> </target> <target name="jar" description="JARs the Task" depends="compile"> <jar destfile="apache-ant.jar" basedir="${classes.dir}"/> </target> <target name="use.init" description="Taskdef the HelloWorld-Task" depends="jar"> <taskdef name="helloworld" classname="HelloWorld" classpath="apache-ant.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> </pre> And the code of the task: <pre class="code"> 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. * @author Jan Matèrne * @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 <i>false</i>. 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; } } } </pre> And it works: <pre class="output"> 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> </pre> Next step: test ... <a name="TestingTasks"></a> <h2>Test the Task</h2> <p>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 baseclass <tt>org.apache.tools.ant.BuildFileTest</tt>. This class extends <tt>junit.framework.TestCase</tt> and can therefore be integrated into the unit tests. But this class provides some for testing tasks useful methods: initialize Ant, load a buildfile, execute targets, expecting BuildExceptions with a specified text, expect a special text in the output log ... </p> <p>In Ant it is usual that the testcase has the same name as the task with a prepending <i>Test</i>, therefore we will create a file <i>HelloWorldTest.java</i>. Because we have a very small project we can put this file into <i>src</i> 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 <a href="http://gump.covalent.net/jars/latest/ant/ant-testutil.jar"> 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: <pre class="code"> ... <font color="#9F9F9F"><project name="MyTask" basedir="." </font>default="test"<font color="#9F9F9F">></font> ... <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="/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-launcher.jar:/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Classes/.compatibility/14compatibility.jar:/Users/antoine/dev/asf/ant-core/lib/optional/activation.jar:/Users/antoine/dev/asf/ant-core/lib/optional/ant-antunit-1.0Beta2.jar:/Users/antoine/dev/asf/ant-core/lib/optional/antlrall.jar:/Users/antoine/dev/asf/ant-core/lib/optional/bcel.jar:/Users/antoine/dev/asf/ant-core/lib/optional/bsf-2.4.0.jar:/Users/antoine/dev/asf/ant-core/lib/optional/bsh-2.0b4.jar:/Users/antoine/dev/asf/ant-core/lib/optional/bsh-core-2.0b4.jar:/Users/antoine/dev/asf/ant-core/lib/optional/commons-logging-api.jar:/Users/antoine/dev/asf/ant-core/lib/optional/commons-logging.jar:/Users/antoine/dev/asf/ant-core/lib/optional/commons-net-1.4.0.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jai_codec.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jai_core.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jakarta-oro-2.0.8.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jakarta-regexp-1.2.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jdepend.jar:/Users/antoine/dev/asf/ant-core/lib/optional/js-1.6R3.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jsch-0.1.29.jar:/Users/antoine/dev/asf/ant-core/lib/optional/junit-3.8.2.jar:/Users/antoine/dev/asf/ant-core/lib/optional/jython.jar:/Users/antoine/dev/asf/ant-core/lib/optional/log4j-1.2.9.jar:/Users/antoine/dev/asf/ant-core/lib/optional/mail.jar:/Users/antoine/dev/asf/ant-core/lib/optional/NetRexxC.jar:/Users/antoine/dev/asf/ant-core/lib/optional/NetRexxR.jar:/Users/antoine/dev/asf/ant-core/lib/optional/resolver.jar:/Users/antoine/dev/asf/ant-core/lib/optional/starteam-sdk.jar:/Users/antoine/dev/asf/ant-core/lib/optional/stylebook-1.0-b2.jar:/Users/antoine/dev/asf/ant-core/lib/optional/weblogic.jar:/Users/antoine/dev/asf/ant-core/lib/optional/weblogicaux.jar:/Users/antoine/dev/asf/ant-core/lib/optional/weblogicclasses.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xalan.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xalan1.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xercesSamples.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xmlParserAPIs.jar:/Users/antoine/dev/asf/ant-core/lib/optional/xsltc.jar:/Users/antoine/dev/asf/ant-core/lib/optional:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-antlr.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-bcel.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-bsf.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-log4j.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-oro.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-regexp.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-apache-resolver.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-commons-logging.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-commons-net.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-jai.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-javamail.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-jdepend.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-jmf.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-jsch.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-junit.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-launcher.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-netrexx.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-nodeps.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-starteam.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-stylebook.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-swing.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-testutil.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-trax.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant-weblogic.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/ant.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/xercesImpl.jar:/Users/antoine/dev/asf/ant-core/bootstrap/lib/xml-apis.jar"/> <path location="apache-ant.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="apache-ant.jar"/> <fileset dir="${classes.dir}"/> <fileset dir="${report.dir}"/> </delete> </target> <font color="#9F9F9F"><target name="compile" description="Compiles the Task"> <mkdir dir="${classes.dir}"/> <javac srcdir="src" destdir="${classes.dir}" </font>classpath="${ant.test.lib}"<font color="#9F9F9F">/> </target></font> ... <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" 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" /> ... </pre></p> <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. <pre class="code"> import org.apache.tools.ant.BuildFileTest; public class HelloWorldTest extends BuildFileTest { public HelloWorldTest(String s) { super(s); } public void setUp() { // initialize Ant configureProject("build.xml"); } public void testWithout() { executeTarget("use.without"); assertEquals("Message was logged but should not.", getLog(), ""); } public void testMessage() { // execute target 'use.nestedText' and expect a message // 'attribute-text' in the log expectLog("use.message", "attribute-text"); } public void testFail() { // execute target 'use.fail' and expect a BuildException // with text 'Fail requested.' expectBuildException("use.fail", "Fail requested."); } public void testNestedText() { expectLog("use.nestedText", "nested-text"); } public void testNestedElement() { executeTarget("use.nestedElement"); assertLogContaining("Nested Element 1"); assertLogContaining("Nested Element 2"); } } </pre></p> <p>When starting <tt>ant</tt> we'll get a short message to STDOUT and a nice HTML-report. <pre class="output"> 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> </pre></p> <a name="resources"></a> <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> <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> <li>the ant-testutil.jar (nightly build of 2003-08-18)</li> <li>generated classes</li> <li>generated jar</li> <li>generated reports</li> </ul> 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/using.html#built-in-props">http://ant.apache.org/manual/using.html#built-in-props</a><br> [2] <a href="http://ant.apache.org/manual/CoreTasks/taskdef.html">http://ant.apache.org/manual/CoreTasks/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> </body> </html> --- NEW FILE: LICENSE --- /* * Apache License * Version 2.0, January 2004 * http://www.apache.org/licenses/ * * TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION * * 1. Definitions. * * "License" shall mean the terms and conditions for use, reproduction, * and distribution as defined by Sections 1 through 9 of this document. * * "Licensor" shall mean the copyright owner or entity authorized by * the copyright owner that is granting the License. * * "Legal Entity" shall mean the union of the acting entity and all * other entities that control, are controlled by, or are under common * control with that entity. For the purposes of this definition, * "control" means (i) the power, direct or indirect, to cause the * direction or management of such entity, whether by contract or * otherwise, or (ii) ownership of fifty percent (50%) or more of the * outstanding shares, or (iii) beneficial ownership of such entity. * * "You" (or "Your") shall mean an individual or Legal Entity * exercising permissions granted by this License. * * "Source" form shall mean the preferred form for making modifications, * including but not limited to software source code, documentation * source, and configuration files. * * "Object" form shall mean any form resulting from mechanical * transformation or translation of a Source form, including but * not limited to compiled object code, generated documentation, * and conversions to other media types. * * "Work" shall mean the work of authorship, whether in Source or * Object form, made available under the License, as indicated by a * copyright notice that is included in or attached to the work * (an example is provided in the Appendix below). * * "Derivative Works" shall mean any work, whether in Source or Object * form, that is based on (or derived from) the Work and for which the * editorial revisions, annotations, elaborations, or other modifications * represent, as a whole, an original work of authorship. For the purposes * of this License, Derivative Works shall not include works that remain * separable from, or merely link (or bind by name) to the interfaces of, * the Work and Derivative Works thereof. * * "Contribution" shall mean any work of authorship, including * the original version of the Work and any modifications or additions * to that Work or Derivative Works thereof, that is intentionally * submitted to Licensor for inclusion in the Work by the copyright owner * or by an individual or Legal Entity authorized to submit on behalf of * the copyright owner. For the purposes of this definition, "submitted" * means any form of electronic, verbal, or written communication sent * to the Licensor or its representatives, including but not limited to * communication on electronic mailing lists, source code control systems, * and issue tracking systems that are managed by, or on behalf of, the * Licensor for the purpose of discussing and improving the Work, but * excluding communication that is conspicuously marked or otherwise * designated in writing by the copyright owner as "Not a Contribution." * * "Contributor" shall mean Licensor and any individual or Legal Entity * on behalf of whom a Contribution has been received by Licensor and * subsequently incorporated within the Work. * * 2. Grant of Copyright License. Subject to the terms and conditions of * this License, each Contributor hereby grants to You a perpetual, * worldwide, non-exclusive, no-charge, royalty-free, irrevocable * copyright license to reproduce, prepare Derivative Works of, * publicly display, publicly perform, sublicense, and distribute the * Work and such Derivative Works in Source or Object form. * * 3. Grant of Patent License. Subject to the terms and conditions of * this License, each Contributor hereby grants to You a perpetual, * worldwide, non-exclusive, no-charge, royalty-free, irrevocable * (except as stated in this section) patent license to make, have made, * use, offer to sell, sell, import, and otherwise transfer the Work, * where such license applies only to those patent claims licensable * by such Contributor that are necessarily infringed by their * Contribution(s) alone or by combination of their Contribution(s) * with the Work to which such Contribution(s) was submitted. If You * institute patent litigation against any entity (including a * cross-claim or counterclaim in a lawsuit) alleging that the Work * or a Contribution incorporated within the Work constitutes direct * or contributory patent infringement, then any patent licenses * granted to You under this License for that Work shall terminate * as of the date such litigation is filed. * * 4. Redistribution. You may reproduce and distribute copies of the * Work or Derivative Works thereof in any medium, with or without * modifications, and in Source or Object form, provided that You * meet the following conditions: * * (a) You must give any other recipients of the Work or * Derivative Works a copy of this License; and * * (b) You must cause any modified files to carry prominent notices * stating that You changed the files; and * * (c) You must retain, in the Source form of any Derivative Works * that You distribute, all copyright, patent, trademark, and * attribution notices from the Source form of the Work, * excluding those notices that do not pertain to any part of * the Derivative Works; and * * (d) If the Work includes a "NOTICE" text file as part of its * distribution, then any Derivative Works that You distribute must * include a readable copy of the attribution notices contained * within such NOTICE file, excluding those notices that do not * pertain to any part of the Derivative Works, in at least one * of the following places: within a NOTICE text file distributed * as part of the Derivative Works; within the Source form or * documentation, if provided along with the Derivative Works; or, * within a display generated by the Derivative Works, if and * wherever such third-party notices normally appear. The contents * of the NOTICE file are for informational purposes only and * do not modify the License. You may add Your own attribution * notices within Derivative Works that You distribute, alongside * or as an addendum to the NOTICE text from the Work, provided * that such additional attribution notices cannot be construed * as modifying the License. * * You may add Your own copyright statement to Your modifications and * may provide additional or different license terms and conditions * for use, reproduction, or distribution of Your modifications, or * for any such Derivative Works as a whole, provided Your use, * reproduction, and distribution of the Work otherwise complies with * the conditions stated in this License. * * 5. Submission of Contributions. Unless You explicitly state otherwise, * any Contribution intentionally submitted for inclusion in the Work * by You to the Licensor shall be under the terms and conditions of * this License, without any additional terms or conditions. * Notwithstanding the above, nothing herein shall supersede or modify * the terms of any separate license agreement you may have executed * with Licensor regarding such Contributions. * * 6. Trademarks. This License does not grant permission to use the trade * names, trademarks, service marks, or product names of the Licensor, * except as required for reasonable and customary use in describing the * origin of the Work and reproducing the content of the NOTICE file. * * 7. Disclaimer of Warranty. Unless required by applicable law or * agreed to in writing, Licensor provides the Work (and each * Contributor provides its Contributions) on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or * implied, including, without limitation, any warranties or conditions * of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A * PARTICULAR PURPOSE. You are solely responsible for determining the * appropriateness of using or redistributing the Work and assume any * risks associated with Your exercise of permissions under this License. * * 8. Limitation of Liability. In no event and under no legal theory, * whether in tort (including negligence), contract, or otherwise, * unless required by applicable law (such as deliberate and grossly * negligent acts) or agreed to in writing, shall any Contributor be * liable to You for damages, including any direct, indirect, special, * incidental, or consequential damages of any character arising as a * result of this License or out of the use or inability to use the * Work (including but not limited to damages for loss of goodwill, * work stoppage, computer failure or malfunction, or any and all * other commercial damages or losses), even if such Contributor * has been advised of the possibility of such damages. * * 9. Accepting Warranty or Additional Liability. While redistributing * the Work or Derivative Works thereof, You may choose to offer, * and charge a fee for, acceptance of support, warranty, indemnity, * or other liability obligations and/or rights consistent with this * License. However, in accepting such obligations, You may act only * on Your own behalf and on Your sole responsibility, not on behalf * of any other Contributor, and only if You agree to indemnify, * defend, and hold each Contributor harmless for any liability * incurred by, or claims asserted against, such Contributor by reason * of your accepting any such warranty or additional liability. * * END OF TERMS AND CONDITIONS * * APPENDIX: How to apply the Apache License to your work. * * To apply the Apache License to your work, attach the following * boilerplate notice, with the fields enclosed by brackets "[]" * replaced with your own identifying information. (Don't include * the brackets!) The text should be enclosed in the appropriate * comment syntax for the file format. We also recommend that a * file or class name and description of purpose be included on the * same "printed page" as the copyright notice for easier * identification within third-party archives. * * Copyright [yyyy] [name of copyright owner] * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ --- NEW FILE: proxy.html --- <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> <html> <head> <meta http-equiv="Content-Language" content="en-us"> <link rel="stylesheet" type="text/css" href="stylesheets/style.css"> <title>Proxy Configuration</title> </head> <body> <h2>Proxy Configuration</h2> <p> This page discussing proxy issues on command-line ant. Consult your IDE documentation for IDE-specific information upon proxy setup. </p> <p> All tasks running in Ant's JVM share the same HTTP/FTP/Socks proxy configuration. </p> <p> When any task tries to retrieve content from an HTTP page, including the <code><get></code> task, any automated URL retrieval in an XML/XSL task, or any third-party task that uses the <code>java.net.URL</code> classes, the proxy settings may make the difference between success and failure. </p> <p> Anyone authoring a build file behind a blocking firewall will immediately appreciate the problems and may want to write a build file to deal with the problem, but users of third party build build files may find that the build file itself does not work behind the firewall. </p> <p> This is a long standing problem with Java and Ant. The only way to fix it is to explictly configure Ant with the proxy settings, either by passing down the proxy details as JVM properties, or to tell Ant on a Java1.5+ system to have the JVM work it out for itself. </p> <h3>Java1.5+ proxy support (new for Ant1.7)</h3> <p> When Ant starts up, if the <code>-autoproxy</code> command is supplied, Ant sets the <code>java.net.useSystemProxies</code> system property. This tells a Java1.5+ JVM to use the current set of property settings of the host environment. Other JVMs, such as the Kaffe and Apache Harmony runtimes, may also use this property in future. It is ignored on the Java1.4 and earlier runtimes. </p> <p> This property maybe enough to give command-line Ant builds network access, although in practise the results are somewhat disappointing. </p> <p> We are not entirely sure where it reads the property settings from. For windows, it probably reads the appropriate bits of the registry. For Unix/Linux it may use the current Gnome2 settings. <p> One limitation of this feature, other than requiring a 1.5+ JVM, is that it is not dynamic. A long-lasting build hosted on a laptop will not adapt to changes in proxy settings. </p> <p> It is has also been reported a breaking the IBM Java 5 JRE on AIX, and does not appear to work reliably on Linux. Other odd things can go wrong, like Oracle JDBC drivers or pure Java SVN clients. </p> <p> To make the <code>-autproxy</code> option the default, add it to the environment variable <code>ANT_ARGS</code>, which contains a list of arguments to pass to Ant on every command line run. </p> <h3>JVM options</h3> <p> Any JVM can have its proxy options explicitly configured by passing the appropriate <code>-D</code> system property options to the runtime. Ant can be configured through all its shell scripts via the <code>ANT_OPTS</code> environment variable, which is a list of options to supply to Ant's JVM: </p> <p> For bash: </p> <pre> export ANT_OPTS="-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080" </pre> For csh/tcsh: <pre> setenv ANT_OPTS "-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080" </pre> <p> For Windows, set the ANT_OPTS environment variable in the appropriate "MyComputer" properties dialog box. </p> <p> This mechanism works across Java versions, is cross-platform and reliable. Once set, all build files run via the command line will automatically have their proxy setup correctly, without needing any build file changes. It also apparently overrides Ant's automatic proxy settings options. </p> <p> It is limited in the following ways: </p> <ol> <li>Does not work under IDEs. These need their own proxy settings changed</li> <li>Not dynamic enough to deal with laptop configuration changes.</li> </ol> <h3>SetProxy Task</h3> <p> The <a href="OptionalTasks/setproxy.html">setproxy task</a> can be used to explicitly set a proxy in a build file. This manipulates the many proxy configuration properties of a JVM, and controls the proxy settings for all network operations in the same JVM from that moment. </p> <p> If you have a build file that is only to be used in-house, behind a firewall, on an older JVM, <i>and you cannot change Ant's JVM proxy settings</i>, then this is your best option. It is ugly and brittle, because the build file now contains system configuration information. It is also hard to get this right across the many possible proxy options of different users (none, HTTP, SOCKS). </p> <p> Note that proxy configurations set with this task will probably override any set by other mechanisms. It can also be used with fancy tricks to only set a proxy if the proxy is considered reachable: </p> <pre> <target name="probe-proxy" depends="init"> <condition property="proxy.enabled"> <and> <isset property="proxy.host"/> <isreachable host="${proxy.host}"/> </and> </condition> </target> <target name="proxy" depends="probe-proxy" if="proxy.enabled"> <property name="proxy.port" value="80"/> <property name="proxy.user" value=""/> <property name="proxy.pass" value=""/> <setproxy proxyhost="${proxy.host}" proxyport="${proxy.port}" proxyuser="${proxy.user}" proxypassword="${proxy.pass}"/> </target> </pre> <h3>Summary and conclusions</h3> <p> There are three ways to set up proxies in Ant. </p> <ol> <li>With Ant1.7 using the <code>-autoproxy</code> parameter.</li> <li>Via JVM system properties -set these in the ANT_ARGS environment variable.</li> <li>Via the <setproxy> task.</li> </ol> <h4>Further reading</h4> <ul> <li><a href="http://java.sun.com/j2se/1.5.0/docs/guide/net/properties.html"> Java Networking Properties</a>. Notice how not all proxy settings are documented there. <li><a href="http://blogs.sun.com/roller/resources/jcc/Proxies.pdf">Proxies</a> </li> </ul> </body> </html> --- NEW FILE: develop.html --- <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> <html> <head> <meta http-equiv="Content-Language" content="en-us"> <link rel="stylesheet" type="text/css" href="stylesheets/style.css"> <title>Writing Your Own Task</title> </head> <body> <h1>Developing with Ant</h1> <h2><a name="writingowntask">Writing Your Own Task</a></h2> <p>It is very easy to write your own task:</p> <ol> <li>Create a Java class that extends <code>org.apache.tools.ant.Task</code> or <a href="base_task_classes.html">another class</a> that was designed to be extended.</li> <li>For each attribute, write a <i>setter</i> method. The setter method must be a <code>public void</code> method that takes a single argument. The name of the method must begin with <code>set</code>, followed by the attribute name, with the first character of the name in uppercase, and the rest in lowercase<a href="#footnote-1"><sup>*</sup></a>. That is, to support an attribute named <code>file</code> you create a method <code>setFile</code>. Depending on the type of the argument, Ant will perform some conversions for you, see <a href="#set-magic">below</a>.</li> <li>If your task shall contain other tasks as nested elements (like <a href="CoreTasks/parallel.html"><code>parallel</code></a>), your class must implement the interface <code>org.apache.tools.ant.TaskContainer</code>. If you do so, your task can not support any other nested elements. See <a href="#taskcontainer">below</a>.</li> <li>If the task should support character data (text nested between the start end end tags), write a <code>public void addText(String)</code> method. Note that Ant does <strong>not</strong> expand properties on the text it passes to the task.</li> <li>For each nested element, write a <i>create</i>, <i>add</i> or <i>addConfigured</i> method. A create method must be a <code>public</code> method that takes no arguments and returns an <code>Object</code> type. The name of the create method must begin with <code>create</code>, followed by the element name. An add (or addConfigured) method must be a <code>public void</code> method that takes a single argument of an <code>Object</code> type with a no-argument constructor. The name of the add (addConfigured) method must begin with <code>add</code> (<code>addConfigured</code>), followed by the element name. For a more complete discussion see <a href="#nested-elements">below</a>.</li> <li>Write a <code>public void execute</code> method, with no arguments, that throws a <code>BuildException</code>. This method implements the task itself.</li> </ol> <hr> <p><a name="footnote-1">*</a> Actually the case of the letters after the first one doesn't really matter to Ant, using all lower case is a good convention, though.</p> <h3>The Life-cycle of a Task</h3> <ol> <li>The task gets instantiated using a no-argument constructor, at parser time. This means even tasks that are never executed get instantiated.</li> <li>The task gets references to its project and location inside the buildfile via its inherited <code>project</code> and <code>location</code> variables.</li> <li>If the user specified an <code>id</code> attribute to this task, the project registers a reference to this newly created task, at parser time.</li> <li>The task gets a reference to the target it belongs to via its inherited <code>target</code> variable.</li> <li><code>init()</code> is called at parser time.</li> <li>All child elements of the XML element corresponding to this task are created via this task's <code>createXXX()</code> methods or instantiated and added to this task via its <code>addXXX()</code> methods, at parser time.</li> <li>All attributes of this task get set via their corresponding <code>setXXX</code> methods, at runtime.</li> <li>The content character data sections inside the XML element corresponding to this task is added to the task via its <code>addText</code> method, at runtime.</li> <li>All attributes of all child elements get set via their corresponding <code>setXXX</code> methods, at runtime.</li> <li><a name="execute"><code>execute()</code></a> 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 <code>target1</code> and <code>target2</code> both depend on <code>target3</code>, then running <code>'ant target1 target2'</code> will run all tasks in <code>target3</code> twice.</li> </ol> <h3><a name="set-magic">Conversions Ant will perform for attributes</a></h3> <p>Ant will always expand properties before it passes the value of an attribute to the corresponding setter method.</p> <p>The most common way to write an attribute setter is to use a <code>java.lang.String</code> 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</p> <ul> <li><code>boolean</code>, your method will be passed the value <i>true</i> if the value specified in the build file is one ... [truncated message content] |
