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