After reading the tutorial about writing -tasks this tutorial explains how to get and set properties and how to use -nested filesets and paths.
+tasks [1] this tutorial explains how to get and set properties and how to use +nested filesets and paths. Finally it explains how to contribute tasks to Ant.The buildfile is in the archive +tutorial-tasks-filesets-properties.zip [2] in /build.xml.01-propertyaccess +(future version saved as *.02..., final version as build.xml; same for sources).
+Our first step is to set a property to a value and print the value of property. So our scenario -would be +
Our first step is to set a property to a value and print the value of that property. +So our scenario would be
<find property="test" value="test-value"/>
<find print="test"/>
@@ -60,8 +72,8 @@ ok, can be rewritten with the core tasks
<echo message="${test}"/>
but I have to start on known ground :-)
-So what to do? Handling three attributes (property, value, print) and an execute. Because this -is only an introduction example I donīt do much checking: +
So what to do? Handling three attributes (property, value, print) and an execute method. +Because this is only an introduction example I donīt do much checking:
import org.apache.tools.ant.BuildException;
@@ -92,10 +104,10 @@ public class Find extends Task {
As said in the other tutorial, the property access is done via Project instance.
-This instance we get via the public getProject() method which we inherit from
+We get this instance via the public getProject() method which we inherit from
Task (more precise from ProjectComponent). Reading a property is done via
getProperty(propertyname) (very simple, isnīt it?). This property returns
-the value (String) or null if not set.What do we need? A task with two attributes (file, location) and nested -filesets. Because we had attribute handling already in the example above and the handling -of nested elements is described in the other tutorial the code should be very easy: +filesets. Because we had attribute handling already explained in the example above and the +handling of nested elements is described in the other tutorial the code should be very easy:
public class Find extends Task {
@@ -281,9 +293,9 @@ can implement our task, so that these test cases will pass.
On //1 we check the prerequisites for our task. Doing that in a validate-method
is a common way, because we separate the prerequisites from the real work. On //2 we iterate
-over all nested filesets. We we donīt want to handle multiple filesets, the addFileset()
-method has to reject the further calls. We can get the result of fileset via its DirectoryScanner
-like done //3. After that we create a plattform independend String representation of
+over all nested filesets. If we donīt want to handle multiple filesets, the addFileset()
+method has to reject the further calls. We can get the result of a fileset via its DirectoryScanner
+like done in //3. After that we create a plattform independend String representation of
the file path (//4, can be done in other ways of course). We have to do the replace(),
because we work with a simple string comparison. Ant itself is platform independant and can
therefore run on filesystems with slash (/, e.g. Linux) or backslash (\, e.g. Windows) as
@@ -298,9 +310,10 @@ location of the file as property, if we had found one (//6).
whithout being complex :-)
The test case uses the ant property ant.home as reference. This property is set by the
-Launcher class which starts ant. We can use that property in our buildfiles as a build-in
-property (see [XXX]). But if we create a new ant environment we have to set that value for our own.
-And we use the <junit< task in fork-mode. Therefore we have do modify our buildfile:
+Launcher class which starts ant. We can use that property in our buildfiles as a
+build-in property [3]. But if we create a new ant
+environment we have to set that value for our own. And we use the <junit> task in fork-mode.
+Therefore we have do modify our buildfile:
<target name="junit" description="Runs the unit tests" depends="jar">
<delete dir="${junit.out.dir.xml}" />
@@ -323,9 +336,10 @@ And we use the <junit< task in fork-mode. Therefore we have do modify our
possibility of bundling files: the <path>. Fileset are easy if the files are all under
a common base directory. But if this is not the case you have a problem. Another disadvantage
is its speed: if you have only a few files in a huge directory structure, why not use a
-<fileset> instead? <path>s combines these datatypes in that way that a path contains
-other paths, filesets, dirsets and filelists. This is way Ant-Contribs [XXX]
-<foreach> task is modified to support paths instead of filesets. So we want that, too.
+<filelist> instead? <path>s combines these datatypes in that way that a path contains
+other paths, filesets, dirsets and filelists. This is why
+Ant-Contribs [4] <foreach> task is modified to support paths instead of filesets. So we want that,
+too.
Changing from fileset to path support is very easy:
@@ -353,7 +367,7 @@ other paths, filesets, dirsets and filelists. This is way Ant-Contrib
On *1 we rename only the vector. Itīs just for better reading the source. On *2
we have to provide the right method: an addName(Type t). Therefore replace the
fileset with path here. Finally we have to modify our buildfile on *3 because our task
-donīt support nested filesets any longer. So we wrap the fileset inside a path.
+doesnīt support nested filesets any longer. So we wrap the fileset inside a path.
And now we modify the testcase. Oh, not very much to do :-) Renaming the testMissingFileset()
(not really a must-be but better itīs named like the think it does) and update the
@@ -363,9 +377,9 @@ modified in the manner described above.
The test are finished. Now we have to adapt the task implementation. The easiest modification is
in the validate() method where we change le last line to if (paths.size()<1) throw new
-BuildException("path not set");. In the execute() method we have a liitle more work.
-... mmmh ... in reality itīs lesser work, because the Path class does a the whole DirectoryScanner-handling
-and creating absolute paths stuff for us. So the execute method is just:
+BuildException("path not set");. In the execute() method we have a little more work.
+... mmmh ... in reality itīs lesser work, because the Path class does the whole DirectoryScanner-handling
+and creating-absolute-paths stuff for us. So the execute method is just:
public void execute() {
@@ -463,7 +477,7 @@ elements are concatenated and separated with a customizable separator (default '
Now we need a directory structure where we CAN find files with the same
name in different directories. Because we canīt sure to have one we create
-one on *1, *2. And of course we clean up that on *4. The creation
+one on *1 and *2. And of course we clean up that on *4. The creation
can be done inside our test target or in a separate one, which will be better
for reuse later (*3).
@@ -534,7 +548,8 @@ form you do that depends on your favourite. But inside Ant there is a common for
it has advantages if you use that: all task users know that form, this form is requested if
you decide to contribute your task. So we will doc our task in that form.
-If you have a look at the manual page of the java [XXX] task you will see
+If you have a look at the manual page of the java [5]
+ task you will see
- it is plain html
- starts with the name
- has sections: description, parameters, nested elements, (maybe return codes) and (most
@@ -595,7 +610,7 @@ As a template we have:
</html>
-For our task we have that [XXX]:
+For our task we have that [6]:
<html>
@@ -680,7 +695,8 @@ If we decide to contribute our task, we should do some things:
Now we will check the "Checklist before submitting a new task" described in that guideline.
This task does not depend on any external library. Therefore we can use this as +a core task. This task contains only one class. So we can use the standard package for core tasks: org.apache.tools.ant.taskdefs. Implementations are in the directory src/main, tests in src/testcases and buildfiles for -tests in src/etc/testcases. +tests in src/etc/testcases.
+ +Now we integrate our work into Ants distribution. So first we do an update of our +cvs tree. If not done yet, you have to checkout the ant module from Apaches cvs server +as described in Access the Source Tree (AnonCVS) +[8] (password is anoncvs):
+cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login //1 +cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic checkout ant //2 ++If you have a local copy of Ants sources just do an update +
+cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login +cd ant //3 +cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic update //4 ++ +
We use the -d flag on //1 to specifiy the cvs directory. You can +specify the environment variable CVSROOT with that value and after that you havenīt +to use that flag any more. On //2 we get the whole cvs tree of ant. (Sorry, +but that uses a lot of time ... 10 up to 30 minutes are not unusual ... but this has +to be done only once :-). A cvs update doesnīt use a modulename but you have to be +inside the directory. Therefore we go into that on //3 and do the update +on //4.
+ +Now we will build our Ant distribution and do a test. So we can see if there +are any tests failing on our machine. (We can ignore these failing tests on later +steps; windows syntax used here- translate to xNIX if needed): +
+ANTHOME> build // 1 +ANTHOME> set ANT_HOME=%CD%\dist // 2 +ANTHOME> ant test -Dtest.haltonfailure=false // 3 ++ +First we have to build our Ant distribution (//1). On //2 we set the ANT_HOME +environment variable to the directory where the new created distribution is stored +(%CD% is expanded to the current directory on Windows 2000 and XP, on 9x and NT +write it out). On //3 we let Ant do all the tests (which enforced a compile +of all tests) without stopping on first failure. + +
Next we apply our work onto Ants sources. Because we havenīt modified any, this is +a relative simple step. (Because I have a local copy of Ant and usually contribute my +work, I work on the local copy just from the beginning. The advantage: this step isnīt +necessary and saves a lot of work if you modify existing source :-). + +
+ANTHOME> build +ANTHOME> ant run-single-test // 1 + -Dtestcase=org.apache.tools.ant.taskdefs.FindTest // 2 + -Dtest.haltonfailure=false ++Because we only want to test our new class, we use the target for single tests, specify +the test to use and configure not to halt on the first failure - we want to see all +failures of our own test (//1 + 2). + +
And ... oh, all tests fail: Ant could not find the task or a class this task relies upon.
+ +Ok: in the earlier steps we told Ant to use the Find class for the <find> task (remember the +<taskdef> statement in the "use.init" target). But now we want to introduce that task as +a core task. And nobody wants to taskdef the javac, echo, ... So what to do? The answer is the +src/main/.../taskdefs/default.properties. Here is the mapping between taskname and implementing +class done. So we add a find=org.apache.tools.ant.taskdefs.Find as the last core +task (just before the # optional tasks line). Now a second try: +
+ANTHOME> build // 1 +ANTHOME> ant run-single-test + -Dtestcase=org.apache.tools.ant.taskdefs.FindTest + -Dtest.haltonfailure=false ++We have to rebuild (//1) Ant because the test look in the %ANT_HOME%\lib\ant.jar +(more precise: on the classpath) for the properties file. And we have only modified it in the +source path. So we have to rebuild that jar. But now all tests pass and we check whether our class +breaks some other tests. +
+ANTHOME> ant test -Dtest.haltonfailure=false ++Because there are a lot of tests this step requires a little bit of time. So use the run-single-test +during development and do the test only at the end (maybe sometimes during development too). +We use the -Dtest.haltonfailure=false here because there could be other tests fail and we have +to look into them. + +
This test run should show us two things: our test will run and the number of failing tests +is the same as directly after the cvs update (without our modifications).
+Simply copy the license text from one the other source from the Ant source tree. But ensure that the current year is used in the * Copyright (c) 2000-2003 The Apache Software -Foundation. All rights reserved. lines. +Foundation. All rights reserved. lines. Donīt forget to add a license statement at the end +of the find.html. (Can be copied from other manual files.)
+ + +Until version 1.5 Ant must be able to run on a JDK 1.1. With version 1.6 this is not a +requisite any more. But JDK 1.2 is a must be able. So we have to test that. You can download older +JDKs from Sun [9].
+ +Clean the ANT_HOME variable, delete the build, bootstrap and dist directory +and point JAVA_HOME to the JDK 1.2 home directory. Then do the build, set ANT_HOME +and run ant test (like above).
+ +Our test should pass.
+There are many things we have to ensure. Indentation with 4 spaces, blanks here and there, ... +(all described in the Ant Task Guidelines [7] which +includes the Sun code style +[10]). Because there are so many things we would be happy to have a tool for do the checks. +There is one: checkstyle. Checkstyle is available at +Sourceforge [11] and Ant provides with the check.xml a buildfile which will do the job +for us.
+ +Download it and put the checkstyle-*-all.jar into your %USERPROFILE%\.ant\lib directory. +All jarīs stored there are available to Ant so you havenīt to add it to you %ANT_HOME%\lib +directory (this feature was added with Ant 1.6).
+ +So we will run the tests with +
+ANTHOME> ant -f check.xml checkstyle htmlreport ++I prefer the HTML report because there are lots of messages and we can navigate faster. +Open the ANTHOME/build/reports/checkstyle/html/index.html and navigate to the Find.java. Now we +see that there are some errors: missing whitespaces, unused imports, missing javadocs. So we have +to do that. + +
Hint: start at the buttom of the file so the line numbers in the report will keep +up to date and you will find the next error place much more easier without redoing the checkstyle.
+ +After cleaning up the code according to the messages we delete the reports directory and +do a second checkstyle run. Now our task isnīt listed. Thatīs fine :-)
+ + -Creating a diff for Ant is very easy: just start ant -f patch.xml and all is done +automatically. This step requires a cvs executable in your path and internet access (more precise: +cvs access). As a result we get a file XXX .
+ -Finally we publish that archive. As described in the +Ant Task Guidelines [7] we can post it on the developer mailinglist or we create a BugZilla +entry. For both we need some information:
+ +| subject | +short description | +Task for finding files in a path | +
|---|---|---|
| body | +more details about the path | +This new task looks inside a nested <path/> for occurrences of a file and stores + all locations as a property. See the included manual for details. | +
| attachements | +all files needed to apply the path | +Archive containing the path produced with path.xml | +
Sending an email with these information is very easy and I think I havenīt to show that. +The other way - BugZilla - is slightly more difficult. But it has the advantage that entries +will not be forgotten (once per week a report is generated). So I will show this way.
+ +You must have a BugZilla account for that. So open the +BugZilla Main Page [12] and follow the link +Open a new Bugzilla account [13] +and the steps described there if you havenīt one.
+ +Copyright © 2003 Apache Software Foundation. All rights