Apache Ant Integration - AntDoclet

270 Pages·2010·0.84 MB·English

by  Fernando Dobladez

e
l
p
m
a
x
AENTDOCLET EXAMPLE
Fernando Dobladez
[email protected]
December8,2005
e
CONTENTS
l
Abstract
This document serves as reference documentation for the core Apache Ant
tasks. p
ThisisNOTtheof(cid:2)cialApacheAnt1 documentation. Itisexposedherejustas
anexampleofwhatAntDoclet2cangenerate.
Contents
m
1 Introduction 6
1.1 Aboutthisexample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2 controlLibrary 7
2.1 Taskcontrol:Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 Taskcontrol:Available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3 Taskcontrol:Checksum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.4 Typecontrol:ConditionTask . . . . . . . . . . . . . . . . . . . . . . . . . . 21
a
2.5 Taskcontrol:ExecTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.6 Taskcontrol:ImportTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.7 Taskcontrol:Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.8 Taskcontrol:Parallel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
x
2.9 Taskcontrol:Sequential . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.10 Taskcontrol:UpToDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.11 Typecontrol:WaitFor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.12 Taskcontrol:antcall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.13 Taskcontrol:apply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
E
2.14 Taskcontrol:fail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
2.15 Taskcontrol:nice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
2.16 Taskcontrol:subant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3 databaseLibrary 47
3.1 Taskdatabase:sql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
1http://ant.apache.org
2http://antdoclet.neuroning.com
2
e
CONTENTS
l
4 (cid:2)lesystemLibrary 50
4.1 Task(cid:2)lesystem:Chmod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.2 Task(cid:2)lesystem:Copy . . . . . . .p. . . . . . . . . . . . . . . . . . . . . . . 55
4.3 Task(cid:2)lesystem:Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
4.4 Task(cid:2)lesystem:DependSet . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
4.5 Task(cid:2)lesystem:Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
4.6 Task(cid:2)lesystem:FixCRLF . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
m
4.7 Task(cid:2)lesystem:Mkdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
4.8 Task(cid:2)lesystem:Move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
4.9 Task(cid:2)lesystem:Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
4.10 Task(cid:2)lesystem:Sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
4.11 Task(cid:2)lesystem:Sync.MyCopy . . . . . . . . . . . . . . . . . . . . . . . . . 102
4.12 Task(cid:2)lesystem:Touch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
5 internalLibrarya 105
5.1 Taskinternal:Taskdef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
5.2 Taskinternal:Typedef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
6 javaLibrary 109
x
6.1 Taskjava:Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
6.2 Taskjava:Javac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
6.3 Taskjava:Javadoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
6.4 Typejava:Javadoc.DocletInfo . . . . . . . . . . . . . . . . . . . . . . . . . 136
6.5 Typejava:Javadoc.ExtensionInfo . . . . . . . . . . . . . . . . . . . . . . . 137
E
6.6 Typejava:Javadoc.GroupArgument . . . . . . . . . . . . . . . . . . . . . . 138
6.7 Typejava:Javadoc.TagArgument . . . . . . . . . . . . . . . . . . . . . . . 138
6.8 Taskjava:ManifestTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
6.9 Taskjava:Rmic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
6.10 Taskjava:SignJar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
6.11 Taskjava:genkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
6.12 Typejava:genkey.DistinguishedName . . . . . . . . . . . . . . . . . . . . 163
3
e
CONTENTS
l
7 networkLibrary 163
7.1 Tasknetwork:Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
7.2 Tasknetwork:mail . . . . . . . . .p. . . . . . . . . . . . . . . . . . . . . . . 164
8 packagingLibrary 166
8.1 Taskpackaging:BUnzip2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
8.2 Taskpackaging:BZip2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
8.3 Taskpackaging:Ear . . m. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
8.4 Taskpackaging:GUnzip . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
8.5 Taskpackaging:GZip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
8.6 Taskpackaging:Jar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
8.7 Taskpackaging:Tar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
8.8 Typepackaging:Tar.TarFileSet . . . . . . . . . . . . . . . . . . . . . . . . . 204
8.9 Taskpackaging:Untar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
8.10 Taskpackaging:War . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
a
8.11 Taskpackaging:Zip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
8.12 Taskpackaging:unwar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
9 propertyLibrary 242
x
9.1 Taskproperty:Basename . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
9.2 Taskproperty:Dirname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
10 scmLibrary 244
10.1 Taskscm:CVSPass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
E
10.2 Taskscm:Cvs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
11 utilityLibrary 245
11.1 Taskutility:DefaultExcludes . . . . . . . . . . . . . . . . . . . . . . . . . . 245
11.2 Taskutility:Echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
11.3 Taskutility:LoadFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
11.4 Taskutility:LoadProperties . . . . . . . . . . . . . . . . . . . . . . . . . . 247
11.5 Taskutility:Patch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
4
e
CONTENTS
l
11.6 Taskutility:PathConvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
11.7 Taskutility:Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
11.8 Taskutility:Tstamp . . . . . . . .p. . . . . . . . . . . . . . . . . . . . . . . 251
11.9 Taskutility:record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
12 xmlLibrary 252
12.1 Taskxml:AntStructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
12.2 Taskxml:xmlproperty m. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
12.3 Taskxml:xslt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
12.4 Typexml:xslt.Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
a
x
E
5
e
1 INTRODUCTION
l
1 Introduction
This documentation was generated running AntDoclet3 over the source code of the
p
coreApacheAntTasksversion1.6.5.
ThisNOTtheof(cid:2)cial ApacheAnt4 documentation. Itisexposedherejustasanexam-
pleofwhatAntDoclet5 cangenerate.
1.1 Aboutthisexample
m
The source code of the core Ant Tasks was written without any knowledge of AntDo-
clet. Therefore,thequalityofthegenerateddocumentationforthisexampleisfarfrom
perfect.
Forinstance, thesourcecodeofthecoreAntTasksdonotuseallthetagsthat AntDo-
clet supports, and some of the comments use invalid HTML or describe things that
AntDocletalreadyauto-generates.
To get the most out of AntDoclet the source code of your Ant Tasks needs to follow a
fewsimpleguidelinesdescribedintheAntDocletdocumentation.
a
ThefollowingsectionsdescribeeachoftheprovidedAntTasksinmoredetail,includ-
ingalltheattributestheyacceptandexamplesofuse.
x
E
3http://antdoclet.neuroning.com
4http://ant.apache.org
5http://antdoclet.neuroning.com
6
e
2 CONTROLLIBRARY
l
2 control Library
2.1 Taskcontrol:Ant
p
Buildasub-project.
<target name="foo" depends="init">
<ant antfile="build.xml" target="bar" >
<property name="property1" value="aaaaa" />
<property name="foo" value="baz" />
</ant>
m
</target>
<target name="bar" depends="init">
<echo message="prop is ${property1} ${foo}" />
</target>
Parameters:
(cid:15) output (cid:150) String Set the (cid:2)lename to write the output to. This is relative to the
value of the dir attribute if it has been set or to the base directory of the current
a
projectotherwise.
(cid:15) inheritall (cid:150) boolean If true, pass all properties to the new Ant project. De-
faultstotrue.
(cid:15) dir (cid:150) File The directory to use as a base directory for the new Ant project. De-
faultsxto the current project’s basedir, unless inheritall has been set to false, in
whichcaseitdoesn’thaveadefaultvalue. Thiswilloverridethebasedirsetting
ofthecalledproject.
(cid:15) inheritrefs (cid:150) boolean If true, pass all references to the new Ant project. De-
faultstofalse.
(cid:15) target(cid:150)StringThetargetofthenewAntprojecttoexecute. Defaultstothenew
E
project’sdefaulttarget.
(cid:15) antfile (cid:150) String The build (cid:2)le to use. Defaults to (cid:148)build.xml(cid:148). This (cid:2)le is ex-
pectedtobea(cid:2)lenamerelativetothedirattributegiven.
Parametersacceptedasnestedelements:
<reference> Helper class that implements the nested <reference>element of
<ant>and<antcall>.
Parameters:
7
e
2 CONTROLLIBRARY
l
(cid:15) torefid(cid:150)String
(cid:15) refid(cid:150)String
<propertyset>(cid:150)(See??onpage??)Apsetofproperties.
Parameters:
(cid:15) refid(cid:150)Reference
(cid:15) dynamic(cid:150)boolean
(cid:15) negate(cid:150)boolean
m
<property>(cid:150)(See??onpage??)Setsapropertybyname,orsetofproperties(from
(cid:2)leorresource)intheproject. Propertiesareimmutable: whoeversetsaproperty
(cid:2)rstfreezesitfortherestofthebuild;theyaremostde(cid:2)nitelynotvariable.
Thereare(cid:2)vewaystosetproperties:
(cid:15) Bysupplyingboththenameandvalueattribute.
(cid:15) Bysupplyingboththenameandre(cid:2)dattribute.
(cid:15) By setting the (cid:2)le attribute with the (cid:2)lename of the property (cid:2)le to load.
This property (cid:2)le has the format as de(cid:2)ned by the (cid:2)le used in the class
java.util.Properties.
a
(cid:15) By setting the resource attribute with the resource name of the property (cid:2)le
to load. This property (cid:2)le has the format as de(cid:2)ned by the (cid:2)le used in the
classjava.util.Properties.
(cid:15) By setting the environment attribute with a pre(cid:2)x to use. Properties will be
de(cid:2)nedforeveryenvironmentvariablebypre(cid:2)xingthesuppliednameand
aperiodtothenameofthevariable.
x
Although combinations of these ways are possible, only one should be used at
a time. Problems might occur with the order in which properties are set, for
instance.
Thevaluepartofthepropertiesbeingset,mightcontainreferencestootherprop-
erties. Thesereferencesareresolvedatthetimethesepropertiesareset. Thisalso
Eholdsforpropertiesloadedfromaproperty(cid:2)le.
Propertiesarecasesensitive.
Parameters:
(cid:15) refid(cid:150)Reference
(cid:15) url(cid:150)URL
(cid:15) name(cid:150)String
(cid:15) classpath(cid:150)Path
(cid:15) userproperty(cid:150)boolean
(cid:15) file(cid:150)File
8
e
2 CONTROLLIBRARY
l
(cid:15) resource(cid:150)String
(cid:15) environment(cid:150)String
(cid:15) prefix(cid:150)String p
(cid:15) classpathref(cid:150)Reference
(cid:15) value(cid:150)String
<target> Helper class that implements the nested <target>element of
<ant>and<antcall>.
Parameters: m
(cid:15) name(cid:150)String
2.2 Taskcontrol:Available
Will set the given property if the requested resource is available at runtime. This task
mayalsobeusedasaconditionbytheconditiontask.
a
Parameters:
(cid:15) classpath (cid:150) Path Set the classpath to be used when searching for classes and
resources.
(cid:15) filex(cid:150) File Set the (cid:2)le which must be present in the (cid:2)le system to set the given
property.
(cid:15) classname(cid:150)StringSetaclassnameofaclasswhichmustbeavailabletosetthe
givenproperty.
(cid:15) resource (cid:150) String Set the name of a Java resource which is required to set the
Eproperty.
(cid:15) ignoresystemclasses(cid:150)booleanSetwhetherthesearchforclassesshouldig-
noretheruntimeclassesandjustusethegivenclasspath.
(cid:15) type (cid:150) String [(cid:148)(cid:2)le(cid:148), (cid:148)dir(cid:148)]Set what type of (cid:2)le is required - either directory or
(cid:2)le.
(cid:15) classpathref(cid:150)ReferenceSettheclasspathbyreference.
(cid:15) value(cid:150)StringSetthevaluetobegiventothepropertyifthedesiredresourceis
available.
9
e
2 CONTROLLIBRARY
l
(cid:15) property(cid:150)StringSetthenameofthepropertywhichwillbesetiftheparticular
resourceisavailable.
(cid:15) filepath(cid:150)PathSetthepathtousepwhenlookingfora(cid:2)le.
Parametersacceptedasnestedelements:
<classpath>(cid:150)(See??onpage??)ThisobjectrepresentsapathasusedbyCLASS-
PATHorPATHenvironmentvariable.
<sometask> m
<somepath>
<pathelement location="/path/to/file.jar" />
<pathelement path="/path/to/file2.jar:/path/to/class2;/path/to/class3"
/>
<pathelement location="/path/to/file3.jar" />
<pathelement location="/path/to/file4.jar" />
</somepath>
</sometask>
The object aimplemention sometask must provide a method called
createSomepathwhichreturnsaninstanceofPath. Nestedpathde(cid:2)nitionsare
handledbythePathobjectandmustbelabeledpathelement.
The path element takes a parameter path which will be parsed and split into
single elements. It will usually be used to de(cid:2)ne a path from an environment
variable.
x
Parameters:
(cid:15) refid(cid:150)Reference
(cid:15) path(cid:150)String
<filepath> (cid:150) (See??onpage??) This object represents a path as used by CLASS-
PATHorPATHenvironmentvariable.
E
<sometask>
<somepath>
<pathelement location="/path/to/file.jar" />
<pathelement path="/path/to/file2.jar:/path/to/class2;/path/to/class3"
/>
<pathelement location="/path/to/file3.jar" />
<pathelement location="/path/to/file4.jar" />
</somepath>
</sometask>
10