Home

Apache Ant 1.5.4 Manual

1. 90 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Copies a file or FileSet to a new file or directory By default files are only copied if the source file is newer than the destination file or when the destination file does not exist However you can explicitly overwrite files with the overwrite attribute FileSets are used to select a set of files to copy To use a lt fileset gt the todir attribute must be set Note If you employ filters in your copy operation you should limit the copy to text files Binary files will be corrupted by the copy operation This applies whether the filters are implicitly defined by the filter task or explicitly provided to the copy operation as filtersets Parameters Attribute Description O Required file The file to copy Yes unless a nested lt fileset gt element is used preservelastmodifiedGive the copied files the same last No defaults to false modified time as the original source files Note Ignored on Java 1 1 The file to copy to With the file attribute either tofile or The directory to copy to todir can be used With nested lt fileset gt elements if the set of files is greater than 1 or if only the dir attribute is specified in the lt fileset gt or if the file attribute is also specified then only todir is allowed overwrite Overwrite existing files even if the No defaults to false destination files are newer Indicates whether token filtering using No default
2. 143 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Some technical issues the file s print stream is flushed for finished events buildFinished targetFinished and taskFinished and is closed on a buildFinished event Parameters Attribute Description Required name The name of the file this logger is associated with yes action This tells the logger what to do should it start recording or stop The first time that the recorder task is called for this logfile and if this attribute is not provided then the default for this attribute is start If this attribute is not no provided on subsequent calls then the state remains as previous Values start stop Default no state change append Should the recorder append to a file or create a new one This is only applicable the first time this task is called for this file Values yes no no Default yes emacsmode Removes task banners like Ant s emacs command line switch if set to true no default is false loglevel At what logging level should this recorder instance record to This is not a once only parameter like append is you can increase or decrease the logging level as the build process continues Values error warn info verbose debug Default no change no Examples The following build xml snippet is an example of how to use the recorder to record just the lt javac gt task lt compile gt lt record name log txt action start gt lt javac
3. As noted above the jonas element supports additional lt classpath gt nested elements Examples This example shows ejbjar being used to generate deployment jars using aJOnAS EJB container This example requires the naming standard to be used for the deployment descriptors Using this format will create a EJB JAR file for each variation of jar xml that is found in the deployment descriptor directory lt ejbjar srcdir S build classes descriptordir S descriptor dir gt lt jonas destdir S deploymentjars dir jonasroot jonas root orb RMI gt lt include name xm1 gt lt exclude name 3jonas xml gt lt support dir build classes gt lt include name class gt lt support gt lt ejbjar gt 206 305 Ant Manual 1 5 4 12 9 2003 7 47 PM This example shows ejbjar being used to generate a single deployment jar using a JONAS EJB container This example does require the deployment descriptors to use the naming standard This will create only one ejb jar file TheE BJ ar jar lt ejbjar srcdir S build classes descriptordir descriptor dir basejarname TheEJBJar gt lt jonas destdir deploymentjars dir jonasroot jonas root suffix jar classpath descriptorbuild classpath gt lt include name e3jb Jar xml gt lt exclude name jonas ejb jar xml gt lt ejbjar gt 10 8 echoproperties Description Displ
4. lt tar destfile dist manual tar basedir htdocs manual excludes mydocs todo html gt tars all files in the htdocs manual directory into a file called manual tar in the dist directory Files in the directory mydocs or files with the name todo html are excluded lt tar destfile basedir docs tar gt lt tarfileset dir dir src docs fullpath usr doc ant README preserveLeadingSlashes true gt lt include name readme txt gt lt tarfileset gt lt tarfileset dir dir src docs prefix usr doc ant preserveLeadingSlashes true gt lt include name html gt lt tarfileset gt lt tar gt Writes the file docs readme txt aS usr doc ant README into the archive All htm1 files in the docs directory are prefixed by usr doc ant so for example docs index html is written as usr doc ant index html to the archive lt tar longfile gnu destfile S dist base S dist name sre tar gt lt tarfileset dir S dist name mode 755 username ant group ant gt lt include name S dist name bootstrap sh gt lt include name dist name build sh gt lt tarfileset gt lt tarfileset dir S dist name username ant group ant gt lt include name S dist name gt lt exclude name S dist name bootstrap sh gt lt exclude name S dist name build sh gt lt tarfileset gt
5. StarTeam is maintaining for the file If rootlocalfolder is set then this should be set true as otherwise the checkout will be based on statuses which do not relate to the target folder Defaults to false locked If true file will be locked against changes by other users If false Either or default has no effect neither but not 271 305 Ant Manual 1 5 4 12 9 2003 7 47 PM unlocked If true file will be unlocked so that other users may change it both may be This is a way to reverse changes that have not yet been checked true in If false default has no effect Examples lt stcheckout servername STARTEAM serverport 49201 projectname AProject viewname AView username auser password secret rootlocalfolder C dev buildtest co force true gt The minimum necessary to check out files out from a StarTeam server This will check out all files in the AView view of the AProject project to C dev buildtest co Empty folders in StarTeam will have local folders created for them and any non StarTeam files found in the tree will be deleted lt stcheckout URL STARTEAM 49201 Aproject AView username auser password secret rootlocalfolder C dev buildtest co forced true gt And this is a simpler way of accomplishing the same thing as the previous example using the URL attribute lt stcheckout URL STARTEAM 49201 Aproject AView username auser password secret rootlocal
6. String value appended to the basename of the deployment No defaults to jar descriptor to create the filename of the WebLogic EJB jar file This controls whether the generic file used as input to No defaults to false ejbdeploy is retained This controls whether ejbdeploy is called although no No defaults to false changes have occurred A directory where ejbdeploy will write temporary files No defaults to ejbdeploy_temp These options are passed to ejbdeploy No This option is passed to ejbdeploy Valid options are for No example SQL92 SQL99 DB2UDBWIN_V71 DB2UDBOS390_ V6 DB2UDBAS400_V4R5 ORACLE_V8 INFORMIX_V92 SYBASE_V1192 MYSQL_V323 MSSQLSERVER_V7 This is also used to determine the name of the Map mapxmi and Schema dbxmi files for example Account DB2UDBWIN_V71 Map mapxmi and Account DB2UDBWIN_V71 Schema dbxmi These options are all passed to ejbdeploy All options No except quiet default to false This option is passed to ejbdeploy and will be passed on to No rmic This example shows ejbjar being used to generate deployment jars for all deployment descriptors in the descriptor dir lt property name websphere home value was4 home gt lt ejbjar srcdir build class descriptordir etc ejb gt lt include name ejb jar xml gt lt websphere dbvendor DB2UDBOS390_V6 jbdeploy true oldCMP false tempdir tmp destdir S dist server gt lt wasclasspath gt lt
7. eJb jar xml gt lt exclude name ias xml gt lt dtd publicId Sun Microsystems Inc DID Enterprise JavaBeans 1 1 EN location ias home APPS ejb Jar_1_1 dtd gt lt dtd publicId Sun Microsystems Inc DTD iAS Enterprise JavaBeans 1 0 EN location S ias home APPS IASEJb_jar_1_0 dtd gt lt ejbjar gt 10 7 3 6JONAS JAVA OPEN APPLICATION SERVER ELEMENT The lt jonas gt nested element is used to build JOnAS specific stubs and skeletons thanks to the GenlC specific tool and construct a JAR file which may be deployed to the J OnAS Application Server The build process will always determine if the EJB stubs skeletons and the EJB JAR file are up to date and it will do the minimum amount of work required Like the WebLogic element a naming convention for the EJB descriptors is most commonly used to specify the name for the completed JAR file For example if the EJB descriptor ejb Account ejb jar xml is found in the descriptor directory the lt jonas gt element will search for a J OnAS specific EJB descriptor file named ejb Account jonas ejb jar xml and a JAR file named ejb Account jar will be written in the destination directory But the lt jonas gt element can also use the JOnAS naming convention With the same example as below the EJB descriptor can also be named ejb Account xml no base name terminator here in the descriptor directory Then the lt jonas gt
8. lt entry key progress default operation value gt lt propertyfile gt Each time called a will be appended to progress 10 32 Ant Pvcs Task User Manual Note Before using this task the user running ant must have access to the commands of PVCS get and pcli and must have access to the repository Note that the way to specify the repository is platform dependent so use property to specify location of repository by e Thomas Christensen tchristensen nordija com e Don Jeffery donj apogeenet com Version 1 1 2001 06 27 Problems with UNC pathnames and the use of in paths are fixed and an updateonly argument introduced Version 1 0 2001 01 31 Initial release 254 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 10 32 1 Introduction The pvcs task allows the user of ant to extract the latest edition of the source code from a PVCS repository PVCS is a version control system developed by Merant This version has been tested agains PVCS version 6 5 and 6 6 under Windows and Solaris 10 32 2 Pvcs Task Description The pvcs task is set to point at a PVCS repository and optionally a project within that repository and can from that specification get the latest version of the files contained by the repository Parameters Attribute Description Required repository The location of the repository see your PVCS manuals Yes pvcsproject The project within the PVCS repository to extract files from is root N
9. lt param name max value 1 gt lt custom gt lt fileset gt Selects all files in the base directory and one directory below that For more details concerning writing your own selectors consult Programming Selectors in Ant 7 3 23 XMLCatalog An XMLCatalog is a catalog of public resources such as DTDs or entities that are referenced in an XML document Catalogs are typically used to make web references to resources point to a locally cached copy of the resource 61 305 Ant Manual 1 5 4 12 9 2003 7 47 PM This allows the XML Parser XSLT Processor or other consumer of XML documents to efficiently allow a local substitution for a resource available on the web This data type provides a catalog of resource locations based on the OASIS Open Catalog standard The catalog entries are used both for Entity resolution and URI resolution in accordance with the org xml sax EntityResolver and javax xml transform URIResolver interfaces as defined in the Java API for XML Processing JAXP Specification For example in a web xml file the DTD is referenced as lt DOCTYPE web app PUBLIC Sun Microsystems Inc DID Web Application 2 2 EN http java sun com 3j2ee dtds web app_2_2 dtd gt The XML processor without XMLCatalog support would need to retrieve the DTD from the URL specified whenever validation of the document was required This can be very time consuming during the build process especially where net
10. 113 305 Ant Manual 1 5 4 12 9 2003 7 47 PM username 1214 password secret gt Fetches some file from a server with access control Because https is being used the fact that basic auth sends passwords in plaintext is moot 9 33 GUnzip See BUnzip2 9 34 GZip BZip2 See BZip2 9 35 Input Description Allows user interaction during the build process by prompting for input To do so it uses the configured nputHandler The prompt can be set via the message attribute or as character data nested into the element Optinonally a set of valid imput arguments can be defined via the validargs attribute Input task will no accept value that don t match one of the predefined Optionally a property can be created from the value entered by the user This property can then be used during the following build run Input behaves according to property task which means that existing properties cannot be overriden Parameters Attribute Description Required message the Message which gets displayed to the user during the build run No validargs comma separated String containing valid input arguments If set input task No will reject any input not defined here Validargs are compared case sensitive If you want a and A to be accepted you will need to define both arguments within validargs addproperty the name of a property to be created from input Behaviour is equal to No property task which means that existing properties cannot be
11. No preserve and fail The default value is add Nested elements lib The nested lib element specifies a FileSet All files included in this fileset will end up in the WEB INF lib directory of the war file classes The nested classes element specifies a FileSet All files included in this fileset will end up in the WEB INF classes directory of the war file webinf The nested webinf element specifies a FileSet All files included in this fileset will end up in the WEB INF directory of the war file If this fileset includes a file named web xml the file is ignored and you will get a warning metainf The nested metainf element specifies a FileSet All files included in this fileset will end up in the META INF directory of the war file If this fileset includes a file named MANIFEST MF the file is ignored and you will get a warning Examples Assume the following structure in the project s base directory thirdparty libs jdbcl jar thirdparty libs jdbc2 jar build main com myco myapp Servlet class src metadata myapp xml src html myapp index html src jsp myapp front jsp src graphics images gifs small logo gif src graphics images gifs large logo gif then the war file myapp war created with lt war destfile myapp war webxml src metadata myapp xml gt lt fileset dir src html myapp gt lt fileset dir src jsp myapp gt 169 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt lib dir th
12. No Note that the default value depends on the J VM that is running Ant In particular if you use J DK 1 4 the generated classes will not be usable for a 1 1 Java VM unless you explicitly set this attribute to the value 1 1 which is the default value for JDK 1 1 to 1 3 Asks the compiler for verbose output No Enables dependency tracking for compilers that support this No jikes and classic Whether to include the Ant run time libraries in the classpath No defaults to yes Whether to include the default run time libraries from the No executing VM in the classpath defaults to no Whether to execute javac using the J DK compiler externally No defaults to no Complete path to the javac executable to use in case of No fork yes Defaults to the compiler of the J ava version that is currently running Ant Ignored if fork no The initial size of the memory for the underlying VM if javac is No run externally ignored otherwise Defaults to the standard VM memory setting Examples 83886080 81920k or 80m The maximum size of the memory for the underlying VM if No javac is run externally ignored otherwise Defaults to the standard VM memory setting Examples 83886080 81920k or 80m Indicates whether the build will continue even if there are No compilation errors defaults to true Value of the source command line switch will be ignored by No 122 305 Ant Manual 1 5 4 12 9 2003 7 47 PM all implementations
13. classname The class to look for in the classpath ile The file to look for Yes resource The resource to look for in the J VM 80 305 Ant Manual 1 5 4 12 9 2003 7 47 PM classpath The classpath to use when looking up classname or resource ilepath The path to use when looking up file No classpathref The classpath to use given as a reference to a path defined elsewhere No type The type of file to look for either a directory type dir or a file type file If not set the property will be set if the name specified i the file attribute exists as either a file or a directory ignoresystemclasses lgnore Ant s runtime classes using only the specified classpath Only affects the classname attribute Defaults to false Parameters specified as nested elements classpath Available s classpath attribute is a path like structure and can also be set via a nested lt classpath gt element filepath Available s filepath attribute is a path like structure and can also be set via a nested lt filepath gt element Examples lt available classname org whatever Myclass property Myclass present gt sets the Myclass present property to the value true if the class org whatever Myclass is found in Ant s classpath lt property name Jaxp jar value lib jaxpll1 jaxp jar gt lt available file S jaxp jar property Jjaxp jar present gt sets the jaxp jar present property to the value true if the file
14. comment adduncontrolled includes excludes recursive forced unlocked Examples 12 9 2003 7 47 PM associated with rootstarteamfolder is used Checkin comment to be saved with the file no if true any files or folders NOT in StarTeam will be added to the no repository Defaults to false Only check in files that match at least one of the patterns in this list no Patterns must be separated by commas Patterns in excludes take precedence over patterns in includes Do not check in files that match at least one of the patterns in this list no Patterns must be separated by commas Patterns in excludes take precedence over patterns in includes Indicates if subfolders should be searched for files to check in Defaults no to false If true checkins will occur regardless of the status that StarTeam is no maintaining for the file If rootlocalfolder is set then this should be set true as otherwise the checkin will be based on statuses which do not relate to the target folder Defaults to false If true file will be unlocked so that other users may change it If false no default lock status will not change lt stcheckin servername STARTEAM gt serverport 49201 projectname AProject viewname AView username auser password secret rootlocalfolder C dev buildtest co forced true The minimum necessary to check files into a StarTeam server This will check all files on the local tree
15. lt description gt This buildfile is used to build the Foo subproject within the large complex Bar project lt description gt 7 3 2 Directory based Tasks Some tasks use directory trees for the actions they perform For example the javac task which compiles a directory tree with java files into class files is one of these directory based tasks Because some of these tasks do so much work with a directory tree the task itself can act as an implicit FileSet 32 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Whether the fileset is implicit or not it can often be very useful to work on a subset of the directory tree This section describes how you can select a subset of such a directory tree when using one of these directory based tasks Ant gives you two ways to create a subset of files in a fileset both of which can be used at the same time e Only include files and directories that match any include patterns and do not match any exclude patterns in a given PatternSet e Select files based on selection criteria defined by a collection of selector nested elements Patternset We said that Directory based tasks can sometimes act as an implicit lt fileset gt but in adation to that a FileSet acts as an implicit lt patternset gt The inclusion and exclusion elements of the implicit PatternSet can be specified inside the directory based task or explicit fileset via either the attributes includes and excludes
16. quiet which instructs Ant to print less information to the console verbose which causes Ant to print additional information to the console and debug which causes Ant to print considerably more additional information It is also possible to specify one or more targets that should be executed When omitted the target that is specified in the default attribute of the project tag is used The projecthelp option prints out a list of the build file s targets Targets that include a description attribute are listed as Main targets those without a description are listed as Subtargets then the Default target is listed Command line Options Summary ant options target target2 target3 Options help print this message projecthelp print project help information version print the version information and exit diagnostics print information that might be helpful to diagnose or report problems quiet 9 be extra quiet 21 305 Ant Manual 1 5 4 12 9 2003 7 47 PM verbose v be extra verbose debug print debugging information emacs produce logging information without adornments logfile lt file gt use given file for log 1 lt file gt rr logger lt classname gt the class which is to perform logging listener lt classname gt add an instance of class as a project listener buildfile lt file gt use given buildfile file lt file gt q f lt file gt
17. source Same as one entry in the list given by sourcefiles Parameters Attribute Description Required file The source file to document Yes illa a iia way Similar to lt doctitle gt 128 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 8 footer Similar to lt doctitle gt o OE 9 bottom Similar to lt doctitle gt oo O 10 link Create link to javadoc output at the given URL This performs the same role as the link and linkoffline attributes You can use either syntax or both at once but with the nested elements you can easily specify multiple occurrences of the arguments Parameters Attribute Description Required href The URL for the external documentation Yes you wish to link to offline True if this link is not available online at No the time of generating the documentation packagelistLoc The location to the directory containing Only if the offline the package list file for the external attribute is true documentation 11 group Separates packages on the overview page into whatever groups you specify one group per table This performs the same role as the group attribute You can use either syntax or both at once but with the nested elements you can easily specify multiple occurrences of the arguments Parameters Attribute Description Required title Title of the group Yes unless nested lt title gt given packages List of packages to include in that group Yes unless nested Multiple packages are separat
18. 86 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt exclude name trial gt lt fileset gt lt fileset refid other shared sources gt lt chmod gt makes all files below shared sources1 except those below any directory named trial writable for members of the same group on a UNIX system In addition all files belonging to a FileSet with id other shared sources get the same permissions 9 12 Concat Description Concatenates a file or a series of files to a single file or the console The destination file will be created if it does not exist though the the append attribute may be used to alter this behavior FileSets and or FileLists are used to select which files are to be concatenated There is no singular file attribute to specify a single file to cat a fileset or filelist must also be used in these cases Parameters Attribute Description destfile The destination file for the concatenated stream If not specified the console will No be used instead append Specifies whether or not the file specified by destfile should be overwritten No E to no La a the encoding for the input files Please see http java sun com products jdk 1 2 docs quide internat encoding doc html for a list of possible values Defaults to the platform s default character encoding Parameters specified as nested elements fileset FileSets are used to select files to be concatenated Note that the order in which the file
19. Load a file don t fail if it is missing a message is printed though lt loadfile property mail recipients srcFile recipientlist txt gt lt filterchain gt lt striplinebreaks gt lt filterchain gt lt loadfile gt Load a property which can be used as a parameter for another task in this case mail merging lines to ensure this happens lt loadfile property system configuration xml srcFile configuration xml gt lt expandproperties gt lt loadfile gt Load an XML file into a property expanding all properties declared in the file in the process 9 41 LoadProperties Description Load a file s contents as Ant properties This is equivalent to lt property file gt except that it supports nested lt filterchain gt elements and it cannot be specified outside a target If you want to simulate property s prefix attribute please use prefixlines filter Parameters Attribute Description Required srcFile source file Yes The LoadProperties task supports nested FilterChains 132 305 Ant Manual 1 5 4 Examples 12 9 2003 7 47 PM lt loadproperties srcFile file properties gt Load contents of file properties as Ant properties lt loadproperties srcFile file properties gt lt filterchain gt lt linecontains gt lt contains value import gt lt linecontains gt lt filterchain gt lt loadproperties gt Read the lines that contain
20. No Examples This strips the r and n characters lt loadfile srcfile S src filej property src file contents gt lt filterchain gt lt filterreader classname org apache tools ant filters StripLineBreaks gt lt filterchain gt lt loadfile gt Convenience method lt loadfile srcfile S src filej property src file contents gt lt filterchain gt 48 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt striplinebreaks gt lt filterchain gt lt loadfile gt This treats the and characters as line break characters and strips them lt loadfile srcfile S src file property S src file contents gt lt filterchain gt lt filterreader classname org apache tools ant filters StripLineBreaks gt lt param name linebreaks value gt lt filterreader gt lt filterchain gt lt loadfile gt 7 3 17 StripLineComments This filter removes all those lines that begin with strings that represent comments as specified by the user Parameter Parameter Value Required Type comment Strings that identify a line as a comment when they appear at the start of Yes the line Examples This removes all lines that begin with REM rem and lt filterreader classname org apache tools ant filters StripLineComments gt lt param type comment value gt lt param type comment value gt lt param type comment value REM gt lt param type comment va
21. PCOVERAG Cr A A a ee eee a 228 LOV2T 3y JIPCOVMELRG a id 230 TOZLA PCOVREPO tucan Yee it AVEA nt peeved vera 231 10 22 Oi Been stable sta Sten rect Oe ated EAE EREE A EIEE te sitet MLAS A Lok ae Lag RI ti E 233 10 23 JU MERE PORE dai Wied nie yebecen ia 237 10 24 MMOChICS sar ce ticles ceria a nd AA in Ota ate RNS Bh Sg 238 10 25 MAU Iter hate een E A Ye lanes A A eee ae eE 239 10 26 MimeMail Deprecated ceccee eect eee eee eee eee eee rr rre 241 10 27 MPA ii A dee een Saad aby aA o gad ease 242 10 28 Native ZAS liseren eii AA it AS 243 10 29 NetRexxC ocio nie dd cs TEKEAR 244 10 30 Perforce Tasks User Manual ooccccoccccnnnnccnnnnnnnnnnrnnnnnrnnnrrrnrnnrrnrrrnrrrnrnnns 246 TO 730 IMtrOMUCtION osare ir fous spades eased Ii dica 247 1030 2 The Tasks ws aussie ida ae ee 247 8 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 10 30 3 General P4 Properties 0 cee cece cece eee eee eee eee eee rn nnr rr 247 LOB ORs ASKO SE rr seh ated a 248 10 3005 PASAN AA A AAA eae nee 248 TO 30 0 PACO ANI a as 249 10130 7 PAE ds a 249 10 30 8 PAS UM A A ve os 249 10 30 9 PAH VE resi enla 250 10 30 10 E A eis aceed divin docile wE KEEA nie rey yee cee QiGvi Ina SE inves 250 10 30 11 PA GOUT T tamena lohd toe el te aii an sie date da do Se loe 250 10 30 12 PA REOPEN erein Aana E nhome NEAN tea eed abe seeded aa bie EEEE NEA aA 251 10 30 13 PAREVE IT ee A iio nts 251 10 30 14 PAA ts a A Seen alae A 251 10 31 PROPERLY
22. bodewig Created By Apache Ant 1 5alpha 135 305 Ant Manual 1 5 4 Name common Specification Title Example Specification Vendor Example Organization Implementation Vendor Example Corp Specification Version 1 1 Implementation Version 1 1 February 19 2002 Implementation Title common Name common classl class Sealed false 9 44 Mkdir Description 12 9 2003 7 47 PM Creates a directory Also non existent parent directories are created when necessary Parameters Attribute Description Required dir the directory to create Yes Examples lt mkdir dir dist gt creates a directory dist lt mkdir dir dist lib gt creates a directory dist lib 9 45 Move Description Moves a file to a new file or directory or sets of files to a new directory By default the destination file is overwritten if it already exists When overwrite is turned off then files are only moved if the source file is newer than the destination file or when the destination file does not exist FileSets are used to select sets of files to move to the todir directory Parameters Attribute Description file the file to move preservelastmodified Give the moved files the same last modified time as the original source files Note Ignored on Java 1 1 tofile the file to move to todir the directory to move to overwrite overwrite existing files even if the 136 305 Required
23. element will search for a JOnAS specific EJB descriptor file called ejb jonas Account xm1 This convention do not follow strictly the ejb jar naming convention recommendation but is supported for backward compatibility with previous version of JOnAS Note that when the EJB descriptors are added to the JAR file they are automatically renamed META INF ejb jar xml and META INF jonas ejb jar xml Of course this naming behavior can be modified by specifying attributes in the ejbjar task for example basejarname basenameterminator and flatdestdir as well as the iplanet element for example suffix Refer to the appropriate documentation for more details Parameters Attribute Description Required destdir The base directory into which the generated JAR files will be written Each Yes J AR file is written in directories which correspond to their location within the descriptordir namespace jonasroot The root directory for JOnAS Yes 205 305 Ant Manual 1 5 4 12 9 2003 7 47 PM classpath The classpath used when generating EJ B stubs and skeletons If omitted No the classpath specified in the ejbjar parent task will be used If specified the classpath elements will be prepended to the classpath specified in the parent ejbjar task see also the ORB attribute documentation below Note that nested classpath elements may also be used keepgenerateditrue if the intermediate Java source files generated by GenIC must be No de
24. file to the given sourcebase directory Specify the J DK version for the generated stub code Specify 1 1 to pass the v1 1 option to rmic The classpath to use during compilation The classpath to use during compilation given as reference to a PATH defined elsewhere comma or space separated list of patterns of files that must be included All files are included when omitted the name of a file Each line of this file is taken to be an include pattern comma or space separated list of patterns of files that must be excluded No files except default excludes are excluded when omitted the name of a file Each line of this file is taken to be an exclude pattern indicates whether default excludes should be used or not yes no Default excludes are used when omitted check that classes implement Remote before handing them to rmic default is false indicates that portable RMI IIOP stubs should be generated additional arguments for I1OP class generation indicates that I DL output files should be generated additional arguments for IDL file generation generate debug info passes g to rmic Defaults to false whether to include the Ant run time libraries defaults to yes whether to include the default run time libraries from the executing VM defaults to no location of installed extensions The compiler implementation to use If this attribute is not set the value of the build rmic property if set wil
25. is used If no target attribute is supplied the default target of the new project is used By default all of the properties of the current project will be available in the new project Alternatively you can set the inheritAll attribute to false and only user properties i e those passed on the command line will be passed to the new project In either case the set of properties passed to the new project will override the properties that are set in the new project See also the property task You can also set properties in the new project from the old project by using nested property tags These properties are always passed regardless of the setting of inheritAll This allows you to parameterize your subprojects Properties defined on the command line can not be overridden by nested lt property gt elements References to data types can also be passed to the new project but by default they are not If you set the inheritrefs attribute to true all references will be copied but they will not override references defined in the new project Nested lt reference gt elements can also be used to copy references from the calling project to the new project optionally under a different id References taken from nested elements will override existing references in the new project Inherited references are not available to top level tasks of the child project Parameters Attribute Description ero eire the buildfile to use Defaults t
26. jvmarg If fork is enabled additional parameters may be passed to the new VM via nested lt jvmarg gt elements For example lt junit fork yes gt lt jvmarg value Djava compiler NONE gt lt junit gt would run the test in a VM without JIT lt jvmarg gt allows all attributes described in Command line Arguments sysproperty Use nested lt sysproperty gt elements to specify system properties required by the class These properties will be made available to the VM during the execution of the test either ANT s VM or the forked VM if fork is enabled The attributes for this element are the same as for environment variables lt junit fork no gt lt sysproperty key basedir value basedir gt lt junit gt would run the test in ANT s VM and make the basedir property available to the test env It is possible to specify environment variables to pass to the forked VM via nested lt env gt elements For a description of the lt env gt element s attributes see the description in the exec task Settings will be ignored if fork is disabled 234 305 Ant Manual 1 5 4 12 9 2003 7 47 PM formatter The results of the tests can be printed in different formats Output will always be sent to a file unless you set the usefile attribute to false The name of the file is determined by the name of the test and can be set by the outfile attribute of lt test gt There are three predefined formatters one prints t
27. lib jaxpl11l jaxp jar is found lt available file usr local lib type dir property local lib present gt sets the local lib present property to the value true if the directory usr local lib is found in project lt property name Jaxp jar value lib jaxpll jaxp jar gt lt path id jaxp location jaxp jar gt in target lt available classname jJavax xml transform Transformer classpathref Jaxp property jaxp11 present gt sets the jaxp11 present property to the value true if the class javax xml transform Transformer is found in the classpath referenced by jaxp in this case 1lib jaxp11 jaxp jar lt available property have extras resource extratasks properties gt lt classpath gt lt pathelement location usr local ant extra jar gt lt classpath gt lt available gt 81 305 Ant Manual 1 5 4 12 9 2003 7 47 PM sets the have extras property to the value true if the resource file extratasks properties is found 9 6 Basename Description Task to determine the basename of a specified file optionally minus a specified suffix When this task executes it will set the specified property to the value of the last path element of the specified file If file is a directory the basename will be the last directory element If file is a full path relative path or simple filename the basename will be the simple file name without any directory elements Parame
28. lt jdepend gt This invokes J Depend on the src directory writing the output on the standard output The classpath is defined using a classpath reference lt jdepend outputfile docs jdepend xml fork yes format xml gt lt sourcespath gt lt pathelement location src gt lt sourcespath gt lt classpath gt lt pathelement location classes gt lt pathelement location lib jdepend jar gt lt classpath gt lt jdepend gt This invokes J Depend in a separate VM on the src and testsrc directories writing the output to the lt docs jdepend xml gt file in xml format The classpath is defined using nested elements 10 19 Jj Tree Description Invokes the J J Tree preprocessor for the JavaCC compiler compiler It inserts parse tree building actions at various places in the JavaCC source that it generates The output of JJ Tree is run through J avaCC to create the parser To use the jjtree task set the target attribute to the name of the jjtree grammar file to process You also need to specify the directory containing the J avaCC installation using the javacchome attribute so that ant can find the JavaCC classes Optionally you can also set the outputdirectory to write the generated file to a specific directory Otherwise jjtree writes the generated JavaCC grammar file to the directory containing the JJ Tree grammar file This task only invokes JJ Tree if the grammar file is newer than the generated J
29. lt tar gt 159 305 Ant Manual 1 5 4 12 9 2003 7 47 PM This example shows building a tar which uses the GNU extensions for long paths and where some files need to be marked as executable mode 755 and the rest are use the default mode read write by owner The first fileset selects just the executable files The second fileset must exclude the executable files and include all others Note The tar task does not ensure that a file is only selected by one fileset If the same file is selected by more than one fileset it will be included in the tar file twice with the same path Note The patterns in the include and exclude elements are considered to be relative to the corresponding dir attribute as with all other filesets In the example above dist name is not an absolute path but a simple name of a directory so dist name is a valid path relative to dist name 9 60 Taskdef Description Adds a task definition to the current project such that this new task can be used in the current project Two attributes are needed the name that identifies this task uniquely and the full name of the class including the packages that implements this task You can also define a group of tasks at once using the file or resource attributes These attributes point to files in the format of Java property files Each line defines a single task in the format taskname fully qualified java classname Taskdef should be used to add yo
30. q gt lt argument value diff gt lt argument value u gt lt argument value N gt lt commandline gt 95 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt cvs gt or lt cvs output patch gt lt commandline gt lt argument line q diff u N gt lt commandline gt lt cvs gt You may include as many lt commandline gt elements as you like Each will inherit the failonerror compression and other global parameters from the lt cvs gt element lt cvs command update A d gt Updates from the head of repository ignoring sticky bits A and creating any new directories as necessary d Note the text of the command is passed to cvs as is so any cvs options should appear before the command and any command options should appear after the command as in the diff example above See the cvs manual for details specifically the Guide to CVS commands 9 18 CvsChangeLog Description Generates an XML formatted report file of the change logs recorded in a CVS repository Important This task needs cvs on the path If it isn t you will get an error such as error 2 on windows If lt cvs gt doesn t work try to execute cvs exe from the command line in the target directory in which you are working Parameters Attribute Description Required dir The directory from which to run the CVS log command No defaults to basedir destfile The file in which to write the change log report Yes
31. so that an HTML report can be generated from the XML file Parameters Attribute Description Required tofile The XML file to which the Audit result should be written to Yes metamatahome The home directory containing the Metamata distribution Yes fix Automatically fix certain errors those marked as fixable in the No Default to manual false list Creates listing file for each audited file A maudit file will be generated No Default to in the same location as the source file false unused Finds declarations unused in search paths It will look for unused global No Default to declarations in the source code within a use domain specified by the false searchpath element maxmemory Set the maximum memory for the J VM this is a convenient way to set No the mx or Xmx argument Nested elements jvmarg Additional parameters may be passed to the VM via nested lt jvmarg gt attributes lt jvmarg gt allows all attributes described in Command line arguments You can avoid using the lt jvmarg gt by adding these empty entries to metamata properties located at metamata home bin metamata classpath metamata sourcepath metamata baseclasspath classpath Sets class path also source path unless one explicitly set Overrides METAPATH CLASSPATH environment variables The classpath element represents a PATH like structure sourcepath Sets source path Overrides the SOURCEPATH environment variable The sourcepath element
32. the descriptors normally use the generic descriptor names such as ejb jar xml along with any associated vendor specific descriptor names For example If the value of the lt ejb name gt were to be given in the deployment descriptor as follows lt ejb jar gt lt enterprise beans gt lt entity gt lt ejb name gt Sample lt ejb name gt lt home gt org apache ant ejbsample SampleHome lt home gt then the name of the generated bean would be Sample jar This scheme is useful where you want to use the standard deployment descriptor names which may be more compatible with other EJB tools This scheme must have one bean per jar e directory In this mode the name of the generated bean jar is derived from the directory containing the deployment descriptors Again the deployment descriptors typically use the standard filenames For example if the path to the deployment descriptor is home user dev appserver dd sample then the generated bean will be named sample jar This scheme is also useful when you want to use standard style descriptor names It is often most useful when the descriptors are located in the same directory as the bean source code although that is not mandatory This scheme can handle multiple beans per jar e basejarname The final scheme supported by the lt ejbjar gt task is used when you want to specify the generated bean jar name directly In this case the name of the generated jar is specified by the ba
33. the file org_foo_bar_Wibble h is created there If this file already exists it is left unchanged lt javah outputFile wibble h gt lt class name org foo bar Wibble org foo bar Bobble gt lt javah gt is similar to the previous example except the output is written to a file called wibble h in the current directory lt javah destdir c force yes gt 220 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt class name org foo bar Wibble gt lt class name org foo bar Bobble gt lt class name org foo bar Tribble gt lt javah gt writes three header files one for each of the classes named Because the force option is set these header files are always written when the Javah task is invoked even if they already exist lt javah destdir c verbose yes old yes force yes gt lt class name org foo bar Wibble gt lt class name org foo bar Bobble gt lt class name org foo bar Tribble gt lt 3javah gt lt javah destdir c verbose yes stubs yes old yes force yes gt lt class name org foo bar Wibble gt lt class name org foo bar Bobble gt lt class name org foo bar Tribble gt lt javah gt writes the headers for the three classes using the old JNI format then writes the corresponding c stubs The verbose option will cause Javah to describe its progress 10 17 jspc Description Ant task to run the JSP compiler and turn JSP pages into J
34. truncate table some_other_table lt sql gt Connects to the database given in url as the sa user using the org database jdbcDriver and executes the two SQL statements inserting data into some_table and truncating some_other_table Note that you may want to enclose your statements in lt CDATA gt sections so you don t need to escape lt gt or other special characters For example lt sql driver org database jdbcDriver url 3jdbc database url userid sa password pass gt lt CDATA update some_table set columnl columnl 1 where column2 lt 42 1 gt lt sql gt The following connects to the database given in url as the sa user using the org database jdbcDriver and executes the SQL statements contained within the files datal sql data2 sql and data3 sql and then executes the truncate operation on some_other_table lt sql driver org database JdbcDriver url jdbc database url userid sa password pass gt lt transaction src datal sql gt lt transaction src data2 sql gt lt transaction src data3 sql gt lt transaction gt truncate table some_other_table lt transaction gt lt sql gt 153 305 Ant Manual 1 5 4 12 9 2003 7 47 PM The following example does the same as and may execute additional SQL files if there are more files matching the pattern data sql but doesn t guarantee that datal sql will be run before data2 sql lt sql driver org database jdb
35. 177 305 Ant Manual 1 5 4 12 9 2003 7 47 PM extraOptions Any extra options which aren t explicitly supported by the task like all the proxy server config stuff 10 1 4 Change Log Version 0 5 This revision goes along with NET 1 0 SP1 1 CSC added filealign 2 CSC added reference to office dll 3 CSC dependency checking only if destFile is set 4 WsdlToDotnet written Version 0 4 This is the beta 2 revision of the tasks 1 ILASM pulled the owner attribute added keyfile for giving binaries a strong name MD5 hash of the checksum 2 CSC added win32res noConfig utf8output fullpaths Version 0 3 The changes here reflect Beta 1 of the dotnet SDK and experience of use in more complex projects This build does not work with the older SDK primarily because the automatic reference feature references libraries only found in the new SDK version External changes e Recursive inclusion of cs and il files e Documentation enhanced includes examples and details of all parameters e The csc task automatically includes the common dotnet assemblies so there is no need to remember to refer to System dll System Web Services etc This feature can be disabled by setting the includeDefaultReferences flag to false e References can also be referred to using the ReferenceFiles parameter which is an ant path specification The old references string is still retained e An extraoptions attribute enables the build file to
36. 2 ANTUR r et eee eee ni A Vasa A yy bee Be Eee aed 179 VO 3 Cabealncieecchaet ees gti beth en age cds eer tah a pea eee SPA pen Sead aaea 180 10 4 ClearCase Support ici A Paden a EE E E 181 10 4 1 CE CHEECKIN AL o cee Oe oe a en as eB O sad 181 10 4 2 CC Checkouts iian a eave era da 182 10 43 CCURCHECKOUE scr o CEM sf oe RAR OS 182 10 4 4 CCUpdateln ccc at Volante Beste abel eda a ey 183 10 5 ContinuuS SUpport suisse ieee Gare deena e 183 10 5 1 COMCRECKIN ceci el iis pean REECE ee ie ened Sedat a IRA 183 10 5 2 CEMCHECK OUT et cares ves A a thane eee 184 10 5 3 COMChECKINT ASK irisi ip rt pad 184 10 5 4 CCMRECONFIQUIC oi ies anini ye cies eee hited ey pees eee eee anette dc eee tenes 184 10 5 5 COMCreatelasks 2sc2 sects dais ge peri Ae cios 185 Ant Manual 1 5 4 12 9 2003 7 47 PM 100 Dependi inenen Sa A Baers EA rr nd Ga a EA 185 10 7 Ant EJB Tasks User Manual cccccee cece eee cece ee ee ee eens eeeeeeeeeeeeeeeeeeeeenennnees 187 10 7 1 MEFOGUCTION naaa a A nebo e wae A 188 10 7 2 EJB TASKS iriiria kEi EnA KAPE E cave Sandee yds KEE KEKEE due eee yea hed vie dane 188 10 7 2 1 CICLO AVOT A EE 188 10 7 2 2 A O 189 10 7 2 3 A A acu E E EE E eonsem 189 10 7 2 4 bi T E Lj DREE irae Ore ier a EE Sct Cor EOE EEE COR ORE SORT Pact anne NER CPI OEY COTE EAE 191 10 7 2 5 A A E 192 10 7 2 6 EI 193 10 7 3 Vendor specific deployment elements oocooccccccncccccnnnncnnnnnnnnrnnnnrnnrnnrns 197 10 7 3 1 IL la 197 10 7 3 2 WEDIO
37. 2003 7 47 PM root tag inner tag Text root tag inner tag someattr val root tag a2 a3 al false These are the properties loaded by this task from the previous example file lt xmlproperty file somefile xml collapseAttributes true gt Load contents of somefile xml as Ant properties collapsing attributes as nodes root tag myattr true root tag inner tag Text root tag inner tag someatt val root tag a2 a3 al false These are the properties loaded by this task from the previous example file with attribute collapsing true 9 70 Xsit Style See Style 9 71 Zip Description Creates a zipfile The basedir attribute is the reference directory from where to zip Note that file permissions will not be stored in the resulting zipfile It is possible to refine the set of files that are being zipped This can be done with the includes includesfile excludes excludesfile and defaultexcludes attributes With the includes or includesfile attribute you specify the files you want to have included by using patterns The exclude or excludesfile attribute is used to specify the files you want to have excluded This is also done with patterns And finally with the defaultexcludes attribute you can specify whether you want to use default exclusions or not See the section on directory based tasks on how the inclusion exclusion of files works and how to write patterns This task forms an implicit FileSet and supports all attributes of l
38. 305 Ant Manual 1 5 4 12 9 2003 7 47 PM All files contained contained within set that are jars and implement an extension are added to extension set However the extension information may be modified by attributes of libfileset Examples lt extension id el extensionName MyExtensions specificationVersion 1 0 specificationVendor Peter Donald implementationVendorID vv implementationVendor Apache implementationVersion 2 0 implementationURL http somewhere com myExt jar gt lt libfileset id lfs includeUrl true includelmpl false dir tools lib gt lt include name jar gt lt libfileset gt lt extensionSet id exts gt lt libfileset dir lib gt lt include name jar gt lt libfileset gt lt libfileset refid lfs gt lt extension refid el gt lt extensionSet gt 67 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 8 Ant Tasks 8 1 Overview of Ant Tasks Given the large number of tasks available with Ant it may be difficult to get an overall view of what each task can do The following tables provide a short description of each task and a link to the complete documentation 8 1 1 Archive Tasks TaskName Descriptim_ BUnzip2 Expands a file packed using GZip or BZip2 BZip2 Packs a file using the GZip or BZip2 algorithm This task does not do any dependency checking the output file is always generated Cab Creates Microsoft CAB archive files
39. 4 12 9 2003 7 47 PM 7 3 10 HeadFilter This filter reads the first few lines from the data supplied to it Parameter Name Parameter Value Required lines Number of lines to be read Defaults to 10 No Example This stores the first 15 lines of the supplied data in the property src file head lt loadfile srcfile S src file property src file head gt lt filterchain gt lt filterreader classname org apache tools ant filters HeadFilter gt lt param name lines value 15 gt lt filterreader gt lt filterchain gt lt loadfile gt Convenience method lt loadfile srcfile src file property src file head gt lt filterchain gt lt headfilter lines 15 gt lt filterchain gt lt loadfile gt 7 3 11 LineContains This filter includes only those lines that contain all the user specified strings Parameter Type Parameter Value Required contains Substring to be searched for Yes Example This will include only those lines that contain foo and bar lt filterreader classname org apache tools ant filters LineContains gt lt param type contains value foo gt lt param type contains value bar gt lt filterreader gt Convenience method lt linecontains gt lt contains value foo gt lt contains value bar gt lt linecontains gt 46 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 7 3 12 LineContainsRegExp Filter which includes only those line
40. ANTLR your best option is probably to build the whole jar with the provided script mkalljar and drop the resulting jar about 300KB into ant home lib Dropping the default jar 7OKB is probably not enough for most needs and your only option will be to add ANTLR home directory to your classpath as described in ANTLR install htmi document Antlr 2 7 2 Note Instead of the above you will need antlrall jar that can be created by the antir all jartarget of the Makefile provided with the download Parameters Attribute Description Required target The grammar file to process Yes outputdirectory The directory to write the generated files to If not set the files are written No to the directory containing the grammar file glib An optional super grammar file that the target grammar overrides This No feature is only needed for advanced vocabularies debug When set to yes this flag adds code to the generated parser that will No launch the ParseView debugger upon invocation The default is no Note ParseView is a separate component that needs to be installed or your grammar will have compilation errors html Emit an html version of the grammar with hyperlinked actions No diagnostic Generates a text file with debugging infomation based on the target No grammar trace Forces all rules to call traceln traceOut if set to yes The default is no No traceParser Only forces parser rules to call traceln traceOut if set to yes The def
41. Description Required Required for 6 0 for 4 5 1 and 5 1 BEA Home The location of the BEA Home where the server s N A Yes config is defined If this attribute is present wlrun assumes that the server will be running under Weblogic 6 0 home The location of the weblogic home that is tobe Yes Yes Note this is used This is the location where weblogic is the absolute installed location not relative to BEA home Domain The domain to which the server belongs N A Yes classpath The classpath to be used with the J ava Virtual Yes Yes Machine that runs the Weblogic Server Prior to Weblogic 6 0 this is typically set to the Weblogic boot classpath Under Weblogic 6 0 this should include all the weblogic jars wlclasspath The weblogic classpath used by the Weblogic No N A Server properties The name of the server s properties file within Yes N A the weblogic home directory used to control the weblogic instance name The name of the weblogic server within the No No weblogic home which is to be run This defaults to myserver policy The name of the security policy file within the No No weblogic home directory that is to be used If not specified the default policy file weblogic policy is used username The management username used to manage the N A No server password The server s management password N A Yes pkPassword The private key password so the server can N A No decrypt the SSL private key file jvmargs Additional argument string pa
42. E See NEE aN aA ade cee An eee Bae NSA E 48 7 3 17 StripLinecommMmEentS iriiri ire unedited cee kee AE AA EN 49 7 3 18 TADS TOS PAS is A A e a a 49 7 3 19 TAFE Eier e E ENEE E A E EEN AN EE ETE 50 7 3 20 Alla eae EP EAEE e UM EPEE A EEES 51 7 3 21 PAIN Sia A A a EA E oie AOE RS asi 52 7 3 22 S CLECEOES a add elaine 54 7 3 22 1 How to us a Selector tii ot Re tes toe eee 54 71 3 22 2 COSES E A A A E A 54 7 3 22 3 Contains Selec A E E aa 54 7 3 22 4 Date Selec lO iconos potato conil io a dia 55 T3225 Depend Sel Si 55 71 3 22 6 Depth Selec lOa ir ici 56 7 3 22 7 Filename Selector e R a E E east WA aes eR 56 7 3 22 8 Present elec E e e ade e o 57 7 3 22 9 SIZE Elia 57 7 3 2210 Selector Contae Sinnani nnn ass ieitel A R E N IGN 58 TS 22 11 And Selector oia E eee ea N ENA 58 T2212 Majority Selec ii 59 7322213 None Selector aa iat E a E ode ea ema eel 59 PILI Not Selec iia ii indic 39 73221 OrsSelector isis dada tada 60 13 22 16 Selector Referente sseni aldo ieee eda etek 60 13 22 14 Custom Selector iia via 60 7 3 23 AMECA ui a heh A a ha ial ce REE EM a 61 7 3 23 1 Entity DTD URI Resolution Al gorithm coocnnccnnnnnnonononononnnonnncnnncnnnonancnnnnos 62 13232 SIME C ataloe attrib teS s 63 T3233 AME Gata low nested elemen i 63 7 4 Optional TPS iee o A Geeta eee 64 AVI ClassSFileSet A A o Yeas iaa 64 TAA EXCONSION arras dices de 65 JA33 Extension ui A o a 66 8 LANE TASKS A A A A 68 8 1 Overview OF Ant TAS
43. M 1 5 BUILD SUCCESSFUL Total time 19 seconds ERANT Al tool java ERANT All get v6 6 10 Build 870 for Windows NT 80x86 rights reserved l rights reserved rj main java lt C mypvcs archives myprj main java arc lt This next example extracts the latest version of the files in the pvcs repository from two projects using nested lt pvcsproject gt elements lt lt Get latest from myprj and myprj2 gt lt I lt target name getlatest2 gt lt pvcs repository mnt pvcs gt lt pvcsproject name mypr3 gt lt pvcsproject name myprj2 gt lt pvcs gt lt target gt Now run ant getlatest2 This will cause the following output to appear 256 305 Ant Manual 1 5 4 12 9 2003 7 47 PM getlatest2 pvcs PVCS Version Manager VMGUI v6 6 10 Build 870 for Windows NT 80x86 pvcs Copyright 1985 2000 MERANT All rights reserved pvcs PVCS Version Manager get v6 6 10 Build 870 for Windows NT 80x86 pvcs Copyright 1985 2000 MERANT All rights reserved pvcs c myws myprj main java lt C mypvcs archives myprj main java arc pvcs rev 1 1 pvcs c myws myprj apache tool java lt C mypvcs archives myprj apache tool java arc pvcs rev 1 5 pvcs c myws myprj2 apache tool2 java lt C mypvces archives myprj2 apache tool2 java arc pvcs rev 1 2 BUILD SUCCESSFUL Total time 22 seconds PVCS i
44. Manual 1 5 4 12 9 2003 7 47 PM verbosity quiet when an assertion is violated Defaults to java lang Error Indicates the verbosity level of iContract Any combination of No error warning note info progress debug comma separated can be used Defaults to error Indicates if iContract should be quiet Turn it off if many your No classes extend uninstrumented classes and you don t want warnings about this Defaults to false updateicontrol If set to true it indicates that the properties file for iControl in the No controlfile classdir targets current directory should be updated or created if it doesn t exist Defaults to false The name of the control file to pass to iContract Consider using Only if iControl to generate the file Default is not to pass a file updateicontrol true Indicates where compiled unistrumented classes are located Only if This is required in order to properly update the icontrol properties updateicontrol true file not for instrumentation Name of the file that will be generated by this task which lists all No the classes that iContract will instrument If specified the file will not be deleted after execution If not specified a file will still be created but it will be deleted after execution Note Contract will use the java compiler indicated by the project s build compiler property See documentation of the Javac task for more information Nested includes and exclu
45. MessageFormat Defaults to 0 arc 1 Repositories where the archive extension is not arc should set this linestart Used to parse the output of the pcli command It defaults to P The No parser already knows about and this property is useful in cases where the repository is accessed on a Windows platform via a drive letter mapping Nested Elements pvcsproject element pvcs supports a nested lt pvcsproject gt element that represents a project within the PVCS repository to extract files from By nesting multiple lt pvcsproject gt elements under the lt pvcs gt task multiple projects can be specified Parameters 255 305 Ant Manual 1 5 4 Attribute Description The name of the pvcs project Yes name Examples 12 9 2003 7 47 PM Required The following set up extracts the latest version of the files in the pvcs repository lt lt Get th latest version lt I lt target name getlatest gt lt target gt Now run ant getlatest lt pvcs repository mnt pvcs pvesproject mypr3 gt This will cause the following output to appear get pvcs pvcs pvcs pvcs pvcs pvcs pvcs pvcs latest PVCS Copy PVCS Copy c myws myp rev l c myws myprj apache C mypvcs archives myprj apache tools java arc PGY La Version Manager VMGUI v6 6 10 Build 870 for Windows NT 80x86 right 1985 2000 M Version Manager right 1985 2000
46. NS 139 9483 PathGOnVent oi a a ad iaa 139 9 49 POPE a A A SS 141 9 50 URAC ii A A A In 143 9 51 Rename Deprecated ccccee cece eect rr nr rre rre 145 9 52 ROA A A oan ee ee 145 9 52 1 replaced tt dd ae te LEO 146 9 53 E O Soe be 147 IA SAQUE A A ao 149 MIA SON Mi A AAA A he AAA A A 150 9 56 Sleep k n A ds Ul eeee dee en ANa E a EE LT EE a OPADE Ia yl teach ee aed 150 DIO SO a aa 151 9 58 Style AS lio A ARE 155 959 TaT eccsisantivensigiten secs Bilecne tee ay ee yey aeed ment agh Mee Prat yeue dd EE EErEE EEEa 157 9 60 Taskdet sviiccs eee ies nocd oe ee ie vane ey ok by a 160 QOL Templo tao at Us OO 161 9 62 ROUGH cesar ent aden a E EAEE enactment ene AAE N 161 9 63 E 162 904 Ty Ped hen mii A oil gad Rh ie tine eee RRS 163 9 65 Unjar Untar Unwar UNnZip 00 cece eee eee nee eee teens enna eee nneee es 164 9 66 Uptodatesss cietuciedeageree tall ed ige nh pews ad e 165 907 Walton cs eevee hla es A ves cee eee ee ee nee 167 908 Wali crs inti ea gb foctee as the aeaa dae Dea ey eee pas dee et Sede eee Sea 168 9 69 XMIPFOPeErtys er kiinne se A rey e eed cela els nain da ean 170 9 70 ASIA SY la da SE con fake ola ds 171 O A o E E NA 171 10 Optional Task a aA A EE RA 175 TOETS SNET tasks xia A A A A ORA 175 10 1 1 LCS Cna A e et SU Aa e a a 175 10 1 2 LUISA e E 176 10 1 3 lt WsdIToDOtN e gt ini eeni dees PEKEN yee eE dee VENAE EE eens oe eke oe eS 177 10 1 4 ENANA R A Ee TD T een 178 10
47. One of file or at least one nested fileset element No defaults to false With the file attribute either tofile or todir can be used With nested filesets if the fileset size is greater than 1 or if the only entry in the fileset is a directory or if the file attribute is already specified only todir is allowed No Ant Manual 1 5 4 12 9 2003 7 47 PM destination files are newer default is true filtering indicates whether token filtering should No take place during the move See the filter task for a description of how filters work flatten ignore directory structure of source No directory copy all files into a single directory specified by the todir attribute default is false Note that you can achieve the same effect by using a flatten mapper includeEmptyDirs Copy empty directories included with No the nested FileSet s Defaults to yes failonerror Log a warning message but do not stop No defaults to true the build when the file to move does not exist Only meaningful when moving a single file verbose Log the files that are being moved No defaults to false encoding The encoding to assume when filter moving the mice since Ane 1 5 No defaults to default J VM encoding Parameters specified as nested elements mapper You can define file name transformations by using a nested mapper element The default mapper used by lt copy gt is the identity filterchain The Move task supports nested FilterCha
48. Users can define their own FilterReaders by just extending the java io FilterReader class Such custom FilterReaders can be easily plugged in as nested elements of lt filterchain gt by using lt filterreader gt elements Example lt copy file S src file tofile S dest file gt lt filterchain gt lt filterreader classname your extension of java io FilterReader gt lt param name foo value bar gt lt filterreader gt lt filterreader classname another extension of java io FilterReader gt lt classpath gt lt pathelement path classpath gt lt classpath gt lt param name blah value blee gt lt param type abra value cadabra gt lt filterreader gt lt filterchain gt lt copy gt Ant provides some built in filter readers These filter readers can also be declared using a syntax similar to the above syntax However they can be declared using some simpler syntax also Example lt loadfile srcfile S src file property S src file head gt lt filterchain gt lt headfilter lines 15 gt lt filterchain gt lt loadfile gt is equivalent to lt loadfile srcfile S src file property S src file head gt lt filterchain gt lt filterreader classname org apache tools ant filters HeadFilter gt 43 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt param name lines value 15 gt lt filterreader gt lt filterchain gt lt loadfile gt The following
49. When set to no the default the JAR file is overwritten An example use of this is provided in the Zip task documentation Please note that ZIP files store file modification times with a granularity of two seconds If a file is less than two seconds newer than the entry in the archive Ant will not consider it newer The Jar task is a shortcut for specifying the manifest file of a J AR file The same thing can be accomplished by using the fullpath attribute of a zipfileset in a Zip task The one difference is that if the manifest attribute is not specified the Jar task will include an empty one for you Manifests are processed by the Jar task according to the Jar file specification Note in particular that this may result in manifest lines greater than 72 bytes being wrapped and continued on the next line Parameters Attribute Description Required destfile the J AR file to create Yes basedir the directory from which to jar the files No compress Not only store data but also compress them defaults to true No encoding The character encoding to use for filenames inside the archive Defaults No to UTF8 It is not recommended to change this value as the created archive will most likely be unreadable for J ava otherwise filesonly Store only file entries defaults to false No includes comma or space separated list of patterns of files that must be included No All files are included when omitted includesfile the name of a file Each lin
50. Yes torefid The id of the reference in the new project No defaults to the value of refid Examples lt target name default gt lt antcall target doSomethingElse gt lt param name paraml value value gt lt antcall gt lt target gt lt target name doSomethingElse gt lt echo message paraml1 paraml gt lt target gt Will run the target doSomethingElse and echo param1 value lt antcall gt lt reference refid pathl1 torefid path2 gt lt antcall gt will copy the parent s definition of path1 into the new project using the id path2 9 3 AntStructure Description Generates a DTD for Ant buildfiles which contains information about all tasks currently known to Ant 77 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Note that the DTD generated by this task is incomplete you can always add XML entities using lt taskdef gt or lt typedef gt See here for a way to get around this problem This task doesn t know about required attributes all will be listed as IMPLIED Parameters Attribute Description_______ Required ile to write the DTD to Yes Examples lt antstructure output project dtd gt 9 4 Apply ExecOn The name execon is deprecated and only kept for backwards compatibility Description Executes a system command When the os attribute is specified then the command is only executed when Ant is run on one of the specified operating system
51. a local directory In fact the dir attribute of the fileset is ignored completely lt ftp action del server ftp apache org userid anonymous password me myorg com gt lt fileset gt lt include name tmp gt lt fileset gt lt ftp gt Logs in to ftp apache org aS anonymous and tries to delete all tmp files from the default directory for that user If you don t have permission to delete a file a BuildException is thrown 10 9 4 Listing Files lt ftp action list server ftp apache org userid anonymous 210 305 Ant Manual 1 5 4 12 9 2003 7 47 PM password me myorg com isting data ftp listing gt lt fileset gt lt include name gt lt fileset gt lt ftp gt This provides a file listing in data ftp listing of all the files on the FTP server relative to the default directory of the anonymous user The listing is in whatever format the FTP server normally lists files 10 9 5 Creating Directories Note that with the mkdir action the directory to create is specified using the remotedir attribute lt ftp action mkdir server ftp apache org userid anonymous password me myorg com remotedir some remote dir gt This creates the directory some remote dir beneath the default root directory As with all other actions the directory separator character must be correct according to the desires of the FTP server 10 10 icontract Description Instruments J ava classes w
52. a shortcut for specifying the particular layout of a EAR file The same thing can be accomplished by using the prefix and fullpath attributes of zipfilesets in a Zip or J ar task The extended zipfileset element from the zip task with attributes prefix fullpath and src is available in the Ear task Parameters Attribute Description Required destfile the EAR file to create Yes appxml The deployment descriptor to use META INF application xml Yes unless update is set to true basedir the directory from which to jar the files No compress Not only store data but also compress them defaults to true No encoding The character encoding to use for filenames inside the archive No Defaults to UTF8 It is not recommended to change this value as the created archive will most likely be unreadable for J ava otherwise filesonly Store only file entries defaults to false No includes comma or space separated list of patterns of files that must be No included All files are included when omitted includesfile the name of a file Each line of this file is taken to be an include No pattern excludes comma or space separated list of patterns of files that must be No excluded No files except default excludes are excluded when omitted excludesfile the name of a file Each line of this file is taken to be an exclude No pattern defaultexcludes indicates whether default excludes should be used or not No yes no Default excludes are used when omit
53. according to the location of the deployment descriptor within the descriptor dir hierarchy dependency This attribute controls which additional classes and interfaces are No added to the jar Please refer to the description above Nested Elements In addition to the vendor specific nested elements the ejbjar task provides three nested elements Classpath The lt classpath gt nested element allows the classpath to be set It is useful when setting the classpath from a reference path In all other respects the behaviour is the same as the classpath attribute dtd The lt dtd gt element is used to specify the local location of DTDs to be used when parsing the EJB deployment descriptor Using a local DTD is much faster than loading the DTD across the net If you are running ejbjar behind a firewall you may not even be able to access the remote DTD The supported vendor specific nested elements know the location of the required DTDs within the vendor class hierarchy and in general this means lt dtd gt elements are not required It does mean however that the vendor s class hierarchy must be available in the classpath when Ant is started If your want to run Ant without requiring the vendor classes in the classpath you would need to use a lt dtd gt element Attribute Description Required publicld The public Id of the DTD for which the location is being provided Yes location The location of the local copy of the DTD This can eith
54. an alias e kjc the kopi compiler e gcj the gcj compiler from gcc e sj Symantec java compiler symantec can be used as an alias 120 305 Ant Manual 1 5 4 12 9 2003 7 47 PM e extJavac run either modern or classic in a JVM of its own The default is javac1 x with x depending on the JDK version you use while you are running Ant If you wish to use a different compiler interface than those supplied you can write a class that implements the CompilerAdapter interface package org apache tools ant taskdefs compilers Supply the full classname in the build compiler property or the compiler attribute The fork attribute overrides the build compiler property or compiler attribute setting and expects a JDK1 1 or higher to be set in JAVA_HOME You can also use the compiler attribute to tell Ant which J DK version it shall assume when it puts together the command line switches even if you set fork true This is useful if you want to run the compiler of JDK 1 1 while you current JDK is 1 2 If you use compiler javac1 1 and for example depend true Ant will use the command line switch depend instead of Xdepenad This task will drop all entries that point to non existent files directories from the classpath it passes to the compiler Windows Note When the modern compiler is used in unforked mode on Windows it locks up the files present in the classpath of the lt javac gt task and does not release them The side eff
55. are redundant and will be ignored The http condition checks for a valid response from a web server of the specified url By default HTTP responses errors of 400 or greater are viewed as invalid Attribute Description____ gt gt gt gt _ Required return a status code below the value of errorsBeginAt i he lowest HTTP response code that signals an error by prorat 400 server errors not authorized not found and No the like are detected The socket condition checks for the existence of a TCP IP listener at the specified host and port Attribute Description Required Test two files for matching Nonexistence of either file results in false This test does a byte for byte comparision so test time scales with byte size NB if the files are different sizes one of them is missing or the filenames match the answer is so obvious the detailed test is omitted Tests whether a string contains another one Attribute Description _________________Required string fhe string to searchin es Substring The string to search for Yes Tests whether a string equals any of the ant definitions of true that is true yes or on Attribute Description Required lt istrue value someproperty gt lt istrue value false gt Tests whether a string is not true the negation of lt istrue gt Attribute Description Required value value to testiYes lt isfalse value someproperty gt lt isfalse value false gt
56. arg value arg2 gt lt fileset dir tmp gt lt apply gt invokes somecommand argl SOURCEFILENAME arg2 for each file in tmp replacing SOURCEFILENAME with the absolute filename of each file in turn If parallel had been set to true SOURCEFILENAME would be replaced with the absolute filenames of all files separated by spaces lt apply executable cc dest src C parallel false gt lt arg value c gt lt arg value 0 gt lt targetfile gt lt srcfile gt lt fileset dir src C includes c gt lt mapper type glob from c to o gt lt apply gt invokes cc c o TARGETFILE SOURCEFILE for each c file that is newer than the corresponding o replacing TARGETFILE with the absolute filename of the o and SOURCEFILE with the absolute name of the c file 9 5 Available Description Sets a property if a resource is available at runtime This resource can be a file a directory a Class in the classpath or a JVM system resource If the resource is present the property value is set to true by default otherwise the property is not set You can set the value to something other than the default by specifying the value attribute Normally this task is used to set properties that are useful to avoid target execution depending on system parameters Parameters roperty The name of the property to set value The value to set the property to Defaults to true
57. avaCC file Parameters Attribute Description Required target The jjtree grammar file to process Yes javacchome The directory containing the JavaCC distribution Yes outputdirectory The directory to write the generated file to If not set the files are written No to the directory containing the grammar file buildnodefiles Sets the BUILD_NODE_FILES grammar option This is a boolean option No multi Sets the MULTI grammar option This is a boolean option No nodedefaultvoid Sets the NODE_DEFAULT_VOID grammar option This is a boolean option No nodefactory Sets the NODE_FACTORY grammar option This is boolean option No nodescopehook Sets the NODE_SCOPE_HOOK grammar option This is a boolean option No nodeusesparser Sets the NODE_USES_PARSER grammar option This is a boolean option No static Sets the STATIC grammar option This is a boolean option No visitor Sets the VISITOR grammar option This is a boolean option No 225 305 Ant Manual 1 5 4 12 9 2003 7 47 PM nodepackage Sets the NODE_PACKAGE grammar option This is a string option No visitorexception Sets the VISITOR_EXCEPTION grammar option This is a string option No nodeprefix Sets the NODE_ PREFIX grammar option This is a string option No Example lt jjtree target src Parser jjt outputdirectory build src javacchome c program files Javacc nodeusesparser true gt This invokes J Tree on grammar file src Parser jjt writing the generated gra
58. by java lang Runtime exec Ignored jis java if fork is disabled dir The directory in which to invoke the VM Ignored if fork is disabled No newenvironment Do not propagate the old environment when new environment No default variables are specified Ignored if fork is disabled is false includeantruntime I mplicitly add the Ant classes required to run the tests and J Unit to the No default classpath in forked mode is true showoutput Send any output generated by tests to Ant s logging system as well as No to the formatters By default only the formatters receive the output 233 305 Ant Manual 1 5 4 12 9 2003 7 47 PM By using the errorproperty and failureproperty attributes it is possible to perform setup work such as starting an external server execute the test clean up and still fail the build in the event of a failure The filtertrace attribute condenses error and failure stack traces before reporting them It works with both the plain and XML formatters It filters out any lines that begin with the following string patterns junit framework TestCase 3unit framework TestResult Junit framework TestSuite Junit framework Assert jJunit swingui TestRunner Junit awtui TestRunner Junit textui TestRunner Java lang reflect Method invoke org apache tools ant Nested Elements The lt junit gt task supports a nested lt classpath gt element that represents a PATH like structure
59. code to parse MS DOS listings any takers Parameters Attribute Description Required server the address of the remote ftp server Yes port the port number of the remote ftp server Defaults to port 21 No userid the login id to use on the ftp server Yes password the login password to use on the ftp server Yes remotedir the directory to which to upload files on the ftp server No action the ftp action to perform defaulting to send Currently supports No out get del list chmod and mkdir binary selects binary mode yes or text mode no transfers Defaults No to yes passive selects passive mode yes transfers Defaults to no No verbose displays information on each file transferred if set to yes Defaults No to no depends transfers only new or changed files if set to yes Defaults to no No newer a synonym for depends No separator sets the file separator used on the ftp server Defaults to No umask sets the default file permissions for new files unix only No chmod sets or changes file permissions for new or existing files unix only No If used with a put action chmod will be issued for each file listing the file to write results of the list action Required for the list No action ignored otherwise ignoreNoncriticalErrors flag which permits the task to ignore some non fatal error codes No 208 305 Ant Manual 1 5 4 12 9 2003 7 47 PM sent by some servers during dir
60. com gt lt message gt The buildname nightly build has completed lt message gt lt fileset dir dist gt lt includes name zip gt lt fileset gt lt mail gt Sends an eMail from me myisp com to all xyz com with a subject of Test Build and attaches any zip files from the dist directory The task will attempt to use JavaMail and fall back to UU encoding or no encoding in that order depending on what support classes are available buildname will be replaced with the buildname property s value 9 43 Manifest Description Creates a manifest file This task can be used to write a Manifest file optionally replacing or updating an existing file 134 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Manifests are processed according to the Jar file specification Specifically a manifest element consists of a set of attributes and sections These sections in turn may contain attributes Note in particular that this may result in manifest lines greater than 72 bytes being wrapped and continued on the next line Parameters Attribute Description Required file the manifest file to create update Yes mode One of update or replace default is replace No encoding The encoding used to read the existing manifest when No defaults to UTF 8 updating encoding Nested elements attribute One attribute for the manifest file Those attributes that are not nested into a section will be added to the Main sectio
61. comment text gt Does a ClearCase checkout on the file c views viewdir afile It is checked out as reserved on branch called abranch All warning messages are suppressed A Some comment text is added to ClearCase as a comment 10 4 3 CCUnCheckout Description Task to perform a UnCheckout command to ClearCase Parameters Attribute Values Required viewpath Path to the ClearCase view file or directory that the command will operate on No keepcopy Specifies whether to keep a copy of the file with a keep extension or not No Examples lt ccuncheckout viewpath c views viewdir afile 182 305 Ant Manual 1 5 4 12 9 2003 7 47 PM keepcopy true gt Does a ClearCase uncheckout on the file c views viewdir afile A copy of the file called c views viewdir afile keep is kept 10 4 4 CCUpdate Description Task to perform an Update command to ClearCase Parameters Attribute Values Required viewpath Path to the ClearCase view file or directory that the command will operate on No graphical Displays a graphical dialog during the update No log Specifies a log file for ClearCase to write to No overwrite Specifies whether to overwrite hijacked files or not No rename Specifies that hijacked files should be renamed with a keep extension No Specifies that modification time should be written as the current time Either currenttime or preservetime can be specified Specifies that modification time should preserved from the VOB t
62. compiler should force catching of No exceptions by explicitly named types Whether debug symbols should be generated into the No class file Asks the NetRexx compiler to print compilation times to No the console Turns on or off tracing and directs the resultant trace No output Tells the NetRexx compiler that the source is in UTF8 No Whether lots of warnings and error messages should be No generated suppressMethodArgumentNotUsed Tells whether we should filter out the amp Method argument no suppressPrivatePropertyNotUsed suppressVariableNotUsed suppressExceptionNotSignalled suppressDeprecation Examples not used amp messages in strictargs mode Tells whether we should filter out the amp Private Property no defined but not used amp messages in strictargs mode Tells whether we should filter out the amp Variable set but no not used amp messages in strictargs mode Please be careful with this one as you can hide errors behind it Tells whether we should filter out the amp Exception is no declared but not signalled within the method amp messages in strictsignal mode Tells wether we should filter out any deprecation no messages of the compiler out lt netrexxc srcDir source project includes vnr util destDir source project build classpath source project2 proj jar comments true 10 30 by f false replace true keep true gt Perforce Tasks User Manual e Les Hughes leslie
63. dependant username The user with privileges to deploy applications to the server Tool dependant password The password of the user with privileges to deploy applications to the server Tool dependant Also supported are nested vendor specific elements 10 36 2 Generic element This element is provided for generic J ava based deployment tools The generic task accepts but does not require nested arg and jvmarg elements A JVM will be spawned with the provided attributes It is recommended that a vendor specific element be used over the generic one if at all possible The following attributes are supported by the generic element Attribute Description Required classname This is the fully qualified classname of the Java based deployment tool to Yes execute Nested Elements The generic element supports nested lt arg gt and lt jvmarg gt elements Example This example shows the use of generic deploy element to deploy a component using a Java based deploy tool lt serverdeploy action deploy source lib dir ejb_myApp ear gt lt generic classname com yamato j2ee tools deploy DeployTool classpath S classpath username user name password user password gt lt arg value component WildStar gt lt arg value force gt lt jvmarg value ms64m gt lt jvmarg value mx128m gt lt generic gt lt serverdeploy gt 10 36 3 WebLogic element The WebLogic element contains additional attributes
64. deprecation target verbose depend includeAntRuntime includeJ avaRuntime fork executable memorylnitialSize memoryMaximumSize failonerror source 12 9 2003 7 47 PM elsewhere Location of bootstrap class files given as a reference to a path No defined elsewhere Location of installed extensions No Encoding of source files Note gcj doesn t support this option No yet Indicates whether the nowarn switch should be passed to the No compiler defaults to off Indicates whether source should be compiled with debug No information defaults to off If set to off g none will be passed on the command line for compilers that support it for other compilers no command line argument will be used If set to true the value of the debuglevel attribute determines the command line argument Keyword list to be appended to the g command line switch No This will be ignored by all implementations except modern and classic ver gt 1 2 Legal values are none or a comma separated list of the following keywords lines vars and source If debuglevel is not specified by default nothing will be appended to g If debug is not turned on this attribute will be ignored Indicates whether source should be compiled with optimization No defaults to off Indicates whether source should be compiled with deprecation No information defaults to off Generate class files for specific VM version e g 1 1 or 1 2
65. different No sigfile name of SF DSA file No signedjar name of signed JAR file No verbose true false verbose output when signing No default false internalsf true false include the SF file inside the signature block No default false sectionsonly true false don t compute hash of entire manifest No default false lazy flag to control whether the presence of a signature file means a No default false JAR is signed maxmemory Specifies the maximum memory the jarsigner VM will use No Specified in the style of standard java memory specs e g 128m 128 MBytes Parameters as nested elements Attribute Description Required fileset fileset of J AR files to sign Will be ignored if the jar attribute of the task has been No set Examples lt signjar jar S dist lib ant jar alias apache group storepass secret gt signs the ant jar with alias apache group accessing the keystore and private key via secret password 9 56 Sleep Description A task for sleeping a short period of time useful when a build or deployment process requires an interval between tasks Parameters Attribute Description Required hours hours to to add to the sleep time No 150 305 Ant Manual 1 5 4 12 9 2003 7 47 PM minutes minutes to add to the sleep time No seconds seconds to add to the sleep time No milliseconds milliseconds to add to the sleep time No failonerror flag controlling whether to break the build on an error No The sleep
66. docs examples The archive might end up containing the files docs user guide html index html docs ChangeLog txt docs examples index html The code lt zip destfile S dist manual zip gt lt zipfileset dir htdocs manual prefix docs user guide gt lt zipgroupfileset dir includes examples zip gt lt zip gt zips all files in the htdocs manual directory into the docs user guide directory in the archive and includes all the files in any file that maches examples zip such as all files within examples1l zip or examples _for_brian zip 174 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 10 Optional Tasks 10 1 NET tasks 10 1 1 lt CSC gt This task compiles CSharp source into executables or modules This task compiles CSharp source into executables or modules The task will only work on win2K XP or other platforms with csc exe or an equivalent CSC must be on the execute path All parameters are optional lt csc gt should suffice to produce a debug build of all cs files References to external files do require explicit enumeration so are one of the first attributes to consider adding The task is a directory based task so attributes like includes cs and excludes broken cs can be used to control the files pulled in By default all cs files from the project folder down are included in the command When this happens the destFile if not specified is taken as the first file in the list which may be
67. ejbjar parses the weblogic deployment descriptor to discover the CMP descriptors which are then included automatically This behaviour is controlled by the newCMP attribute Note that if you move to the new method of determining CMP descriptors you will need to update your weblogic deployment descriptor s lt type storage gt element In the above example you would define this as META INF Customer weblogic cmp rdbms jar xml 197 305 Ant Manual 1 5 4 Attribute destdir genericjarsuffix suffix classpath wiclasspath keepgeneric compiler rebuild keepgenerated args weblogicdtd wldtd ejbdtd newCMP oldCMP 12 9 2003 7 47 PM Description Required The base directory into which the generated weblogic ready jar files are Yes deposited J ar files are deposited in directories corresponding to their location within the descriptordir namespace A generic jar is generated as an intermediate step in build the weblogic No defaults deployment jar The suffix used to generate the generic jar file is not to particularly important unless it is desired to keep the generic jar file It generic jar should not however be the same as the suffix setting String value appended to the basename of the deployment descriptor No defaults to create the filename of the WebLogic EJB jar file to jar The classpath to be used when running the weblogic ejbc tool Note No that this tool typically requires the cl
68. entries to this file has the same oe A CvsTagDiff Generates an XML formatted report file of the changes between two tags A E ccupdate commands ccmcheckintask ccmreconfigure and ccmcreateTask commands vsscheckin vsscheckout vssadd vsscp and vsscreate commands Perforce asks to perform the Perforce p4sync p4change p4edit p4submit eee ee p4label p4counter p4reopen p4revert and p4add commands asks to perform the SourceOffSite sosget soslabel soscheckin and Soscheckout commands asks to perform the StarTeam stcheckout stcheckin stlabel and stlist commands The Starteam task is deprecated use STCheckout instead 8 1 18 Testing Tasks Runs tests from the Junit testing framework This task has been tested with J Unit 3 0 up to J Unit 3 7 it won t work with versions prior to J Unit 3 0 unitReport Merges the individual XML files generated by the unit task and applies a stylesheet on the resulting merged document to provide a browsable report of the testcases results Test Executes a unit test in the org apache testlet framework 8 1 19 Visual Age for Java Tasks isual Age for Java Tasks See the documentation describing the Visual Age for Java tasks 72 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 9 Core Tasks 9 1 Ant Description Runs Ant on a supplied buildfile This can be used to build subprojects When the antfile attribute is omitted the file build xml in the supplied directory dir attribute
69. except javacl 4 or modern when Ant is not running in a 1 3 VM and jikes If you use this attribute together with jikes you must make sure that your version of jikes supports the source switch Legal values are 1 3 and 1 4 by default no source argument will be used at all compiler The compiler implementation to use If this attribute is not set No the value of the build compiler property if set will be used Otherwise the default compiler for the current VM will be used See the above list of valid compilers listfiles Indicates whether the source files to be compiled will be listed No defaults to no Parameters specified as nested elements This task forms an implicit FileSet and supports all attributes of lt fileset gt dir becomes srcdir as well as the nested lt include gt lt exclude gt and lt patternset gt elements src classpath sourcepath bootclasspath and extdirs lt javac gt s srcdir classpath sourcepath bootclasspath and extdirs attributes are path like structures and can also be set via nested lt src gt lt classpath gt lt sourcepath gt lt bootclasspath gt and lt extdirs gt elements respectively compilerarg You can specify additional command line arguments for the compiler with nested lt compilerarg gt elements These elements are specified like Command line Arguments but have an additional attribute that can be used to enable arguments only if a given compiler implementation will b
70. fails then throw an exception Note does not check that library implements extension lt extension id dve ext extensionName org realityforge dve specificationVersion 1 2 specificationVendor Peter Donald gt lt jarlib resolve property dve library checkExtension false gt lt extension refid dve ext gt lt ant antfile dve build xml target main destfile lib dve jar gt lt jarlib resolve gt Resolve Extension via multiple methods First check local file to see if it implements extension If it does not then try to build it from source in parralel directory If that fails then finally try to download it from a website If all steps fail then throw a build exception lt extension id dve ext extensionName org realityforge dve specificationVersion 1 2 specificationVendor Peter Donald gt Fh H lt jarlib resolve property dve library gt lt extension refid dve ext gt lt location location opt jars dve jar gt lt ant antfile dve build xml target main destfile lib dve jar gt lt url url http www realityforge net jars dve jar destfile lib dve jar gt lt jarlib resolve gt 10 15 JavaCC Description Invokes the JavaCC compiler compiler on a grammar file To use the javacc task set the target attribute to the name of the grammar file to process You also need to specify the directory containing the J avaCC inst
71. file but it does guarantee that the file did not exist when the task was executed Parameters Attribute Description Required destdir The directory the temporary file should be located in If not set the current No directory is used prefix A prefix for the temporary file name No property The name of the property to set with the value of the temporary file name Yes suffix A suffix for the temporary file name No Examples lt tempfile property temp file gt will set temp file to the name of a new temporary file lt tempfile property temp file suffix xml gt will set temp file to the name of a new temporary file with a suffix of xml lt tempfile property temp file destdir build gt will set temp file to the name of a new temporary file located in the build sub directory 9 62 Touch Description Changes the modification time of a file and possibly creates it at the same time In addition to working with a single file this Task can also work a Fileset which also includes directories For JDK 1 1 only the creation of new files with a modification time of now works all other cases will emit a warning Parameters Attribute Description Required file the name of the file unless a nested fileset element 161 305 Ant Manual 1 5 4 12 9 2003 7 47 PM has been specified millis specifies the new modification time of the file in No milliseconds since midnight Jan 1 1970 datetime specifies
72. file or resource have been specified file Name of the property file to load typename classname pairs No from resource Name of the property resource to load typename classname No pairs from classpath the classpath to use when looking up classname No loaderRef the name of the loader that is used to load the class No constructed from the specified classpath Use this to allow multiple tasks types to be loaded with the same loader so they can call each other introduced in ant1 5 Parameters specified as nested elements classpath Typedef s classpath attribute is a PATH like structure and can also be set via a nested classpath element Examples lt typedef name urlset classname com mydomain URLSet gt makes a data type called urlset available to Ant The class com mydomain URLSet implements this type 9 65 Unjar Untar Unwar Unzip Description Unzips a zip war tar or jarfile For JDK 1 1 last modified time field is set to current time instead of being carried from the archive file PatternSets are used to select files to extract from the archive If no patternset is used all files are extracted FileSets may be used used to select archived files to perform unarchival upon File permissions will not be restored on extracted files The untar task recognizes the long pathname entries used by GNU tar 164 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Parameters Attribute Description Required src arc
73. fileset gt The name of a file Each line of this file No is taken to be an include pattern excludes Deprecated Use lt fileset gt Comma or space separated list of No patterns of files that must be excluded from the deletion list All files are relative to the directory specified in dir No files except default excludes are excluded when omitted excludesfile Deprecated Use lt fileset gt The name of a file Each line of this file No is taken to be an exclude pattern defaultexcludes Indicates whether default excludes should be used or not No yes no Default excludes are used when omitted Examples lt delete file lib ant jar gt deletes the file lib ant ar lt delete dir lib gt deletes the 1ib directory including all files and subdirectories of lib lt delete gt lt fileset dir includes bak gt lt delete gt deletes all files with the extension bax from the current directory and any subdirectories lt delete includeEmptyDirs true gt lt fileset dir build gt lt delete gt deletes all files and subdirectories of build including build itself 101 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 9 22 Deltree Deprecated This task has been deprecated Use the Delete task instead Description Deletes a directory with all its files and subdirectories Parameters Attribute Description Required dir the directory to delete Yes Examples lt deltree dir d
74. for Xalan transformer like XSL P used to live at http www clc marketing com xslp Xalan or XSL P but the link doesn t work any longer and we are not aware of a replacement site jakarta regexp regexp type http j akarta apache org regexp 1 3 jar with mappers 17 305 Ant Manual 1 5 4 jakarta oro 2 0 7 jar junit jar xalan jar stylebook jar testlet jar antlr jar bsf jar netrexx jar js jar jpython jar jacl jar and tcljava jar BeanShell J AR s netcomponents ja F bcel jar mail jar activation jar jdepend jar 12 9 2003 7 47 PM regexp type with mappers http jakarta apache org oro and the perforce tasks junit tasks http www junit org junitreport task http xml apache org xalan j stylebook task CVS repository of http xml apache org deprecated Build from the gzip compress tar archive in test task http avalon apache org historiccvs testlet antlr task http www antir org script task http oss software ibm com developerworks projects bsf netrexx task http www2 hursley ibm com netrexx javascript with http www mozilla org rhino script task python with http www jpython org script task TCL with script http www scriptics com software java task BeanShell with http www beanshell org script task ftp and telnet j http www savarese org oro downloads index html NetCompone tasks nts classfileset http jakarta apache org bcel data
75. for details attribute 25 fn peewee provided alue of dir attribute provided omitted basedir of ga project the one whose build file contains the basedir Paiute of the lt project gt element of the new project Examples lt ant antfile subproject subbuild xml dir subproject target compile gt lt ant dir subproject gt lt ant antfile subproject property_based_subbuild xml gt lt property name paraml value version 1 x gt lt property file config subproject default properties gt lt ant gt lt ant inheritAll false antfile subproject subbuild xml gt lt property name output type value html gt lt ant gt The build file of the calling project defines some lt path gt elements like this lt path id pathl1 gt lt path gt lt path id path2 gt lt path gt and the called build file subbuild xm1 also defines a lt path gt with the id path1 but path2 is not defined lt ant antfile subbuild xml inheritrefs true gt will not override subbuild s definition of path1 but make the parent s definition of path2 available in the subbuild 75 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt ant antfile subbuild xml gt as well as lt ant antfile subbuild xml inheritrefs false gt will neither override path1 nor copy path2 lt ant antfile subbuild xml inheritrefs false gt lt reference refid path1 gt lt ant gt wi
76. from where to jar Note that file permissions will not be stored in the resulting jarfile It is possible to refine the set of files that are being jarred This can be done with the includes includesfile excludes excludesfile and defaultexcludes attributes With the includes or includesfile attribute you specify the files you want to have included by using patterns The exclude or excludesfile attribute is used to specify the files you want to have excluded This is also done with patterns And finally with the defaultexcludes attribute you can specify whether you want to use default exclusions or not See the section on directory based tasks on how the inclusion exclusion of files works and how to write patterns This task forms an implicit FileSet and supports all attributes of lt fileset gt dir becomes basedir as well as the nested lt include gt lt exclude gt and lt patternset gt elements You can also use nested file sets for more flexibility and specify multiple ones to merge together different trees of files into one JAR The extended fileset and groupfileset attributes from the zip task are also available in the jar task See the Zip task for more details and examples 115 305 Ant Manual 1 5 4 12 9 2003 7 47 PM If the manifest is omitted a simple one will be supplied by Ant The update parameter controls what happens if the JAR file already exists When set to yes the JAR file is updated with the files specified
77. gt lt fileset gt 58 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Selects all the JAR file larger than 4096 bytes which haven t been update since the last millenium 7 3 22 12 MAJ ORITY SELECTOR The lt majority gt tag selects files provided that a majority of the contained elements also select it Ties are dealt with as specified by the allowtie attribute Attribute Description Required allowtie Whether files should be selected if there are an even number of selectors No selecting them as are not selecting them Default is true Here is an example of how to use the Majority Selector lt fileset dir docs includes html gt lt majority gt lt contains text project casesensitive false gt lt contains text taskdef casesensitive false gt lt contains text IntrospectionHelper casesensitive true gt lt majority gt lt fileset gt Selects all the HTML files which contain at least two of the three phrases project taskdef and IntrospectionHelper this last phrase must match case exactly 7 3 22 13 NONE SELECTOR The lt none gt tag selects files that are not selected by any of the elements it contains It returns as soon as it finds a selector that selects the file so it is not guaranteed to check every selector Here is an example of how to use the None Selector lt fileset dir src includes Java gt lt none gt lt present targetdir dest gt lt p
78. gt Something wrong here lt fail gt 108 305 Ant Manual 1 5 4 12 9 2003 7 47 PM will give the same result as above 9 29 Filter Description Sets a token filter for this project or read multiple token filter from an input file and sets these as filters Token filters are used by all tasks that perform file copying operations through the Project commodity methods Note 1 the token string must not contain the separators chars Note 2 Either token and value attributes must be provided or only the filtersfile attribute Parameters Attribute Description Required token the token string without Yes value the string that should be put to replace the token when the file is copied Yes filtersfile The file from which the filters must be read This file must be a formatted asa Yes property file see notes 1 and 2 above parameters table Examples lt filter token year value 2000 gt lt copy todir dest dir filtering true gt lt fileset dir S sre dir gt lt copy gt will copy recursively all the files from the src dir directory into the dest dir directory replacing all the occurrences of the string Oyear with 2000 lt filter filtersfile deploy_env properties gt will read all property entries from the deploy_env properties file and set these as filters 9 30 FixCRLF Description Adjusts a text file to local conventions The set of files to be adjusted can be refined with the incl
79. haltonfailure no outfile result gt lt formatter type xml gt lt test gt 236 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt batchtest fork yes todir S reports tests gt lt fileset dir src tests gt lt include name Test java gt lt exclude name AllTests java gt lt fileset gt lt batchtest gt lt junit gt Runs my test TestCase in the same VM ignoring the given CLASSPATH only a warning is printed if this test fails In addition to the plain text test results for this test a XML result will be output to result xml Then for each matching file in the directory defined for src tests a test is run in a separate VM If a test fails the build process is aborted Results are collected in files named TEST name txt and written to reports tests 10 23 JUnitReport Merge the individual XML files generated by the J Unit task and eventually apply a stylesheet on the resulting merged document to provide a browsable report of the testcases results Note This task depends on external libraries not included in the Ant distribution See Library Dependencies for more information Requirements The task needs Xalan 2 x although Xalan 1 2 2 does work but as Xalan1 is not supported we do not recommend this If you do you use Xalan 1 2 2 you will need a compatible older version of Xerces as well as BSF bsf jar Again using Xalan 2 is simpler and supported Parameters Attri
80. include any CSC options which are not explicitly supported in the CSC task Internal changes e Some minor refactoring move common code a method e Application of J edits JavaStyle task resulted in a major reshaping of the codebase and the insertion of a blank line every second line Significant effort was required to revert some but not all changes e Removed throws clause from methods which can t throw exceptions The test harness has been expanded to include unicode source file the build works but the rest of the system has issues with high unicode package and method names Version 0 2 First public edition added to the ant cvs tree Tested on the PDC build of the dotnet SDK only and still immature The command execution code was refactored out into a NetCommand class for re use The llasm task was added at this time Version 0 1 Initial proof of concept very rudimentary support for CSC only 178 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 10 2 ANTLR Description Invokes the ANTLR Translator generator on a grammar file To use the ANTLR task set the target attribute to the name of the grammar file to process Optionally you can also set the outputdirectory to write the generated file to a specific directory Otherwise ANTLR writes the generated files to the directory containing the grammar file This task only invokes ANTLR if the grammar file is newer than the generated files Antlr 2 7 1 Note To successfully run
81. indent value yes gt lt xslt gt 9 59 Tar Description Creates a tar archive The basedir attribute is the reference directory from where to tar This task is a directory based task and as such forms an implicit Fileset This defines which files relative to the basedir will be included in the archive The tar task supports all the attributes of Fileset to refine the set of files to be included in the implicit fileset 157 305 Ant Manual 1 5 4 12 9 2003 7 47 PM In addition to the implicit fileset the tar task supports nested filesets These filesets are extended to allow control over the access mode username and groupname to be applied to the tar entries This is useful for example when preparing archives for Unix systems where some files need to have execute permission Early versions of tar did not support path lengths greater than 100 characters Modern versions of tar do so but in incompatible ways The behaviour of the tar task when it encounters such paths is controlled by the longfile attribute If the longfile attribute is set to fail any long paths will cause the tar task to fail If the longfile attribute is set to truncate any long paths will be truncated to the 100 character maximum length prior to adding to the archive If the value of the longfile attribute is set to omit then files containing long paths will be omitted from the archive Either option ensures that the archive can be untarred by any compliant
82. jar e super this is the default value and replicates the original ejbjar behaviour where super classes and super interfaces are added to the jar e full In this mode all classes used by the bean s classes and interfaces are added to the jar The super and full values require the jakarta BCEL library to be available If it is not ejbjar will drop back to the behaviour corresponding to the value none Parameters Attribute Description Required descriptordir The base directory under which to scan for EJB deployment No descriptors If this attribute is not specified then the deployment descriptors must be located in the directory specified by the srcdir attribute srcdir The base directory containing the class files that make up the Yes bean Included are the home remote pk and implementation classes and all classes that these depend on Note that this can be the same as the descriptordir if all files are in the same directory tree destdir The base directory into which generated jar files are deposited Yes Jar files are deposited in directories corresponding to their location within the descriptordir namespace Note that this attribute is only used if the task is generating generic jars i e no vendor specific deployment elements have been specified naming Controls the naming convention used to name generated EJB jars No 195 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Please refer to the description above basejarnam
83. la A da e a tg 252 TOZA Introductio iesi a A A alt 252 10 31 27 PropertyFile Task A e e 252 10 32 Ant Pvcs Task User Manual occccccccccccccnnnncnnncccnnn cnn eee cnn rr rr rr 254 LOLI ZA NEO UN iiide Geet ae aes eek dine EER lA S 255 EA Pacs Tia SK vives sce teat ei Pa Adame ae A 255 10 33 RenameExtensions Deprecated 00 cceceeee eect eee ee eee eee eeeteaeetenaee enna 257 10 34 ReplaGG ReGEXP ieiceccrgetsiieeed ar AR ERE pall pioa ae 258 10 35 RDM seer A A eerie eke as 259 10 36 ANT ServerDeploy User Manual ceceeee cnet reeset eee eee eeeeenaae tenes tenes 260 10 36 1 ServerDeploy element cece eee eee eee ete enna een ee seen neat 260 10 36 2 Generic element cece cece cece eee carr eee ened seen rr 261 10 36 3 WebLogic element cece cece eee eee ee eee nee ene eens enna 261 10 36 4 JONAS Java Open Applicaton Server element c cece eee eee eee ee eee 262 10 37 SEED OK it A A 263 10 38 SP a A e RD ida eli 264 10 39 SOUNG O 265 10 40 SourceOffSite Tasks User Manual ooocccoccccccnnccccnnncnnnnnnnnnrnnnnnrnrnnnrrrrrn nn 266 10 40 11 INTTOdU CON ii Is 266 10 40 2 The Tasks it de e i 267 10 403 SOS GEE oa e a ds ni La O e a 267 10 40 4 SOS Label iaa al A ai 267 A A A cea ele 8 i ue Jie he dia 268 10 40 60 SOS CHECKOUE xc teci tices Te lei ba eid eee eas tare tee eee 269 10 41 Splash sci Sette e a Bota eS IEC 269 10 42 Star leam SUPPONE roaraa a eE ER ad DEE D
84. local bin verbose true username build password build projectpath SourceRoot projecti sosserverpath 192 168 10 6 8888 vssserverpath server2 vss srcsafe ini gt hi hi Connects to a SourceOffsite server on server1 8888 with build build as the username amp password The SourceSafe database resides on a different box server2 amp the VSS database is on a share called vss Checks out project1 Only the project1 directory will be locked as the recursive option was not set Extra status messages will be displayed on screen The soscmd exe file to be used resides in usr local bin 10 41 Splash by Les Hughes leslie hughes rubus com Description This task creates a splash screen The splash screen is displayed for the duration of the build and includes a handy progress bar as well Use in conjunction with the sound task to provide interest whilst waiting for your builds to complete Parameters Attribute Description Required Default imageurl A URL pointing to an image to display No antlogo gif from the classpath showduration I nitial period to pause the build to show the splash No 5000 ms in milliseconds 269 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Deprecated properties The following properties can be used to configure the proxy settings to retrieve an image from behind a firewall However the settings apply not just to this task but to all following tasks Therefore they are now mostly
85. looking at the project in the workspace it is often difficult to distinguish between project name and version name e g as in My GUI Components Java 2 3 5 Check if you have the right project name by switching off the version name display temporarilly Q How do control the import export of sourcefiles compiled files and project resources explicity A Via the Boolean values exportClasses default false exportSources default true and exportResources default true In some situations Resources are not exported correctly without this being explicity set VAJ doesn t export resources correctly if a package contains only resources see below Known Problems Exporting a package containing just resources doesn t work This is a VAJ Tool API bug Workaround create a dummy class and set exportSources to false VisualAge for J ava Versions This tool integration has been tested with versions 3 02 and 3 5 of VisualAge for Java It should run with the 2 x Versions too but we didn t try The graphical user interface is built with AWT so it is JDK independent by now History 1 0 2000 09 11 nitial Version SS ieee ae Added Task documentation and more FAQs thanks to Richard Bourke for the FAQ additions 1 2 2001 07 02Added documentation of new remote feature Minor corrections 11 2 1 2003 01 16Added documentation for haltonerror and version qualifiers 10 48 Microsoft Visual SourceSafe Tasks User Manual by e Cra
86. lt lt e lt t A timeout can be specified at the lt telnet gt level or at the lt read gt level This will connect issue a sleep command that is suppressed from displaying and wait 10 seconds before quitting lt telnet userid bob password badpass server localhost timeout 20 gt lt read gt home bob lt read gt lt writ cho false gt sleep 15 lt write gt lt read timeout 10 gt home bob lt read gt lt telnet gt The task can be used with other ports as well lt telnet port 80 server localhost timeout 20 gt lt read gt lt write gt GET http 0 9 lt write gt lt write gt lt read timeout 10 gt amp 1t HTML gt lt read gt lt telnet gt To use this task against the WinNT telnet service you need to configure the service to use classic authentication rather than NTLM negotiated authentication This can be done in the Telnet Server Admin app select display change registry settings then NTLM then set the value of NTLM to 1 10 45 Test Description This is a primitive task to execute a unit test in the org apache testlet framework This task is deprectated as the Testlet framework has been abandoned in favor of J Unit by the Avalon community Note This task depends on external libraries not included in the Ant distribution See Library Dependencies for more information Parameters 282 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Attribute Description Requi
87. lt depend gt tag selects files whose last modified date is later than another equivalent file in another location The lt depend gt tag supports the use of a contained lt mapper gt element to define the location of the file to be compared against If no lt mapper gt element is specified the identity type mapper is used The lt depend gt selector is case sensitive 55 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Attribute Description Required targetdir The base directory to look for the files to compare against The precise location Yes depends on a combination of this attribute and the lt mapper gt element if any granularity The number of milliseconds leeway to give before deciding a file is out of date No This is needed because not every file system supports tracking the last modified time to the millisecond level Default is O milliseconds except on Windows systems where it is 2000 milliseconds 2 seconds Here is an example of how to use the Depend Selector lt fileset dir ant 1 5 src main includes java gt lt depend targetdir S ant 1 4 1 src main gt lt fileset gt Selects all the Java source files which were modified in the 1 5 release 7 3 22 6DEPTH SELECTOR The lt depth gt tag selects files based on how many directy levels deep they are in relation to the base directory of the fileset Attribute Description Required min The minimum number of directory levels below the base directory
88. lt patternset gt are identical The include patterns will be read from the file some file one pattern per line lt patternset gt lt includesfile name some file gt lt includesfile name some other file if some other file gt lt patternset gt will also read include patterns from the file the property some other file points to if a property of that name has been defined 7 3 22 Selectors Selectors are a mechanism whereby the files that make up a fileset can be selected based on criteria other than filename as provided by the lt include gt and lt exclude gt tags 7 3 22 1HOW TO USE A SELECTOR A selector is an element of FileSet and appears within it It can also be defined outside of any target by using the lt selector gt tag and then using it as a reference Different selectors have different attributes Some selectors can contain other selectors and these are called Selector Containers There is also a category of selectors that allow user defined extensions called Custom Selectors The ones built in to Ant are called Core Selectors 7 3 22 2 CORE SELECTORS Core selectors are the ones that come standard with Ant They can be used within a fileset and can be contained within Selector Containers The core selectors are e lt contains gt Select files that contain a particular text string e lt date gt Select files that have been modified either before or after a particular date and
89. lt record name log txt action stop gt lt compile gt The following two calls to lt record gt set up two recorders one to file records simple log at logging level info the default and one to file 1SO log using logging level of verbose lt record name records simple log gt lt record name ISO log loglevel verbose gt Notes There is some functionality that would like to be able to add in the future They include things like the following Attribute Description Required listener A classname of a build listener to use from this point on instead of the default listener includetarget A comma separated list of targets to automatically record If this value is no excludetarget all then all targets are recorded Default all no includetask A comma separated list of task to automatically record or not This could be no excludetask difficult as it could conflict with the includetarg et excludetarget e g includetarget compile exlcudetask javac what should happen action add greater flexibility to the action attribute Things like close to close the no print stream 144 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 9 51 Rename Deprecated This task has been deprecated Use the Move task instead Description Renames a given file Parameters Attribute Description Required src file to rename Yes dest new name of the file Yes replace Enable replacing of existing file defa
90. myfile jar gt Display Extension info for a fileset lt jarlib display gt lt fileset dir lib gt lt include name jar gt lt fileset gt lt jarlib display gt 10 13 jarlib manifest Description Task to generate a manifest that declares all the dependencies in manifest The dependencies are determined by looking in the specified path and searching for Extension Optional Package specifications in the manifests of the jars Note that this task works with extensions as defined by the Optional Package specification For more information about optional packages see the document Optional Package Versioning in the documentation bundle for your Java2 Standard Edition package in file a a ai td html or online at See the Extension and ExtensionSet documentation for further details Parameters Attribute Description Required destfile The file to generate Manifest into Yes Parameters specified as nested elements extension Extension the extension that this library implements depends ExtensionSets containing all dependencies for jar options ExtensionSets containing all optional dependencies for jar Optional dependencies will be used if present else they wilkl be ignored Examples Basic Manifest generated for single Extension lt extension id el extensionName MyExtensions specificationVersion 1 0 specificationVendor Peter Donald 215 305 Ant Manual 1 5 4 12 9 2003 7 47 PM implementat
91. path If the refid attribute is not specified then a nested lt path gt element must be supplied See Path like Structures for details Examples In the examples below assume that the wl home property has the value d weblogic and wl home unix has the value weblogic 140 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Example 1 lt path id wl path gt lt pathelement location S wl home lib weblogicaux jar gt lt pathelement location wl home classes gt lt pathelement location wl home mssqlserver4 classes gt lt pathelement location c winnt System32 gt lt path gt lt pathconvert targetos unix property wl path unix refid wl path gt lt map from S wl home to S wl home unix gt lt map from c to gt lt pathconvert gt will generate the path shown below and store it in the property named wl path unix weblogic lib weblogicaux jar weblogic classes weblogic mssqlserver4 classe s WINNT SYSTEM32 Example 2 Given a FileList defined as lt filelist id custom_tasks jars dir S env HOME ant lib files njavac jar xproperty jar gt then lt pathconvert targetos unix property custom_tasks jars refid custom_tasks jars gt lt map from env HOME to usr local gt lt pathconvert gt will convert the list of files to the following Unix path usr local ant lib njavac jar usr local ant lib xproperty jar Example 3 lt fileset dir
92. pathelement location S was4 home deploytool itp plugins org eclipse core boot boot jar gt lt pathelement location S was4 home deploytool itp plugins com ibm etools ejbdeploy runtim e batch jar gt 202 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt pathelement location S was4 home lib xerces jar gt lt pathelement location S was4 home lib ivjejb35 jar gt lt pathelement location S was4 home lib j2ee jar gt lt pathelement location was4 home lib vaprt jar gt lt wasclasspath gt lt classpath gt lt path refid build classpath gt lt classpath gt lt websphere gt lt dtd publicld Sun Microsystems Inc DID Enterprise JavaBeans 1 1 EN location 1ib dtd ejb jar_1_1 dtda gt lt ejbjar gt 10 7 3 51PLANET APPLICATION SERVER IAS ELEMENT The lt iplanet lt nested element is used to build AS specific stubs and skeletons and construct a JAR file which may be deployed to the Planet Application Server 6 0 The build process will always determine if the EJB stubs skeletons and the EJ B J AR file are up to date and it will do the minimum amount of work required Like the WebLogic element a naming convention for the EJB descriptors is most commonly used to specify the name for the completed JAR file For example if the EJB descriptor ejb Account ejb jar xml is found in the descriptor directory the iplanet element will s
93. perforce P4Edit gt lt taskdef name p4submit classname org apache tools ant taskdefs optional perforce P4Submit gt lt taskdef name p4have classname org apache tools ant taskdefs optional perforce P4Have gt lt taskdef name p4label classname org apache tools ant taskdefs optional perforce P4Label gt lt taskdef name p4counter classname org apache tools ant taskdefs optional perforce P4Counter gt lt taskdef name p4reopen classname org apache tools ant taskdefs optional perforce P4Reopen gt lt taskdef name p4revert classname org apache tools ant taskdefs optional perforce P4Revert gt lt taskdef name p4add classname org apache tools ant taskdefs optional perforce P4Add gt Task Descriptions 10 30 5 P4Sync Description Synchronize the current workspace with the depot 248 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Parameters Attribute Description Required force force a refresh of files if this attribute no if ommitted it will be off otherwise a has been set refresh will be forced label sync client to label no Examples lt p4sync label nightlybuild 0 0123 force foo gt lt p4sync view depot projects projectfoo main src gt 10 30 6 P4Change Description Request a new changelist from the Perforce server This task sets the p4 change property which can then be passed to P4Submit P4Edit or P4Add Parameters Attribute Description Re
94. retained If omitted it defaults to no debug Indicates whether or not the ejbc utility should log additional debugging No statements to the standard output If yes the additional debugging statements will be generated If omitted it defaults to no iashome May be used to specify the home directory for this AS installation This is No used to find the ejbc utility if it isn t included in the user s system path If specified it should refer to the install location iplanet ias6 ias directory If omitted the ejbc utility must be on the user s system path Examples lt iplanet ejbc ejbdescriptor ejb jar xml lasdescriptor ias ejb Jar xml dest build classesdir classpath S ias ejbc cpath gt lt iplanet ejbc ejbdescriptor ejb Jar xml lasdescriptor ias ejb Jar xml dest S build classesdir keepgenerated yes debug yes iashome S ias home gt lt classpath gt lt pathelement path gt lt pathelement path build classpath gt lt classpath gt lt iplanet ejbc gt 190 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 10 7 2 4WLRUN Description The wlrun task is used to start a weblogic server The task runs a weblogic instance in a separate Java Virtual Machine A number of parameters are used to control the operation of the weblogic instance Note that the task and hence ant will not complete until the weblogic instance is stopped Parameters Attribute
95. rooted at C dev buildtest co into the AView view of the AProject project in the repository For files and folders in the local tree but not in starteam nothing will be done Since the forced attribute is set the files which are checked in will be checked in without regard to what the StarTeam repository considers their status to be This is a reasonable choice of attributes since StarTeam s status for a file is calculated based on the local file in the StarTeam default directory not on the directory we are actually working with lt stcheckin URL STARTEAM 49201 Aproject AView gt username auser password secret rootlocalfolder C dev buildtest co forced true And this is a simpler way of giving the same commands as the command above using the URL shortcut lt stcheckin URL STARTEAM 49201 Aproject AView username auser password secret rootlocalfolder C dev buildtest co rootstarteamfolder Dev excludes bak old 274 305 Ant Manual 1 5 4 12 9 2003 7 47 PM forced true gt This will check all files in to the Dev folder and below that do not end in bakor old from the tree rooted at C dev buildtest co lt stcheckin URL STARTEAM 49201 Aproject AView username auser password secret rootlocalfolder C dev buildtest co includes htm html xcludes index forced true gt This is an example of overlapping includes and excludes attributes Because e
96. run this task set fork true to use a new JVM Parameters Attribute Description Required classname the J ava class to execute Either jar or classname jar the location of the jar file to execute must have a Main Class entry injEither jar or the manifest Fork must be set to true if this option is selected classname args the arguments for the class that is executed deprecated use nested No lt arg gt elements instead classpath the classpath to use No classpathref the classpath to use given as reference to a PATH defined elsewhere No fork if enabled triggers the class execution in another VM disabled by No default jvm the command used to invoke the Java Virtual Machine default is No java The command is resolved by java lang Runtime exec Ignored if fork is disabled jvmargs the arguments to pass to the forked VM ignored if fork is disabled No deprecated use nested lt jvmarg gt elements instead maxmemory Max amount of memory to allocate to the forked VM ignored if fork is No disabled failonerror Stop the buildprocess if the command exits with a returncode other No than 0 Default is false dir The directory to invoke the VM in ignored if fork is disabled No output Name of a file to write the output to No append whether output should be appended to or overwrite an existing file No 118 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Defaults to false newenvironment Do not propagate old environment when new environ
97. same level as target i e as children of lt project gt PatternSets can be specified as nested lt patternset gt elements In addition DirSet holds an implicit PatternSet and supports the nested lt include gt lt includesfile gt lt exclude gt and lt excludesfile gt elements of lt patternset gt directly as well as lt patternset gt s attributes Attribute Description Required dir The root of the directory tree of this DirSet Yes includes A comma or space separated list of patterns of directories that must No be included all directories are included when omitted includesfile The name of a file each line of this file is taken to be an include No pattern excludes A comma or space separated list of patterns of directories that must No be excluded no directories are excluded when omitted excludesfile The name of a file each line of this file is taken to be an exclude No pattern 36 305 Ant Manual 1 5 4 12 9 2003 7 47 PM casesensitive Specifies whether case sensitivty should be applied true yes on or No defaults to false no off true followsymlinks Shall symbolic links be followed Defaults to true See fileset s No documentation Examples lt dirset dir S build dir gt lt include name apps classes gt lt exclude name apps Test gt lt dirset gt Groups all directories named classes found under the apps subdirectory of build dir except those that have the text
98. sets the specified property to that name Touch Changes the modification time of a file and possibly creates it at the same time 8 1 9 Java2 Extensions Tasks arlib availablelCheck whether an extension is present in a FileSet or an ExtensionSet If the extension is present the specified property is set Display the Optional Package and Package Specification information contained within the specified jars dependencies are determined by looking in the specified path and searching for Extension Optional Package specifications in the manifests of the jars ry to locate a jar to satisfy an extension and place the location of the jar into the specified property 8 1 10 Logging Tasks Runs a listener that records the logging output of the build process events to a file Several recorders can exist at the same time Each recorder is associated with a file 8 1 11 Mail Tasks Task Name Mail Atask to send SMTP email MimeMail__ Deprecated Use the Mail task instead 8 1 12 Miscellaneous Tasks Echo Echoes text to System out or to a file Fail Exits the current build by throwing a BuildException optionally printing additional information IGenKey Generates a key in keystore Input Allows user interaction during the build process by displaying a message and reading a line of input from the console 70 305 Ant Manual 1 5 4 12 9 2003 7 47 PM cript Executes a script in a BSF supported language S
99. specify the distinguished name by creating a sub element named dname and populating it with param elements that have a name and a value When using the subelement it is automatically encoded properly and commas are replaced with MN w The following two examples are identical Examples lt genkey alias apache group storepass secret dname CN Ant Group OU Jakarta Division O Apache org C US gt lt genkey alias apache group storepass secret gt lt dname gt lt param name CN value Ant Group gt lt param name 0U value Jakarta Division gt lt param name 0 value Apache Org gt lt param name C value US gt lt dname gt lt genkey gt 112 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 9 32 Get Description Gets a file from a URL When the verbose option is on this task displays a for every 100 Kb retrieved Any URL schema supported by the runtime is valid here including http ftp and jar https is only valid if the appropriate support is added to the pre 1 4 Java runtimes This task should be preferred above the CVS task when fetching remote content CVS is significantly slower than loading a compressed archive compared to http ftp The usetimestamp option enables you to control downloads so that the remote file is only fetched if newer than the local copy If there is no local copy the download always takes place When a file is downloaded the timestamp of the downloaded file is se
100. terminator e JDK 1 4 uses n r n u0085 u2028 1u2029 as a default but is configured in the wrapper to use only n UNI X_LINE We strongly recommend that you use J akarta Oro Parameters Attribute Description Required file file for which the regular expression should be replaced Yes if no nested lt fileset gt is used match The regular expression pattern to match in the file s Yes if no nested lt regexp gt is used replace The substitution pattern to place in the file s in place of the regular Yes if no nested expression lt substitution gt is used flags The flags to use when matching the regular expression For more No information consult the Perl5 syntax g Global replacement Replace all occurences found i Case Insensitive Do not consider case in the match m Multiline Treat the string as multiple lines of input using and as the start or end of any line respectively rather than start or end of string s Singleline Treat the string as a single line of input using to match any character including a newline which normally it would not match byline Process the file s one line at a time executing the replacement on No one line at a time true false This is useful if you want to only replace the first occurence of a regular expression on each line which is not easy to do when processing the file as a whole Defaults to false Examples lt replaceregexp file src build p
101. the depend task is able to cache dependency information Only those class files which have changed will have their dependency information re analysed Note that if you change a class dependencies by changing the source it will be recompiled anyway You can examine the dependency files created to understand the dependencies of your classes Please do not rely however on the format of the information as it may change in a later release 185 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Once depend discovers all of the class dependencies it inverts this relation to determine for each class which other classes are dependent upon it This affects list is used to discover which classes are invalidated by the out of date class The class files of the invalidated classes are removed triggering the compilation of the affected classes The depend task supports an attribute closure which controls whether depend will only consider direct class class relationships or whether it will also consider transitive indirect relationships For example say there are three classes A which depends on B which in turn depend on C Now Say that class C is out of date Without closure only class B would be removed by depend With closure set class A would also be removed Normally direct relationships are sufficient it is unusual for a class to depend on another without having a direct relationship With closure set you will notice that depend typically rem
102. the selector will not end up being selected Attribute Description Required value The size of the file which should be tested for Yes units The units that the value attribute is expressed in When using the standard single No letter SI designations such as k M or G multiples of 1000 are used If you want to use power of 2 units use the IEC standard Ki for 1024 Mi for 1048576 and so on The default is no units which means the value attribute expresses the exact number of bytes when Indicates how to interpret the size whether the files to be selected should be No larger smaller or equal to that value Acceptable values for this attribute are less select files less than the indicated size more select files greater than the indicated size equal select files this exact size The default is equal Here is an example of how to use the Size Selector 57 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt fileset dir jar path gt lt patternset gt lt include name Jjar gt lt patternset gt lt size value 4 units Ki when more gt lt fileset gt Selects all JAR files that are larger than 4096 bytes 7 3 22 10 SELECTOR CONT AINERS To create more complex selections a variety of selectors that contain other selectors are available for your use They combine the selections of their child selectors in various ways The selector containers are e lt and gt select a file only if all the containe
103. the string import from the file file properties and load them as Ant properties 9 42 Mail Description A task to send SMTP email This task can send mail using either plain text UU encoding or MIME format mail depending on what is available Attachments may be sent using nested fileset elements Note This task may depend on external libraries that are not included in the Ant distribution See Library Dependencies for more information or a lt from gt element Parameters Attribute Description Required from Email address of sender Either a from attribute tolist Comma separated list of recipients At least one of these or cclist Comma separated list of recipients to carbon copy the equivalent bcclist Comma separated list of recipients to carbon copy message Message to send in the body of the email messagefile File to send as the body of the email Property values in lt message gt element the file will be expanded messagemimetype The content type of the message The default is No text plain files Files to send as attachments to the email Separate No multiple file names using a comma or space You can also use lt fileset gt elements to specify files failonerror flag to indicate whether to halt the build on any error TheNo includefilenames mailhost mailport encoding default value is true Include filename s before file contents Valid only when No the plain encoding is used The default value i
104. time e lt depend gt Select files that have been modified more recently than equivalent files elsewhere e lt depth gt Select files that appear so many directories down in a directory tree e lt filename gt Select files whose name matches a particular pattern Equivalent to the include and exclude elements of a patternset e lt present gt Select files that either do or do not exist in some other location e lt size gt Select files that are larger or smaller than a particular number of bytes 7 3 22 3 CONTAINS SELECTOR The lt contains gt tag in a FileSet limits the files defined by that fileset to only those which contain the string specified by the text attribute 54 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Attribute Description Required text Specifies the text that every file must contain Yes casesensitive Whether to pay attention to case when looking for the string in the text No attribute Default is true Here is an example of how to use the Contains Selector lt fileset dir doc path includes html gt lt contains text script casesensitive no gt lt fileset gt Selects all the HTML files that contain the string script 7 3 22 4DATE SELECTOR The lt date gt tag in a FileSet will put a limit on the files specified by the include tag so that tags whose last modified date does not meet the date limits specified by the selector will not end up being selected Attribute Description Require
105. time is the sum of specified values hours minutes seconds and milliseconds A negative value can be supplied to any of them provided the total sleep time is positive Note that sleep times are always hints to be interpred by the OS how it feels small times may either be ignored or rounded up to a minimum timeslice Note also that the system clocks often have a fairly low granularity too which complicates measuring how long a sleep actually took Examples lt sleep milliseconds 10 gt Sleep for about 10 mS lt sleep seconds 2 gt Sleep for about 2 seconds lt sleep hours 1 minutes 59 seconds 58 gt Sleep for one hour less 59 58 or two seconds again lt sleep gt Sleep for no time at all This may yield the CPU time to another thread or process 9 57 Sql Description Executes a series of SQL statements via J DBC to a database Statements can either be read in from a text file using the src attribute or from between the enclosing SQL tags Multiple statements can be provided separated by semicolons or the defined delimiter Individual lines within the statements can be commented using either or REM at the start of the line The autocommit attribute specifies whether auto commit should be turned on or off whilst executing the statements If auto commit is turned on each statement will be executed and committed If it is turned off the statements will all be executed as one transaction The one
106. to be compiled are located as java files are by javac That is elements such as includes and excludes can be used directly inside the task declaration Elements specific to the jspc task are classpath 222 305 Ant Manual 1 5 4 12 9 2003 7 47 PM The classpath used to compile the JSP pages specified as for any other classpath classpathref a reference to an existing classpath webapp Instructions to jasper to build an entire web application The base directory must have a WEB INF subdirectory beneath it When used the task hands off all dependency checking to the compiler Attribute Description Required basedir the base directory of the web application Yes Example lt jspe srcdir S basedir src war destdir basedir gensrc package com i3sp jsp compiler jasper41 verbose 9 gt lt include name jsp gt lt jspc gt Build all jsp pages under src war into the destination gensrc in a package heirarchy beginning with com i3sp jsp lt jspe destdir interim verbose 1 srcdir src compiler jasper41 package com i3sp jsp gt lt include name jsp gt lt jspc gt lt depend srcdir interim destdir build cache build dependencies classpath lib taglibs jar gt lt javac srcdir interim destdir build classpath lib taglibs jar debug on gt Generate jsp pages then javac them down to bytecodes Include lib taglib jar in the java compilat
107. to deploy the EJB to iAS Since the XML descriptors can include multiple EJ Bs this is a convenient way of specifying many EJBs in a single Ant task For each EJB specified the task will locate the three classes that comprise the EJB in the destination directory If these class files cannot be located in the destination directory the task will fail The task will also attempt to locate the EJB stubs and skeletons in this directory If found the timestamps on the stubs and skeletons will be checked to ensure they are up to date Only if these files cannot be found or if they are out of date will the iAS ejbc utility be called to generate new stubs and skeletons Parameters Attribute Description Required ejbdescriptor Standard EJB 1 1 XML descriptor typically titled ejb jar xml Yes iasdescriptor iAS specific EJB XML descriptor typically titled ias ejb jar xml Yes dest The is the base directory where the RMI stubs and skeletons are written In Yes addition the class files for each bean home interface remote interface and EJB implementation must be found in this directory classpath The classpath used when generating EJB stubs and skeletons If omitted No the classpath specified when Ant was started will be used Nested classpath elements may also be used keepgenerated I ndicates whether or not the Java source files which are generated by ejbc No will be saved or automatically deleted If yes the source files will be
108. to run the weblogic deploy deployment tool Valid actions for the tool are deploy undeploy list update and delete 261 305 Ant Manual 1 5 4 12 9 2003 7 47 PM If the action is deploy or update the application and source attributes must be set If the action is undeploy or delete the application attribute must be set If the username attribute is omitted it defaults to system The password attribute is required for all actions Attribute Description Required application This is the name of the application being deployed Yes component This is the component string for deployment targets It is in the form lt component gt lt target1 gt lt target2 gt Ab Where component is the archive name minus the jar ear war extension Targets are the servers where the components will be deployed debug If set to true additional information will be printed during the deployment No process Examples This example shows the use of serverdeploy to deploy a component to a WebLogic server lt serverdeploy action deploy source lib dir ejb_myApp ear gt lt weblogic application myapp server t3 myserver 7001 classpath weblogic home lib weblogic jar username user name password S user password component ejb_foobar myserver productionserver debug true gt lt serverdeploy gt This example shows serverdeploy being used to delete a component from a WebLogic server lt serverdeploy a
109. to specify them Examples lt replace dir src value wombat gt lt include name html gt lt replacetoken gt lt CDATA multi line token gt lt replacetoken gt lt replace gt replaces occurrences of the string multi linel ntoken with the string wombat in all HTML files in the directory src Where In is the platform specific line separator lt replace file src index html gt lt replacetoken gt lt CDATA two line token gt lt replacetoken gt lt replacevalue gt lt CDATA two line token gt lt replacevalue gt lt replace gt 9 52 1 replacefilter In addition to allowing for multiple replacements optional nested lt replacefilter gt elements allow replacement values to be extracted from a property file The name of this file is specified using the lt replace gt attribute propertyFile Attribute Description Required token The string to search for Yes 146 305 Ant Manual 1 5 4 12 9 2003 7 47 PM value The replacement string Either may be specified but not both Both property Name of the property whose value is to serve can be omitted if desired as the replacement value If neither value nor property is used the value provided using the lt replace gt attribute value and or the lt replacevalue gt element is used If no value was specified using either of these options the token is replaced with an empty string Examples lt replace file co
110. to whether the build failed or succeeded You can specify either a specific sound file to play or if a directory is specified the lt sound gt task will randomly select a file to play Note At this point the random selection is based on all the files in the directory not just those ending in appropriate suffixes for sound files so be sure you only have sound files in the directory you specify Unless you are running on Java 1 3 or later you need the Java Media Framework on the classpath javax sound Nested Elements success Specifies the sound to be played if the build succeeded 265 305 Ant Manual 1 5 4 12 9 2003 7 47 PM fail Specifies the sound to be played if the build failed Nested Element Parameters The following attributes may be used on the lt success gt and lt fail gt elements Attribute Description Required source the path to a sound file directory or the name of a specific sound file to be Yes played loops the number of extra times to play the sound file default is 0 No duration the amount of time in milliseconds to play the sound file No Examples lt target name fun if fun unless fun done gt lt sound gt lt success source S user home sounds bell wav gt lt fail source user home sounds ohno wav loops 2 gt lt sound gt lt property name fun done value true gt lt target gt plays the be11 wav sound file if the build succeeded or the ohno wav sound file if
111. tools The task is a directory based task so attributes like includes il and excludes broken il can be used to control the files pulled in Each file is built on its own producing an appropriately named output file unless manually specified with outfile 176 305 Ant Manual 1 5 4 12 9 2003 7 47 PM a eee yes no Default excludes are used when omitted pas ee separated list of patterns of files that must be excluded No iles except default excludes are excluded when omitted he name of a file Each line of this file is taken to be an exclude pattern lextraOptions Any extra options which aren t explicitly supported by the ilasm ask primarily because they arent really documented use ilasm o see them failOnError_ Should a failed compile halt the build true default ullpaths Should error text provide the full path to files true default ee eee separated list of patterns of files that must be included All iles are included when omitted keyfile he name of a file containing a private key with which the assembly output is checksumed and then MD5 signed to have a strong name listing Produce a listing off by default Listings go to the current output on off stream default outputFile filename of output sfx exe resourceFile name of resource file to include ier res srcDir___ source directory default project directory ____ argetType ype of target library means DLL is output exe d
112. type J avaClassHelpe r used by the ClassConstants filter reader and optionally used by ejbjar for dependency determination Mail task with Mime encoding and the MimeMail task Mail task with Mime encoding and the MimeMail task jdepend task http java sun com products javamail http java sun com products javabeans qlasgow jaf html http www clarkware com software Depend html 4 6 Platform Issues 4 6 1 Unix e You should use a GNU version of tar to untar the ant source tree if you have downloaded this as a tar file e Ant does not preserve file permissions when a file is copied moved or archived Use lt chmod gt to set permissions and when creating a tar archive use the mode attribute of lt tarfileset gt to set the permissions in the tar file e Ant is not symbolic link aware in moves deletes and when recursing down a tree of directories to build up a list of files Unexpected things can happen 18 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 4 6 2 Microsoft Windows Windows 9x win95 win98 win98SE and winME has a batch file system which does not work fully with long file names so we recommend that ant and the JDK are installed into directories without spaces and with 8 3 filenames The Perl and Python launcher scripts do not suffer from this limitation All versions of windows are usually case insensitive although mounted file systems Unix drives Clearcase views can be case sensitive un
113. use Properties will be defined for every environment variable by prefixing the supplied name and a period to the name of the variable 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 The value part of the properties being set might contain references to other properties These references are resolved at the time these properties are set This also holds for properties loaded from a property file A list of predefined properties can be found here Parameters Attribute Description Required name the name of the property to set No value the value of the property location Sets the property to the absolute filename of the given file If the value of this attribute is an absolute path it is left unchanged with and One of these characters converted to the current platforms conventions Otherwise it when using the is taken as a path relative to the project s basedir and expanded name attribute refid Reference to an object defined elsewhere Only yields reasonable results for references to PATH like structures or properties resource the resource name of the property file file the filename of the property file environment the prefix to use when retrieving environment variables Thus if you specify environment myenv you will be able to access OS specific environment variables via property names myenv PATH or m
114. version of tar If the loss of path or file information is not acceptable and it rarely is longfile may be set to the value gnu The tar task will then produce a GNU tar file which can have arbitrary length paths Note however that the resulting archive will only be able to be untarred with GNU tar The default for the longfile attribute is warn which behaves just like the gnu option except that it produces a warning for each file path encountered that does not match the limit This task can perform compression by setting the compression attribute to gzip or bzip2 Parameters Attribute Description Required destfile the tar file to create Yes basedir the directory from which to tar the files No longfile Determines how long files gt 100 chars are to be handled Allowable values No are truncate fail warn omit and gnu Default is warn includes comma or space separated list of patterns of files that must be included No All files are included when omitted includesfile the name of a file Each line of this file is taken to be an include pattern No excludes comma or space separated list of patterns of files that must be excluded No No files except default excludes are excluded when omitted excludesfile the name of a file Each line of this file is taken to be an exclude pattern No defaultexcludes indicates whether default excludes should be used or not yes no No Default excludes are used when omitted comp
115. with xabc then is matched with 33 305 Ant Manual 1 5 4 12 9 2003 7 47 PM foobar and finally java is matched with test java They all match so the path matches the pattern To make things a bit more flexible we add one extra feature which makes it possible to match multiple directory levels This can be used to match a complete directory tree or a file anywhere in the directory tree To do this must be used as the name of a directory When is used as the name of a directory in the pattern it matches zero or more directories For example test matches all files directories under test such as test x java or test foo bar xyz html but not xyz xml There is one shorthand if a pattern ends with or then is appended For example mypackage test is interpreted as if it were mypackage test Example patterns CVS Matches all files in CVS directories that can be located anywhere in the directory tree Matches CVS Repository org apache CVS Entries org apache jakarta tools ant CVS Entries But not org apache CVS foo bar Entries foo bar part does not match org apache jakarta Matches all files in the org apache jakarta directory tree Matches org apache jakarta tools ant docs index html org apache jakarta test xml But not org apache xyz java jakarta part is missing org apache CVS Matches all files in CVS directories that are located anywhere in the directory tree under org apa
116. xml warn false gt lt dtd publicld Apache Software Foundation DTD Struts Configuration 1 0 EN location struts config_1_0 dtd gt lt xmlvalidate gt lt xmlvalidate failonerror no gt lt fileset dir S project dir includes xml1 gt lt xmlcatalog refid mycatalog gt lt xmlvalidate gt lt xmlvalidate failonerror no gt 300 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt fileset dir S project dir includes xm1 gt lt xmlcatalog gt lt dtd publicId ArielPartners DTD XML Article V1 0 EN location com arielpartners knowledgebase dtd article dtd gt lt xmlcatalog gt lt xmlvalidate gt 301 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 11 Listeners amp Loggers 11 1 Overview Ant has two related features to allow the build process to be monitored listeners and loggers 11 1 1 Listeners A listener is alerted of the following events e build started build finished target started target finished task started task finished e message logged 11 1 2 Loggers Loggers extend the capabilities of listeners and add the following features e Receives a handle to the standard output and error print streams and therefore can log information to the console or the logfile specified file e Logging level quiet verbose debug aware e Emacs mode aware 11 2 Built in Listeners Loggers with the logger command line switch output org apache tools a
117. you will need to do e Add the bin directory to your path e Set the ANT_HOME environment variable to the directory where you installed Ant On some operating systems the ant wrapper scripts can guess ANT_HOME Unix dialects and Windows NT 2000 but it is better to not rely on this behavior e Optionally set the JAVA_HOME environment variable see the Advanced section below This should be set to the directory where your J DK is installed Note Do not install Ant s ant jar file into the lib ext directory of the JDK JRE Ant is an application whilst the extension directory is intended for JDK extensions In particular there are security restrictions on the classes which may be loaded by an extension 4 3 2 Optional Tasks Ant supports a number of optional tasks An optional task is a task which typically requires an external library to function The optional tasks are packaged together with the core Ant tasks The external libraries required by each of the optional tasks is detailed in the Library Dependencies section These external libraries may either be placed in Ant s lib directory where they will be picked up automatically or made available on the system CLASSPATH environment variable 4 3 3 Windows Assume Ant is installed in c ant The following sets up the environment set ANT_HOME c ant set JAVA_HOME c jdk1 2 2 set PATH PATHS SANT_HOME bin 15 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 4
118. 0 shutdown No classpath The classpath to be used with the Java Virtual Machine that runs the Weblogic Yes Shutdown command user The username of the account which will be used to shutdown the server Yes password The password for the account specified in the user parameter Yes url The URL which describes the port to which the server is listening for T3 Yes connections For example t3 localhost 7001 delay The delay in seconds after which the server will stop This defaults to an No immediate shutdown Nested Element The classpath of the wistop task can be set by a lt classpath gt nested element Examples This example show the shutdown for a Weblogic 6 0 server lt wlstop classpath weblogic classes user system 192 305 Ant Manual 1 5 4 12 9 2003 7 47 PM url t3 localhost 7001 password foobar beahome bea home gt 10 7 2 6EJBJAR Description This task is designed to support building of EJB jar files EJB 1 1 2 0 Support is currently provided for vanilla EJB jar files i e those containing only the user generated class files and the standard deployment descriptor Nested elements provide support for vendor specific deployment tools These currently include Borland Application Server 4 5 iPlanet Application Server 6 0 JBoss 2 1 and above Weblogic 5 1 6 0 session entity beans using the weblogic ejbc tool IBM WebSphere 4 0 TOPLink for WebLogic 2 5 1 enabled entity beans JONAS 2 4 x a
119. 0014 formated date 028 171 34 The slashes conform to the expectations of the Properties class The file will be stored in a manner so that each character is examined and escaped if necessary Note that the original comment is now lost Please keep this in mind when running this task against heavily commented properties files It may be best to have a commented version in the source tree 253 305 Ant Manual 1 5 4 12 9 2003 7 47 PM copy it to a deployment area and then run the modifications on the copy Future versions of PropertyFile will hopefully eliminate this shortcoming lt propertyfile file my properties comment My properties gt lt entry key akey value avalue gt lt entry key adate type date value now gt lt entry key anint type int operation gt lt entry key formated int type int default 0013 operation pattern 0000 gt lt entry key formated date type date value now pattern DDD HH mm gt lt propertyfile gt To produce dates relative from today lt propertyfile file my properties comment My properties gt lt entry key formated date 1 type date default now pattern DDD operation value 1 gt lt entry key formated tomorrow type date default now pattern DDD operation value 1 gt lt propertyfile gt Concatenation of strings lt propertyfile file my properties comment My properties gt
120. 003 7 47 PM ee ee the buildprocess if the command exits with a returncode other han 0 ailifexecutionfailsiStop the build if we can t start the program Defaults to true k parallel Run the command only once appending all files as arguments If alse command will be executed once for every file Defaults to false i yp One of file dir or both If set to file only the names of plain files will No default is be sent to the command If set to dir only the names of directories file are considered Skipemptyfilesets Don t run the command if no source files have been found or are No default is newer than their corresponding target files false e newenvironment Do not propagate old environment when new environment variables No default is are specified false mlauncher Run command using the Java VM s execution facilities where No default is available If set to false the underlying OS s shell either directly or true hrough the antRun scripts will be used Under some operating Systems this gives access to facilities not normally available through he VM including under Windows being able to execute scripts rather than their associated interpreter If you want to specify the name of the executable as a relative path to the directory given by he dir attribute it may become necessary to set vmlauncher to false as well Parameters specified as nested elements fileset You can use any number of nested lt fileset gt elemen
121. 3 4 Unix bash Assume Ant is installed in usr local ant The following sets up the environment export ANT_HOME usr local ant export JAVA_HOME usr local jdk 1 2 2 export PATH S PATH S ANT_HOME bin 4 3 5 Unix csh setenv ANT_HOME usr local ant setenv JAVA_HOME usr local jdk 1 2 2 set path Spath SANT_HOME bin 4 3 6 Advanced There are lots of variants that can be used to run Ant What you need is at least the following e The classpath for Ant must contain ant jar and any jars classes needed for your chosen J AXP compliant XML parser e When you need JDK functionality such as for the javac task or the rmic task then for JDK 1 1 the classes zip file of the JDK must be added to the classpath for JDK 1 2 or JDK 1 3 tools jar must be added The scripts supplied with Ant in the bin directory will add the required JDK classes automatically if the JAVA _HOME environment variable is set e When you are executing platform specific applications such as the exec task or the cvs task the property ant home must be set to the directory containing where you installed Ant Again this is set by the Ant scripts to the value of the ANT_HOME environment variable The supplied ant shell scripts all support an ANT_OPTS environment variable which can be used to supply extra options to ant Some of the scripts also read in an extra script stored in the users home directory which can be used to set such op
122. 3 7 47 PM e If the system property ant regexp matcherimpl has been set it is taken as the name of the class implementing org apache tools ant util regexp RegexpMatcher that should be used e If it has not been set first try the JDK 1 4 classes then jakarta ORO and finally try jakarta regexp Examples lt mapper type regexp from X Java to 1 java bak gt Source file name Target file name A java A java bak foo bar B java foo bar B java bak C properties ignored Classes dir dir2 A properties ignored lt mapper type regexp from to 1 2 2 3 gt Source file name Target file name A java ignored foo bar B java foo bar bar B java C properties ignored Classes dir dir2 A properties Classes dir dir2 dir2 A properties lt mapper type regexp from to X2 11 gt Source file name Target file name A java java A foo bar B java java foo bar B C properties properties C Classes dir dir2 A properties properties Classes dir dir2 A package Sharing the same syntax as the glob mapper the package mapper replaces directory separators found in the matched source pattern with dots in the target pattern placeholder This mapper is particularly useful in combination with lt uptodate gt and lt junit gt output Example lt mapper type package from Test java to TEST Test xml gt Source file name Target file name org apache tools ant util Pac
123. ARE eg 270 10 42 1 Common Parameters for All Starteam Tasks ssssscscsesssererrrireerrerrrrrreres 271 10 42 2 SUCHE CKOUL ees setting deacon ty sido See ved AR A T EEEE E eee ee 271 10 423 STChHeECKIN iiieincce A aae A eet ethos aii See VES Pan eee 273 10 42 4 STLADE main iganen ot a be oan Dede da SEPA eee eee gs 276 10 42 35 SPEC scr ote ees tc A atone hehe aseo 277 10 42 6 Starteam Deprecated 00 c cece cece eee eee eee eee tennessee enna 278 10 43 Stylebook israe bil Shiels tet aa 280 10 44 Tenet a do Rt Laa A dd c Reels OE EL 281 10 45 MOE A A dara 282 10 46 Traduccion ce AEAEE CEKEL seeded ee Nave este deat EAE Eaa een 283 10 47 Visual Age for Java Tasks and Plugin User Manual cceceeeceeeeeeeeeeeeees 284 10 47 1 Table of CONtent 2 0 0 ccc ceeee cece eee eee scene rre 285 104 72 INtrOdU CON escarnio A da a a 285 10 47 33 The TASKS cito a ibi 285 T0444 MAJO uniicocanrito lora e di 286 Ant Manual 1 5 4 12 9 2003 7 47 PM 10 4725 VA EXPOrt aieia inaa O tha eed EA Red eae 286 10 47 67 VAI Mporti a cet rss Rams en ae nae ek Aa 287 TOILETTE eR 288 10 47 8 Frequently Asked QuestiOns cc ccc cece eect ence eee eee een ee een ee eee nnaee es 291 10 48 Microsoft Visual SourceSafe Tasks User Manual ccceeeeeeeeeee tenes eenees 292 10 48 1 Introduction Arba 293 10 48 2 he Task irradia a gai daa 293 10 48 32 MSG 293 10 48 40 Mesa A A ido 294 10 48 59 VsSHlStO Vita A A
124. Ant Manual 1 5 4 12 9 2003 7 47 PM Apache Ant 1 5 4 Manual Compiled By Abdul Habra www tek271 com From http ant apache org manual index html 12 2003 Copyright 2000 2003 Apache Software Foundation All rights Reserved 1 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Contents At a Glance 1 Apache Ant User Manual Authors cc cece cee ence eee eee eee eee eee nr ee en eeee nae 11 2 Feedback and TroubleshootinQ ccocccccocccccccccnnnnnnncccca nan nnnnrnr nan n rr rrr rana rr rr rra raras 12 3 INtroductiON vocaci n 13 E UNOS MIA Ai A RRA 14 5 RUNNING ANE avec e A ace 21 O USM ANE ora A a A A A A aA 24 T CONCEDE seven ween each eed dain ah Mansa sae a E EEEE heats tonsa 32 8 SANT TASKS ads arses atce dibs OA 68 Oi SCOPES TASKS ia A a Aah tial ARANA 74 10 Optional FAaSKS sa e AE TE EEA T e O do 175 11 Listeners Gy LOGO ELS ici a a A St A weaned 302 3 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Table Of Contents 1 Apache Ant User Manual Authors 0 c cece eee ene eee eee eee enna seen neeeeeaaee enna 11 2 Feedback and TroubleShooting ccceece cette eee eee eee ene eee nee nnn neers 12 3 IMEFOAUCTION pst tess ca G00 ad de BOL Baan dake weeded 13 3 1 WY eceek sot ee eee le A spel Goede A Pd 13 4 installing Ant everest nected tes gee ee we tebe pean Se eee ees vee beget eae Ea T eee eae eae 14 4 1 Getting ANC cerar nc A LA vba deeseaue ys ENEA 14 4 1 1 Binary EGtho
125. BIC E EMOL a a OR 197 10 7 3 3 TOPLink for Weblogic element Deprecated ooonooooconinoccccnanannncnnnanonnnnnnnos 199 10 7 3 4 Websphere cl Mt tii dane 201 10 7 3 5 Planet Application Server AS elemMent oooooconnnococonncccnoncnononcnonancconananinns 203 10 7 3 6 JOnAS Java Open Application Server element ooooooccnnnocccconcccnnnccnnnncnnnno 205 10 8 ECNOPrOpPertieS tania e ae bai SERENE 207 10 90 ET NA sae od ote ae de o cod a A ears ote Be ca ee Mane 208 10 9 1 Sending Files se canted litt AAA RAS 209 10 9 2 GETTING Fl S L EA E A AE EA E TTT EEEN RE 210 10 9 3 Deleting Files peed dirie rita ta IA paa T peaa 210 10 9 4 Listing Files vscs ccc cee renens serennu dE da E ada 210 10 9 5 Creating Directories ccc cece eee ene ee ERETTA enna 211 10 10 ICONURACT cece ecey a a o 211 10 11 Jarlib available ey ON 212 10 12 jarib displaya aa a n tt io 214 10 13 Jarlib Ma Est SA EEA E EA 215 10 14 Jarlib TESO MS ii A A da Pe ne ER 216 10 15 A shin E cite Phen S ARAS caged shies tace RRM AIN St Soc it ehh E AIENT 218 10 16 Jaa Devise cots eet A adits A A eee eel cee AS 220 10 17 SPG aeiGe finest A alee ieee ble dais 221 10 18 DE BON reniir aidyeed th aus ded scce egy guded se a aS EE ee i EEr lide ceeds 224 10 19 JJ Tree es sce eel Sh eee da ee been ede dees ok lv dan eae ved a A ete 225 10 20 JliaK Deprecated cszc2 ced esse oh pee rita EGR eee ded Eee eens dan 226 10 21 O 228 LOZ Introduction ea a A Dd 228 10 22
126. CKOUT commands to Microsoft Visual SourceSafe If you specify two or more attributes from version date and label only one will be used in the order version date label Parameters Attribute Values Required SourceSafe path which specifies the project file s you wish to perform the vsspath laction on You should not specify the leading dollar sign it is prepended by Yes Ant automatically usernamel password The username and password needed to get access to VSS Note that you may need to specify both if you have a password N login Ant VSS will hang if you leave the password out and VSS does not accept a login without a password localpath Override the working directory and get to the specified path No directory where ss exe resides By default the task expects it to be in the ssdir No PATH serverPath directory where srssafe ini resides No writable true or false No recursive true or false No version a version number to get No only one date a date stamp to get at of these label a label to get for allowed Examples lt vsscheckout vsspath test localpath D build recursive true login me mypass gt Does a recursive checkout of the project test to the directory D build 10 48 8 VssAdd Description Task to perform ADD commands to Microsoft Visual SourceSafe Parameters Attribute Values Required localpath Specify the local file s to add to VSS Yes username password The username and password neede
127. DK lt 1 2 will pass these as separate arguments to the program you are calling JDK gt 1 2 will pass them as a single argument and cause most calls to fail Note2 If you are using Ant on Windows and a new DOS Window pops up for every command which is executed this may be a problem of the JDK you are using This problem may occur with all JDK s lt 1 2 Timeouts If a timeout is specified when it is reached the sub process is killed and a message printed to the log The return value of the execution will be 1 which will halt the build if failonerror true but be ignored otherwise 9 28 Fail Description Exits the current build just throwing a BuildException optionally printing additional information The message of the Exception can be set via the message attribute or character data nested into the element Parameters Attribute Description Required message A message giving further information on why the build exited No if Only fail if a property of the given name exists in the current project No unless Only fail if a property of the given name doesn t exist in the current project No Examples lt fail gt will exit the current build with no further information given BUILD FAILED build xml 4 No message lt fail message Something wrong here gt will exit the current build and print something like the following to wherever your output goes BUILD FAILED build xml 4 Something wrong here lt fail
128. E 86 IZ EAN CAL aces 87 91r AN 88 9 13 1 Conditions sieer oint EA A A See 89 OVA COPY inar n a AT 90 9 15 Copydir Deprecated ssessesrsrrersesrsrrrrresrrerrrrrerrerrerresresrernerrosrrereerres 93 9 16 Copyfile Deprecated cc ccc ee eens 94 QT CV Svosdessevesciecisk vis A Jaccceevs scdsseee ess Pd a succes 94 O18 CVSCHANG SLOG a o a 96 9 19 ESAS ais 98 DEBO EU as 98 92b CNA 100 9 22 Deltree Deprecatd a a LL 102 9 23 DEPENdS eticii ea da get e AR A capi 102 9 24 DITNAME siii A ee Meee ewe RER 103 LO SEAR ss a A A A AR 104 9 206 ElhOO0ii a dea Somes 105 DEBIL E A bbe hice a A A aa A Bae LEE id 106 SEA li A A aa 108 A O E ETE cakes OAN 109 9 30 FIXGREF 2 cies tc E a cannes 109 3d GEN ii A e dito Rone eaa 112 9 32 AO 113 9 33 GUI ZIP icono E a A A emi 114 SS A IA A TAS 114 ENS o NS 114 IO JAE erare eddie a Gon 09 a clase A A r IANA eA add BREE 115 A 118 938 A ee cde a a AA pene geet peace ceh Eae Soe eee beard G i Da BER EP RG RES 120 Ant Manual 1 5 4 12 9 2003 7 47 PM 9 39 Javadoc JaVadoCZ2 2 a eee E Eee eee A Eee ee eE EEE Eee eee E EER ea 125 Ord Or Load ca a tees teh uns cod dia e ae ee cA N I Sal 131 9 41 lt L adPropertieS ii a Ra ds 132 9 42 Mall tn ay ee ea ee ee RV ae 133 9 43 M nifeSt aires ete elec age coe be A ds LENG Been gad pede 134 9 44 MKI ss eee ec rr eee oe a A ves cee ee ce oe ee ns 136 O 136 9 46 Paralleloodocicio ii A el Medved esas 138 NA A
129. It constructs target file names based on rules that can be parameterized with from and to attributes the exact meaning of which is implementation dependent These instances are defined in lt mapper gt elements with the following attributes 39 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Attribute Description Required type specifies one of the built in implementations Exactly one classname specifies the implementation by class name of both classpath the classpath to use when looking up classname No classpathref the classpath to use given as reference to a path defined elsewhere No from the from attribute for the given implementation Depends on implementation to the to attribute for the given implementation Depends on implementation Note that Ant will not automatically convert or characters in the to and from attributes to the correct directory separator of your current platform If you need to specify this separator use file separator instead Parameters specified as nested elements The classpath can be specified via a nested lt classpath gt as well that is a path like structure The built in mapper types are All built in mappers are case sensitive identity The target file name is identical to the source file name Both to and from will be ignored Examples lt mapper type identity gt Source file name Target file name A java A java foo bar B java foo bar B java C properties C proper
130. It is invoked similar to the ar or Zip tasks This task will work on Windows using the external cabarc tool provided by Microsoft which must be located in your executable path An extension of the ar task with special treatment for files that should end up in an Enterprise Application archive O Use the zipfileset and zipgroupfileset attributes of the ar or Zip tasks instead mo nvokes the rpm executable to build a Linux installation file This task currently only works on Linux or other Unix platforms with RPM support An extension of the ar task with special treatment for files that should end up in the WEB INF lib WEB INF classes or WEB INF directories of the Web Application Archive Zip Creates a zipfile 8 1 2 Audit Coverage Tasks pend Invokes the Depend parser This parser traverses a set of J ava source file directories and generates design quality metrics for each Java package e es tasks run the tools from the Probe suite This task was written using J Probe Suite Server Side 3 0 A the metrics of a set of Java source files using the Metamata Metrics WebGain Quality Analyzer source code analyzer and writes the results to an XML file mo Aa static analysis on aset of Java source code and byte code files using the Metamata Metrics WebGain Quality Analyzer source code analyzer Determines which classfiles are out of date with respect to their source removing the classfiles of any other classes that de
131. KS it e ed ta id aoe 68 STA E a KS E a e a a Ba a A i ROM At A Rata cenc E e AA 68 8 1 2 Audit Coverage TASKS irren cece eee eee EEEE rr rra 68 8 1 3 COMPll TASKS a E a NS ote Be a 68 8 1 4 Deployment TaSkS ia i heartened eens Aa ano 69 8 1 5 DOCUMENTATION TASKS cece cece ccc ee eee e eect cece tees eect ee a a a er Ean iY 69 821 6 EB TASKS io e A Bean hee Pade se dd 69 5 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 8 17 Execution asks A kednne evden ris 69 ll TASKS AAA A EL 69 8 1 9 Java2 Extensions TaSKS occccccoccccncnccnnnnnnnncccn nan n nn eee ee nr rra rr 70 8 1 10 LOGGING TASKS iia ted Eee ed 70 8 1 11 Mail Task Sid O95 aA ad 70 8 1 12 Miscellaneous TASKS cece cece cee nn rr nn rr cnn rr eee eee rr rr 70 8 1 13 NET TASKS cocos a ia E EKKA 71 8 1 14 Pre process TaskKS oc ends 71 8 1 15 Property TFAaSKS steak kee ns a O a o tls 71 8 1 16 Remote Tak SW A A a a 72 8 1 17 SGM A AO 72 8 1 18 TESTI TASKS A A a a ts 72 8 1 19 Visual Age for Java TaSKS ooooocccconcccnnncncnnnnccnnnnnnnn nn nnn rn rn rr a erre 72 9 A SAA AR 74 9 1 Ar A id de TE ELA 74 9 2 AMC A A A A A Na 76 9 3 ANUS TRU GCU Cex SS A SS 77 9 4 Apply ExecOnisscc inset dts A hee sae oe eek ee 78 9 5 Available vico in O nda Maidana deci 80 9 6 BASAN Murciana o A A a A ape a 82 9 7 BULLI NUMD OF civic A a a E 82 9 8 BU ZIpP2 7 GUN P ieres trotar TA a AS 83 9 9 BZip2 GZIP celeste ccs cn o e do Dean bounces y 84 AO Che MA oa 84 EL CEAMS
132. Manual 1 5 4 12 9 2003 7 47 PM 6 1 9 Command line Arguments Several tasks take arguments that will be passed to another process on the command line To make it easier to specify arguments that contain space characters nested arg elements can be used Attribute Description Required value a single command line argument can contain space characters file The name of a file as a single command line argument will be replaced with the absolute filename of the file 7 Exactly one of path A string that will be treated as a path like string as a single command line these argument you can use or as path separators and Ant will convert it to the platform s local conventions line a space delimited list of command line arguments It is highly recommended to avoid the line version when possible Ant will try to split the command line in a way similar to what a Unix shell would do but may create something that is very different from what you expect under some circumstances 6 1 10 Examples lt arg value 1 a gt is a single command line argument containing a space character lt arg line 1 a gt represents two separate command line arguments lt arg path dir dir2 dir3 gt is a single command line argument with the value dir dir2 dir3 on DOS based systems and dir dir2 dir3 on Unix like systems 6 1 11 References The id attribute of the buildfile s elements can be used to refer to them This can b
133. MyClass in classic mode VM lt jvmarg gt allows all attributes described in Command line arguments arg Parameters may be passed to the executed class via nested lt arg gt attributes as described in Command line arguments socket Define a host and port to connect to if you want to do remote viewing Attribute Description Required host the host name ip of the machine on which the Viewer is running No default to localhost port The port number on which you will connect to the Viewer No default to 4444 filters Defines class method filters based on pattern matching The syntax is filters is similar to a fileset Attribute Description Required defaultexclude As a default the coverage excludes all classes and methods No default to true Default filters are equivalent to lt filters gt lt exclude class method gt lt filters gt As seen above nested elements are include and exclude with a name attribute Attribute Description Required class The class mask as a simple regular expression No defaults to method The method mask as a simple regular expression No defaults to enabled _ jis the filter enabled No defaults to true Example of filters 229 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt filters gt lt include class com mycompany method gt lt exclude class com mycompany MyClass method test gt lt filters gt reports the coverage on all packages classes and meth
134. N ALGORITHM When an entity DTD or URI is looked up by the XML processor the XMLCatalog searches its list of entries to see if any match That is it attempts to match the publicld attribute of each entry with the PubliclD or URI of the entity to be resolved Assuming a matching entry is found XMLCatalog then executes the following steps 62 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 1 Filesystem lookup The location is first looked up in the filesystem If the Location is a relative path the ant project basedir attribute is used as the base directory If the location specifies an absolute path it is used as is Once we have an absolute path in hand we check to see if a valid and readable file exists at that path If so we are done If not we proceed to the next step 2 Classpath lookup The location is next looked up in the classpath Recall that jar files are merely fancy zip files For classpath lookup the location is used as is no base is prepended We use a Classloader to attempt to load the resource from the classpath For example if hello jar is in the classpath and it contains foo bar blat dtd it will resolve an entity whose location is foo bar blat dtd Of course it will not resolve an entity whose location iS blat dtd 3 URL space lookup Finally we attempt to make a URL out of the location At first this may seem like this would defeat the purpose of XMLCatalogs why go back out to the internet But in fact this
135. NING_COLOR 2 35 AnsiColorLogger INFO_COLOR 2 36 V D AnsiColorLogger VERBOSE_COLOR 2 32 AnsiColorLogger DEBUG_COLOR 2 34 Each key takes as value a color combination defined as Attribute Foreground Background n the above example background value has not been used 303 305 Ant Manual 1 5 4 12 9 2003 7 47 PM This file must be specfied as the value of a system variable named ant logger defaults and passed as an argument using the D option to the java command that invokes the Ant application An easy way to achieve this is to add Dant logger defaults path to your file to the ANT_OPTS environment variable Ant s launching script recognizes this flag and will pass it to the java command appropriately Format AnsiColorLogger Attribute Foreground Background Attribute is one of the following O gt Reset All Attributes return to normal mode 1 gt Bright Usually turns on BOLD 2 gt Dim 3 gt Underline 5 gt link 7 gt Reverse 8 gt Hidden Foreground is one of the following 30 gt Black 31 gt Red 32 gt Green 33 gt Yellow 34 gt Blue 35 gt Magenta 36 gt Cyan 37 gt White Background is one of the following 40 gt Black 41 gt Red 42 gt Green 43 gt Yellow 44 gt Blue 45 gt Magenta 46 gt Cyan 47 gt White ant logger org apache tools ant listener AnsiColorLogger 11 2 5 Log4jListener Passes build event
136. NIX style like the arguments for the chmod command oncat Concatenates multiple files into a single one or to Ant s logging system 69 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Copies a file or Fileset to a new file or directory opydir eprecated Use the Copy task instead opyfile eprecated Use the Copy task instead Delete Deletes either a single file all files and sub directories in a specified directory ora Set of files specified by one or more FileSets eltree Filter Sets a token filter for this project or reads multiple token filters from a specified file and sets these as filters Token filters are used by all tasks that perform file ing operations FixCRLF Modifies a file to add or remove tabs carriage returns linefeeds and EOF characters Gets a file from a URL Mkdir Creates a directory Non existent parent directories are created when necessary Move Moves a file to a new file or directory or a set s of file s to a new directory Patch Applies a diff file to originals Rename __ _ _ Deprecated Use the Move task instead RenameExtensions Deprecated Use the Move task with a glob mapper instead ee ae is a directory based task for replacing the occurrence of a given string with another string in selected file ReplaceRegExp Directory based task for replacing the occurrence of a given regular expression with a substitution pattern in a file or set of files eas WN coos a name for anew temporary file and
137. O 10 47 Visual Age for Java Tasks and Plugin User Manual by e Wolf Siberski siberski at kbs uni hannover de 284 305 Ant Manual 1 5 4 12 9 2003 7 47 PM e Christoph Wilhelms christoph wilhelms at tui de e Martin Landers martin landers at bea de e Francois Rey francois dot rey at capco dot com Version 1 2 1 2003 01 16 10 47 1 Table of Contents e Introduction e The Tasks o VA Load o VAJExport o VAJ Import e A sample build file e The Plugin o Installation o Usage e Frequently Asked Questions e Visual Age Versions e History 10 47 2 Introduction Visual Age for Java is a great Java IDE but it lacks decent build support for creating deliveries On the other hand Ant supports the build process very good but is at least at the moment command line based So we decided to write some tasks to access the VAJ repository and a small visual Ant frontend to make running Ant from VAJ possible We use the Tool API to integrate Ant in VisualAge for Java In combination with the VAJ tasks vajload vajexport vajimport you can load defined versions of projects into your workspace export the source code compile it with an external compiler and build a jar without leaving the IDE Of course compile messages are viewed in a logging window Concluding This tool provides decent deployment support VAJ has not out of the box What s new 2003 01 16 Now works outside of VAJ Added attribute haltonerror and ve
138. RL into No But one of destfile or destdir must be present destdir The directory in which to place downloaded No But one of destfile or destdir must be file present ant The ant resolver allows you to run a ant build file to generate a library Attribute Description Required antfile The build file Yes destfile The file that the ant build creates Yes target The target to run in build file No Examples Resolve Extension to file f file does not exist or file does not implement extension then throw an exception lt extension id dve ext extensionName org realityforge dve specificationVersion 1 2 specificationVendor Peter Donald gt lt jarlib resolve property dve library gt lt extension refid dve ext gt lt location location opt jars dve jar gt 217 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt jarlib resolve gt Resolve Extension to url f url does not exist or can not write to destfile or files does not implement extension then throw an exception lt extension id dve ext extensionName org realityforge dve specificationVersion 1 2 specificationVendor Peter Donald gt lt jarlib resolve property dve library gt lt extension refid dve ext gt lt url url http www realityforge net jars dve jar destfile lib dve jar gt lt jarlib resolve gt Resolve Extension to file produce by ant build If file does not get produced or ant file is missing or build
139. STAMP desc Auto Nightly Build lock locked gt 10 30 11 P4Counter Description Obtain or set the value of a counter When used in its base form where only the counter name is provided the counter value will be printed to the output stream When the value is provided the counter will be set to the value provided When a property name is provided the property will be filled with the value of the counter You may not specify to both get and set the value of the counter in the same Task The user performing this task must have Perforce review permissions as defined by Perforce protections in order for this task to succeed Parameters Attribute Description Required name The name of the counter Yes value The new value for the counter No property The property to be set with the value of the counter No Examples Print the value of the counter named last clean build to the output stream 250 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt p4counter name last clean build gt Set the value of the counter based on the value of the TSTAMP property lt p4counter name last clean build value TSTAMP gt Set the value of the p4 last clean build property to the current value of the last clean build counter lt p4counter name last clean build property p4 last clean build gt 10 30 12 P4Reopen Description Move or reopen in Perforce speak checkout files between changelists Par
140. Test in their name lt dirset dir build dir gt lt patternset id non test classes gt lt include name apps classes gt lt exclude name apps Test gt lt patternset gt lt dirset gt Groups the same directories as the above example but also establishes a PatternSet that can be referenced in other lt dirset gt elements rooted at a different directory lt dirset dir debug_build dir gt lt patternset refid non test classes gt lt dirset gt Groups all directories in directory debug_build dir using the same patterns as the above example 7 3 4 FileList FileLists are explicitly named lists of files Whereas FileSets act as filters returning only those files that exist in the file system and match specified patterns FileLists are useful for specifying files that may or may not exist Multiple files are specified as a list of files relative to the specified directory with no support for wildcard expansion filenames with wildcards will be included in the list unchanged FileLists can appear inside tasks that support this feature or at the same level as lt target gt i e as children of lt project gt Attribute Description Required dir The base directory of this FileList Yes files The list of file names Yes Examples lt filelist id docfiles dir S doc src files foo xml bar xml gt The files doc src foo xml and doc src bar xml Note that these fi
141. They are located under Yes here according to the given package name srcdir Where to look for source jsp files Yes verbose The verbosity integer to pass to the compiler Default 0 No 221 305 Ant Manual 1 5 4 12 9 2003 7 47 PM package Name of the destination package for generated java classes No compiler class name of aJSP compiler adapter such as jasper or No defaults to jasper41 jasper ieplugin Java Plugin classid for Internet Explorer No mapped boolean Generate separate write calls for each HTML line in No the JSP classpath The classpath to use to run the jsp compiler This can also be No but it seems to specified by the nested element classpath Path work better when used classpathref A Reference As per classpath No failonerror flag to control action on compile failures default yes No uribase The uri context of relative URI references in the JSP pages If it No does not exist then it is derived from the location of the file relative to the declared or derived value of uriroot uriroot The root directory that uri files should be resolved against No compiler Class name of jsp compiler adapter to use Defaults to the No standard adapter for J asper compilerclasspath The classpath used to find the compiler adapter specified by No the compiler attribute webinc Output file name for the fraction of web xml that lists servlets No webxml File name for web xml to be generated No The mapped option will if
142. Used to specify how you wish the result tree to be output as specified in the XSLT specifications Parameters 156 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Attribute Description______ Required hame Name of the propert alue of the property Yes Examples lt style basedir doc destdir build doc extension html style style apache xsl gt Using an xmlcatalog lt xslt basedir doc destdir build doc extension html style style apache xsl gt lt xmlcatalog refid mycatalog gt lt xslt gt lt xslt basedir doc destdir build doc extension html style style apache xsl gt lt xmlcatalog gt lt dtd publicId ArielPartners DTD XML Article V1 0 EN location com arielpartners knowledgebase dtd article dtd gt lt xmlcatalog gt lt xslt gt Using XSL parameters lt xslt basedir doc destdir build doc extension html style style apache xsl gt lt param name date expression 07 01 2000 gt lt xslt gt Then if you declare a global parameter date with the top level element lt xsl param name date gt the variable date will subsequently have the value 07 01 2000 Using output properties lt xslt in doc xml out build doc output xml style style apache xsl gt lt outputproperty name method value xm1 gt lt outputproperty name standalone value yes gt lt outputproperty name encoding value iso8859_1 gt lt outputproperty name
143. a package the directory structure of the source tree should follow the package hierarchy It is possible to refine the set of files that are being compiled This can be done with the includes includesfile excludes and excludesfile attributes With the includes or includesfile attribute you specify the files you want to have included The exclude or excludesfile attribute is used to specify the files you want to have excluded In both cases the list of files can be specified by either the filename relative to the directory s specified in the srcdir attribute or nested lt src gt element s or by using wildcard patterns See the section on directory based tasks for information on how the inclusion exclusion of files works and how to write wildcard patterns It is possible to use different compilers This can be specified by either setting the global build compiler property which will affect all lt javac gt tasks throughout the build or by setting the compiler attribute specific to the current lt javac gt task Valid values for either the build compiler property or the compiler attribute are e classic the standard compiler of JDK 1 1 1 2 javac1 1 and javac1 2 can be used as aliases e modern the standard compiler of JDK 1 3 1 4 javac1 3 and javac1 4 can be used as aliases e ikes the Jikes compiler e jvc the Command Line Compiler from Microsoft s SDK for Java Visual J microsoft can be used as
144. aa at 295 10 48 70 MS CAOS a ias 296 10 48 7 WSSCNECKOUP Na eine tec tenis Seeing ba Red eee ee ES 297 TOVA BiB NV o A NORM AS ERS io GGA E a Ce ace cote RS LUM ENS ee ieee Aly 297 1074899 WS EP A teen anne Sa eS 298 10 48 10 VSS Create E T EETA E EA ight cia atense er AA EEEE E A A aes 298 10 49 WISE A E NN e E ANa 299 10 50 AMEN Alida aena A E NS oe ea E AEN 300 11 LISTEN ESQ LOJgETS nita nt a AA 302 nn a a E n E E a A dd dc 302 11 1 1 LISTEN SES ics so cececes da cid 302 11 1 2 LOTES airin e Ad eens 302 11 2 Built in Listeners LoggerS 0 cece eee ee eee nee eens e enna 302 11 2 1 Default LOgOer reiii eds sence doe bs co er eds 302 11 2 2 NoBannerloggetitii h cchisastiat edited atlanta ti 302 11 2 3 Mallo grin daa eis 302 T1 2 4 ANSICO O LOA fie ee eel Manian ened A OR hema A ens 303 11 2 5 LOA SEN A A ata tiie eee RSS 304 11 2 6 XMILOGG Sii yi bees vd Menai ck ed LN cda BOSSES 305 T13 Writing VOU OWN rieres candies itek AA Ea paaa dae grea iaa 305 10 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 1 Apache Ant User Manual Authors by 07100 SO O ON Stephane Bailliez Sbailliez imediation com Nicola Ken Barozzi nicolaken apache org Jacques Bergeron jacques bergerontdogico com Stefan Bodewig stefan bodewig freenet de Patrick Chanezon chanezon netscape com James Duncan Davidson duncan x180 com Tom Dimock tad1 cornell edu Peter Donald donaldp apache org dion Gillard dion apache org Erik Hatcher ehat
145. ables parser debugging No debugscanner Enables scanner debugging No 242 305 Ant Manual 1 5 4 12 9 2003 7 47 PM cleanup Remove the intermediate Sun J avaCC file created during the No Default to transformation of the grammar file false maxmemory Set the maximum memory for the J VM this is a convenient way to set No the mx or Xmx argument Nested elements jvmarg Additional parameters may be passed to the VM via nested lt jvmarg gt attributes lt jvmarg gt allows all attributes described in Command line arguments classpath Sets class path also source path unless one explicitly set Overrides METAPATH CLASSPATH environment variables The classpath element represents a PATH like structure sourcepath Sets source path Overrides the SOURCEPATH environment variable The sourcepath element represents a PATH like structure Example lt mparse target c metamata examples parseexamples javagrammars singlefile JavaParser JG metamatahome c metamata cleanup true gt lt classpath gt lt pathelement location c metamata examples gt lt classpath gt lt mparse gt This invokes Metamata MParse installed in c metamata on one of the grammar file example JavaParser jj and cleans up the intermediate Sun J avaCC file 10 28 Native2Ascii Description Converts files from native encodings to ASCII with escaped Unicode A common usage is to convert source files maintained in a native operating system encoding t
146. accessing CVS Please checkout the ant module See the section Building Ant on how to build Ant from the source code You can also access the Ant CVS repository on line 4 2 System Requirements Ant has been used successfully on many platforms including Linux commercial flavours of Unix such as Solaris and HP UX Windows 9x and NT Novell Netware 6 and MacOS X To build and use Ant you must have a J AXP compliant XML parser installed and available on your classpath The binary distribution of Ant includes the latest version of the Apache Xerces2 XML parser Please see http java sun com xml for more information about J AXP If you wish to use a different J AXP compliant parser you should remove xercesImpl jar and xml apis jar from Ant s lib directory You can then either put the jars from your preferred parser into Ant s lib directory or put the jars on the system classpath For the current version of Ant you will also need a J DK installed on your system version 1 1 or later Some tasks work better on post 1 1 systems some tasks only work on Java 1 2 and successors A future version of Ant Ant 2 0 will require JDK 1 2 or later though Ant 1 x strives to retain 1 1 compatibility Note The Microsoft J VM J DK is not adequate on its own although the MS compiler is supported Note 2 If aJDK is not present only the JRE runtime then many tasks will not work 4 3 Installing Ant The binary distribution of Ant consists of the follo
147. ace yes version name of the requested version or one of the special qualifiers or yes loads the latest versioned edition of the project xx will load the latest version including open editions Example lt vajload remote localhost 32767 gt lt vajproject name My App version gt lt vajproject name My Testcases version gt lt vajproject name JUnit version 3 2 gt lt vajload gt 10 47 5 VAJExport Description Exports Java source files class files and or resources from the workspace to the file system Exports can be specified by giving the VAJ project name and package name s This works very similar to FileSets Parameters Attribute Description Required destdir location to store the exported files yes exportSources export source files default yes no exportResources jexport resource files default yes no exportClasses export class files default no no exportDebugI nfo include debug info in exported class files default no no defaultexcludes use default excludes when exporting default yes no Default excludes are IBM Java class libraries Sun class libraries JSP Page Compile Generated Code VisualAge overwrite overwrite existing files default yes no remote name and port of a remote tool server format lt servername gt lt port no gt ae attribute is set the tasks will be executed on the specified tool server haltonerror Stop t
148. ache ant lib xercesImpl jar envset CLASSPATH SCLASSPATH SYS apache ant 1lib xml apis jar envset CLASSPATH SCLASSPATH SYS apache ant lib optional junit jar envset CLASSPATH SCLASSPATH SYS apache ant bootstrap lib optional jar setenv ANT_OPTS envCWD sys apache ant envset ANT_OPTS envCWD sys apache ant setenv ANT_HOME sys apache ant dist lib envset ANT_HOME sys apache ant dist lib perl sys apache ant dist bin runant pl 19 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Ant works on JVM version 1 3 or higher You may have some luck running it on JVM 1 2 but serious problems have been found running Ant on JVM 1 1 7B These problems are caused by JVM bugs that will not be fixed JVM 1 3 is supported on Novell NetWare versions 5 1 and higher 4 6 5 Other platforms Support for other platforms is not guaranteed to be complete as certain techniques to hide platform details from build files need to be written and tested on every particular platform Contributions in this area are welcome 20 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 5 Running Ant 5 1 Command Line If you ve installed Ant as described in the Installing Ant section running Ant from the command line is simple just type ant When no arguments are specified Ant looks for a build xml file in the current directory and if found uses that file as the build file and runs the target specified in the default attribute of the lt project gt tag To make Ant use a bu
149. al parameters to the all javadoc command line Useful for doclets Parameters containing spaces need to be quoted using amp quot Stop the buildprocess if the command exits all with a returncode other than 0 comma separated list of packages you don t all want docs for indicates whether default excludes should be all 127 305 12 9 2003 7 47 PM No No No No No No No No No No No No No No No No No No No No No No No No No No No No No No No No No Ant Manual 1 5 4 12 9 2003 7 47 PM used yes no default excludes are used when omitted useexternalfile indicates whether the sourcefile name specified 1 2 No in srcfiles or as nested source elements should be written to a temporary file to make the command line shorter Also applies to the package names specified via the packagenames attribute or nested package elements yes no Default is no source Necessary to enable javadoc to handle 1 4 No assertions present in J2SE v 1 4 source code Set this to 1 4 to documents code that compiles using javac source 1 4 Format of the group attribute The arguments are comma delimited Each single argument is 2 space delimited strings where the first one is the group s title and the second one a colon delimited list of packages If you need to specify more than one group or a group whose title contains a comma or a space character using nested group elements is highly recommend
150. allation of Perforce may require other settings e g PAPASSWD P4CONFIG At the moment these can only be set outside of Ant as environment variables Additionally you may also specify the following attributes Attribute Description Required failonerror Specifies whether to stop the build true yes on or keep going No defaults to false no off if an error is returned from the p4 command true Examples Setting in the environment Unix csh setenv P4PORT myperforcebox 1666 247 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Unix sh et al P4USER myp4userid export P4USER Using build properties lt property name p4 client value nightlybuild gt Using task attributes lt p4Whatever port myserver 1666 client smoketest user smoketestdude gt For more information regarding the underlying p4 commands you are referred to the Perforce Command Reference available from the Perforce website 10 30 4 Taskdefs Standard taskdefs for you to copy n paste normally this is done automatically if you install this optional task lt taskdef name p4sync classname org apache tools ant taskdefs optional perforce P4Sync gt lt taskdef name p4change classname org apache tools ant taskdefs optional perforce P4Change gt lt taskdef name p4edit classname org apache tools ant taskdefs optional
151. allation using the 218 305 Ant Manual 1 5 4 12 9 2003 7 47 PM javacchome attribute so that ant can find the JavaCC classes Optionally you can also set the outputdirectory to write the generated file to a specific directory Otherwise javacc writes the generated files to the directory containing the grammar file This task only invokes J avaCC if the grammar file is newer than the generated J ava files javacc assumes that the Java class name of the generated parser is the same as the name of the grammar file ignoring the jj If this is not the case the javacc task will still work but it will always generate the output files Parameters Attribute Description Required target The grammar file to process Yes javacchome The directory containing the J avaCC distribution Yes outputdirectory The directory to write the generated files to If not set the files are No written to the directory containing the grammar file buildparser Sets the BUILD_PARSER grammar option This is a boolean option No buildtokenmanager Sets the BUILD_TOKEN_MANAGER grammar option This is a No boolean option cachetokens Sets the CACHE_TOKENS grammar option This is a boolean option No choiceambiguitycheck Sets the CHOICE_AMBIGUITY_CHECK grammar option Thisisan _ No integer option commontokenaction Sets the COMMON_TOKEN_ACTION grammar option This is a No boolean option debuglookahead Sets the DEBUG_LOOKAHEAD grammar option This is a boole
152. ameters Attribute Description Required tochange The changelist to move files to Yes Examples Move all open files to the default changelist lt p4reopen view tochange default gt Create a new changelist then reopen into it any files from the view projects foo main lt p4change description Move files out of the way gt lt p4reopen view projects foo main tochange p4 change gt 10 30 13 P4Revert Description Reverts files Parameters Attribute Description Required change The changelist to revert No revertOnlyUnchanged Revert only unchanged files p4 revert a No Examples Revert everything lt p4revert view gt Revert any unchanged files in the default change lt p4revert change default revertonlyunchanged true gt 10 30 14 P4Add Description Adds files specified in nested fileset children Parameters 251 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Attribute Description Required commandlengthiA positive integer specifying the maximum length of the commandline No when calling Perforce to add the files Defaults to 450 higher values mean faster execution but also possible failures changelist If specified the open files are associated with the specified pending No changelist number otherwise the open files are associated with the default changelist Examples Require a changelist add all java files starting from a directory and submit lt p4change gt lt p4a
153. ample derived HTML files in the output dir directory will be removed if any are out of date with respect to the DTD of their source XML files a common DTD imported by the main DTD a subordinate XSLT stylesheet imported by the main stylesheet or the buildfile PUNE If any of the source files in the above example does not exist all target files will also be removed To ignore missing source files instead use filesets instead of filelists for the source files 9 24 Dirname Description Task to determine the directory path of a specified file When this task executes it will set the specified property to the value of the specified file up to but not including the last path element If the specified file is a path that ends in a filename the filename will be dropped If the specified file is just a filename the directory will be the current directory Parameters 103 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Attribute Description Required file The path to take the dirname of Yes property The name of the property to set Yes Examples lt dirname property antfile dir file S ant file gt will set antfile dir to the directory path for S ant file lt dirname property foo dirname file foo txt gt will set foo dirname to the project s basedir 9 25 Ear Description An extension of the Jar task with special treatment for files that should end up in an Enterprise Application archive The Ear task is
154. an No option debugparser Sets the DEBUG_PARSER grammar option This is a boolean option No debugtokenmanager Sets the DEBUG_TOKEN_MANAGER grammar option This is a No boolean option errorreporting Sets the ERROR_REPORTING grammar option This is a boolean No option forcelacheck Sets the FORCE_LA_CHECK grammar option This is a boolean No option ignorecase Sets the IGNORE_CASE grammar option This is a boolean option No javaunicodeescape Sets the JAVA_UNICODE_ESCAPE grammar option This is a boolean No option lookahead Sets the LOOKAHEAD grammar option This is an integer option No optimizetokenmanager Sets the OPTIMIZE_TOKEN_MANAGER grammar option This is a No boolean option otherambiguitycheck Sets the OTHER_AMBIGUITY_CHECK grammar option This is an No integer option sanitycheck Sets the SANITY_CHECK grammar option This is a boolean option No static Sets the STATIC grammar option This is a boolean option No unicodeinput Sets the UNICODE_INPUT grammar option This is a boolean option No usercharstream Sets the USER_CHAR_STREAM grammar option This is a boolean No option usertokenmanager Sets the USER TOKEN MANAGER grammar option This is a boolean No option Example lt javacc 219 305 Ant Manual 1 5 4 12 9 2003 7 47 PM target src Parser J3 outputdirectory build src javacchome c program files Javacc static true gt This invokes JavaCC on grammar file src Parser jj writing the
155. ar algorithm SHA fileext asc gt Generates a SHA checksum for foo bar and stores the checksum in the destination file foo bar asc foo bar asc is overwritten only if foo bar is newer than itself Example 6 lt checksum file foo bar property md5 verifyProperty isEqual gt Generates a MD5 checksum for foo bar compares it against the value of the property md5 and sets isEqual to either true or false depending upon the result Example 7 lt checksum gt lt fileset dir gt lt include name foo gt lt fileset gt lt checksum gt Works just like Example 1 but generates a MD5 file for every file that begins with the name foo Example 8 lt condition property isChecksumEqual gt lt checksum gt lt fileset dir gt lt include name foo bar gt lt fileset gt lt checksum gt lt condition gt 85 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Works like Example 4 but only sets isChecksumEqual to true if the checksum matches it will never be set to false This example demonstrates use with the Condition task Note When working with more than one file if condition and or verifyproperty is used the result will be true only if the checksums matched correctly for all files being considered 9 11 Chmod Description Changes the permissions of a file or all files inside specified directories Right now it has effect only under Unix The permissions are also UNIX style like the arg
156. asses are not present or are out of date the ejbc tool is run to generate new versions Parameters Attribute Description Required descriptors This is the base directory from which the serialized deployment Yes descriptors are selected dest The base directory where the generated classes RIM stubs and RMI Yes skeletons are written manifest The name of a manifest file to be written This manifest will contain Yes an entry for each EJ B processed src The base directory of the source tree containingthe source files of Yes the home interface remote interface and bean implementation classes classpath This classpath must include both the weblogic ejbc class and the No class files of the bean home interface remote interface etc of the bean being pro cessed keepgenerated Controls whether ejbc will keep the intermediate J ava files used to build the class files This can be useful when debugging No defaults to false Examples lt ejbc descriptors gen classes srce S sre dir dest gen classes manifest build manifest classpath descriptorbuild classpath gt lt include name ser gt lt ejbe gt 10 7 2 31PLANET EJ BC Description 189 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Task to compile EJB stubs and skeletons for the iPlanet Application Server 6 0 Given a standard EJB 1 1 XML descriptor as well as an iAS specific EJB descriptor this task will generate the stubs and skeletons required
157. asses that make up the bean to be available on the classpath Currently however this will cause the ejbc tool to be run in a separate VM Weblogic 6 0 will give a warning if the home and remote interfaces of a No bean are on the system classpath used to run weblogic ejbc In that case the standard weblogic classes should be set with this attribute or equivalent nested element and the home and remote interfaces located with the standard classpath attribute This controls whether the generic file used as input to ejbc is retained No defaults to false This allows for the selection of a different compiler to be used for the No compilation of the generated J ava files This could be set for example to Jikes to compile with the Jikes compiler If this is not set and the build compiler property is set to jikes the Jikes compiler will be used If this is not desired the value default may be given to use the default compiler This flag controls whether weblogic ejbc isalways invoked to build the No defaults jar file In certain circumstances such as when only a bean class has to true been changed the jar can be generated by merely replacing the changed classes and not rerunning ejbc Setting this to false will reduce the time to run ejbjar Controls whether weblogic will keep the generated Java files used to No defaults build the class files added to the jar This can be useful when to false debugging Any additional argument
158. ault No is no traceLexer Only forces lexer rules to call traceln traceOut if set to yes The default No is no traceTreeWalker Only forces tree walker rules to call traceln traceOut if set to yes The No default is no dir The directory to invoke the VM in No Nested Elements ANTLR supports a nested lt classpath gt element that represents a PATH like structure It is given as a convenience if you have to specify the original ANTLR directory In most cases dropping the appropriate ANTLR jar in the normal Ant lib repository will be enough jvmarg 179 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Additional parameters may be passed to the new VM via nested lt jvmarg gt attributes for example lt antlr target gt lt jvmarg value Djava compiler NONE gt lt antlr gt would run ANTLR in a VM without JIT lt jvmarg gt allows all attributes described in Command line arguments Example lt antlr target etc java g outputdirectory build src gt This invokes ANTLR on grammar file etc java g writing the generated files to build src 10 3 Cab Description The cab task creates Microsoft cab archive files It is invoked similar to the jar or zip tasks This task will work on Windows using the external cabarc tool provided by Microsoft which must be located in your executable path To use this task on other platforms you need to download and compile libcabinet from http trill cis
159. ault is warning One of error warning info verbose debug Examples lt echo message Hello world gt lt echo gt This is a longer message stretching over two lines lt echo gt lt echo gt This is a longer message stretching over thr lines the first line is a blank lt echo gt As XML parsers are wont to do the first newline in the text element has been included in the text lt echo message Deleting drive C level debug gt A message which only appears in debug mode 105 305 Ant Manual 1 5 4 lt echo level 12 9 2003 7 47 PM rror gt Imminent failure in the antimatter containment facility Please withdraw to safe location at least 50km away lt echo gt A message which appears even in quiet mode lt echo file runner csh append false gt bin tcsh java 1 3 1 mx1024m fproject entrypoint Generate a shell script by echoing to a file Note the use of a double symbol to stop Ant filtering out the single during variable expansion 9 27 Exec Description Executes a system command When the os attribute is specified then the command is only executed when Ant is run on one of the specified operating systems Cygwin Users In general the lt exec gt task will not understand paths such as bin sh for the executable parameter This is because the Java VM in which Ant is running is a Windows executable and is not aware of Cygwin con
160. ava source It can be used to precompile JSP pages for fast initial invocation of JSP pages deployment on a server without the full JDK installed or simply to syntax check the pages without deploying them In most cases a javac task is usually the next stage in the build process The task does basic dependency checking to prevent unnecessary recompilation this checking compares source and destination timestamps and does not factor in class or taglib dependencies or lt jsp include gt references By default the task uses the Jasper JSP compiler This means the task needs jasper jar and jasperruntime jar which come with builds of Tomcat 4 Catalina from the Jakarta Tomcat project We recommend Tomcat version 4 1 x for the most robust version of jasper There are many limitations with this task which partially stem from the many versions of Jasper others from implementation issues in the task i e nobody s willingness to radically change large bits of it to work around jasper Because of this and the fact that JSP pages do not have to be portable across implementations or versions of implementations this task is better used for validating JSP pages before deployment rather than precompiling them For that just deploy and run your httpunit junit tests after deployment to compile and test your pages all in one go Parameters The Task has the following attributes Attribute Description Required destdir Where to place the generated files
161. ay be passed to the VM via nested lt jvmarg gt attributes lt jvmarg gt allows all attributes described in Command line arguments classpath 238 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Sets class path also source path unless one explicitly set Overrides METAPATH CLASSPATH environment variables The classpath element represents a PATH like structure sourcepath Sets source path Overrides the SOURCEPATH environment variable The sourcepath element represents a PATH like structure path Sets the list of directories to analyze the code for metrics It represents a PATH structure fileset Sets a set of files to analyze for metrics source It represents a FILESET structure Note For the sake of readability it is highly recommended to analyze for a single unique directory instead than using filesets or several directories Otherwise there will be multiple metrics outputs without any way to know what metrics refers to what source Chance are also that the XML handler that does some heuristic will be confused by the different outputs Example lt mmetrics tofile mmetrics xml etamatahome c metamata granularity methods gt lt classpath gt lt pathelement location c metamata examples metricsexamples gt lt classpath gt lt sourcepath gt lt pathelement location c metamata examples metricsexamples gt lt sourcepath gt lt path gt lt pathelement location c metamata examples metricsexamples gt lt path
162. ays all the current properties in the project The output can be sent to a file if desired You can also specify a subset of properties to save by naming a prefix only properties starting with this prefix will be saved This task can be used as a somewhat contrived means of returning data from an lt ant gt invocation but is really for debugging build files Parameters Attribute Description Required destfile If specified the value indicates the name of the file to send the output of the No statement to The generated output file is compatible for loading by any Java application as a property file If not specified then the output will go to the Ant log prefix a prefix which is used to filter the properties only those properties starting with No this prefix will be echoed failonerror By default the failonerror attribute is enabled If an error occurs while writing No the properties to a file and this attribute is enabled then a BuildException will be thrown causing the build to fail If disabled then 10 errors will be reported as a log statement and the build will continue without failure from this task Examples lt echoproperties gt Report the current properties to the log lt echoproperties destfile my properties gt Report the current properties to the file my properties and will fail the build if the file could not be created or written to lt echoproperties destfile my properties failonerror fals
163. be handled No Valid values for this property are add ensure that there is an EOF character at the end of the file asis leave EOF characters alone remove remove any EOF character found at the end Default is based on the platform on which you are running this task For Unix platforms the default is remove For DOS based systems including Windows the default is asis encoding The encoding of the files Defaults to default JVM encoding No Examples lt fixcrlf srcdir S src eol 1f eof remove includes sh gt Replaces EOLs with LF characters and removes eof characters from the shell scripts Tabs and spaces are left as is lt fixcrlf srcdir S src eol crlf includes bat gt Replaces all EOLs with cr If pairs in the batch files Tabs and spaces are left as is EOF characters are left alone if run on DOS systems and are removed if run on Unix systems lt fixcrlf srcdir S src tab add includes Makefile gt Sets EOLs according to local OS conventions and converts sequences of spaces and tabs to the minimal set of spaces and tabs which will maintain spacing within the line Tabs are set at 8 character intervals EOF characters are left alone if run on DOS systems and are removed if run on Unix systems Many versions of make require tabs prior to commands lt fixcrlf srcdir S src tab remove tablength 3 eol 1f javafiles yes includes Jjava gt Converts a
164. build classes 9 54 Sequential Description Sequential is a container task it can contain other Ant tasks The nested tasks are simply executed in sequence Sequential s primary use is to support the sequential execution of a subset of tasks within the parallel task The sequential task has no attributes and does not support any nested elements apart from Ant tasks Any valid Ant task may be embedded within the sequential task Example lt parallel gt lt wlrun gt lt sequential gt lt sleep seconds 30 gt lt junit gt lt wlstop gt lt sequential gt lt parallel gt This example shows how the sequential task is used to execute three tasks in sequence while another task is being executed in a separate thread 149 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 9 55 Sign ar Description Signs jar or zip files with the javasign command line tool The tool detailed dependency checking files are only signed if they are not signed The signjar attribute can point to the file to generate if this file exists then its modification date is used as a cue as to whether to resign any JAR file Note Requires Java 1 2 or later Parameters Attribute Description Required jar the jar file to sign Yes unless nested filesets have been used alias the alias to sign under Yes storepass password for keystore integrity Yes keystore keystore location No storetype keystore type No keypass password for private key if
165. built in tasks support nested lt filterchain gt elements Copy LoadFile LoadProperties Move A FilterChain is formed by defining zero or more of the following nested elements FilterReader ClassConstants ExpandProperties HeadFilter LineContains LineContainsRegExp PrefixLines ReplaceTokens Strip avaComments StripLineBreaks StripLineComments TabsToSpaces TailFilter 7 3 8 FilterReader The filterreader element is the generic way to define a filter User defined filter elements are defined in the build file using this Please note that built in filter readers can also be defined using this syntax A FilterReader element must be supplied with a class name as an attribute value The class resolved by this name must extend java io FilterReader If the custom filter reader needs to be parameterized it must implement org apache tools type Parameterizable Attribute Description Required classname The class name of the filter reader Yes Nested Elements lt filterreader gt supports lt classpath gt and lt param gt as nested elements Each lt param gt element may take in the following attributes name type and value The following FilterReaders are supplied with the default distribution ClassConstants This filters basic constants defined in a Java Class and outputs them in lines composed of the format name value Example 44 305 Ant Manual 1 5 4 12 9 2003 7 47 PM This loads the basic constants define
166. bute Description Required language The programming language the script is written in Must be a supported BSF Yes language src The location of the script as a file if not inline No Examples lt project name squares default main basedir gt lt target name setup gt lt script language Javascript gt lt CDATA for i l i lt 10 i echo squares createTask echo main addTask echo cho setMessage i i gt lt script gt lt target gt lt target name main depends setup gt lt project gt generates setup main 1 4 9 16 25 36 49 64 264 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 81 100 BUILD SUCCESSFUL Another example using references by id and two different scripting languages lt project name testscript default main gt lt target name sub gt lt echo id theEcho gt lt target gt lt target name subl gt lt script language netrexx gt lt CDATA theEcho setMessage In subl sub execute gt lt script gt lt target gt lt target name sub2 gt lt script language Jjavascript gt lt CDATA theEcho setMessage In sub2 sub execute gt lt script gt lt target gt lt target name main depends subl sub2 gt lt project gt generates subl In subl sub2 In sub2 main BUILD SUCCESSFUL 10 39 Sound Description Plays a sound file at the end of the build according
167. bute Description Required tofile The name of the XML file that will aggregate all individual XML No Default to TESTS testsuite previously generated by the J Unit task TestSuites xml todir The directory where should be written the file resulting from the No Default to current individual XML testsuite aggregation directory Nested Elements fileset junitreport collects individual xml files generated by the J Unit task using the nested lt FileSet gt element report Generate a browsable report based on the document created by the merge Parameters Attribute Description Required format The format of the generated report Must be noframes or No default to frames frames styledir The directory where the stylesheets are defined They must be No Default to embedded conforming to the following conventions stylesheets frames format the stylesheet must be named junit frames xsl noframes format the stylesheet must be named junit noframes xsl 237 305 Ant Manual 1 5 4 12 9 2003 7 47 PM todir The directory where the files resulting from the transformation No Default to current should be written to directory Example of report lt junitreport todir reports gt lt fileset dir reports gt lt include name TEST xml gt lt fileset gt lt report format frames todir report html gt lt junitreport gt would generate a TESTS TestSuites xml file in the directory reports and genera
168. cDriver url jdbc database url userid sa password pass gt lt fileset dir gt lt include name data sql gt lt fileset gt lt transaction gt truncate table some_other_table lt transaction gt lt sql gt The following connects to the database given in url as the sa user using the org database jdbcDriver and executes the SQL statements contained within the file data sql with output piped to outputfile txt searching some jdbc jar as well as the system classpath for the driver class lt sql driver org database jdbcDriver url jdbc database url userid sa password pass src data sql print yes output outputfile txt gt lt classpath gt lt pathelement location some jdbc jar gt lt classpath gt lt sql gt The following will only execute if the RDBMS is oracle and the version starts with 8 1 lt sql driver org database jdbcDriver url 3jdbc database url userid sa password pass src data sql rdbms oracle version 8 1 gt insert into table some_table values 1 2 3 4 truncate table some_other_table lt sql gt 154 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 9 58 Style XsIt Description Process a set of documents via XSLT This is useful for building views of XML based documentation or for generating code Note This task depends on external libraries not included in the Ant distribution See Library Dependencies for more infor
169. can be used to in a sense implement HTTP redirects substituting one URL for another The mapped to URL might also be served by a local web server If the URL resolves to a valid and readable resource we are done Otherwise we give up In this case the XML processor will perform its normal resolution algorithm Depending on the processor configuration further resolution failures may or may not result in fatal i e build ending errors 7 3 23 2 XMLCATALOG ATTRIBUTES Attribute Description Required id a unique name for an XMLCatalog used for referencing the XMLCatalog s No contents from another XMLCatalog refid the id of another XMLCatalog whose contents you would like to be used for this No XMLCatalog 7 3 23 3XMLCATALOG NESTED ELEMENTS dtd entity The dtd and entity elements used to specify XMLCatalogs are identical in their structure Attribute Description Required publicld The public identifier used when defining a dtd or entity e g Sun Yes Microsystems Inc DTD Web Application 2 2 EN location The location of the local replacement to be used for the public identifier specified Yes This may be specified as a file name resource name found on the classpath or a URL Relative paths will be resolved according to the base which by default is the Ant project basedir classpath The classpath to use for entity resolution The nested lt classpath gt is a path like structure Examples Set up an XMLCatalog with a si
170. che Matches org apache CVS Entries org apache jakarta tools ant CVS Entries But not org apache CVS foo bar Entries foo bar part does not match test Matches all files that have a test element in their path including test as a filename When these patterns are used in inclusion and exclusion you have a powerful way to select just the files you want Selectors The lt fileset gt whether implicit or explicit in the directory based task also acts as an lt and gt selector container This can be used to create arbitrarily complicated selection criteria for the files the task should work with See the Selector documentation for more information Standard Tasks Filesets 34 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Many of the standard tasks in ant take one or more filesets which follow the rules given here This list a subset of those is a list of standard ant tasks that can act as an implicit fileset lt checksum gt lt copydir gt deprecated lt delete gt lt dependset gt lt fixcrif gt lt javac gt lt replace gt lt rmic gt lt style gt aka lt xslt gt lt tar gt lt zip gt lt ddcreator gt lt ejbjar gt lt ejbc gt lt cab gt lt icontract gt lt netrexxc gt lt renameextensions gt lt depend gt lt ilasm gt lt csc gt lt vbc gt lt translate gt lt vajexport gt lt image gt lt jlink gt deprecated lt jspc gt lt wljspc gt Examples lt c
171. cher apache org Diane Holt holtdlI yahoo com Bill Kelly bill kelly softwired inc com Arnout J Kuiper ajkuiper wxs nl Conor MacNeill Stefano Mazzocchi stefano apache org Erik Meade emeade geekfarm org Sam Ruby rubys us ibm com Nico Seessle nico seessle de Jon S Stevens jon latchkey com Magesh Umasankar Roger Vaughn rvaughn seaconinc com Dave Walend dwalend cs tufts edu Phillip Wells philwells rocketmail com Craeg Strong cstrong arielpartners com Version 1 5 4 id credits html v 1 15 2 9 2003 09 29 08 42 08 bodewig Exp Copyright O 2000 2002 Apache Software Foundation All rights Reserved 11 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 2 Feedback and Troubleshooting If things do not work especially simple things like ant version then something is wrong with your configuration Before filing bug reports and emailing all the ant mailing lists 1 Check your environment variables Are ANT_HOME and JAVA_HOME correct If they have quotes or trailing slashes remove them 2 Unset CLASSPATH if that is wrong things go horribly wrong Ant does not need the CLASSPATH variable defined to anything to work 3 Make sure there are no versions of crimson jar or other XML parsers in J RE ext 4 Is your path correct is Ant on it What about JDK bin have you tested this If you are using Jikes is it on the path A createProcess error especially with ID 2 on windows usually mea
172. ction delete source lib dir ejb_myApp jar gt lt weblogic application myapp server 13 myserver 7001 classpath weblogic home lib weblogic jar username user name password S user password gt lt serverdeploy gt 10 36 4 JOnAS Java Open Applicaton Server element The JOnAS element contains additional attributes to run the JonasAdmin deployment tool Valid actions for the tool are deploy undeploy list and update You can t use user and password property with this task Attribute Description Required jonasroot The root directory for J OnAS Yes orb Choose your ORB RMI JEREMIE DAVID If omitted it defaults to the one present in classpath The corresponding J OnAS JAR is automatically added to the No classpath If your orb is DAVID RMI IIOP you must specify davidhost and davidport properties davidhost The value for the system property david CosNaming default_host No davidport The value for the system property david CosNaming default_port No classname This is the fully qualified classname of the Java based deployment tool to No execute Default to org objectweb jonas adm J onasAdmin Nested Elements 262 305 Ant Manual 1 5 4 12 9 2003 7 47 PM The jonas element supports nested lt arg gt and lt jvmarg gt elements Examples This example shows the use of serverdeploy to deploy a component to a JOnAS server lt serverdeploy action deploy source lib dir ejb_myApp
173. ctory of the jar file If this fileset includes a file named MANIFEST MF the file is ignored and you will get a warning manifest The manifest nested element allows the manifest for the Jar file to be provided inline in the build file rather than in an external file This element is identical to the manifest task but the file and mode attributes must be omitted If both an inline manifest and an external file are both specified the manifests are merged When using inline manifests the Jar task will check whether the build file is more recent that the Jar file when deciding whether to rebuild the Jar This will not take into account property file changes which may affect the resulting Jar Examples lt jar destfile S dist lib app jar basedir build classes gt jars all files in the build classes directory into a file called app jar in the dist lib directory lt jar destfile S dist lib app jar basedir build classes xcludes Test class gt jars all files in the build classes directory into a file called app jar in the dist lib directory Files with the name Test class are excluded lt jar destfile S dist lib app jar basedir build classes includes mypackage test xcludes Test class gt jars all files in the build classes directory into a file called app jar in the dist lib directory Only files under the directory mypackage test are used a
174. cute task only if this rdbms No no restriction version Execute task only if rdbms version match No no restriction caching Should the task cache loaders and the driver No default true Parameters specified as nested elements transaction Use nested lt transaction gt elements to specify multiple blocks of commands to the executed executed in the same connection but different transactions This is particularly useful when there are multiple files to execute on the same schema Attribute Description Required src File containing SQL statements Yes unless statements enclosed within tags fileset You can specify multiple source files via nested fileset elements Each file of the fileset will be run in a transaction of its own the order by which the files of a single fileset will be executed is not defined classpath Sql s classpath attribute is a PATH like structure and can also be set via a nested classpath element It is used to load the J DBC classes Examples lt sql driver org database jdbcDriver url jdbc database url userid sa password pass src data sql gt 152 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Connects to the database given in url as the sa user using the org database jdbcDriver and executes the SQL statements contained within the file data sql lt sql driver org database jdbcDriver url jdbc database url userid sa password pass gt insert into table some_table values 1 2 3 4
175. d All No iles are included when omitted includesfile he name of a file Each line of this file is taken to be an include pattern excludes comma or space separated list of patterns of files that must be excluded No No files except default excludes are excluded when omitted Default excludes are used when omitted latten ignore directory structure of source directory copy all files into a single Ma directory specified by the dest attribute default is false orceoverwrite loverwrite existing files even if the destination files are newer default is fee alse Examples lt copydir src S src resources dest S dist gt copies the directory src resources to dist lt copydir src src resources dest S dist includes Java 93 305 Ant Manual 1 5 4 12 9 2003 7 47 PM xcludes Test java gt copies the directory src resources to dist recursively All java files are copied except for files with the name Test java lt copydir src S src resources dest S dist includes Jjava excludes mypackage test gt copies the directory src resources to dist recursively All java files are copied except for the files under the mypackage test directory 9 16 Copyfile Deprecated This task has been deprecated Use the Copy task instead Description Copies a file from the source to the destination The file is only copied if the source file is newer than the d
176. d datetime Specifies the date and time to test for using a string of the format At least one MM DD YYYY HH MM AM_or_PM of the two millis The number of milliseconds since 1970 that should be tested for It is usually much easier to use the datetime attribute granularity The number of milliseconds leeway to give before deciding whether a files No modification time matches a date This is needed because not every file system supports tracking the last modified time to the millisecond level The file will be selected provided the condition could be true were the granularity added or subtracted from the actual time Default is O milliseconds except on Windows systems where it is 2000 milliseconds 2 seconds when Indicates how to interpret the date whether the files to be selected are those No whose last modified times should be before after or equal to the specified value Acceptable values for this attribute are before select files whose last modified date is before the indicated date after select files whose last modified date is after the indicated date equal select files whose last modified date is this exact date The default is equal Here is an example of how to use the Date Selector lt fileset dir S jar path includes Jar gt lt date datetime 01 01 2001 12 00 AM when before gt lt fileset gt Selects all JAR files which were last modified before midnight January 1 2001 7 3 22 5DEPEND SELECTOR The
177. d and write the build number from to JNo defaults to build number Examples lt buildnumber gt Read increment and write a build number to the default file build number lt buildnumber file mybuild number gt Read increment and write a build number to the file mybuild number 9 8 BUnzip2 GUnzip Description Expands a file packed using GZip or BZip2 If dest is a directory the name of the destination file is the same as src with the gz or bz2 extension removed if present If dest is omitted the parent dir of src is taken The file is only expanded if the source file is newer than the destination file or when the destination file does not exist Parameters Attribute Description Required src the file to expand dest the destination file or directory No Examples lt gunzip src test tar gz gt expands test tar gz to test tar lt bunzip2 src test tar bz2 gt expands test tar bz2 to test tar lt gunzip src test tar gz dest test2 tar gt expands test tar gz to test2 tar lt gunzip src test tar gz dest subdir gt expands test tar gz to subdir test tar assuming subdir is a directory 83 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 9 9 BZip2 GZip Description Packs a file using the GZip or BZip2 algorithm The output file is only generated if it doesn t exist or the source file is newer Parameters Attribute Description_____ Required he file to gzip bzip Yes he
178. d in a Java class as Ant properties lt loadproperties srcfile foo class gt lt filterchain gt lt filterreader classname org apache tools ant filters ClassConstants gt lt filterchain gt lt loadproperties gt Convenience method lt loadproperties srcfile foo class gt lt filterchain gt lt classconstants gt lt filterchain gt lt loadproperties gt 7 3 9 ExpandProperties If the data contains data that represents Ant properties of the form that is substituted with the property s actual value Example This results in the property modifiedmessage holding the value All these moments will be lost in time like teardrops in the rain lt echo message All these moments will be lost in time like teardrops in the S weather file loadfilel tmp gt lt property name weather value rain gt lt loadfile property modifiedmessage srcFile loadfilel tmp gt lt filterchain gt lt filterreader classname org apache tools ant filters ExpandProperties gt lt filterchain gt lt loadfile gt Convenience method lt echo message All these moments will be lost in time like teardrops in the S weather file loadfilel tmp gt lt property name weather value rain gt lt loadfile property modifiedmessage srcFile loadfilel tmp gt lt filterchain gt lt expandproperties gt lt filterchain gt lt loadfile gt 45 305 Ant Manual 1 5
179. d path path reference filelist reference or fileset reference to the form usable on a specified platform and or to a list of items separated by the specified Separator and stores the result in the specified property ee ces a property by name and value or set of properties from a file or resource in the project PropertyFile Creates or modifies property files Useful when wanting to make unattended modifications to configuration files for application servers and applications Typically used for things such as automatically generating a build number and saving it to a build properties file or doing date manipulation Uptodate Sets a property if a given target file is newer than a set of source files XmlPropert Loads property values from a valid XML file 8 1 16 Remote Tasks Description e A mplements a basic FTP client that can send receive list and delete files and create directories ask to automate a remote telnet session This task uses nested lt read gt and lt write gt tags to indicate strings to wait for and specify text to send setprox Sets Java s web proxy properties so that tasks and code run in the same J VM can have through the firewall access to remote web sites 8 1 17 SCM Tasks TaskName Description Cvs Handles packages modules retrieved from a CVS repository CvsChangeLog Generates an XML report of the changes recorded in a CVS repository CVSPass Adds entries to a cvspass file Adding
180. d selectors select it e lt majority gt select a file if a majority of its selectors select it lt none gt select a file only if none of the contained selectors select it lt not gt can contain only one selector and reverses what it selects and doesn t select lt or gt selects a file if any one of the contained selectors selects it lt selector gt contains only one selector and forwards all requests to it without alteration This is the selector to use if you want to define a reference It is usable as an element of lt project gt All selector containers can contain any other selector including other containers as an element Using containers the selector tags can be arbitrarily deep Here is a complete list of allowable selector elements within a container e lt and gt lt contains gt lt custom gt lt date gt lt depend gt lt depth gt lt filename gt lt majority gt lt none gt lt not gt lt or gt lt present gt lt selector gt lt size gt 7 3 22 11 AND SELECTOR The lt and gt tag selects files that are selected by all of the elements it contains It returns as soon as it finds a selector that does not select the file so it is not guaranteed to check every selector Here is an example of how to use the And Selector lt fileset dir dist includes Jar gt lt and gt lt size value 4 units Ki when more gt lt date datetime 01 01 2001 12 00 AM when before gt lt and
181. d to get access to login VSS Note that you may need to specify both if you have a password No Ant VSS will hang if you leave the password out and VSS does not accept 297 305 Ant Manual 1 5 4 12 9 2003 7 47 PM login without a password directory where ss exe resides By default the task expects it to be in the ssdir PATH No serverPath directory where srssafe ini resides No writable true or false No recursive true or false No comment Comment to use for the files that where checked in No autoresponse Y N or empty Specify how to reply to questions from VSS No Examples lt vssadd localpath D build build 00012 zip comment Added by automatic build gt Add the file named build 00012 zip into the project current working directory see vsscp 10 48 9 VssCp Description Task to perform CP Change Project commands to Microsoft Visual SourceSafe This task is typically used before a VssAdd in order to set the target project Parameters Attribute Values Required SourceSafe path which specifies the project you wish to make the current vsspath project You should not specify the leading dollar sign it is prepended by Ant Yes automatically username password The username and password needed to get access to VSS Note that you may need to specify both if you have a password login Ant VSS will hang if you leave the password out and VSS does not accept login Ne without a password ssdir directory where ss
182. dd commandlength 20000 changelist p4 change gt lt fileset dir dir src includes java gt lt p4add gt lt p4submit change p4 change gt Change History Sept 2000 Internal Release within Rubus Nov 2000 V1 0 Initial Release donated to ASF Jan 2001 V1 1 fixed cross platform NT Unix bug refactored p4 output handling code refactored exec ing code 10 31 PropertyFile by e Thomas Christen chr active ch e Jeremy Mawson jem loftinspace com au 10 31 1 Introduction Ant provides an optional task for editing property files This is very useful when wanting to make unattended modifications to configuration files for application servers and applications Currently the task maintains a working property file with the ability to add properties or make changes to existing ones However any comments are lost 10 31 2 PropertyFile Task Parameters Attribute Description Required file Location of the property file to be edited Yes comment Header for the file itself no Parameters specified as nested elements Entry Use nested lt entry gt elements to specify actual modifications to the property file itself Attribute Description Required key Name of the property name value pair Yes value Value to set to add or subtract At least one must be default Initial value to set for a property if it is not already defined in the Specified 252 305 Ant Manual 1 5 4 12 9 2003 7 47 PM prope
183. deprecated in preference to the lt setproxy gt task that makes it clear to readers of the build exactly what is going on We say mostly as this task s support includes proxy authentication so you may still need to use its proxy attributes useproxy Use a proxy to access imgurl Note Only tested on JDK 1 2 2 and above No None proxy IP or hostname of the proxy server No None port Proxy portnumber No None user User to authenticate to the proxy as No None password Proxy password No None Examples lt splash gt Splash images ant_logo_large gif from the classpath lt splash imageurl http jakarta apache org images jakarta logo gif useproxy true showduration 5000 gt Splashes the jakarta logo for an initial period of 5 seconds 10 42 StarTeam Support e STCheckout e STCheckin e STLabel e STList e StarTeam deprecated These tasks make use of functions from the StarTeam API As a result they are only available to licensed users of StarTeam You must have starteam sdk jar in your classpath to run these tasks For more information about the StarTeam API and how to license it see the Borland web site Important Note on Installation and Licensing On Windows machines the mere presence of starteam sdk jar on the classpath is not sufficient for getting these tasks to work properly These tasks also require a fully installed and fully licensed version of the StarGate Runtime This is part of a StarTeam client installatio
184. derneath confusing patternsets Ant can often not delete a directory which is open in an Explorer window There is nothing we can do about this short of spawning a program to kill the shell before deleting directories 4 6 3 Apple MacOS X MacOS X is the first of the Apple platforms that Ant supports completely it is treated like any other Unix 4 6 4 Novell Netware To give the same level of sophisticated control as Ant s startup scripts on other platforms it was decided to make the main ant startup on NetWare be via a Perl Script runant pl This is found in the bin directory for instance bootstrap bin or dist bin One important item of note is that you need to set up the following to run ant e CLASSPATH put ant jar xerceslmpl jar xml apis jar and any other needed jars on the system classpath e ANT_OPTS On NetWare ANT_OPTS needs to include a parameter of the form envCWD ANT_HOME with ANT_HOME being the fully expanded location of Ant not an environment variable This is due to the fact that the NetWare System Console has no notion of a current working directory It is suggested that you create up an ant ncf that sets up these parameters and calls perl ANT_HOME dist bin runant pl The following is an example of such an NCF file assuming ant is installed in sys apache ant envset CLASSPATH SYS apache ant bootstrap lib ant jar envset CLASSPATH SCLASSPATH SYS ap
185. des are also supported Example Note Contract will use the java compiler indicated by the project s build compiler property See documentation of the Javac task for more information Nested includes and excludes can be done very much the same way as any subclass of MatchingTask lt icontract srcdir build src instrumentdir build instrument repositorydir build repository builddi updatei classdi contro lfile control r build instrclasses control true r S build classes targets targets verbosi quiet gt ty error warning true lt classpath refid compile classpath gt lt icontrac 10 11 Description t gt jarlib available Check whether an extension is present in a fileset or an extensionSet If the extension is present then a property is set 212 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Note that this task works with extensions as defined by the Optional Package specification For more information about optional packages see the document Optional Package Versioning in the documentation bundle for your Java2 Standard Edition package in file o O html or online at http java sun com j2se 1 3 docs quide extensions versioning html See the Extension and ExtensionSet documentation for further details Parameters Attribute Description Required property The name of property to set if Yes extensions is available f
186. destination file Examples lt gzip src test tar zipfile test tar gz gt lt bzip2 src test tar zipfile test tar bz2 gt 9 10 Checksum Description Generates checksum for files This task can also be used to perform checksum verifications Parameters Attribute Description Cd Required file The file to generate checksum for One of either file or at least one nested fileset element algorithm Specifies the algorithm to be used to compute the checksum No Defaults to MD5 Other popular algorithms like SHA may be used as well provider Specifies the provider of the algorithm fileex The generated checksum file s name will be the original filename with No and fileext added to it Defaults to the algorithm name being used property This attribute can mean two different things it depends on the No presence of the verifyproperty attribute If you don t set the verifyproperty attribute property specifies the name of the property to be set with the generated checksum value If you set the verifyproperty attribute property specifies the checksum you expect to be generated the checksum itself not a name of a property containing the checksum This cannot be specified when fileext is being used or when the number of files for which checksums is to be generated is greater than 1 forceoverwrite Overwrite existing files even if the destination files are newer No Defaults to no verifyproperty Specifies the
187. e gt Report the current properties to the file my properties and will log a message if the file could not be created or written to but will still allow the build to continue lt echoproperties prefix java gt 207 305 Ant Manual 1 5 4 12 9 2003 7 47 PM List all properties beginning with java 10 9 FTP Description The ftp task implements a basic FTP client that can send receive list delete files and create directories See below for descriptions and examples of how to perform each task Note This task depends on external libraries not included in the Ant distribution See Library Dependencies for more information The ftp task makes no attempt to determine what file system syntax is required by the remote server and defaults to Unix standards remotedir must be specified in the exact syntax required by the ftp server If the usual Unix conventions are not supported by the server separator can be used to set the file separator that should be used instead See the section on directory based tasks on how the inclusion exclusion of files works and how to write patterns This task does not currently use the proxy information set by the lt setproxy gt task and cannot go through a firewall via socks Warning for the get and delete actions to work properly with a Windows 2000 ftp server it needs to be configured to generate Unix style listings and not the default MS DOS listing Or someone needs to write the
188. e Buildtile esy ereere pea dh e id 27 6 17 Token Filters conoci a e EY 28 6 187 Path like Structure a o ad Bat 28 6 1 9 Command line ArguMentS occcocccccccccnnnnnnnccccnnannnnnc rr n nn rr rr rr eee arar rr rra raras 30 6 1 10 Example rags pace ees MMR re dd do de 30 6 1 11 REA COS A A Aa ee 30 E AS A A E 32 7 1 builds ysclass patria ar ia as 32 7 2 Common Attributes of all TasKS ccc cece cece eee eee eee eee eee ene eens 32 7 3 CORE TY POS iii A cada aids tad eend gia a n 32 LL DESCRIPTION a tS ate A ATE 32 Taa Directory based TaSkS iscsi des goron eurin a 32 7323 DIPS Otis cccueees eke vaneseee e y el Shee ek ea aS i RAD gadis 36 Fis A eae See ate hele HORST bene Pade tained EA ey pune gga etaniadeen 37 A ll O O 38 4 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 7 3 6 Mapping File Names tanisin cece cence eee eee eee eee nese rr rra 39 7 3 7 FilterChains and FilterReaders cece cece cece cece eee e ete eeeeee ee rr nnn cnn nn ra ranas 42 378 FilterRedade weirs centile did ea banned Maharani ke cbatiaad a beamed tales 44 7 359 ExpamdPropertles miii tds de ec 45 7 3 10 He adFilte soc ccaba A A ae 46 7 3 11 aleea aeea coon A ADA uke 46 7 3 12 LineContainsReg xXP 2 penegi due iaeaea OEKE eet rn rr nr rr rn a ee an 47 7 3 13 Prefix LiIMe S iistavicaitene ied staves a A Aa iaa DROSS 47 7 3 14 Replace Sii A SE ane E 47 7 3 15 Strip aVACOMIMENES oeira i EN ias 48 7 3 16 Strip LineBreak S rennan a
189. e version paragraphs all Create class and package usage pages 1 2 Include author paragraphs all Split index into one file per letter 1 2 Browser window title for the documentation 1 2 text Include title for the package index first page 1 2 html code Include header text for each page html code 1 2 Include footer text for each page html code 1 2 Include bottom text for each page html code 1 2 Create links to javadoc output at the given URL 1 2 Link to docs at lt url gt using package list at 1 2 lt url2 gt separate the URLs by using a space character Group specified packages together in overview 11 2 page The format is as described below Do not include deprecated information all Do not generate deprecated list 1 2 Do not generate class hierarchy all Do not generate index all Do not generate help link 1 2 Do not generate navigation bar 1 2 Generate warning about serial tag 1 2 Specifies the HTML help file to use 1 2 Specifies the CSS stylesheet to use 1 2 Charset for cross platform viewing of generated 1 2 documentation Output file encoding name all Specifies the class file that starts the doclet 1 2 used in generating the documentation Specifies the path to the doclet class file that is 1 2 specified with the doclet option Specifies the path to the doclet class file that is 1 2 specified with the doclet option by reference to a PATH defined elsewhere Lets you add addition
190. e The base name that is used for the generated jar files If this No attribute is specified the generic jar file name will use this value as the prefix followed by the value specified in the genericjarsuffix attribute and the resultant ejb jar file followed by any suffix specified in the nested element basenameterminator String value used to substring out a string from the name of each No defaults deployment descriptor found which is then used to locate related to deployment descriptors e g the WebLogic descriptors For example a basename of and a deployment descriptor called FooBean ejb jar xml would result in a basename of FooBean which would then be used to find FooBean weblogic ejb jar xml and FooBean weblogic cmp rdbms jar xml as well as to create the filenames of the jar files as FooBean generic jar and FooBean wl jar This attribute is not used if the basejarname attribute is specified genericjarsuffix String value appended to the basename of the deployment No defaults descriptor to create the filename of the generic EJB jar file to generic jar classpath This classpath is used when resolving classes which are to be No added to the jar Typically nested deployment tool elements will also support a classpath which will be combined with this classpath when resolving classes flatdestdir Set this attribute to true if you want all generated jars to be No placed in the root of the destdir rather than
191. e following picture C gt Options General El Appearance Lists Source Dialog Banner Printer E Coding El Help El Resources RMI Registry El Visual Composition IDL toJawa Compile Remote Access To Tool API rent mnang tHe STAEN TE AA ar Now you should be able to execute VAJ Tasks from the command line Usage Plugin When the tool is installed correctly and your Ant build file is configured it is really easy to use 289 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Go to your Workbench select the project you want to deploy and open its context menu In the submenu Tools you should find the new entry Ant Build Klick it to start the tool AA Attribute Filters File Edit Workspace Import Esport Replace With Delete Reorganize 7 hot l Manage gt ae t Build 69 deploy 09 Compare with malin Enterprise Access Builder gt El rc gt Make Run M ET 390 gt a mi Document gt oo Servlet Launcher Tools WebLogic Server Tools Bova After a short time this frame should pop up fey Ant VisualAge for Java Tool Integration File Help Projectname Ant Ant Buildfile CATEMPibuild xml Ej Target r Y daninw iawadnr z Message Level info Re Load Execute Er Close This frame contains the following elements e A menubar with some options described later e The name of your selec
192. e instructions actually do exactly the same as the ant command The options and target are the same as when running Ant with the ant command This example assumes you have set your classpath to include e ant jar e jars classes for your XML parser e the JDK s required jar zip files 23 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 6 Using Ant 6 1 Writing a Simple Buildfile Ant s buildfiles are written in XML Each buildfile contains one project and at least one default target Targets contain task elements Each task element of the buildfile can have an id attribute and can later be referred to by the value supplied to this The value has to be unique For additional information see the Tasks section below 6 1 1 Projects A project has three attributes Attribute Description Required name the name of the project No default the default target to use when no target is supplied Yes basedir the base directory from which all path calculations are done This attribute might No be overridden by setting the basedir property beforehand When this is done it must be omitted in the project tag If neither the attribute nor the property have been set the parent directory of the buildfile will be used Optionally a description for the project can be provided as a top level lt description gt element see the description type Each project defines one or more targets A target is a set of tasks you want to be executed When starti
193. e of this file is taken to be an include pattern No excludes comma or space separated list of patterns of files that must be No excluded No files except default excludes are excluded when omitted excludesfile the name of a file Each line of this file is taken to be an exclude pattern No defaultexcludes indicates whether default excludes should be used or not yes no No Default excludes are used when omitted manifest the manifest file to use This can be either the location of a manifest or No the name of a jar added through a fileset If its the name of an added jar the task expects the manifest to be in the jar at META INF MANIFEST MF update indicates whether to update or overwrite the destination file if it already No exists Default is false whenempty behavior when no files match Valid values are fail skip and create No Default is skip duplicate behavior when a duplicate file is found Valid values are add No preserve and fail The default value is add index whether to create an index list to speed up classloading This is a JDK No 1 3 specific feature Defaults to false manifestencoding The encoding used to read the JAR manifest when a manifest file is No specified Defaults to the platform encoding Nested elements metainf 116 305 Ant Manual 1 5 4 12 9 2003 7 47 PM The nested metainf element specifies a FileSet All files included in this fileset will end up in the META INF dire
194. e under which your J SP s would be compiled Yes classpath Class path to use when compiling jsp s Yes A classpath should be set which contains the weblogic classes as well as all application classes referenced by the JSP The system classpath is also appended when the jspc is called so you may choose to put everything in the classpath while calling Ant However since presumably the J SP s will reference classes being build by Ant it would be better to explicitly add the classpath in the task The task checks timestamps on the J SP s and the generated classes and compiles only those files that have changed It follows the weblogic naming convention of putting classes in _dirName _fileName class for dirname fileName jsp Example lt target name jspcompile depends compile gt lt wljspe src c weblogic myserver public_html dest c weblogic myserver serverclasses package myapp jsp gt lt classpath gt lt pathelement location weblogic classpath gt lt pathelement path compile dest gt lt classpath gt lt wljspe gt lt target gt Limitations e This works only on weblogic 4 5 1 e It compiles the files thru the Classic compiler only e Since it is my experience that weblogic jspc throws out of memory error on being given too many files at one go it is called multiple times with one jsp file each 299 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 10 50 XMLValidate Description This task checks xml f
195. e used Attribute Description Required value line Exactly See Command line Arguments one of file these path compiler Only pass the specified argument if the chosen compiler implementation matches the value of this attribute Legal values are the same as those in the No above list of valid compilers Examples lt javac srcdir S src destdir build classpath xyz jar debug on gt compiles all java files under the src directory and stores the class files in the build directory The classpath used includes xyz jar and compiling with debug information is on lt javac srcdir S src destdir build fork true gt 123 305 Ant Manual 1 5 4 12 9 2003 7 47 PM compiles all java files under the src directory and stores the class files in the build directory This will fork off the javac compiler using the default javac executable lt javac srcdir src destdir S build fork Java Sjavac exe gt compiles all java files under the src directory and stores the class files in the build directory This will fork off the javac compiler using the executable named javaSjavac exe Note that the sign needs to be escaped by a second one lt javac srcdir srce destdir S build includes mypackage p1 mypackage p2 excludes mypackage pl testpackage classpath xyz jar debug on gt compiles java files under the src directory and sto
196. e useful if you are going to replicate the same snippet of XML over and over again using a lt classpath gt structure more than once for example The following example lt project gt lt target gt LEME ei lt classpath gt lt pathelement location 1lib gt lt pathelement path S java class path gt lt pathelement path S additional path gt lt classpath gt lt rmic gt lt target gt lt target gt lt javac gt 30 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt classpath gt lt pathelement location lib gt lt pathelement path S java class path gt lt pathelement path S additional path gt lt classpath gt lt javac gt lt target gt lt project gt could be rewritten as lt project gt lt path id project class path gt lt pathelement location lib gt lt pathelement path java class path gt lt pathelement path S additional path gt lt path gt lt EAEJET sisi gt LEMIC is lt classpath refid project class path gt lt rmic gt lt target gt lt arge iar gt lt javac gt lt classpath refid project class path gt lt javac gt lt target gt lt project gt All tasks that use nested elements for PatternSets FileSets or path like structures accept references to these structures as well 31 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 7 Concepts 7 1 build sysclasspath The value
197. earch for an AS specific EJB descriptor file named ejb Account ias ejb jar xml if it isn t found the task will fail and a JAR file named ejb Account jar will be written in the destination directory Note that when the EJB descriptors are added to the JAR file they are automatically renamed META INF ejb jar xml and META INF ias ejb jar xml Of course this naming behaviour can be modified by specifying attributes in the ejbjar task for example basejarname basenameterminator and flatdestdir as well as the iplanet element for example suffix Refer to the appropriate documentation for more details Parameters Attribute Description Required destdir The base directory into which the generated JAR files will be written Each Yes J AR file is written in directories which correspond to their location within the descriptordir namespace classpath The classpath used when generating EJ B stubsand skeletons If omitted No the classpath specified in the ejbjar parent task will be used If specified the classpath elements will be prepended to the classpath specified in the parent ejbjar task Note that nested classpath elements may also be used keepgenerated I ndicates whether or not the J ava source files which are generated by ejbc No will be saved or automatically deleted If yes the source files will be retained If omitted it defaults to no debug Indicates whether or not the ejbc utility should log additional debuggin
198. ect of this is that you will not be able to delete or move those files later on in the build The workaround is to fork when invoking the compiler Parameters Attribute Description Required srcdir Location of the java files See the note below Yes unless nested lt src gt elements are present destdir Location to store the class files No includes Comma or space separated list of files may be specified using No wildcard patterns that must be included all java files are included when omitted includesfile The name of a file that contains a list of files to include may be No specified using wildcard patterns excludes Comma or space separated list of files may be specified using No wildcard patterns that must be excluded no files except default excludes are excluded when omitted excludesfile The name of a file that contains a list of files to exclude may No be specified using wildcard pattems classpath The classpath to use No sourcepath The sourcepath to use defaults to the value of the srcdir No attribute or nested lt src gt elements To suppress the sourcepath switch use sourcepath bootclasspath Location of bootstrap class files No classpathref The classpath to use given as a reference to a path defined No elsewhere sourcepathref The sourcepath to use given as a reference to a path defined No 121 305 Ant Manual 1 5 4 bootclasspathref extdirs encoding nowarn debug debuglevel optimize
199. ecthelp invocation option to list them as public targets with the descriptions the other target is internal and not listed Finally for this target to work the source in the src subdirectory should be stored in a directory tree which matches the package names Check the lt javac gt task for details 6 1 7 Token Filters A project can have a set of tokens that might be automatically expanded if found when a file is copied when the filtering copy behavior is selected in the tasks that support this These might be set in the buildfile by the filter task Since this can potentially be a very harmful behavior the tokens in the files must be of the form etokene where token is the token name that is set in the lt filter gt task This token syntax matches the syntax of other build systems that perform such filtering and remains sufficiently orthogonal to most programming and scripting languages as well as with documentation systems Note If a token with the format etokene is found in a file but no filter is associated with that token no changes take place therefore no escaping method is available but as long as you choose appropriate names for your tokens this should not cause problems Warning If you copy binary files with filtering turned on you can corrupt the files This feature should be used with text files only 6 1 8 Path like Structures You can specify PATH and CLASSPATH type references using both and as separat
200. ectory creation wu ftp in particular Default false skipFailedTransfers flag which enables unsuccessful file put delete and get operations tcNo be skipped with a warning and the remainder of the files still transferred Default false 10 9 1 Sending Files The easiest way to describe how to send files is with a couple of examples lt ftp server ftp apache org userid anonymous password me myorg com gt lt fileset dir htdocs manual gt lt ftp gt Logs in to ftp apache org aS anonymous and uploads all files in the htdocs manual directory to the default directory for that user lt ftp server ftp apache org remotedir incoming userid anonymous password me myorg com depends yes gt lt fileset dir htdocs manual gt lt j tip gt Logs in to ftp apache org aS anonymous and uploads all new or changed files in the htdocs manual directory to the incoming directory relative to the default directory for anonymous lt ftp server ftp apache org port 2121 remotedir pub incoming userid coder password Javal depends yes binary no lt fileset dir htdocs manual gt lt include name html gt lt fileset gt lt ftp gt Logs in to ftp apache org at port 2121 as coder with password javal and uploads all new or changed HTML files in the htdocs manual directory to the pub incoming directory The files are transferred in text mode Passive mode has been switched on to send files f
201. ecute cvs exe from the command line in the target directory in which you are working Parameters 98 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Attribute Description Required startTag The earliest tag from which diffs are to be included in the report exactly one of the two startDate The earliest date from which diffs are to be included in the report endTag The latest tag from which diffs are to be included in the report exactly one of the two endDate The latest date from which diffs are to be included in the report destfile The file in which to write the diff report Yes rootdir Root directory for the package if different from the package name No Parameters inherited from the cvs task Attribute Description Required compression true false or the number 1 9 corresponding to No Defaults to no compression if possible values for CVS z argument Any other passed true level 3 compression is value is treated as false assumed cvsRoot the CVSROOT variable No cvsRsh the CVS_RSH variable No package the package module to analyze Yes quiet suppress informational messages No default false port Port used by CVS to communicate with the server No default port 2401 passfile Password file to read passwords from No default file cvspass failonerror Stop the buildprocess if the command exits with a No returncode other than 0 Defaults to false Examples lt cvstagdiff cvsRoot pserver anoncvs cvs apache or
202. ed No No files except default excludes are excluded when omitted the name of a file Each line of this file is taken to be an exclude pattern No indicates whether default excludes should be used or not yes no No Default excludes are used when omitted Specifies how end of line EOL characters are to be handled The EOL No characters are CR LF and the pair CRLF Valid values for this property are asis leave EOL characters alone cr convert all EOLs to a single CR If convert all EOLs to a single LF crif convert all EOLs to the pair CRLF Default is based on the platform on which you are running this task For Unix platforms the default is If For DOS based systems including Windows the default is crlf For Mac OS the default is cr This is the preferred method for specifying EOL The cr attribute see below is now deprecated N B One special case is recognized The three characters CR CR LF are regarded as a single EOL Unless this property is specified as asis this sequence will be converted into the specified EOL type Deprecated Specifies how CR characters are to be handled at end of line No EOL Valid values for this property are asis leave EOL characters alone add add a CR before any single LF characters The intent is to convert all EOLs to the pair CRLF remove remove all CRs from the file The intent is to convert all EOLs to a single LF Default is based on the platform on which y
203. ed E g group XSLT_Packages org apache xalan xslt XPath_Packages org apache xalan xpath Parameters specified as nested elements Parameter Description 1 packageset A DirSet All matched directories that contain Java source files will be passed to javadoc as package names Package names are created from the directory names by translating the directory separator into dots Ant assumes the base directory of the packageset points to the root of a package hierarchy The packagenames excludepackagenames and defaultexcludes attributes of the task have no effect on the nested lt packageset gt elements 2 fileset A FileSet All matched files will be passed to javadoc as source files Ant will automatically add the include pattern java to these filesets Nested filesets can be used to document sources that are in the default package or if you want to exclude certain files from documentation If you want to document all source files and don t use the default package packagesets should be used instead as this increases javadocs performance The packagenames excludepackagenames and defaultexcludes attributes of the task have no effect on the nested lt fileset gt elements 3 package Same as one entry in the list given by packagenames Parameters Attribute Description Required name The package name may be a wildcard Yes iad nica Same as one entry in the list given by excludepackagenames Parameters Same as for package 5
204. ed this just select About in the Help menu Servlets for Remote Tool Access With the servlets installed and the remote access running you can use Ant from the command line without any restrictions Just make sure the remote attribute in your build file is set correctly 10 47 8 Frequently Asked Questions Q If try to load a build file get the error Can t load default task list Why A Ant not only contains class files but also resource files This messsage appears if the file org apache tools ant taskdefs defaults properties is missing Make sure that you import export not only java class files but also all resource files when importing exporting Ant Q If try to re load a build file get the error XML parser factory has not been configured correctly Why A Make sure the META INF services directory of the xercesImpl jar has also been expanded into the c IBMVJava ide tools org apache tools ant directory Q want to load export and build more then one Visual Age project to one jar How to A The VA tasks are able to load and export several Projects all at once You can choose whatever project you like for storing the tool information it doesn t really matter Q When I load my build file the list of targets is empty Why A You need to add the optional description parameter to the targets you want to come up in the list Then reload the build file in the ant build tool We chose to display only target
205. ed with lt package gt s given The title may be specified as a nested lt title gt element with text contents and the packages may be listed with nested lt package gt elements as for the main task 12 doclet The doclet nested element is used to specify the doclet that javadoc will use to process the input source files A number of the standard javadoc arguments are actually arguments of the standard doclet If these are specified in the javadoc task s attributes they will be passed to the doclet specified in the lt doclet gt nested element Such attributes should only be specified therefore if they can be interpreted by the doclet in use If the doclet requires additional parameters these can be specified with lt param gt elements within the lt doclet gt element These paramaters are restricted to simple strings An example usage of the doclet element is shown below lt javadoc gt lt doclet name theDoclet path path to theDoclet gt lt param name foo value foovalue gt lt param name bar value barvalue gt lt doclet gt lt javadoc gt The tag nested element is used to specify custom tags This option is only available with Java 1 4 Parameters Attribute Description Required name Name of the tag e g todo Yes description Description for tag e g To do Yes 129 305 Ant Manual 1 5 4 12 9 2003 7 47 PM scope Scope for the tag the elements in which it can be No used This is a com
206. eet this can be a relative or absolute file path or an http URL If you set the property to the empty string no XSLT transform is declared at all ant listener org apache tools ant XmlLogger ant logger org apache tools ant XmlLogger verbos logfile build_log xml 11 3 Writing your own See the Build Events section for developers Notes e A listener or logger should not write to standard output or error Ant captures these internally and may cause an infinite loop 305 305
207. efault library e ae progress messages on off default Example lt ilasm includesfile he name of a file Each line of this file is taken to be an include pattern outputFile app exe verbose on listing on owner secret gt 10 1 3 lt WsdlToDotnet gt Why add a wrapper to the MS WSDL tool So that you can verify that your web services be they written with Axis or anyone else s SOAP toolkit work with NET clients This task is dependency aware when using a file as a source and destination so if you lt get gt the file with usetimestamp true then you only rebuild stuff when the WSDL file is changed Of course if the server generates a new timestamp every time you ask for the WSDL this is not enough use the lt filesmatch gt lt condition gt to to byte for byte comparison against a cached WSDL file then make the target conditional on that test failing Attribute Description Example destFile name of file to generate Required ApacheNet cs srcFile name of WSDL file to use Required if url is not set service wsdl url url to retrive WSDL from required if srcFile is unset http localhost service wsdl server generate server stubs not client proxy code optional false default default false namespace namespace to place the source in optional default Apache Net language language one of CS JS or VB optional CS default failOnError Should failure halt the build true default
208. efinition from another FilterSet with a refid attribute It is also possible to nest filtersets into filtersets to get a set union of the contained filters In addition FilterSets can specify begintoken and or endtoken attributes to define what to match Filtersets are used for doing replacements in tasks such as lt copy gt etc Filterset Attribute Description Default Required begintoken The string marking the beginning of a token eg DATE No endtoken The string marking the end of a token eg DATE o No Filter Attribute Description Required token The token to replace eg DATE Yes value The value to replace it with eg Thursday April 26 2001 Yes Filtersfile Attribute Description Required file A properties file of name value pairs from which to load the tokens Yes Examples You are copying the version txt file to the dist directory from the build directory but wish to replace the token DATE with today s date lt copy file S build dir version txt toFile dist dir version txt gt lt filterset gt lt filter token DATE value TODAY gt lt filterset gt lt copy gt You are copying the version txt file to the dist directory from the build directory but wish to replace the token DATE with today s date 51 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt copy file S build dir version txt toFile dist dir version txt gt lt filterset begintoken e
209. elements fileset The cab task supports any number of nested lt fileset gt elements to specify the files to be included in the archive Examples lt cab cabfile dist manual cab basedir htdocs manual gt cabs all files in the htdocs manual directory into a file called manual cab in the dist directory lt cab cabfile dist manual cab basedir htdocs manual excludes mydocs todo html gt cabs all files in the htdocs manual directory into a file called manual cab in the dist directory Files in the directory mydocs or files with the name todo html are excluded lt cab cabfile dist manual cab basedir htdocs manual includes api html excludes todo html verbose yes gt Cab all files in the htdocs manual directory into a file called manual cab in the dist directory Only html files under the directory api are archived and files with the name todo html are excluded Output from the cabarc tool is displayed in the build output 10 4 ClearCase Support 10 4 1 CCCheckin Description Task to perform a Checkin command to ClearCase Parameters Attribute Values Required viewpath Path to the ClearCase view file or directory that the command will operate on No comment Specify a comment Only one of comment or commentfile may be used No commenti Specify a file containing a comment Only one of comment or commentfile No may be used nowarn Suppress warning messages No pres
210. ence to a PATH defined elsewhere Override location of class files loaded by the bootstrap class loader by reference to a PATH defined elsewhere Override location of installed extensions Read overview documentation from HTML file Access mode one of public protected package or private Show only public classes and members Show protected public classes and members default Show package protected public classes and members Show all classes and members Generate output using JDK 1 1 emulating 126 305 Availability Required all all all all all a 1 2 all 1 2 all 1 2 1 2 1 2 all all all all all 1 2 At least one of the three or nested lt sourcepath gt lt fileset gt or lt packageset gt Yes unless a doclet has been specified No No No No No No No No No No default protected No No No No No Ant Manual 1 5 4 Verbose Locale Encoding Version Use Author Splitindex Windowtitle Doctitle Header Footer bottom link linkoffline group nodeprecated nodeprecatedlist notree noindex nohelp nonavbar serialwarn helpfile stylesheetfile charset docencoding doclet docletpath docletpathref additionalparam failonerror excludepackagenames defaultexcludes doclet Output messages about what Javadoc is doing 1 2 Locale to be used e g en_US oren_US_WIN 1 2 Source file encoding name all Includ
211. entation is generated Yes The user can also specify the nested lt classpath gt element which defines classpath in which the task is executed 280 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Examples lt stylebook targetdirectory build docs book src xdocs book xml skindirectory src skins myskin gt The above will generate documentation in build docs starting from the book src xdocs book xml and using the skin located in directory src skins myskin 10 44 Telnet Description Task to automate a remote telnet session The task uses nested lt read gt to indicate strings to wait for and lt write gt tags to specify text to send If you do specify a userid and password the system will assume a common unix prompt to wait on This behavior can be easily over ridden Note This task depends on external libraries not included in the Ant distribution See Library Dependencies for more information Parameters Attribute Values Required userid the login id to use on the telnet server Only ii password is specified password the login password to use on the telnet server Only if userid is specified server the address of the remote telnet server Yes port the port number of the remote telnet server Defaults to port 23 No initialCR send a cr after connecting yes Defaults to no No timeo t set a default timeout to wait for a response Specified in seconds No Default is no timeout Nested Elements The commands t
212. er be a file or a resource Yes 196 305 Ant Manual 1 5 4 12 9 2003 7 47 PM loadable from the classpath support The lt support gt nested element is used to supply additional classes files to be included in the generated jars The lt support gt element is a FileSet so it can either reference a fileset declared elsewhere or it can be defined in place with the appropriate lt include gt and lt exclude gt nested elements The files in the support fileset are added into the generated EJB jar in the same relative location as their location within the support fileset Note that when ejbjar generates more than one jar file the support files are added to each one 10 7 3 Vendor specific deployment elements Each vendor specific nested element controls the generation of a deployable jar specific to that vendor s EJB container The parameters for each supported deployment element are detailed here 10 7 3 1J BOSS ELEMENT The jboss element searches for the J Boss specific deployment descriptors and adds them to the final ejb jar file JBoss has two deployment descriptors jboss xml and jaws xml for container manager persistence only The JBoss server uses hot deployment and does not require compilation of additional stubs and skeletons Attribute Description Required destdir The base directory into which the generated weblogic ready jar files Yes are deposited J ar files are deposited in directories corresponding to their location within
213. er will be attempted in specified order until library is found or no resolvers are left If no resolvers are left and failOnError is true then a BuildException will be thrown Note that this task works with extensions as defined by the Optional Package specification For more information about optional packages see the document Optional Package Versioning in the documentation bundle for your Java2 Standard Edition package in file o o eee html or online at http j ava sun com 2se 1 3 docs quide extensions versioning html 216 305 Ant Manual 1 5 4 12 9 2003 7 47 PM See the Extension and ExtensionSet documentation for further details Parameters Attribute Description Required property The name of property to set to library location Yes failOnError True if failure to locate library should result in build exception No defaults to true checkExte nsion True if librarys returned by nested resolvers should be checked to No defaults to see if they supply extension true Parameters specified as nested elements extension Extension the extension to resolve Must be present location The location sub element allows you to look for a library in a location relative to project directory Attribute Description Required location The pathname of library Yes url The url resolver allows you to download a library from a URL to a local file Attribute Description Required url The URL to download Yes destfile The file to download U
214. erence a global properties file for all of your Ant builds using the following lt property file user home ant global properties gt since the user home property is defined by the Java virtual machine to be your home directory This technique is more appropriate for Unix than Windows since the notion of a home directory doesn t exist on Windows On the JVM that tested the home directory on Windows is C Different JVM implementations may use other values for the home directory on Windows lt property environment env gt lt echo message Number of Processors env NUMBER_OF_PROCESSORS gt lt echo message ANT_HOME is set to env ANT_HOME gt reads the system environment variables and stores them in properties prefixed with env Note that this only works on select operating systems Two of the values are shown being echoed 9 50 Record Description A recorder is a listener to the current build process that records the output to a file Several recorders can exist at the same time Each recorder is associated with a file The filename is used as a unique identifier for the recorders The first call to the recorder task with an unused filename will create a recorder using the parameters provided and add it to the listeners of the build All subsequent calls to the recorder task using this filename will modify that recorders state recording or not or other properties like logging level
215. ervetime Preserve the modification time No keepcopy Keeps a copy of the file with a keep extension No identical Allows the file to be checked in even if it is identical to the original No 181 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Examples lt cccheckin viewpath c views viewdir afile comment file acomment txt nowarn true identical true gt Does a ClearCase checkin on the file c views viewdir afile Comment text from the file acomment txt is added to ClearCase as a comment All warning messages are suppressed The file is checked in even if it is identical to the original 10 4 2 CCCheckout Description Task to perform a Checkout command to ClearCase Parameters Attribute Values Required viewpath Path to the ClearCase view file or directory that the command will operate on No reserved Specifies whether to check out the file as reserved or not Yes out Creates a writable file under a different filename No nodata Checks out the file but does not create an editable file containing its data No branch Specify a branch to check out the file to No version Allows checkout of a version other than main latest No nowarn Suppress warning messages No comment Specify a comment Only one of comment or commentfile may be used No commenttile eng file containing a comment Only one of comment or commentfile may No Examples lt cccheckout viewpath c views viewdir afile reserved true branch abranch nowarn true comment Some
216. es No strip Strip the smallest prefix containing num leading No slashes from filenames dir The directory in which to run the patch command No default is the project s basedir Examples lt patch patchfile module 1 0 1 1 patch gt applies the diff included in module 1 0 1 1 patch to the files in base directory guessing the filename s from the diff output lt patch patchfile module 1 0 1 1 patch strip 1 gt like above but one leading directory part will be removed i e if the diff output looked like a mod1 0 A Mon Jun 5 17 28 41 2000 a mod1 1 A Mon Jun 5 17 28 49 2000 the leading a will be stripped 9 48 Pathconvert Description 139 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Converts a nested lt path gt or reference to a Path FileSet DirSet or FileList into a path form for a particular platform and stores the result in a given property It can also be used when you need to convert a Path FileSet or DirSet into a list separated by a given character such as acomma or space or conversely to convert a list of files in a FileList into a path Nested lt map gt elements can be specified to map Windows drive letters to Unix paths and vice versa Parameters Attribute Description Required targetos The target archite cture Must be one of unix windows Yes unless pathsep and or netware or os 2 This is a shorthand mechanism for dirsep are specified specifying both pathsep and dirsep accordi
217. es The output of JTree is run through J avaCC to create the parser This task only invokes JJ Tree if the grammar file is newer than the generated J avaCC file MParse i nvokes the Metamata MParse compiler compiler on a grammar file Native2Ascii Converts files from native encodings to ASCII with escaped Unicode A common usage is to convert source files maintained in a native operating system encoding to ASCII prior to compilation Translate Identifies keys in files delimited by special tokens and translates them with values read from resource bundles Xslt Style Processes a set of documents via XSLT 8 1 15 Property Tasks Task Name Descriptin Available Sets a property if a specified file directory class in the classpath or JVM system resource is available at runtime Basename Sets a property to the last element of a specified path BuildNumber Task that can be used to track build numbers Condition Sets a property if a certain condition holds true this is a generalization of Available and Uptodate Dirname Sets a property to the value of the specified file up to but not including the last path me o lLoadProperties Load a file s contents as Ant properties This task is equivalent to using lt property file gt except that it supports nested lt filterchain gt elements and it cannot be 71 305 Ant Manual 1 5 4 12 9 2003 7 47 PM specified outside a target PathConvert Converts a neste
218. es these changes into the file changelog xml lt cvschangelog dir dve network destfile changelog xml start 20 Feb 2002 end 20 Mar 2002 gt Generates a change log report for any changes that were made between February 20 2002 and March 20 2002 under the dve network directory It writes these changes into the file changelog xml lt cvschangelog dir dve network dest file changelog xml start 20 Feb 2002 gt Generates a change log report for any changes that were made after February 20 2002 under the dve network directory It writes these changes into the file changelog xml lt cvschangelog dir dve network destfile changelog xml gt lt user displayname Peter Donald userid donaldp gt lt cvschangelog gt Generates a change log report for all the changes that were made under the dve network directory substituting the name Peter Donald in the lt author gt tags anytime it encounters a change made by the user ID donaldp It writes these changes into the file changelog xml Generate Report Ant includes a basic XSLT stylesheet that you can use to generate a HTML report based on the xml output The following example illustrates how to generate a HTML report from the XML report 97 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt style in changelog xml out changelog html style S ant home etc changelog xsl gt lt param name title expression Ant ChangeLog gt lt pa
219. esfile explicit format includes includesfile java keep logo replace savelog Description Required Whether literals are treated as the java binary type No rather than the NetRexx types The classpath to use during compilation No Whether comments are passed through to the generated No java source Whether error messages come out in compact or No verbose format Default is the compact format Whether the NetRexx compiler should compile the No generated java code Whether or not messages should be displayed on the No console Whether variable cross references are generated No Whether decimal arithmetic should be used for the No NetRexx code indicates whether default excludes should be used or not No yes no Default excludes are used when omitted the destination directory into which the NetRexx source Yes files should be copied and then compiled Whether diagnostic information about the compile is No generated comma or space separated list of patterns of files that No must be excluded No files except d efault excludes are excluded when omitted the name of a file Each line of this file is taken to be an No exclude pattern Whether variables must be declared explicitly before use No Whether the generated java code is formatted nicely or No left to match NetRexx line numbers for call stack debugging comma or space separated list of patterns of files that No must be included All files are included whe
220. esources_de In addition to language country and variant are also used to form the files in the bundle The resource bundle lookup searches for resource files with various suffixes on the basis of 1 the desired locale and 2 the default locale basebundlename in the following order from lower level more specific to parent level less specific basebundlename _ languagel _ countryl _ variantl basebundlename _ languagel _ countryl basebundlename _ languagel basebundlename basebundlename _ language2 _ country2 _ variant2 basebundlename _ language2 _ country2 basebundlename _ language2 The file names generated thus are appended with the string properties to make up the file names that are to be used File encoding is supported The encoding scheme of the source files destination files and the bundle files can be specified Destination files can be exlicitly overwritten using the forceoverwrite attribute If forceoverwrite is false the destination file is overwritten only if 283 305 Ant Manual 1 5 4 12 9 2003 7 47 PM either the source file or any of the files that make up the bundle have been modified after the destination file was last modified FileSets are used to select files to translate Parameters Attribute Description Required todir Destination directory where destination files are to be created Yes startt
221. ess Only read this file if the named property is not set No patternset Patternsets may be nested within one another adding the nested patterns to the parent patternset Examples lt patternset id non test sources gt lt include name java gt lt exclude name Test gt lt patternset gt Builds a set of patterns that matches all java files that do not contain the text Test in their name This set can be referred to via lt patternset refid non test sources gt by tasks that support this feature or by FileSets Note that while the includes and excludes attributes accept multiple elements separated by commas or spaces the nested lt include gt and lt exclude gt elements expect their name attribute to hold a single pattern The nested elements allow you to use if and unless arguments to specify that the element should only be used if a property is set or that it should be used only if a property is not set For example lt patternset id sources gt lt include name std java gt lt include name prof java if professional gt lt exclude name Test gt lt patternset gt will only include the files in the sub directory prof if the property professional is set to some value The two sets 53 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt patternset includesfile some file gt and lt patternset gt lt includesfile name some file gt
222. ess messages to Yes if success mail is to gger i comma separated be sent MailLogger failure subject Subject of failed build No default Build Failure MailLogger success subjectiSubject of successful build No deraut mug Success F Filename of properties file that will override MailLogger properties file othervalies No ant logger org apache tools ant listener MailLogger 11 2 4 AnsiColorLogger The AnsiColorLogger adds color to the standard Ant output by prefixing and suffixing ANSI color code escape sequences to it It is just an extension of DefaultLogger and hence provides all features that DefaultLogger does AnsiColorLogger differentiates the output by assigning different colors depending upon the type of the message If used with the logfile option the output file will contain all the necessary escape codes to display the text in colorized mode when displayed in the console using applications like cat more etc This is designed to work on terminals that support ANSI color codes It works on XTerm ETerm Win9x Console with ANSI SYS loaded etc NOTE It doesn t work on WinNT even when a COMMAND COM console loaded with ANSI SYS is used If the user wishes to override the default colors with custom ones a file containing zero or more of the custom color key value pairs must be created The recognized keys and their default values are shown below AnsiColorLogger ERROR_COLOR 2 31 AnsiColorLogger WAR
223. estdir S assemble ejbjar iashome S ias home debug yes keepgenerated yes gt lt classpath gt lt pathelement path gt lt pathelement path build classpath gt lt classpath gt lt iplanet gt lt include name ejb jar xml gt lt exclude name ias xml gt lt ejbjar gt This example demonstrates the use of basejarname attribute In this case the completed EJ B J AR will be named HelloWorld jar If multiple EJB descriptors might be found care must be taken to ensure that the completed JAR files don t overwrite each other lt ejbjar srcdir S build classesdir descriptordir src basejarname HelloWorld gt lt iplanet destdir S assemble ejbjar classpath S ias ejbc cpath gt lt include name eJb jar xml gt lt exclude name ias xml gt lt ejbjar gt 204 305 Ant Manual 1 5 4 12 9 2003 7 47 PM This example demonstrates the use of the dtd nested element If the local copies of the DTDs are included in the classpath they will be automatically referenced without the nested elements In AS 6 0 SP2 these local DTDs are found in the iAS install directory APPS directory In iAS 6 0 SP3 these local DTDs are found in the iAS install directory dtd directory lt ejbjar srcdir S build classesdir descriptordir S src gt lt iplanet destdir S assemble ejbjar gt classpath S ias ejbc cpath gt lt include name
224. estination file or when the destination file does not exist Parameters Attribute Description O O Z o o Required he filename of the file to copy he filename of the file where to copy to me whether token filtering should take place during the copy orceoverwriteloverwrite existing files even if the destination files are newer default is alse Examples lt copyfile src test java dest subdir test java gt lt copyfile src src index html dest dist help index html gt 9 17 Cvs Description Handles packages modules retrieved from a CVS repository When doing automated builds the get task should be preferred over the checkout command because of speed Important This task needs cvs on the path If it isn t you will get an error such as error 2 on windows If lt cvs gt doesn t work try to execute cvs exe from the command line in the target directory in which you are working Parameters Attribute Description Cds Required command the CVS command to execute No default checkout compression true or false if set to true this is the same as No Defaults to compressionlevel 3 false compressionlevela number between 1 and 9 corresponding to possible values for No Defaults to 94 305 Ant Manual 1 5 4 12 9 2003 7 47 PM A Pe z argument Any other value is treated as compression false evsRoot_____ the CVSROOT variable cvsRsh__ theCVS RSH variable O i director
225. et that can be referenced in other lt fileset gt elements rooted at a different directory lt fileset dir client src gt lt patternset refid non test sources gt lt fileset gt Groups all files in directory client src using the same patterns as the above example lt fileset dir S server src casesensitive yes gt lt filename name Jjava gt lt filename name Test negate true gt lt fileset gt Groups the same files as the top example but using the lt filename gt selector lt fileset dir S server src casesensitive yes gt lt filename name java gt lt not gt lt filename name Test gt lt not gt lt fileset gt Groups the same files as the previous example using a combination of the lt filename gt selector and the lt not gt selector container 7 3 6 Mapping File Names Some tasks take source files and create target files Depending on the task it may be quite obvious which name a target file will have using javac you know there will be class files for your java files in other cases you may want to specify the target files either to help Ant or to get an extra bit of functionality While source files are usually specified as filesets you don t specify target files directly instead you tell Ant how to find the target file s for one source file An instance of org apache tools ant util FileNameMapper is responsible for this
226. except default excludes are excluded when omitted excludesfile the name of a file Each line of this file is taken to be an No exclude pattern defaultexcludes indicates whether default excludes should be used or not No yes no Default excludes are used when omitted in specifies a single XML document to be styled Should be used No with the out attribute out specifies the output name for the styled result from the in No attribute scanincludeddirectories If any directories are matched by the includes excludes No patterns try to transform all files in these directories Default is true reloadstylesheet Control whether the stylesheet transformer is created anew for No every transform opertaion If you set this to true performance may suffer but you may work around a bug in certain Xalan versions Default is false Since Ant 1 5 2 Parameters specified as nested elements classpath The classpath to load the processor from can be specified via a nested lt classpath gt as well that is a path like structure xmlcatalog The xmlcatalog element is used to perform Entity and URI resolution param Param is used to pass a parameter to the XSL stylesheet Parameters Attribute Description Required name Name of the XSL parameter Yes expression XSL expression to be placed into the param To pass a text value into the style Yes sheet it needs to be escaped using single quotes outputproperty trax processors only
227. exe resides By default the task expects it to be in the PATH No serverPath directory where srssafe ini resides No Examples lt vsscp vsspath Projects ant gt Sets the current VSS project to Projects ant 10 48 10 VssCreate Description Task to perform CREATE commands to Microsoft Visual Source Safe Creates a new project in VSS Parameters Attribute Values Required login username password No vsspath SourceSafe path of project to be created Yes directory where ss exe resides By default the task expects it to be in the ssdir No PATH quiet suppress output off by default No failOnError fail if there is an error creating the project true by default No 298 305 Ant Manual 1 5 4 12 9 2003 7 47 PM What to respond with sets the I option By default I is used values of Y Antares panee or N will be appended to this No comment The comment to use for this label Empty or for no comment No Examples lt vsscreate vsspath existingProject newProject gt Creates the VSS Project existingProject newProject 10 49 wljspc Description Class to precompile J SP s using weblogic s jsp compiler weblogic jspc Tested only on Weblogic 4 5 1 NT4 0 and Solaris 5 7 5 8 Parameters Attribute Values Required src oot of source tree for J SP ie the document root for your weblogic server Yes d st root of destination directory what you have set as WorkingDir in the weblogic Yes properties package start package nam
228. f http developer java sun com developer products xml docs api gt lt javadoc gt is the same as lt javadoc destdir docs api author true version true use true windowtitle Test API gt lt packageset dir src defaultexcludes yes gt lt include name com dummy test gt lt exclude name com dummy test doc files gt lt packageset gt 130 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt doctitle gt lt CDATA lt h1 gt Test lt h1 gt gt lt doctitle gt lt bottom gt lt CDATA lt i gt Copyright amp 169 2000 Dummy Corp All Rights Reserved lt i gt gt lt bottom gt lt tag name todo scope all description To do gt lt group title Group 1 Packages packages com dummy test a gt lt group title Group 2 Packages packages com dummy test b com dummy test c gt lt link offline true href http java sun com products jdk 1 2 docs api packagelistLoc C tmp gt lt link href http developer java sun com developer products xml docs api gt lt javadoc gt or lt javadoc destdir docs api author true version true use true windowtitle Test API gt lt fileset dir src defaultexcludes yes gt lt include name com dummy test gt lt exclude name com dummy test doc files gt lt fileset gt lt doctitle gt lt CDATA lt h1 gt Test lt h1 gt gt lt docti
229. false gt lt classpath gt lt pathelement path S descriptorbuild classpath gt lt classpath gt lt weblogic gt lt include name ejb jar xml gt lt exclude name weblogic ejb Jar xml gt lt dtd publicId Sun Microsystems Inc DTID Enterprise JavaBeans 1 1 EN location S weblogic home classes weblogic ejb deployment xml ejb jar dtd gt lt dtd publicId BEA Systems Inc DTD WebLogic 5 1 0 EJB EN location S weblogic home classes weblogic ejb deployment xml weblogic ejb jar dtd gt lt ejbjar gt This example shows ejbjar being used to generate a single deployment jar using a Weblogic EJB container This example does not require the deployment descriptors to use the naming standard This will create only one ejb jar file TheEJ BJ ar jar lt ejbjar srcdir build classes descriptordir S descriptor dir basejarname TheEJBJar gt lt weblogic destdir deploymentjars dir classpath descriptorbuild classpath gt lt include name e3jb Jar xml gt lt exclude name weblogic xml gt lt ejbjar gt This example shows ejbjar being used to generate deployment jars for a TOPLink enabled entity bean using a Weblogic EJB container This example does not require the deployment descriptors to use the naming standard This will create only one TOPLink enabled ejb jar file Address jar lt ejbjar s
230. fault character encoding filesonly Store only file entries defaults to false O O O includes comma or space separated list of patterns of files that must be included All files are included when omitted includesfile excludes comma or space separated list of patterns of files that must be N excluded No files except default excludes are excluded when omitted excludesfile defaultexcludes indicates whether default excludes should be used or not yes no No Default excludes are used when omitted update indicates whether to update or overwrite the destination file if it already exists Default is false whenempty behavior when no files match Valid values are fail skip and create Default is skip duplicate behavior when a duplicate file is found Valid values are add preserve and fail The default value is add Parameters specified as nested elements fileset The zip task supports any number of nested lt fileset gt elements to specify the files to be included in the archive 172 305 Ant Manual 1 5 4 12 9 2003 7 47 PM zipfileset A lt zipfileset gt is a special form of a lt fileset gt that adds some extra functionality It supports all attributes of lt fileset gt in addition to those listed below Parameters Attribute Description Required prefix all files in the fileset are prefixed with that path in the archive No fullpath the file described by the fileset is placed at that exact location i
231. file by Ant Exactly one of these nd return codes By default the return code of a lt exec gt is ignored when you set failonerror true then any non zero response is treated as an error Alternatively you can set resultproperty to the name of a property and have it assigned to the result code barring immutability of course If the att halts the empt to start the program fails with an OS dependent error code then lt exec gt build unless failifexecutionfails is set You can use that to run a program if it exists but otherwise do nothing What do those error codes mean Well they are OS dependent On Windows boxes you have to look in include error h in your windows compiler or wine files error code 2 means no such program which usually means it is not on the path Any time you see such an error from any ant task it is usually not an ant bug but some configuration problem on your machine Examples lt exec executable emacs gt lt env key DISPLAY value 1 0 gt lt exec gt starts em lt exec acs on display 1 of the X Window System 107 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt env key PATH path S java library path basedir bin gt lt exec gt adds basedir bin to the PATH of the system command Note Although it may work for you to specify arguments using a simple arg element and separate them by spaces it may fail if you switch to a newer version of the JDK J
232. folder C dev buildtest co rootstarteamfolder Dev excludes bak old label v2 6 001 forced true gt This will check out all files from the Dev folder and below that do not end in with the label v2 6 001 lt stcheckout URL STARTEAM 49201 Aproject AView username auser password secret rootlocalfolder C dev buildtest co includes htm html xcludes index forced true gt bak or old This is an example of overlapping includes and excludes attributes Because excludes takes precedence over includes files named index html will not be checked out by this command 272 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt stcheckout URL STARTEAM 49201 Aproject AView username auser password secret rootlocalfolder C dev buildtest co includes htm html xcludes index forced true recursive false gt This example is like the previous one but will only check out files in C dev buildtest co because of the turning off of the recursive attribute lt stcheckout URL STARTEAM 49201 Aproject AView username auser password secret rootstarteamfolder src java rootlocalfolder C dev buildtest co forced true gt lt stcheckout URL STARTEAM 49201 Aproject AView username auser password secret rootstarteamfolder src java gt lt stcheckout URL STARTEAM 49201 Aproject AView username auser password secre
233. fordham edu barbacha cabinet_library See the section on directory based tasks on how the inclusion exclusion of files works and how to write patterns This task forms an implicit FileSet and supports all attributes of lt fileset gt dir becomes basedir as well as the nested lt include gt lt exclude gt and lt patternset gt elements Parameters Attribute Description Required cabfile the name of the cab file to create Yes basedir the directory to start archiving files from Yes verbose set to yes if you want to see the output from the cabarc tool defaults to No no compress set to no tostore files without compressing defaults to yes No options use to set additional command line options for the cabarc tool should not No normally be necessary includes comma or space separated list of patterns of files that must be included No All files are included when omitted includesfile the name of a file Each line of this file is taken to be an include pattern No excludes comma or space separated list of patterns of files that must be excluded No No files except default excludes are excluded when omitted excludesfile the name of a file Each line of this file is taken to be an exclude pattern No defaultexcludes indicates whether default excludes should be used or not yes no No 180 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Default excludes are used when omitted Parameters specified as nested
234. fying the value attribute Conditions are specified as nested elements you must specify exactly one condition Parameters Attribute Description Required property The name of the property to set value The value to set the property to Defaults to true No Parameters specified as nested elements All conditions to test are specified as nested elements for a complete list see here Examples lt condition property javamail complete gt lt and gt lt available classname javax activation DataHandler gt lt available classname javax mail Transport gt lt and gt lt condition gt sets the property javamail complete if both the JavaBeans Activation Framework and JavaMail are available in the classpath lt condition property isMacOsButNotMacOsX gt lt and gt lt os family mac gt lt not gt lt os family unix gt lt not gt lt and gt lt condition gt sets the property isMacOsButNotMacOsx if the current operating system is MacOS but not MacOS X which Ant considers to be in the Unix family as well 88 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt condition property isSunOSonSparc gt lt os name SunOS arch sparc gt lt condition gt sets the property isSunOSonSparc if the current operating system is SunOS and if it is running on a sparc architecture 9 13 1 Conditions These are the nested elements that can be used as conditions in the lt condit
235. g home cvspublic destfile tagdiff xml package ant startTag ANT_14 endTag ANT_141 i Generates a tagdiff report for all the changes that have been made in the ant module between the tags ANT_14 and ANT_141 It writes these changes into the file tagdiff xml lt cvstagdiff destfile tagdiff xml package ant startDate 2002 01 01 ndDate 2002 31 01 gt Generates a tagdiff report for all the changes that have been made in the ant module in january 2002 In this example cvsRoot has not been set The current cvsRoot will be used assuming the build is started from a folder stored in cvs It writes these changes into the file tagdiff xml lt cvstagdiff destfile tagdiff xml package ant rootdir apache ant startDate 2002 01 01 99 305 Ant Manual 1 5 4 12 9 2003 7 47 PM ndDate 2002 31 01 gt Generates a tagdiff report for all the changes that have been made in the ant module in january 2002 with rootdir indicating that the actual location of the ant module in cvs is apache ant rather than ant In this example cvsRoot has not been set The current cvsRoot will be used assuming the build is started from a folder stored in cvs It writes these changes into the file tagdiff xml Generate Report Ant includes a basic XSLT stylesheet that you can use to generate a HTML report based on the xml output The following example illustrates how to generate a HTML report from the XML report lt style in ta
236. g No statements to the standard output If yes the additional debugging statements will be generated If omitted it defaults to no iashome May be used to specify the home directory for this AS installation This is No used to find the ejbc utility if it isn t included in the user s system path If specified it should refer to the install location iplanet ias6 ias directory If omitted the ejbc utility must be on the user s system path suffix String value appended to the J AR filename when creating each J AR If No 203 305 Ant Manual 1 5 4 12 9 2003 7 47 PM omitted it defaults to jar As noted above the iplanet element supports additional lt classpath gt nested elements Examples This example demonstrates the typical use of the lt iplanet gt nested element It will name each EJ B JAR using the basename prepended to each standard EJB descriptor For example if the descriptor named Account ejb jar xml is processed the EJ B J AR will be named Account jar lt ejbjar srcdir S build classesdir descriptordir S src gt lt iplanet destdir S assemble ejbjar classpath S ias ejbc cpath gt lt include name ejb jar xml gt lt exclude name ias xml gt lt ejbjar gt This exa mple demonstrates the use of a nested classpath element as well as some of the other optional attributes lt ejbjar srcdir S build classesdir descriptordir src j gt lt iplanet d
237. gdiff xml out tagdiff html style S ant home etc tagdiff xsl gt lt param name title expression Ant Diff gt lt param name module expression ant gt lt param name cvsweb expression http cvs apache org viewcvs gt lt style gt Sample Output lt xml version 1 0 encoding UTF 8 gt lt tagdiff startTag ANT_14 endTag ANT_141 gt lt entry gt lt file gt lt name gt src main org apache tools ant DirectoryScanner java lt name gt lt revision gt 1 15 2 1 lt revision gt lt prevrevision gt 1 15 lt prevrevision gt lt file gt lt entry gt lt tagdiff gt 9 21 Delete Description Deletes a single file a specified directory and all its files and subdirectories or a set of files specified by one or more FileSets When specifying a set of files empty directories are not removed by default To remove empty directories use the includeEmptyDirs attribute If you use this task to delete temporary files created by editors and it doesn t seem to work read up on the default exclusion set in Directory based Tasks and see the defaultexcludes attribute below Parameters Attribute Description Required file The file to delete specified as either the simple filename if the file exists in the current base directory a relative path filename or a full path filename At least one of dir The directory to delete including all its files and subdirectories the two unless Note dir i
238. generated files to build src The grammar option STATIC is set to true when invoking JavaCC 10 16 Javah Description Generates JNI headers from a Java class When this task executes it will generate the C header and source files that are needed to implement native methods JNI operates differently depending on whether DK1 2 or later or pre DK1 2 systems are used Parameters Attribute Description Required class the fully qualified name of the class or classes separated by commas Yes outputFile concatenates the resulting header or source files for all the classes listed into this file Yes destdir sets the directory where javah saves the header files or the stub files force specifies that output files should always be written J DK1 2 only No old specifies that old JDK1 0 style header files should be generated otherwise No output file contain J NI style native method function prototypes J DK1 2 only stubs generate C declarations from the J ava object file used with old No verbose causes J avah to print a message concerning the status of the generated files No classpath the classpath to use No bootclasspath location of bootstrap class files No extdirs location of installed extensions No Either outputFile or destdir must be supplied but not both Examples lt javah destdir c class org foo bar Wibble gt makes a JNI header of the named class using the JDK1 2 JNI model Assuming the directory c already exists
239. gets In this manual most initialization targets have the name init A target has the following attributes Attribute Description Required name the name of the target Yes depends a comma separated list of names of targets on which this target depends No if the name of the property that must be set inorder for this target to execute No unless the name of the property that must not be set in order for this target to No execute description la short description of this target s function No A target name can be any alphanumeric string valid in the encoding of the XML file The empty string is in this set as is comma and space Please avoid using these as they will not be supported in future Ant versions because of all the confusion they cause IDE support of unusual target names or any target name containing spaces varies with the IDE Targets beginning with a hyphen such as restart are valid and can be used to name targets that should not be called directly from the command line 6 1 3 Tasks A task is a piece of code that can be executed A task can have multiple attributes or arguments if you prefer The value of an attribute might contain references to a property These references will be resolved before the task is executed 25 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Tasks have a common structure lt name attributel valuel attribute2 value2 gt where name is the name of the task attribu
240. gic ddcreator tool No This must include the weblogic ejb utils DDCreator class Examples lt ddcreator descriptors S dd dir dest gen classes classpath descriptorbuild classpath gt lt include name txt gt 188 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt ddcreator gt 10 7 2 2EJBC Description The ejbc task will run Weblogic s ejbc tool This tool will take a serialized deployment descriptor examine the various EJB interfaces and bean classes and then generate the required support classes necessary to deploy the bean in a Weblogic EJB container This will include the RMI stubs and skeletons as well as the classes which implement the bean s home and remote interfaces The ant task which runs this tool is able to compile several beans in a single operation The beans to be compiled are selected by including their serialized deployment descriptors The standard ant include and exclude constructs can be used to select the deployment descriptors to be included Each descriptor is examined to determine whether the generated classes are out of date and need to be regenerated The deployment descriptor is de serialized to discover the home remote and implementation classes The corresponding source files are determined and checked to see their modification times These times and the modification time of the serialized descriptor itself are compared with the modification time of the generated classes If the generated cl
241. gt lt mmetrics gt This invokes Metamata Metrics installed in c metamata on the metrics example Note that here classpath and sourcepath are not normally not needed Generating a report As a convenience there is an XSL file mmetrics frames xsl that allows you to generate a full framed HTML report of the metrics You can find it in the etc directory of Ant As it uses the Xalan redirect extensions you will need Xalan and Xerces to run it The stylesheet takes an output dir parameter otherwise it will be generated in the current directory it can be run in Ant as follows lt style in java S metrics xml style mmetrics frames xsl out null tmp gt lt param name output dir expression report dir gt lt style gt 10 25 MAudit Stephane Bailliez Sbailliez imediation com Requirements 239 305 Ant Manual 1 5 4 12 9 2003 7 47 PM This task requires Metamata Development environment 2 0 Webgain Quality Analyzer 2 0 An evaluation version is available at Webgain Jakarta Oro and a XML parser via J AXP Description Invokes the Metamata Audit Webgain Quality Analyzer on a set of J ava files maudit performs static analysis of the Java source code and byte code files to find and report errors of style and potential problems related to performance maintenance and robustness AS a convenience a stylesheet is given in etc directory
242. have an equivalent file in another directory tree The lt present gt tag supports the use of a contained lt mapper gt element to define the location of the file to be tested against If no lt mapper gt element is specified the identity type mapper is used The lt present gt selector is case sensitive Attribute Description Required targetdir The base directory to look for the files to compare against The precise location Yes depends on a combination of this attribute and the lt mapper gt element if any present Whether we are requiring that a file is present in the src directory tree only or in No both the src and the target directory tree Valid values are srconly select files only if they are in the src directory tree but not in the target directory tree both select files only if they are present both in the src and target directory trees Default is both Setting this attribute to srconly is equivalent to wrapping the selector in the lt not gt selector container Here is an example of how to use the Present Selector lt fileset dir ant 1 5 src main includes java gt lt present present srconly targetdir ant 1 4 1 src main gt lt fileset gt Selects all the Java source files which are new in the 1 5 release 7 3 22 9SIZE SELECTOR The lt size gt tag in a FileSet will put a limit on the files specified by the include tag so that tags which do not meet the size limits specified by
243. he build process if an error occurs default yes no Parameters specified as nested elements 286 305 Ant Manual 1 5 4 12 9 2003 7 47 PM include specifies the packages to include into the export Attribute Description Required name name of the VAJ project and package to export yes The first element of the name must be the project name then the package name elements separated by exclude specifies the packages to exclude from the export Attribute Description Required name name of the VAJ project package not to export yes Example lt vajexport destdir src dir exportResources no gt lt include name MyProject gt lt exclude name MyProject test gt lt vajexport gt This example exports all packages in the VAJ project MyProject except packages starting with test Default Excludes The default excludes are IBM Java class libraries Sun class libraries JSP Page Compile Generated Code VisualAge 10 47 6 VAJI mport Description Imports Java source files class files and or resources from the file system into VAJ These imports can be specified with a fileset Parameters Attribute Description Required project imported files are added to this VAJ project yes importSources import source files default yes no importResources import resource files default yes no importClasses import class files default no no remote name and port of a rem
244. he file that the command will operate on Yes comment Specify a comment No task Specify the task number used to checkin the file may use default No ccmdir path to the ccm executable file required if it is not on the PATH No Examples lt cemcheckout file c wa com foo MyFile java comment mycomment gt Check out the file c wa com foo MyFile java Comment attribute mycomment is added as a task comment The used task is the one set as the default 10 5 3 CCMCheckinTask Description Task to perform a check in default task command to Continuus Parameters Attribute Values Required comment Specify a comment No task Specify the task number used to check in the file may use default No ccmdir path to the ccm executable file required if it is not on the PATH No Examples lt ccemcheckintask comment blahblah gt Does a Checkin default task on all the checked out files in the current task 10 5 4 CCMReconfigure Description Task to perform an reconfigure command to Continuus Parameters Attribute Values Required recurse recurse on Subproject default false No verbose do a verbose reconfigure operation default false No ccmproject Specifies the ccm project on which the operation is applied Yes ccmdir path to the ccm executable file required if it is not on the PATH No 184 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Examples lt ccmreconfigure ccmproject ANTCCM_TEST BMO_1 verbose true gt Does a Contin
245. he label Must be formatted yes yyyyMMddHHmmss description A description of the label to be stored in the StarTeam project no Examples This example shows the use of this tag It will create a label named Version 6 2 with Thorough description as its description 276 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt tstamp gt lt format property nowstamp pattern yyyyMMddHHmmss locale en gt lt tstamp gt lt stlabel URL STARTEAM 49201 Aproject AView username auser password secret label Version 6 2 lastbuild nowstamp description Thorough description gt 10 42 5 STList Description Produces a listing of the contents of the StarTeam repository at the specified view and StarTeamFolder The listing will contain the name of the user if any who has the file locked the size of the file its lastModifiedDate in the repository and the name of the file Unless the rootLocalFolder is specified listing will also show the status of the local file in the default local directory relative to the repository Parameters See also the required common StarTeam parameters Attribute Description Required rootstarteamfolder The root of the subtree in the StarTeam repository to be listed Defaults no to the root folder of the view rootlocalfolder The local folder which will be the root of the tree to which files are no compared If this is not supplied then the StarTeam default folder associated with
246. he test results in XML format the other emits plain text The formatter named brief will only print detailed information for testcases that failed while plain gives a little statistics line for all test cases Custom formatters that need to implement org apache tools ant taskdefs optional junit J UnitResultFormatter can be specified If you use the XML formatter it may not include the same output that your tests have written as some characters are illegal in XML documents and will be dropped Attribute Description Required i r either xml plain or brief type Use a predefined formatter eithe plain or brief Exactly one of these classname Name of a custom formatter class extension Extension to append to the output filename Yes if classname has been used usefile Boolean that determines whether output should be sent to No default is true a file test Defines a single test class Attribute Description Required name Name of the test class Yes fork Run the tests in a separate VM Overrides value set in lt junit gt No haltonerror Stop the build process if an error occurs during the test run No Overrides value set in lt junit gt errorproperty The name of a property to set in the event of an error No Overrides value set in lt junit gt haltonfailure Stop the build process if a test fails errors are considered No failures as well Overrides value set in lt junit gt failureproperty The name of a property to set i
247. he whenempty parameter controls what happens when no files match If skip the default the ZIP is not created and a warning is issued If fail the ZIP is not created and the build is halted with an error If create an empty ZIP file explicitly zero entries is created which should be recognized as such by compliant ZIP manipulation tools This task will now use the platform s default character encoding for filenames this is consistent with the command line ZIP tools but causes problems if you try to open them from within Java and your filenames contain non US ASCII characters Use the encoding attribute and set it to UTF8 to create zip files that can safely be read by Java Starting with Ant 1 5 2 lt zip gt can store Unix permissions inside the archive see description of the filemode and dirmode attributes for lt zipfileset gt Unfortunately there is no portable way to store these permissions Ant uses the algorithm used by Info Zip s implementation of the zip and unzip commands these are the default versions of zip and unzip for many Unix and Unix like systems Parameters Attribute Description Required destfile zipfile basedir compress Not only store data but also compress them defaults to true encoding The character encoding to use for filenames inside the zip file For a list N of possible values see htto java sun com products jdk 1 2 docs quide internat encoding doc him N O o O Defaults to the platform s de
248. hive file to expand Yes if filesets are not used dest directory where to store the expanded files Yes overwrite Overwrite files even if they are newer than the corresponding No entries in the archive true or false default is true compression compression method for untar Allowable values are none gzip No and bzip2 Default is none Examples lt unzip src S tomcat_src tools srce zip dest tools home gt lt gunzip src tools tar gz gt lt untar src tools tar dest tools home gt lt unzip src S tomcat_src tools src zip dest S tools home gt lt patternset gt lt include name java gt lt exclude name Test java gt lt patternset gt lt unzip gt lt unzip dest tools home gt lt patternset gt lt include name java gt lt exclude name Test java gt lt patternset gt lt fileset dir gt lt include name zip gt lt exclude name tmp zip gt lt fileset gt lt unzip gt 9 66 Uptodate Description Sets a property if a target file or set of target files is more up to date than a source file or set of source files A single source file is specified using the srcfile attribute A set of source files is specified using the nested lt srcfiles gt elements These are FileSets whereas multiple target files are specified using a nested lt mapper gt element By default the value of the property is set
249. hughes rubus com e Kirk Wylie kirk radik com 246 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Version 1 1 2001 01 09 10 30 1 Introduction These tasks provide an interface to the Perforce SCM The org apache tools ant taskdefs optional perforce package consists of a simple framework to support p4 functionality as well as some Ant tasks encapsulating frequently used by me p4 commands However the addition of new p4 commands is a pretty simple task see the source Although it is possible to use these commands on the desktop they were primarily intended to be used by automated build systems Note These tasks require the oro 2 0 XXX regular expression package Simply download this package and copy the jakarta oro 2 0 XXX jar file into Ant s lib directory You will also need the Perforce client executable p4 or p4 exe but not p4win exe in your path 10 30 2 The Tasks 10 30 3 General P4 Properties Each p4 task requires a number of settings either through build wide properties individual attributes or environment variables These are Property Attribute Env Var Description Default p4 port port P4PORT The p4d server and port to connect to perforce 1666 p4 client client P4CLIENT The p4 client spec to use The logged in username p4 user user P4USER The p4 username The logged in username view The client branch or label view to operate upon See the p4 user guide for more info Your local inst
250. icsynergy com Conor MacNeill Cyrille Morvan cmorvan ingenosya com Greg Nelson gn sun com 187 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Version VERSION id ejb html v 1 23 2 18 2003 07 17 11 05 34 bodewig Exp 10 7 1 Introduction Ant provides a number of optional tasks for developing Enterprise Java Beans EJBs In general these tasks are specific to the particular vendor s EJB Server At present the tasks support e Borland Application Server 4 5 e Planet Application Server 6 0 e Boss 2 1 and above EJB servers e Weblogic 4 5 1 through to 7 0 EJB servers e JONAS 2 4 x and 2 5 Open Source EJB server e IBM WebSphere 4 0 Over time we expect further optional tasks to support additional EJB Servers 10 7 2 EJB Tasks Task Application Servers sd iplanet ejbdiPlanet Application Server 6 0 borland Borland Application Server 4 5 and 5 x ejbjar 10 7 2 1DDCREATOR Description ddcreator will compile a set of Weblogic text based deployment descriptors into a serialized EJB deployment descriptor The selection of which of the text based descriptors are to be compiled is based on the standard Ant include and exclude selection mechanisms Parameters Attribute Description Required descriptors This is the base directory from which descriptors are selected Yes dest The directory where the serialized deployment descriptors will be written Yes classpath This is the classpath to use to run the underlying weblo
251. ig Cottingham 292 305 Ant Manual 1 5 4 12 9 2003 7 47 PM e Andrew Everitt Balazs Fejes 2 Glenn_Twiggs bmc com Martin Poeschl mpoeschI marmot at Phillip Wells Jon Skeet jon skeet peramon com Nigel Magnay nigel magnay parsec co uk Gary S Weaver Date 2002 10 24 10 27 59 10 48 1 Introduction These tasks provide an interface to the Microsoft Visual SourceSafe SCM The org apache tools ant taskdefs optional vss package consists of a simple framework to support vss functionality as well as some Ant tasks encapsulating frequently used vss commands Although it is possible to use these commands on the desktop they were primarily intended to be used by automated build systems If you get a CreateProcesss OError 2 when running these it means that ss exe was not found Check to see if you can run it from the command line you may need to alter your path or set the ssdir property 10 48 2 The Tasks copies a Me fom the curent projed to the current folder for the purpose of editing a file from the current project to the current fo Ider for the purpose of editing Vssadd Adds a new file into the VSS Archive gt i a new file into the VSS Archive Change the current project being used in VSS Creates a project in VSS 10 48 3 VssGet Description Task to perform GET commands to Microsoft Visual SourceSafe If you specify two or more attributes from version date and label only one will be used in the o
252. ild file other than build xm1 use the command line option buildfile file where file is the name of the build file you want to use If you use the find file option Ant will search for a build file first in the current directory then in the parent directory and so on until either a build file is found or the root of the filesystem has been reached By default it will look for a build file called build xml To have it search for a build file other than build xml specify a file argument Note If you include any other flags or arguments on the command line after the fina flag you must include the file argument for the fina flag even if the name of the build file you want to find is build xml You can also set properties on the command line This can be done with the Dproperty value option where property is the name of the property and value is the value for that property If you specify a property that is also set in the build file see the property task the value specified on the command line will override the value specified in the build file Defining properties on the command line can also be used to pass in the value of environment variables just pass DMYVAR MYVAR Windows or DMYVAR SMYVAR Unix to Ant You can then access these variables inside your build file as MYVAR You can also access environment variables using the property task s environment attribute Options that affect the amount of logging output by Ant are
253. ildtestico necessary to check out files out from a StarTeam server This will check out all files in the AView view of the AProject project to Cc dev buildtest co lt starteam servername STARTEAM gt serverport 49201 projectname AProject viewname AView username auser password secret targetfolder C 1devibuildtestico foldername Dev excludes bak old force true This will checkout all files from the Dev folder and below that do not end in bak or old The force flag will cause any existing files to be overwritten by the version in StarTeam lt starteam servername STARTEAM gt serverport 49201 projectname AProject viewname AView username auser password secret targetfolder C 1devibuildtestico includes htm html xcludes index This is an example of overlapping includes and excludes attributes Because excludes takes precedence over includes files named index html will not be checked out by this command lt starteam servername STARTEAM serverport 49201 projectname AProject foldername src java viewname AView 279 305 Ant Manual 1 5 4 12 9 2003 7 47 PM username auser password secret targetfolder C dev buildtest co targetfolderabsolute true gt lt starteam servername STARTEAM serverport 49201 projectname AProject foldername src java viewname AView username ause
254. ile The file to check for extension No one of file nested ExtensionSet or nested fileset must be present Parameters specified as nested elements extension Extension the extension to search for fileset Filesets are used to select sets of files to check for extension extensionSet ExtensionSets is the set of extensions to search for extension in Examples Search for extension in single file lt jarlib available property myext present file myfile jar gt lt extension extensionName org apache tools ant specificationVersion 1 4 9 specificationVendor Apache Software Foundation gt lt jarlib available gt Search for extension in single file refencing external Extension lt extension id myext extensionName org apache tools ant specificationVersion 1 4 9 specificationVendor Apache Software Foundation gt lt jarlib available property myext present file myfile jar gt lt extension refid myext gt lt jarlib available gt Search for extension in fileset lt extension id myext extensionName org apache tools ant specificationVersion 1 4 9 specificationVendor Apache Software Foundation gt 213 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt jarlib available property myext present gt lt extension refid myext gt lt fileset dir lib gt lt include name jar gt lt lt ja ileset gt lib available gt Search for extension in extens
255. iler cannot produce class files in a specific directory via parameters The directory structure of the source tree should follow the package hierarchy It is possible to refine the set of files that are being compiled copied This can be done with the includes includesfile excludes excludesfile and defaultexcludes attributes With the includes or includesfile attribute you specify the files you want to have included by using patterns The exclude or excludesfile attribute is used to specify the files you want to have excluded This is also done with patterns And finally with the defaultexcludes attribute you can specify whether you want to use default exclusions or not See the section on directory based tasks on how the inclusion exclusion of files works and how to write patterns This task forms an implicit FileSet and supports all attributes of lt fileset gt dir becomes srcdir as well as the nested lt include gt lt exclude gt and lt patternset gt elements 244 305 Ant Manual 1 5 4 12 9 2003 7 47 PM All properties except classpath srcdir and destDir are also available as properties in the form ant netrexxc attributename eg lt property name ant netrexxc verbos or from the command line as value noverbose gt ant Dant netrexxc verbose noverbos Parameters Attribute binary classpath comments compact compile console crossref decimal defaultexcludes destDir diag excludes exclud
256. iles are valid or only well formed The task uses the SAX2 parser implementation provided by JAXP by default probably the one that is used by Ant itself but one can specify any SAX1 2 parser if needed This task supports the use of nested xmlcatalog elements and or nested lt dtd gt elements which are used to resolve DTDs and entities Parameters Attribute Description Required file the file s you want to check optionally can use an embedded fileset No lenient if true only check the xml document is well formed ignored if the specified No parser is as SAX1 parser classname the parser to use No classpathref where to find the parser class Optionally can use an embedded classpath No element failonerror fails on a error if set to true defaults to true No warn log parser warn events No Nested Elements dtd lt dtd gt is used to specify different locations for DTD resolution Attribute Description Required publicld Public 1D of the DTD to resolve Yes location Location of the DTD to use which can be a file a resource or a URL Yes xmlcatalog The xmlcatalog element is used to perform Entity resolution Examples lt xmlvalidate file toto xml gt lt xmlvalidate failonerror no lenient yes warn yes classname org apache xerces parsers SAXParser gt classpath lib xerces jar gt lt fileset dir src includes style xsl gt lt xmlvalidate gt lt xmlvalidate file struts config
257. ime Either currenttime or preservetime can be specified currenttime No preservetime No Examples lt ccupdate viewpath c views viewdir graphical false log log log overwrite tru currenttime tru rename false gt Does a ClearCase update on the directory c views viewdir A graphical dialog will be displayed The output will be logged to log log and it will overwrite any hijacked files The modified time will be set to the current time 10 5 Continuus Support These ant tasks are wrappers around Continuus Source Manager They have been tested with version 5 1 on Windows 2000 but should work on other platforms with ccm installed 10 5 1 CCMCheckin Description Task to checkin a file Parameters Attribute Values Required file Path to the file that the command will operate on Yes comment Specify a comment Default is Checkin plus the date No task Specify the task number used to check in the file may use default No ccmdir path to the ccm executable file required if it is not on the PATH No Examples 183 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt cemcheckin file c wa com foo MyFile java comment mycomment gt Checks in the file c wa com foo MyFile java Comment attribute mycomment is added as a task comment The task used is the one set as the default 10 5 2 CCMCheckout Description Task to perform a Checkout command to Continuus Parameters Attribute Values Required file Path to t
258. ins If lt filterset gt and lt filterchain gt elements are used inside the same lt move gt task all lt filterchain gt elements are processed first followed by lt filterset gt elements Examples Move a single file rename a file lt move file file orig tofile file moved gt Move a single file to a directory lt move file file orig todir dir to move to gt Move a directory to a new directory lt move todir new dir to move to gt lt fileset dir src dir gt lt move gt Move a set of files to a new directory lt move todir some new dir gt lt fileset dir my src dir gt lt include name Jjar gt lt exclude name ant jar gt lt fileset gt lt move gt Append bak to the names of all files in a directory 137 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt move todir my src dir gt lt fileset dir my src dir gt lt exclude name bak gt lt fileset gt lt mapper type glob from to bak gt lt move gt 9 46 Parallel Description Parallel is a container task it can contain other Ant tasks Each nested task within the parallel task will be executed in its own thread Parallel tasks have a number of uses in an Ant build file including e Taking advantage of available processing resources to reduce build time e Testing servers where the server can be run in one thread and the test harness is run in another thread Care mu
259. ion Dependency checking is used to scrub the java files if class dependencies indicate it is needed Notes Using the package attribute it is possible to identify the resulting java files and thus do full dependency checking this task should only rebuild java files if their jsp file has been modified However this only works with some versions of jasper By default the checking supports tomcat 4 0 x with the jasper compiler set the compiler to jasper41 for the 223 305 Ant Manual 1 5 4 12 9 2003 7 47 PM tomcat4 1 x dependency checking Even when it does work changes in TLD imports or in compile time includes do not get picked up Jasper generates JSP pages against the JSP1 2 specification an implementation of version 2 3 of the servlet specification is needed to compile or run the java code 10 18 J Depend Description Invokes the Depend parser This parser traverses a set of Java source file directories and generates design quality metrics for each Java package It allows to automatically measure the quality of a design in terms of its extensibility reusability and maintainability to effectively manage and control package dependencies Source file directories are defined by nested lt sourcespath gt see nested elements Optionally you can also set the outputfile name where the output is stored By default the task writes its report to the standard output The task requires at least the JDepend 1 2 version No
260. ion The version of extension implementation Must be in dewey no decimal aka dotted decimal notation 3 2 4 implementationVendor The implementation vendor no implementationVendorld The implementation vendor ID no implementationURL The url from which to retrieve extension no Examples lt extension id el extensionName MyExtensions specificationVersion 1 0 specificationVendor Peter Donald implementationVendorID vv implementationVendor Apache implementationVersion 2 0 implementationURL http somewhere com myExt jar gt Fully specifiec extension object lt extension id el extensionName MyExtensions specificationVersion 1 0 specificationVendor Peter Donald gt Extension object that just species the specification details 7 4 3 ExtensionSet Utility type that represents a set of Extensions Note that this type works with extensions as defined by the Optional Package specification For more information about optional packages see the document Optional Package Versioning in the documentation bundle for your Java2 Standard Edition package in file guide extensions versioning html or online at http java sun com j2se 1 3 docs quide extensions versioning html Nested Elements extension Extension object to add to set fileset FileSets all files contained contained within set that are jars and implement an extension are added to extension set LibFileSet 66
261. ion gt and lt waitfor gt tasks aaa a ES lt not gt element expects exactly one other condition to be nested into this element negating the result of the condition It doesn t have any attributes and ES all nested elements of the condition task as nested elements as well The lt and gt element doesn t have any attributes and accepts an arbitrary number of conditions as nested elements all nested elements of the condition task are supported This condition is true if all of its contained conditions are conditions will be evaluated in the order they have been specified in the build file The lt and gt condition has the same shortcut semantics as the Java amp amp operator as soon as one of the nested conditions is false no other condition will be evaluated The lt or gt element doesn t have any attributes and accepts an arbitrary number of conditions as nested elements all nested elements of the condition task are supported This condition is true if at least one of its contained conditions is conditions will be evaluated in the order they have been specified in the build file The lt or gt condition has the same shortcut semantics as the Java operator as soon as one of the nested conditions is true no other condition will be evaluated available This condition is identical to the Available task all attributes and nested elements of that task are supported the property and value attributes are redundant and will be ig
262. ionSet lt extension id myext extensionName org apache tools ant specificationVersion 1 4 9 specificationVendor Apache Software Foundation gt lt jarlib availab property myext present gt lt extension refid myext gt lt extensionSet id exts3 gt lt libfileset includeUrl false includeImpl true dir lib gt lt include name jar gt lt libfileset gt lt extensionSet gt lt jarlib available gt 10 12 jarlib display Description Display the Optional Package and Package Specification information contained within the specified jars Note that this task works with extensions as defined by the Optional Package specification For more information about optional packages see the document Optional Package Versioning in the documentation bundle for your Java2 Standard Edition package in file o o ir d html or online at http java sun com j 2se 1 3 docs quide extensions versioning html See the Extension and ExtensionSet documentation for further details Parameters Attribute Description Required file The file to display extension information No but one of file or fileset must be about present Parameters specified as nested elements fileset FileSets contain list of files to display Extension information about Examples Display Extension info for a single file 214 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt jarlib display file
263. ionVendorID vv implementationVendor Apache implementationVersion 2 0 implementationURL http somewhere com gt lt jarlib manifest destfile myManifest txt gt lt extension refid el gt lt jarlib manifest gt Search for extension in fileset A large example with required and optional dependencies lt extension id el extensionName MyExtensions specificationVersion 1 0 specificationVendor Peter Donald implementationVendorID vv implementationVendor Apache implementationVersion 2 0 implementationURL http somewhere com gt GE GE EE et lt extensionSet id option ext gt lt libfileset dir lib option gt lt include name Jjar gt lt libfileset gt lt extensionSet gt lt extensionSet id depends ext gt lt libf leset dir lib required gt lt include name jar gt lt libfileset gt lt extensionSet gt lt jarlib manifes lt extension destfile myManifest txt gt efid e1 gt lt depends refid depends ext gt lt options refid option ext gt lt jarlib manifest gt hhh A 10 14 jarlib resolve Description Try to locate a jar to satisfy an extension and place location of jar into property The task allows you to add a number of resolvers that are capable of locating a library for a specifc extension Each resolv
264. ir parameter otherwise it will be generated in the current directory it can be run in Ant as follows lt style in java S audit xml style maudit frames xsl out null tmp gt lt param name output dir expression report dir gt lt style gt 10 26 MimeMail Deprecated This task has been deprecated Use the mail task instead Description Sends SMTP mail with MIME attachments avaMail and Java Activation Framework are required for this task Multiple files can be attached using FileSets Parameters Attribute Description Required message The message body No but only one of of message or messageFile messageFile A filename to read and used as May be specified If not specified a fileset must the message body be provided messageMimeType MIME type to use for message No defaults to text plain or messageFile when attached tolist Comma separated list of To Yes at least one of tolist cclist or bcclist recipients must be specified cclist Comma separated list of CC recipients 241 305 Ant Manual 1 5 4 12 9 2003 7 47 PM bcclist Comma separated list of BCC recipients mailhost Host name of the mail server No default to localhost subject Email subject line No from Email address of sender Yes failonerror Stop the build process if an No default to true error occurs sending the e mail Examples Send a single HTML file as the body of a message lt mimemail messageMimeTy
265. irdparty libs gt lt exclude name jdbcl jar gt lt lib gt lt classes dir build main gt lt zipfileset dir src graphics images gifs prefix images gt lt war gt will consist of WEB INF web xml WEB INF 1lib jdbc2 jar WEB INF classes com myco myapp Servlet class META INF MANIFEST ME ndex html ront jsp images small logo gif images large logo gif Fh H using Ant s default manifest file The content of WEB INF web xml is identical to src metadata myapp xml 9 69 XmIProperty Description Loads property values from a valid xml file Parameters Attribute Description Required file The XML file to parse Yes prefix The prefix to prepend to each property No keepRoot If false it doesn t include the xml root tag as a first value inthe No default is property name true validate If true it enables validation No default is false collapseAttributes If true it treats attributes as nested elements No default is false Examples lt xmlproperty file somefile xml gt Load contents of somefile xml as Ant properties generating the property names from the file s element and attribute names lt root tag myattr true gt lt inner tag someattr val gt Text lt inner tag gt lt a2 gt lt a3 gt lt a4 gt false lt a4 gt lt a3 gt lt a2 gt lt root tag gt This is an example xml file root tag myattr true 170 305 Ant Manual 1 5 4 12 9
266. is may be addressed using the source file attribute in the classfile Secondly neither depend nor the compiler tasks can detect when a non public class is missing Inner classes are handled by the depend task The most obvious example of these limitations is that the task can t tell which classes to recompile when a constant primitive data type exported by other classes is changed For example a change in the definition of something like public final class Constants public final static boolean DEBUG false will not be picked up by other classes Parameters 186 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Attribute Description Required srcDir This is the directory where the source exists depend will examine this to Yes determine which classes are out of date If you use multiple source directories you can pass this attribute a path of source directories destDir This is the root directory of the class files which will be analysed If this is not No present the srcdir is used cache This is a directory in which depend can store and retrieve dependency No information If this is not present depend will not use a cache closure This attribute controls whether depend only removes classes which directly No depend on out of date classes If this is set to true depend will traverse the class dependency graph deleting all affected classes Defaults to false dump If true the dependency information will be written to the debug level l
267. is up to date The task uses the jakarta BCEL framework to extract all dependent classes This means that in addition to the classes that are mentioned in the deployment descriptor any classes that these depend on are also automatically included in the jar file Naming Convention Ejbjar handles the processing of multiple beans and it uses a set of naming conventions to determine the name of the generated EJB jars The naming convention that is used is controlled by the naming attribute It supports the following values e descriptor 193 305 Ant Manual 1 5 4 12 9 2003 7 47 PM This is the default naming scheme The name of the generated bean is derived from the name of the deployment descriptor For an Account bean for example the deployment descriptor would be named Account ejb jar xml Vendor specific descriptors are located using the same naming convention The weblogic bean for example would be named Account weblogic ejb jar xml Under this arrangement the deployment descriptors can be separated from the code implementing the beans which can be useful when the same bean code is deployed in separate beans This scheme is useful when you are using one bean per EJB jar and where you may be deploying the same bean classes in different beans with different deployment characteristics e ejb name This naming scheme uses the lt ejb name gt element from the deployment descriptor to determine the bean name In this situation
268. ist gt deletes the directory dist including its files and subdirectories lt deltree dir dist gt deletes the directory dist including its files and subdirectories 9 23 DependSet A task to manage arbitrary dependencies between files Description The dependset task compares a set of source files with a set of target files If any of the source files is more recent than any of the target files all of the target files are removed Source files and target files are specified via nested FileSets and or nested FileLists Arbitrarily many source and target filesets filelists may be specified but at least one filelist fileset is required for both sources and targets Use a FileSet when you want to use wildcard include or exclude patterns and don t care about missing files Use a FileList when you want to consider the non existence of a file as if it were out of date If there are any non existing files in any source or target FileList all target files will be removed DependSet is useful to capture dependencies that are not or cannot be determined algorithmically For example the lt style gt task only compares the source XML file and XSLT stylesheet against the target file to determined whether to restyle the source Using dependset you can extend this dependency checking to include a DTD or XSD file as well as other stylesheets imported by the main stylesheet Parameters none Parameters Specified as Nested Element
269. ith Contract DBC preprocessor The task can generate a properties file for iControl a graphical user interface that lets you turn on off assertions iControl generates a control file that you can refer to from this task using the controlfile attribute Parameters Attribute Description Required srcdir Location of the java files Yes instrumentdir Indicates where the instrumented source files should go Yes repositorydir Indicates where the repository source files should go Yes builddir Indicates where the compiled instrumented classes should go No Defaults to the value of instrumentdir NOTE Don t use the same directory for compiled instrumented classes and uninstrumented classes It will break the dependency checking Classes will not be reinstrumented if you change them repbuilddir Indicates where the compiled repository classes should go No Defaults to the value of repositorydir pre Indicates whether or not to instrument for preconditions Defaults No to true unless controlfile is specified in which case it defaults to false post Indicates whether or not to instrument for postconditions No Defaults to true unless controlfile is specified in which case it defaults to false invariant Indicates whether or not to instrument for invariants Defaults to No true unless controlfile is specified in which case it defaults to false failthrowable The full name of the Throwable Exception that should be thrown No 211 305 Ant
270. jar gt lt jonas server MyJOnAS jonasroot jonas root gt lt classpath gt lt pathelement path S jonas root lib RMI_jonas jar gt lt pathelement path S jonas root config gt lt classpath gt lt jonas gt lt serverdeploy gt This example shows serverdeploy being used to list the components from a JOnAS server and a WebLogic server lt serverdeploy action list gt lt jonas jonasroot S jonas root orb JEREMIE gt lt weblogic application myapp server t3 myserver 7001 classpath weblogic home lib weblogic jar username S user name password S user password gt lt serverdeploy gt 10 37 Setproxy Sets Java s web proxy properties so that tasks and code run in the same J VM can have through the firewall access to remote web sites and remote ftp sites Description Sets Java s web proxy properties so that tasks and code run in the same J VM can have through the firewall access to remote web sites and remote ftp sites You can nominate an http and ftp proxy or a socks server reset the server settings or do nothing at all Examples lt setproxy gt do nothing lt setproxy proxyhost firewall gt set the proxy to firewall 80 lt setproxy proxyhost firewall set the proxy to firewall 81 proxyport 81 gt lt setproxy proxyhost gt stop using the http proxy don t change the socks settings lt setproxy socksproxyhost socksy gt luse soc
271. jb jar bnd xmi e ibm ejb jar ext xmi and another two for container managed entity beans e Map mapxmi e Schema dbxmi In terms of WebSphere the generation of container code and stubs is called deployment This step can be performed by the websphere element as part of the jar generation process If the switch ejbdeploy is on the ejbdeploy tool from the websphere toolset is called for every ejb jar Unfortunately this step only works if you use the ibm jdk Otherwise the rmic called by ejbdeploy throws a ClassFormatError Be sure to switch ejbdeploy off if run ant with sun jdk For the websphere element to work you have to provide a complete classpath that contains all classes that are required to reflect the bean classes For ejbdeploy to work you must also provide the classpath of the ejbdeploy tool and set the websphere home property look at the examples below Attribute Description Required destdir The base directory into which the generated weblogic Yes ready jar files are deposited Jar files are deposited in directories corresponding to their location within the descriptordir namespace ejbdeploy Decides wether ejbdeploy is called When you set this to No defaults to true 201 305 Ant Manual 1 5 4 suffix keepgeneric rebuild tempdir dbName dbSchema dbVendor codegen quiet novalidate noinform trace use35MappingRules rmicOptions 12 9 2003 7 47 PM true be sure to run ant with the ibm jdk
272. kageMapperTest java TEST o0rg apache tools ant util PackageMapperTest xml org apache tools ant util Helper java ignored 7 3 7 FilterChains and FilterReaders Look at Unix pipes they offer you so much flexibility say you wanted to copy just those lines that contained the string blee from the first 10 lines of a file foo to a file bar you would do something like cat foolhead nl0O grep blee gt bar 42 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Ant was not flexible enough There was no way for the lt copy gt task to do something similar If you wanted the lt copy gt task to get the first 10 lines you would have had to create special attributes lt copy file foo tofile bar head 10 contains blee gt The obvious problem thus surfaced Ant tasks would not be able to accomodate such data transformation attributes as they would be endless The task would also not know in which order these attributes were to be interpreted That is must the task execute the contains attribute first and then the head attribute or vice versa What Ant tasks needed was a mechanism to allow pluggable filter data tranformer chains Ant would provide a few filters for which there have been repeated requests Users with special filtering needs would be able to easily write their own and plug them in The solution was to refactor data transformation oriented tasks to support FilterChains A FilterChain is a group of ordered FilterReaders
273. ks in Ant Inclusion exclusion by folder is NOT supported Parameters See also the required common StarTeam parameters Attribute Description Required rootstarteamfolder The root of the subtree in the StarTeam repository from which to no check out files Defaults to the root folder of the view rootlocalfolder The local folder which will be the root of the tree to which files no are checked out If this is not supplied then the StarTeam default folder associated with rootstarteamfolder is used createworkingdirs creates local folders even when the corresponding StarTeam no folder is empty Defaults to true deleteuncontrolled if true any files NOT in StarTeam will be deleted Defaults to no true includes Only check out files that match at least one of the patterns in this no list Patterns must be separated by commas Patterns in excludes take precedence over patterns in includes excludes Do not check out files that match at least one of the patterns in no this list Patterns must be separated by commas Patterns in excludes take precedence over patterns in includes label Check out files as of this label The label must exist in starteam no or an exception will be thrown If not specified the most recent version of each file will be checked out recursive Indicates if subfolders should be searched for files to check out no Defaults to true forced If true checkouts will occur regardless of the status that no
274. ks via socksy 1080 lt setproxy socksproxyhost gt stop using the socks server Parameters Attribute Description O o ye nonProxyHosts A list of hosts to bypass the proxy on These should be separated with the vertical bar character Only in Java 1 4 does ftp use this list e g fozbot corp sun com eng sun com proxyHost the HTTP ftp proxy host Set this to for the http proxy option to be disabled lproxyPort the HTTP ftp proxy port number default is 80 263 305 Ant Manual 1 5 4 12 9 2003 7 47 PM socksProxyHost The name of a Socks server Set to to turn socks proxying off String socksProxyPort Set the ProxyPort for socks connections The default value is 1080 10 38 Script Description Execute a script in a BSF supported language Note This task depends on external libraries not included in the Ant distribution See Library Dependencies for more information All items tasks targets etc of the running project are accessible from the script using either their name or id attributes as long as their names are considered valid Java identifiers that is The name project is a pre defined reference to the Project which can be used instead of the project name BeanShell users This task now natively supports the BeanShell scripting language using language beanshell The BeanShell engine is still required Scripts can do almost anything a task written in Java could do Parameters Attri
275. l be used Otherwise the default compiler for the current VM will be used See the above list of valid compilers classpath and extdirs Required Yes No No No No No No No No No No No No No No No No No Ant Manual 1 5 4 12 9 2003 7 47 PM Rmic s classpath and extdirs attributes are PATH like structure and can also be set via a nested classpath and extdirs elements compilerarg You can specify additional command line arguments for the compiler with nested lt compilerarg gt elements These elements are specified like Command line Arguments but have an additional attribute that can be used to enable arguments only if a given compiler implementation will be used Attribute Description Required value line Exactly See Command line Arguments one of file these path compiler Only pass the specified argument if the chosen compiler implementation matches the value of this attribute Legal values are the same as those in the No above list of valid compilers Examples lt rmic classname com xyz FooBar base build classes gt runs the rmic compiler for the class com xyz FooBar The compiled files will be stored in the directory build classes lt rmic base S build classes includes Remote class gt runs the rmic compiler for all classes with class files below build classes whose classname starts with Remote The compiled files will be stored in the directory
276. label should be specified Examples lt vssget localPath C mysrc myproject recursive true label Releasel login me mypassword vsspath source aProject writable true gt Does a get on the VSS Project source myproject using the username me and the password mypassword It will recursively get the files which are labeled Releasel and write them to the local directory C mysrc myproject The local files will be writable 10 48 4 VssLabel Description Task to perform LABEL commands to Microsoft Visual SourceSafe Assigns a label to the specified version or current version of a file or project Parameters Attribute Values Required SourceSafe path which specifies the project file s you wish to perform the vsspath action on You should not specify the leading dollar sign it is prepended by Yes Ant automatically usernamel password The username and password needed to get access to VSS Note that you may need to specify both if you have a password login No 2 Ant VSS will hang if you leave the password out and VSS does not accept login without a password directory where ss exe resides By default the task expects it to be in the ssdir No PATH serverPath directory where srssafe ini resides No label A label to apply to the hierarchy Yes version An existing file or project version to label By default the current version is No labelled comment The comment to use for this label Empty or for no commen
277. les may not yet actually exist 37 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt filelist id docfiles dir S doc src files foo xml bar xml gt Same files as the example above lt filelist refid docfiles gt Same files as the example above 7 3 5 FileSet FileSets are groups of files These files can be found in a directory tree starting in a base directory and are matched by patterns taken from a number of PatternSets and Selectors FileSets can appear inside tasks that support this feature or at the same level as target i e as children of project PatternSets can be specified as nested lt patternset gt elements In addition FileSet holds an implicit PatternSet and supports the nested lt include gt lt includesfile gt lt exclude gt and lt excludesfile gt elements of PatternSet directly as well as PatternSet s attributes Selectors are available as nested elements within the FileSet If any of the selectors within the FileSet do not select the file the file is not considered part of the FileSet This makes FileSets eugivalent to an lt and gt selector container Attribute Description Required dir the root of the directory tree of this FileSet Either dir or file file shortcut for specifying a single file fileset must be specified defaultexcludes indicates whether default excludes should be used or not yes No no default excludes are used when omitted includes comma or space separated lis
278. leted or not If omitted it defaults to false nocompil true if the generated source files must not be compiled via the java and rmi No compilers If omitted it defaults to false novalidation true if the XML deployment descriptors must be parsed without validation If No omitted it defaults to false javac Java compiler to use If omitted it defaults to the value of build compiler No property javacopts Options to pass to the java compiler No rmicopts Options to pass to the rmi compiler No secpropag true if the RMI Skel and Stub must be modified to implement the implicit No propagation of the security context the transactional context is always provided If omitted it defaults to false verbose Indicates whether or not to use verbose switch If omitted it defaults to No false additionalargs Add additional args to GenlC No keepgeneric true if the generic J AR file used as input to GenIC must be retained If No omitted it defaults to false suffix String value appended to the J AR filename when creating each JAR If No omitted it defaults to jar orb Choose your ORB RMI JEREMIE DAVID If omitted it defaults to the one No present in classpath If specified the corresponding JOnAS JAR is automatically added to the classpath nogenic If this attribute is set to true JOnAS s GenIC will not be run on the EJB JAR No Use this if you prefer to run GenIC at deployment time If omitted it defaults to false
279. ll EOLs in the included java source files to a single LF Replace all TAB characters except those in string or character constants with spaces assuming a tab width of 3 If run on a unix system any CTRL Z EOF characters at the end of the file are removed On DOS Windows any such EOF characters will be left untouched 111 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt fixcrlf srcdir S src tab remove includes README gt Sets EOLs according to local OS conventions and converts all tabs to spaces assuming a tab width of 8 EOF characters are left alone if run on DOS systems and are removed if run on Unix systems You never know what editor a user will use to browse README s 9 31 GenKey Description Generates a key in keystore This task needs Javal 2 or later Parameters Attribute Description Required alias the alias to add under Yes storepass password for keystore integrity Must be at least 6 characters longYes keystore keystore location No storetype keystore type No keypass password for private key if different No sigalg the algorithm to use in signing No keyalg the method to use when generating name value pair No verbose true false verbose output when signing No dname The distinguished name for entity Yes if dname element unspecified validity integer indicates how many days certificate is valid No keysize integer indicates the size of key generated No Alternatively you can
280. ll override subbuild s definition of path1 lt ant antfile subbuild xml inheritrefs false gt lt reference refid path1 torefid path2 gt lt ant gt will copy the parent s definition of path1 into the new project using the id path2 9 2 AntCall Description Call another target within the same build file optionally specifying some properties param s in this context By default all of the properties of the current project will be available in the new project Alternatively you can set the inheritAll attribute to false and only user properties i e those passed on the command line will be passed to the new project In either case the set of properties passed to the new project will override the properties that are set in the new project See also the property task You can also set properties in the new project from the old project by using nested param tags These properties are always passed regardless of the setting of inheritAll This allows you to parameterize your subprojects Properties defined on the command line can not be overridden by nested lt param gt elements Nested lt reference gt elements can be used to copy references from the calling project to the new project optionally under a different id References taken from nested elements will override existing references in the new project When a target is invoked by antcall all of its dependent targets will also be called within the contex
281. lterchain gt lt loadfile gt Convenience method lt loadfile srcfile src file property sre file tail gt lt filterchain gt lt tailfilter lines 15 gt lt filterchain gt lt loadfile gt This stores the last 5 lines of the first 15 lines of the supplied data in the property src file mid lt loadfile srcfile S srce file property sre file mid gt lt filterchain gt lt filterreader classname org apache tools ant filters HeadFilter gt lt param name lines value 15 gt lt filterreader gt lt filterreader classname org apache tools ant filters TailFilter gt lt param name lines value 5 gt lt filterreader gt lt filterchain gt lt loadfile gt 50 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Convenience method lt loadfile srcfile S srce file property src file mid gt lt filterchain gt lt headfilter lines 15 gt lt tailfilter lines 5 gt lt filterchain gt lt loadfile gt 7 3 20 FilterSet FilterSets are groups of filters Filters can be defined as token value pairs or be read in from a file FilterSets can appear inside tasks that support this feature or at the same level as lt target gt e as children of lt project gt FilterSets support the id and refid attributes You can define a FilterSet with an id attribute and then refer to that d
282. lude text of the source code lines Only applies to format xml No Defaults to and type verydetailed yes sourcepath Path to source files can be set via nested sourcepath elements that are PATH like structures reference only applies to format xml A reference is a set of classes whose coverage information will be checked against Since Coverage is only able to give you information about loaded classes it will only report classes that were at least used in some points in your tests therefore you will not be able to know what classes are not exercised at all during your tests The reference is an additional feature that will analyze the bytecode of all classes in a given classpath that match some filters and modify the XML report accordingly In short it will e remove the classes that do not exists in the reference classpath For example you might have in your report some helper test classes that you do not want to appear in the report but are unable to filter without adding hundred of filters for all your classes e add classes that exists in the reference set and match the filters but are not reported e remove abstract methods that are incorrectly reported in J Probe 3 0 should be fixed in a later SP e remove classes methods that do not match the filters classpath Path to the reference set of files can be set via nested classpath elements that are PATH like structures filters Nested elements are include and exclude wi
283. lue rem gt lt param type comment value gt lt filterreader gt Convenience method lt striplinecomments gt lt comment value gt lt comment value gt lt comment value REM gt lt comment value rem gt lt comment value gt lt striplinecomments gt 7 3 18 TabsToSpaces This filter replaces tabs with spaces Parameter Name Parameter Value Required lines tablength Defaults to 8 No Examples This replaces tabs in src file with spaces lt loadfile srcfile S src file property srce file notab gt 49 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt filterchain gt lt filterreader classname org apache tools ant filters TabsToSpaces gt lt filterchain gt lt loadfile gt Convenience method lt loadfile srcfile src file property sre file notab gt lt filterchain gt lt tabstospaces gt lt filterchain gt lt loadfile gt 7 3 19 TailFilter This filter reads the last few lines from the data supplied to it Parameter Name Parameter Value Required lines Number of lines to be read Defaults to 10 No Examples This stores the last 15 lines of the supplied data in the property src file tail lt loadfile srcfile src file property sre file tail gt lt filterchain gt lt filterreader classname org apache tools ant filters TailFilter gt lt param name lines value 15 gt lt filterreader gt lt fi
284. lvssisrcsafe ini gt Connects to a SourceOffsite server on 192 168 10 6 8888 with build build as the username amp password The SourceSafe database resides on the same box as the SOS server amp the VSS database is at d vss srcsafe ini Does a recursive GetProject on SourceRoot project1 using tmp as the working directory 10 40 4 SOSLabel Description Task to perform Label commands with SOS Parameters Values Required soscmd Preston which contains soscmd exe soscmd exe must be in the path if this is not specified 267 305 Ant Manual 1 5 4 12 9 2003 7 47 PM sosserverpathladdress and port of the SOS server eg 192 168 0 1 8888Yes projectpath SourceSafe project path without the es label____ The label to apply to aproject_____ Yes Example lt soslabel username build password build label test label projectpath SourceRoot projectl sosserverpath 192 168 10 6 8888 vssserverpath d vss srcesafe ini gt Connects to a SourceOffsite server on 192 168 10 6 8888 with build build as the username amp password The SourceSafe database resides on the same box as the SOS server the VSS database is at d vss srcsafe ini Labels the SourceRoot project1 project with test label 10 40 5 SOSCheckin Description Task to perform Checkin commands with SOS Parameters sema Directory which contains soscmd exe Soscmd exe must be in the path if this is not specified hladdres
285. m lt stlist url WASHINGTON 49201 build username auser password secret rootlocalfolder srcdir2 excludes properties gt might produce this listing The status is missing because we are not going against the default folder 4368 build2 xml stlist overriding local folder to srcdir2 stlist Folder Build Local folder srcdir2 stlist Folder dev Local folder srcdir2 dev stlist Sue Developer 1 1 02 7 25 47 PM CST 4368 build xml stlist 1 1 02 7 25 49 PM CST 4368 build2 xm stlist Folder test Local folder srcdir2 dev test stlist 1 1 02 7 25 50 PM CST 4368 build2 xm 10 42 6 Starteam Deprecated This task has been deprecated Use the STCheckout task instead Description Checks out files from a StarTeam project The includes and excludes attributes function differently from other tasks in Ant Multiple patterns must be separated by spaces not commas See the examples for more information Parameters Attribute Description Required username The username of the account used to log in to the StarTeam server yes password The password of the account used to log in to the StarTeam server yes servername The name of the StarTeam server yes serverport The port number of the StarTeam server yes projectname The name of the StarTeam project yes viewname The name of the view in the StarTeam project yes targetfolder targetFolderAbsolute f
286. ma Separated list of some of the elements overview packages types constructors The taglet nested element is used to specify custom taglets This option is only available with Java 1 4 Parameters Attribute Description Required name The name of the taglet class e g Yes com sun tools doclets ToDoTaglet path A path specifying the search path for the taglet class No e g home taglets The path may also be specified by a nested lt path gt element sourcepath J avadoc s sourcepath classpath and bootclasspath attributes are PATH like classpath and structure and can also be set via nested sourcepath classpath and bootclasspath bootclasspath elements respectively Example lt javadoc packagenames com dummy test sourcepath src excludepackagenames com dummy test doc files defaultexcludes yes destdir docs api author true version true use true windowtitle Test API gt lt doctitle gt lt CDATA lt h1 gt Test lt h1 gt gt lt doctitle gt lt bottom gt lt CDATA lt i gt Copyright amp 169 2000 Dummy Corp All Rights Reserved lt i gt gt lt bottom gt lt tag name todo scope all description To do gt lt group title Group 1 Packages packages com dummy test a gt lt group title Group 2 Packages packages com dummy test b com dummy test cx gt lt link offline true href http java sun com products jdk 1 2 docs api packagelistLoc C tmp gt lt link hre
287. mation It is possible to refine the set of files that are being processed This can be done with the includes includesfile excludes excludesfile and defaultexcludes attributes With the includes or includesfile attribute you specify the files you want to have included by using patterns The exclude or excludesfile attribute is used to specify the files you want to have excluded This is also done with patterns And finally with the defaultexcludes attribute you can specify whether you want to use default exclusions or not See the section on directory based tasks on how the inclusion exclusion of files works and how to write patterns This task forms an implicit FileSet and supports all attributes of lt fileset gt dir becomes basedir as well as the nested lt include gt lt exclude gt and lt patternset gt elements This task supports the use of a nested lt param gt element which is used to pass values to an lt xsl param gt declaration This task supports the use of a nested xmlcatalog element which is used to perform Entity and URI resolution lt style gt and lt xslt gt refer to the same Ant task and can be used interchangeably If you want to use Xalan J 1 or XSL P you also need Ant s optional jar Parameters Attribute Description Required basedir where to find the source XML file default is the project s No basedir destdir directory in which to store the results Yes unless in and out have been specified ex
288. me buildfile optionally passing properties with possibly new values Apply ExecOn Executes a system command When the os attribute is specified the command is only executed when Ant is run on one of the specified operating systems Dependset his task compares a set of source files with a set of target files If any of the source iles is newer than any of the target files all the target files are removed ee ee a system command When theos attribute is specified the command is only executed when Ant is run on one of the specified operating systems ava Par ene a a Java class within the running Ant VM or in another VM if the fork attribute is specified lt parallel gt tag will be executed in its own thread Sequential A container task that can contain other Ant tasks The nested tasks are simply executed ene sequence lts primary use is to support the sequential execution of a subset of tasks within the lt parallel gt tag deployment process requires an interval between tasks aitfor Blocks execution until a set of specified conditions become true This task is intended to i used with the Parallel task to synchronize a set of processes 8 1 8 File Tasks Checksum Generates a checksum for a file or set of files This task can also be used to perform checksum verifications Chmod Changes the permissions of a file or all files inside the specified directories Currently it has effect only under Unix The permissions are also U
289. ment variables No are specified Default is false ignored if fork is disabled timeout Stop the command if it doesn t finish within the specified time given No in milliseconds It is highly recommended to use this feature only if fork is enabled Parameters specified as nested elements arg and jvmarg Use nested lt arg gt and lt jvmarg gt elements to specify arguments for the Java class and the forked VM respectively See Command line arguments sysproperty Use nested lt sysproperty gt elements to specify system properties required by the class These properties will be made available to the VM during the execution of the class either ANT s VM or the forked VM The attributes for this element are the same as for environment variables classpath Java s classpath attribute is a PATH like structure and can also be set via a nested classpath element env It is possible to specify environment variables to pass to the forked VM via nested env elements See the description in the section about exec Settings will be ignored if fork is disabled Examples lt java classname test Main gt lt arg value h gt lt classpath gt lt pathelement location dist test jar gt lt pathelement path S java class path gt lt classpath gt lt java gt Run a class in this JVM with a new jar on the classpath lt java jar dist test jar fork true failonerror true maxmemory 128m gt lt arg value h gt l
290. ml gt lt replaceregexp gt replaces all whitespaces blanks tabs etc by one blank remaining the line separator So with input lt html gt lt body gt lt lt TAB gt gt lt h1 gt TEST lt h1 gt lt lt TAB gt gt lt lt TAB gt gt lt body gt lt html gt would converted to lt html gt lt body gt lt hl gt T E S T lt h1 gt lt body gt lt html gt 10 35 Rpm Description A basic task for invoking the rpm executable to build a Linux installation file The task currently only works on Linux or other Unix platforms with rem support 259 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Parameters Attribute Description Required specFile The name of the spec File to be used Yes topDir this is the directory which will have the expected subdirectories SPECS No SOURCES BUILD SRPMS If this isn t specified the baseDir value is used cleanBuildDir This will remove the generated files in the BUILD directory No removeSpec this will remove the spec file from SPECS No removeSource Flag optional default false to remove the sources after the build See the No the rmsource option of rpmbuild command very similar idea to the cvs task the default is bb No output error where standard output and error go No 10 36 ANT ServerDeploy User Manual by e Christopher A Longo cal cloud9 net e Cyrille Morvan cmorvan ingenosya com At present the tasks support e Weblogic servers e JONAS 2 4 Ope
291. mmar file Parser jj file to build src The grammar option NODE_USES_PARSER is set to true when invoking JJ Tree 10 20 Jlink Deprecated This task has been deprecated Use the zipfileset and zipgroupfileset attributes of the Jar task or Zip task instead Description Links entries from sub builds and libraries The jlink task can be used to build jar and zip files similar to the jar task However jlink provides options for controlling the way entries from input files are added to the output file Specifically capabilities for merging entries from multiple zip or jar files is available If a mergefile is specified directly eg at the top level of a mergefiles pathelement and the mergefile ends in zip or jar entries in the mergefile will be merged into the outfile A file with any other extension will be added to the output file even if it is specified in the mergefiles element Directories specified in either the mergefiles or addfiles element are added to the output file as you would expect all files in subdirectories are recursively added to the output file with appropriate prefixes in the output file without merging In the case where duplicate entries and or files are found among the files to be merged or added jlink merges or adds the first entry and ignores all subsequent entries jlink ignores META INF directories in mergefiles Users should supply their own manifest information for the output file It is possible
292. n Attribute Description Required name the name of the attribute Yes value the value of the attribute Yes section A manifest section you can nest attribute elements into sections Attribute Description Required name the name of the section No if omitted it will be assumed to be the main section Examples lt manifest file MANIFEST MF gt lt attribute name Built By value user name gt lt section name common gt lt attribute name Specification Title value Example gt lt attribute name Specification Version value version gt lt attribute name Specification Vendor value Example Organization gt lt attribute name Implementation Title value common gt lt attribute name Implementation Version value S version TODAY gt lt attribute name Implementation Vendor value Example Corp gt lt section gt lt section name common classl class gt lt attribute name Sealed value false gt lt section gt lt manifest gt Creates or replaces the file MANIFEST MF Note that the Built By attribute will take the value of the Ant property user name The same is true for the version and TODAY properties This example produces a MANIFEST MF that contains package version identification for the package common The manifest produced by the above would look like this Manifest Version 1 0 Built By
293. n Source EJB server Over time we expect further optional tasks to support additional J 2EE Servers Task Application Servers Nested Elements serverdeplo generic Generic task jonas JOnAS 2 4 weblogic Weblogic__ 10 36 1 ServerDeploy element Description The serverdeploy task is used to run a hot deployment tool for vendor specific J 2EE server The task requires nested elements which define the attributes of the vendor specific deployment tool being executed Vendor specific deployment tools elements may enforce rules for which attributes are required depending on the tool Parameters Attribute Description Required action This is the action to be performed For most cases this will be deploy Some tools support additional actions such as delete list undeploy Yes update source A fully qualified path filename of the component to be deployed Tool This may be an ear jar war or any other type that is supported by the dependant server Nested Elements The serverdeploy task supports a nested classpath element to set the classpath 260 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Vendor specific nested elements Parameters used for all tools Attribute Description Required classpath The classpath to be passed to the JVM running the tool The classpath may Tool also be supplied as a nested element dependant server The address or URL for the server where the component will be deployed Tool
294. n a set of root classes will include all of the class files upon which the root classes depend This is typically used to create a jar with all of the required classes for a particular application classfilesets are typically used by reference They are declared with an id value and this is then used as a reference where a normal fileset is expected This type requires the jakarta BCEL library 64 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Attributes The class fileset support the following attributes in addition to those supported by the standard fileset Attribute Description Required rootclass A single root class name No Nested Elements Root When more than one root class is required multiple nested lt root gt elements may be used Attribute Description Required classname The fully qualified name of the root class Yes RootFileSet A root fileset is used to add a set of root classes from a fileset In this case the entries in the fileset are expected to be Java class files The name of the Java class is determined by the relative location of the classfile in the fileset So the file org apache tools ant Project class corresponds to the Java class org apache tools ant Project Examples lt classfileset id reqdClasses dir classes dir gt lt root classname org apache tools ant Project gt lt classfileset gt This example creates a fileset containing all the class files upon which the org apache t
295. n omitted the name of a file Each line of this file is taken to be an No include pattern Whether the generated java code is produced No Sets whether the generated java source file should be No kept after compilation The generated files will have an extension of java keep not java Whether the compiler text logo is displayed when No compiling Whether the generated java file should be replaced No when compiling Whether the compiler messages will be written to No 245 305 Ant Manual 1 5 4 sourcedir srcDir strictargs strictassign strictcase strictimport strictprops strictsignal symbols time trace utf8 verbose 12 9 2003 7 47 PM NetRexxC log as well as to the console Tells the NetRexx compiler to store the class files in the No same directory as the source files The alternative is the working directory Set the source dir to find the source NetRexx files Yes Tells the NetRexx compiler that method calls always No need parentheses even if no arguments are needed e g aStringVar getBytes vs aStringVar getBytes Tells the NetRexx compile that assignments must match No exactly on type Specifies whether the NetRexx compiler should be case No sensitive or not Whether classes need to be imported explicitly using an No import statement By default the NetRexx compiler will import certain packages automatically Whether local properties need to be qualified explicitly No using this Whether the
296. n or may be installed separately The full client install is not required In particular the Windows path must include the directory where the StarGate Runtime dll files are installed Earlier versions of Ant prior to 1 5 2 did not have this restriction because they were not as dependent on the StarTeam runtime which the newer versions use to access StarTeam file status information The older versions lacked this important capability 270 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 10 42 1 Common Parameters for All Starteam Tasks The following parameters having to do with making the connection to a StarTeam project are common to all the following tasks except the deprecated StarTeam task Attribute Description Required username The username of the account used to log in to the StarTeam yes server password The password of the account used to log in to the StarTeam yes server URL A string of the form servername portnum project view which Either this enables user to set all of these elements in one string servername The name of the StarTeam server serverport The port number of the StarTeam server Or all four of these projectname The name of the StarTeam project on which to operate must be defined viewname The name of the view in the StarTeam project on which to operate 10 42 2 STCheckout Description Checks out files from a StarTeam project The includes and excludes attributes function differently from other tas
297. n the archive No src may be used in place of the dir attribute to specify a zip file whose contents will No be extracted and included in the archive filemode A 3 digit octal string specify the user group and other modes in the standard No Unix fashion Only applies to plain files Default is 644 since Ant 1 5 2 dirmode A 3 digit octal string specify the user group and other modes in the standard No Unix fashion Only applies to directories Default is 755 since Ant 1 5 2 The fullpath attribute can only be set for filesets that represent a single file The prefix and fullpath attributes cannot both be set on the same fileset When using the src attribute include and exclude patterns may be used to specify a subset of the zip file for inclusion in the archive as with the dir attribute zipgroupfileset A lt zipgroupfileset gt allows for multiple zip files to be merged into the archive Each file found in this fileset is added to the archive the same way that zipfileset src files are added Examples lt zip destfile dist manual zip basedir htdocs manual gt zips all files in the htdocs manual directory into a file called manual zip in the dist directory lt zip destfile dist manual zip basedir htdocs manual update true gt zips all files in the htdocs manual directory into a file called manual zip in the dist directory If manual zip doesn t exist it is created otherwise it is updated with the
298. n the event of a failure errors No are considered failures as well Overrides value set in lt junit gt filtertrace Filter out J unit and Ant stack frames from error and failure No default is on stack traces Overrides value set in lt junit gt todir Directory to write the reports to No default is the current directory outfile Base name of the test result The full filename is determined No default is TEST by this attribute and the extension of formatter name where name is the name of the test specified in the name attribute if Only run test if the named property is set No unless Only run test if the named property is not set No Tests can define their own formatters via nested lt formatter gt elements 235 305 Ant Manual 1 5 4 12 9 2003 7 47 PM batchtest Define a number of tests based on pattern matching batchtest collects the included files from any number of nested lt fileset gt s It then generates a test class name for each file that ends in java or class Attribute Description Required fork Run the tests in a separate VM Overrides value set in lt junit gt No haltonerror Stop the build process if an error occurs during the test run No Overrides value set in lt junit gt errorproperty The name of a property to set in the event of an error Overrides No value set in lt junit gt haltonfailure Stop the build process if a test fails errors are considered No failures as well Override
299. name of the property to be set with true or false No depending upon whether the generated checksum matches the existing checksum When this is set the generated checksum is not written to a file or property but rather the content of the file or property is used to check against the generated checksum readbuffersize The size of the buffer in bytes to use when reading a file Defaults No to 8192 you may get a better performance on big files if you increase this value 84 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Parameters specified as nested elements fileset FileSets are used to select files to generate checksums for Examples Example 1 lt checksum file foo bar gt Generates a MD5 checksum for foo bar and stores the checksum in the destination file foo bar MD5 foo bar MD5 is overwritten only if foo bar is newer than itself Example 2 lt checksum file foo bar forceOverwrite yes gt Generates a MD5 checksum for foo bar and stores the checksum in foo bar MD5 If foo bar MD5 already exists it is overwritten Example 3 lt checksum file foo bar property foobarMD5 gt Generates a MD5 checksum for foo bar and stores it in the Project Property foobarMD5 Example 4 lt checksum file foo bar verifyProperty isMD5ok gt Generates a MD5 checksum for foo bar compares it against foo bar MD5 and sets isMD5ok to either true or false depending upon the result Example 5 lt checksum file foo b
300. nd 2 5 Open Source EJB server The task works as a directory scanning task and performs an action for each deployment descriptor found As such the includes and excludes should be set to ensure that all desired EJB descriptors are found but no application server descriptors are found For each descriptor found ejbjar will parse the deployment descriptor to determine the necessary class files which implement the bean These files are assembled along with the deployment descriptors into a well formed EJB jar file Any support files which need to be included in the generated jar can be added with the lt support gt nested element For each class included in the jar ejbjar will scan for any super classes or super interfaces These will be added to the generated jar If no nested vendor specific deployment elements are present the task will simply generate a generic EJB jar Such jars are typically used as the input to vendor specific deployment tools For each nested deployment element a vendor specific deployment tool is run to generate a jar file ready for deployment in that vendor s EJB container The jar files are only built if they are out of date Each deployment tool element will examine its target jar file and determine if it is out of date with respect to the class files and deployment descriptors that make up the bean If any of these files are newer than the jar file the jar will be rebuilt otherwise a message is logged that the jar file
301. nd files with the name Test class are excluded lt jar destfile S dist lib app jar gt lt fileset dir build classes xcludes Test class gt lt fileset dir S src resources gt lt jar gt jars all files in the build classes directory and also in the src resources directory together into a file called app jar in the dist lib directory Files with the name Test class are excluded If there are files such as build classes mypackage MyClass class and S src resources mypackage image gif they will appear in the same directory in the JAR and thus be considered in the same package by Java 117 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt jar destfile test jar basedir gt lt include name build gt lt manifest gt lt attribute name Built By value user name gt lt section name common classl class gt lt attribute name Sealed value false gt lt section gt lt manifest gt lt jar gt This is an example of an inline manifest specification Note that the Built By attribute will take the value of the Ant property user name The manifest produced by the above would look like this Manifest Version 1 0 Built By conor Created By Apache Ant 1 5alpha Name common classl class Sealed false 9 37 Java Description Executes a Java class within the running Ant VM or forks another VM if specified If odd things go wrong when you
302. ndtoken gt lt filter token DATE value TODAY gt lt filterset gt lt copy gt Copy all the docs but change all dates and appropriate notices as stored in a file lt copy toDir S dist dir docs gt lt fileset dir build dir docs gt lt include name html gt lt fileset gt lt filterset begintoken endtoken gt lt filtersfile file user dir dist properties gt lt filterset gt lt copy gt Define a FilterSet and reference it later lt filterset id myFilterSet begintoken endtoken gt lt filter token DATE value TODAY gt lt filterset gt lt copy file S build dir version txt toFile dist dir version txt gt lt filterset refid myFilterSet gt lt copy gt 7 3 21 PatternSet Patterns can be grouped to sets and later be referenced by their id attribute They are defined via a patternset element which can appear nested into a FileSet or a directory based task that constitutes an implicit FileSet In addition patternsets can be defined as a stand alone element at the same level as target i e as children of project as well as as children of target Patterns can be specified by nested lt include gt or lt exclude gt elements or the following attributes Attribute Description includes comma or space separated list of patterns of files that must be included All files are included when omit
303. nested elements lt include gt and lt exclude gt external files specified with the attributes includesfile and excludesfile external files specified with the nested elements lt includesfile gt and lt excludesfile gt When dealing with an external file each line of the file is taken as a pattern that is added to the list of include or exclude patterns When both inclusion and exclusion are used only files directories that match at least one of the include patterns and don t match any of the exclude patterns are used If no include pattern is given all files are assumed to match the include pattern with the possible exception of the default excludes Patterns As described earlier patterns are used for the inclusion and exclusion of files These patterns look very much like the patterns used in DOS and UNIX matches zero or more characters matches one character Examples java matches java x java and FooBar java but not FooBar xml does not end with java java matches x java A java but not javaor xyz java both don t have one character before java Combinations of s and s are allowed Matching is done per directory This means that first the first directory in the pattern is matched against the first directory in the path to match Then the second directory is matched and so on For example when we have the pattern abc java and the path xabc foobar test java the first abc is matched
304. new changed files lt zip destfile dist manual zip basedir htdocs manual excludes mydocs todo html gt zips all files in the htdocs manual directory Files in the directory mydocs or files with the name todo html are excluded lt zip destfile dist manual zip basedir htdocs manual includes api html excludes todo html 173 305 Ant Manual 1 5 4 12 9 2003 7 47 PM gt zips all files in the htdocs manual directory Only html files under the directory api are zipped and files with the name todo html are excluded lt zip destfile dist manual zip gt lt fileset dir htdocs manual gt lt fileset dir includes ChangeLog txt gt lt zip gt zips all files in the htdocs manual directory and also adds the file ChangeLog txt in the current directory ChangeLog txt will be added to the top of the ZIP file just as if it had been located at htdocs manual ChangeLog txt lt zip destfile dist manual zip gt lt zipfileset dir htdocs manual prefix docs user guide gt lt zipfileset dir includes ChangeLog27 txt fullpath docs ChangeLog txt gt lt zipfileset src examples zip includes html prefix docs examples gt lt zip gt zips all files in the htdocs manual directory into the docs user guide directory in the archive adds the file ChangeLog27 txt in the current directory as docs ChangeLog txt and includes all the html files in examples zip under
305. nfigure sh value defaultvalue propertyFile source name properties gt lt replacefilter token token1l gt lt replacefilter token token2 value value2 gt lt replacefilter token token3 property property key gt lt replace gt In file configure sh replace all instances of token1 with defaultvalue all instances of token2 with value2 and all instances of token3 with the value of the property property key as it appears in property file src name properties Note It is possible to use either the token lt replacetoken gt and value lt replacevalue gt attributes elements the nested replacefilter elements or both in the same operation 9 53 Rmic Description Runs the rmic compiler for a certain class Rmic can be run on a single class as specified with the classname attribute or a number of classes at once all classes below base that are neither Stub nor _Skel classes If you want to rmic a single class and this class is a class nested into another class you have to specify the classname in the form OuterS Inner instead of Outer Inner It is possible to refine the set of files that are being rmiced This can be done with the includes includesfile excludes excludesfile and defaultexcludes attributes With the includes or includesfile attribute you specify the files you want to have included by using patterns The exclude or excludesfile attribute is used to specif
306. ng Ant you can select which target s you want to have executed When no target is given the project s default is used 6 1 2 Targets A target can depend on other targets You might have a target for compiling for example and a target for creating a distributable You can only build a distributable when you have compiled first so the distribute target depends on the compile target Ant resolves these dependencies It should be noted however that Ant s depends attribute only specifies the order in which targets should be executed it does not affect whether the target that specifies the dependency s gets executed if the dependent target s did not need to run Ant tries to execute the targets in the depends attribute in the order they appear from left to right Keep in mind that it is possible that a target can get executed earlier when an earlier target depends on it lt target name A gt lt target name B depends A gt lt target name C depends B gt lt target name D depends C B A gt Suppose we want to execute target D From its depends attribute you might think that first target C then B and then A is executed Wrong C depends on B and B depends on A so first A is executed then B then C and finally D A target gets executed only once even when more than one target depends on it see the previous example 24 305 Ant Manual 1 5 4 12 9 2003 7 47 PM A target also has the ability
307. ng to the specified target architecture dirsep The character s to use as the directory separator in the No defaults to current J VM generated paths File separator pathsep The character s to use as the path element separator in No defaults to current J VM the generated paths File pathS eparator property The name of the property in which to place the converted Yes path refid What to convert given as areference to a lt path gt No if omitted a nested lt fileset gt lt dirset gt or lt filelist gt defined elsewhere lt path gt element must be supplied setonempty Should the property be set even if the result is the empty No default is true string Parameters specified as nested elements map Specifies the mapping of path prefixes between Unix and Windows Attribute Description Required From The prefix to match Note that this value is case insensitive when the build is Yes running on a Windows platform and case sensitive when running on a Unix platform To The replacement text to use when from is matched Yes Each map element specifies a single replacement map to be applied to the elements of the path being processed If no map entries are specified then no path prefix mapping is performed Note The map elements are applied in the order specified and only the first matching map element is applied So the ordering of your map elements can be important if any from values are prefixes of other from values
308. ngle dtd referenced locally in a user s home directory 63 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt xmlcatalog gt lt dtd publicId OASIS DTD DocBook XML V4 1 2 EN location home dion downloads docbook docbookx dtd gt lt xmlcatalog gt Set up an XMLCatalog with a multiple dtds to be found either in the filesystem relative to the Ant project basedir or in the classpath lt xmlcatalog id commonDTDs gt lt dtd publicId OASIS DTD DocBook XML V4 1 2 EN location docbook docbookx dtd gt lt dtd publicld Sun Microsystems Inc DTD Web Application 2 2 EN location web app_2_2 dtd gt lt xmlcatalog gt Set up an XMLCatalog with a combination of DTDs and entities as well as a nested XMLCatalog lt xmlcatalog id allcatalogs gt lt dtd publicId ArielPartners DTD XML Article V1 0 EN location com arielpartners knowledgebase dtd article dtd gt lt entity publicId LargeLogo location com arielpartners images ariel logo large gif gt lt xmlcatalog refid commonDTDs gt lt xmlcatalog gt To reference the above XMLCatalog in an xs1t task lt xslt basedir source doc destdir dest xdocs extension xml style S source xsl converter docbook includes x xml force true gt lt xmlcatalog refid allcatalogs gt lt xslt gt 7 4 Optional Types 7 4 1 ClassFileSet A classfileset is a specialised type of fileset which give
309. nize ccc as nce egstilnededggad eee digtede een Pepto ened E tddi 14 4 122 Source EGIM ON 24 gaat oes So SRA ony ha ns a ee a ed ee 14 4 2 System R UE ES ii 14 4 3 installing ANE iii eee Reve AA pe cane ea 14 Ar A a tees sd secon A ces CRUEL Oh E AT A ILAP Blas GARE IMC tt 15 4 3 2 Optional Tasks is A otis eae haw eee eee 15 4 3 3 WINKOWS iii E A Mei ia ee A eens 15 43 4 URI DAS eee rris A a 16 43 5 UNIX ESA secede eieid odes cece evs E eed seaev ee EYE Suu iiue vA admeuede evs Saumeees 16 A336 Advance iio eia ds 16 4 4 Building ANE iii ida daa 16 4 5 Library Dependencies ii A eee 17 4 6 Platform ISSUE Sina eoe A ia tea 18 A UNE A hah tempus E tee uah ata a nodeep AR aao k a 18 4 6 2 Microsoft WiNdOWS ocoooccocccnnnnccnnnnncnnnnn rr ne ene nna enna enna enna 19 1037 APPIE MacOS A rais Stee Ea EA ah cide cas os Oe dhe Rael EEEE nhs 19 4 6 4 Novell Netware cccccccc cece eee e cece eee enn n eee ee en RE AEE EEE EDD ran ESSER DESEO rra 19 4 6 5 Other plathonms cod o NL lo eas 20 Be RUNNING ANE rt A ey ends gded eases ddl Adi 21 5 1 Command LINE viciomicicn a a cc 21 5 2 CYQWINHUSORS init EA emg A A Ea 23 5 3 RUANING Ata JAVA ba adt di 23 6 USING ANT a e SOO e o e ro 24 6 1 Writing a Simple Buildfile ooo a a ri 24 Ck NE A O A 24 A Targets ye Ne AN 24 6 153 O a E T 25 6 14 PEOPerteS a ie ede eea da read pod de 26 6 1 5 Built in Properties aers raini reiini i eee ee EE eee nese AEEY enay 26 6 1 6 Exampl
310. nored 5 uptodate This condition is identical to the Uptodate task all attributes and nested elements of that task are supported the property and value attributes are redundant and will be ignored os Test whether the current operating system is of a given type Each defined attribute is tested and the result is true only if all the tests succeed Attribute Description Required version The version of the operating system to expect Supported values for the family attribute are windows for all versions of Microsoft Windows dos for all Microsoft DOS based operating systems including Microsoft Windows and OS 2 mac for all Apple Macintosh systems unix for all Unix and Unix like operating systems netware for Novell NetWare os 2 for OS 2 win9x for Microsoft Windows 95 and 98 z os for z OS and OS 390 89 305 Ant Manual 1 5 4 equals isset checksum iL 2 filesmatch E W 9 14 Copy Description 12 9 2003 7 47 PM Tests whether the two given Strings are identical Attribute Description Required argh ist sing toes Ensesensitucpertorm a case sensitive comparision Defaultls tue Wo rim whitespace from arguments before comparing then E Default i is false Test whether a property has been set in this AttributeDescription Required This condition is identical to the Checksum task all attributes and nested elements of that task are supported the property and overwrite attributes
311. ns executable not found on the path 5 Which version of ant are you running Other applications distribute a copy it may be being picked up by accident 6 If a task is failing to run is optional jar in ANT_HOME lib Are there any libraries which it depends on missing 7 Ifa task doesn t do what you expect run ant verbose or ant debug to see what is happening If you can t fix your problem start with the Ant User Mailing List These are other ant users who will help you learn to use ant If they cannot fix it then someone may suggest filing a bug report which will escalate the issue Remember of course that support like all open source development tasks is voluntary If you haven t invested time in helping yourself by following the steps above it is unlikely that anyone will invest the time in helping you Also if you don t understand something the Ant User Mailing List is the place to ask questions Not the developer list nor the individuals whose names appears in the source and documentation If they answered all such emails nobody would have any time to improve ant To provide feedback on this software please subscribe to the Ant User Mailing List If you want to contribute to Ant or stay current with the latest development join the Ant Development Mailing List Archives of both lists can be found at http archives apache org eyebrowse ViewLists A searchable archive can be found at http marc theaimsgroup com If you kno
312. nt listener MailLogger Extends DefaultLogger such that output is BuildLogger still generated the same and when the build is finished an e mail can be sent org apache tools ant listener AnsiColorLogge Colorifies the build output Buildlogger org apache tools ant listener Log4jListener Passes events to Log4j for highly BuildListene customizable logging org apache tools ant XmlLogger Writes the build information to an XML file BuildLogger 11 2 1 DefaultLogger Simply run Ant normally or ant logger org apache tools ant DefaultLogger 11 2 2 NoBannerLogger Removes output of empty target output ant logger org apache tools ant NoBannerLogger 11 2 3 MailLogger The MailLogger captures all output logged through DefaultLogger standard Ant output and will send success and failure messages to unique e mail lists with control for turning off success or failure messages individually Properties controlling the operation of MailLogger 302 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Property MailLogger mailhost___ Mailservertouse_ IN default localhost Mail from address Yes if mail needs to be sent MailLogger failure notify Send build failure e mails No default true N MailLogger success notify Send build success e mails o default true Address es to send failure messages to Yes if failure mail is to be MailLogger failure to comma separated sent Mailtogger uccess to Address es to send succ
313. nt variables if set e JAVACMD full path of the Java executable Use this to invoke a different JVM than JAVA_HOME bin java exe 22 305 Ant Manual 1 5 4 12 9 2003 7 47 PM e ANT_OPTS command line arguments that should be passed to the JVM For example you can define system properties or set the maximum Java heap size here e ANT_ARGS Ant command line arguments For example set ANT_ARGS to point to a different logger include a listener and to include the fina flag Note If you include find in ANT_ARGS you should include the name of the build file to find even if the file is called build xml 5 2 Cygwin Users The Unix launch script that come with Ant works correctly with Cygwin You should not have any problems launching Ant form the Cygwin shell It is important to note however that once Ant is runing it is part of the JDK which operates as a native Windows application The JDK is not a Cygwin executable and it therefore has no knowledge of the Cygwin paths etc In particular when using the lt exec gt task executable names such as bin sh will not work even though these work from the Cygwin shell from which Ant was launched You can use an executable name such as sh and rely on that command being available in the Windows path 5 3 Running Ant via Java If you have installed Ant in the do it yourself way Ant can be started with java Dant home c lant org apache tools ant Main options target Thes
314. o build xml This file is expected to be a filename relative to the dir attribute given the directory to use as a basedir for the new Ant project Defaults to the current No project s basedir unless inheritall has been set to false in which case it doesn t have a default value This will override the basedir setting of the called project arget the target of the new Ant project that should be executed Defaults to the new project s default target Filename to write the ant 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 project otherwise inheritAll lf true pass all properties to the new Ant project Defaults to true inheritRefs lf true pass all references to the new Ant project Defaults to false Parameters specified as nested elements property 74 305 Ant Manual 1 5 4 12 9 2003 7 47 PM See the description of the property task Note that the refid attribute points to a reference in the calling project not in the new one reference Used to chose references that shall be copied into the new project optionally changing their id Attribute Description____________b Required he id of the reference in the calling project he id of the reference in the new project No defaults to the value of refid Basedir of the new project The basedir value of the new project is affected by the two attributes dir and inheritall see the following_ table
315. o project and that is default if this attribute isn t specified label Only files marked with this label are extracted No promotiongroup Only files within this promotion group are extracted Using both the label No and the promotiongroup tag will cause the files in the promotion group and with that label to be extracted force If set to yes all files that exists and are writable are overwritten Default No no causes the files that are writable to be ignored This stops the PVCS command get to stop asking questions workspace By specifying a workspace the files are extracted to that location A PVCS No workspace is a name for a location of the workfiles and isn t as such the location itself You define the location for a workspace using the PVCS GUI clients If this isn t specified the default workspace for the current user is used pvcsbin On some systems the PVCS executables pcli and get are not found in the No PATH In such cases this attribute should be set to the bin directory of the PVCS installation containing the executables mentioned before If this attribute isn t specified the tag expects the executables to be found using the PATH environment variable ignorereturncode If set to true the return value from executing the pvcs commands are No ignored updateonly If set to true files are gotten only if newer than existing local files No filenameformat The format of your folder names in a format suitable for No java text
316. o true or false default read in the compiler settings files csc rsp in its bin directory and then the local directory optimize optimisation flag true or false default to e eee include enn should work directory winexe or librar lunsafe enabletheunsafe keyword true or false default format 4 with 4 being the strictest Wwin32Icon_ filename oficontoinclude_____ res myicon ico to include This is not a NET resource but it what windows is used to Example lt csc optimize true debug false docFile documentation xml warnLevel 4 unsafe false targetType exe incremental false definitions RELEASE excludes src unicode_class cs mainClass MainApp destFile NetApp exe gt 10 1 2 lt ilasm gt Task to assemble net Intermediate Language files The task will only work on windows until other platforms support csc exe or an equivalent ilasm exe must be on the execute path too All parameters are optional lt il gt should suffice to produce a debug build of all il files The option set is roughly compatible with the CSharp class even though the command line options are only vaguely equivalent The low level commands take things like OUT file csc wants out file verbose is used some places quiet here in ildasm etc It would be nice if someone made all the command line tools consistent and not as brittle as the java cmdline
317. o ASCII prior to compilation Files in the directory src are converted from a native encoding to ASCII By default all files in the directory are converted However conversion may be limited to selected files using includes and excludes attributes For more information on file matching patterns see the section on directory based tasks If no encoding is specified the default encoding for the JVM is used If ext is specified then output files are renamed to use it as a new extension More sophisticated file name translations can be achieved using a nested lt mapper gt element By default an identity mapper will be used If dest and src point to the same directory the ext attribute or a nested lt mapper gt is required This task forms an implicit File Set and supports all attributes of lt fileset gt dir becomes src as well as nested lt include gt lt exclude gt and lt patternset gt elements Attribute Description Required 243 305 Ant Manual 1 5 4 12 9 2003 7 47 PM reverse Reverse the sense of the conversion i e convert from ASCII to native No encoding ivy encoding the files are in default is the default encoding for the No src The directory to find files in default is basedir No dest The directory to output file to Yes ext File extension to use in renaming output files No indicates whether default excludes should be used or not yes no Default excludes are used when omitted comma or space separated list
318. o false the underlying OS s shell either directly or through the 106 305 Required Exactly one of the two No No No No No No No No No No default is false No default is true Ant Manual 1 5 4 12 9 2003 7 47 PM antRun scripts will be used Under some operating systems this gives access to facilities not normally available through the VM including under Windows being able to execute scripts rather than their associated interpreter If you want to specify the name of the executable as a relative path to the directory given by the dir attribute it may become necessary to set vmlauncher to false as well Examples lt exec dir S src executable cmd exe os Windows 2000 output dir txt gt lt arg line c dir gt lt exec gt Parameters specified as nested elements arg Command line arguments should be specified as nested lt arg gt elements See Command line arguments env It is possible to specify environment variables to pass to the system command via nested lt env gt e Attribute key value path file Errors a lements Description Required The name of the environment variable Yes The literal value for the environment variable The value for a PATH like environment variable You can use or as path separators and Ant will convert it to the platform s local conventions The value for the environment variable Will be replaced by the absolute filename of the
319. o search in Yes toExtension The string that renamed files will end with on completion Yes Examples lt renameext srcDir source project1 includes excludes samples fromExtension java keep toExtension java replace true gt 257 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 10 34 ReplaceRegExp Description ReplaceRegExp is a directory based task for replacing the occurrence of a given regular expression with a substitution pattern in a selected file or set of files The output file is only written if it differs from the existing file This prevents spurious rebuilds based on unchanged files which have been regenerated by this task Similar to regexp type mappers this task needs a supporting regular expression library and an implementation of org apache tools ant util regexp Regexp Ant comes with implementations for the java util regex package of JDK 1 4 jakarta regexp and jakarta ORO but you will still need the library itself There are cross platform issues for matches related to line terminator For example if you use to anchor your regular expression on the end of a line the results might be very different depending on both your platform and the regular expression library you use It is highly recommended that you test your pattern on both Unix and Windows platforms before you rely on it e Jakarta Oro defines a line terminator as 1n and is consistent with Perl e Jakarta RegExp uses a system dependant line
320. o send to the server and responses to wait for are described as nested elements read declare as a text child of this element a string to wait for The element supports the timeout attribute which overrides any timeout specified for the task as a whole It also has a string attribute which is an alternative to specifying the string as a text element Always declare an opening and closing lt read gt element to ensure that statements are not sent before the connection is ready and that the connection is not broken before the final command has completed write describes the text to send to the server The echo boolean attribute controls whether the string is echoed to the local log this is true by default Examples A simple example of connecting to a server and running a command This assumes a prompt of ogin for the userid and a prompt of assword for the password 281 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt telnet userid bob password badpass server localhost gt lt read gt home bob lt read gt lt write gt ls lt write gt lt read string home bob gt lt telnet gt This task can be rewritten as net server localhost gt read gt ogin lt read gt write gt bob lt write gt read gt assword lt read gt ite gt badpass lt write gt read gt home bob lt read gt write gt ls lt write gt read gt home bob lt read gt lnet gt lt t 5 1 lt lt lt lt lt
321. ods from com mycompany except all methods starting by test on the class MyClass in the package com mycompany triggers Define a number of events to use for interacting with the collection of data performed during coverage For example you may run a whole application but only decide to collect data once it reaches a certain method and once it exits another one The only type of nested element is the method element triggers are performed on method and it has the following attributes Attribute Description Required name The name of the method s as a regular expression The name is the fully Yes qualified name on the form package classname method event the event on the method that will trigger the action Must be enter or exit Yes action the action to execute Must be one of clear pause resume Snapshot Yes suspend or exit They respectively clear recording pause recording resume recording take a snapshot suspend the recording and exit the program Example of triggers lt triggers gt lt method name ClassName event enter action Snapshot gt lt method name ClassName MethodName event exit action exit gt lt triggers gt Will take a snapshot when it enters any method of the class ClassName and will exit the program once it exits the method MethodName of the same class 10 21 3 JPCovMerge Description Perform the merge of several snapshots into a single one Parameters Attribute Descri
322. of course that selector can be a container Here is an example of how to use the Selector Reference lt project default all basedir ant gt lt selector id completed gt lt none gt lt depend targetdir build classes gt lt mapper type glob from java to class gt lt depend gt lt depend targetdir docs manual api gt lt mapper type glob from java to html gt lt depend gt lt none gt lt selector gt lt target gt lt zip gt lt fileset dir src main includes Java gt lt selector refid completed gt lt fileset gt lt zip gt lt target gt lt project gt Zips up all the Java files which have an up to date equivalent class file and javadoc file associated with them 7 3 22 17 CUSTOM SELECTORS You can write your own selectors and use them within the selector containers by specifying them within the lt custom gt tag First you have to write your selector class in Java The only requirement it must meet in order to be a selector is that it implements the 60 305 Ant Manual 1 5 4 12 9 2003 7 47 PM org apache tools ant types selectors FileSelector interface which contains a single method See Programming Selectors in Ant for more information Once that is written you include it in your build file by using the lt custom gt tag Attribute Description Required classname The name of your class that implements Yes org apache tools ant types selec
323. of patterns of files that must be included All files are included when omitted includesfile the name of a file Each line of this file is taken to be an include pattern No comma or space separated list of patterns of files that must be excluded No files except default excludes are excluded when omitted excludesfile the name of a file Each line of this file is taken to be an exclude pattern No defaultexcludes No includes No excludes Examples lt native2ascii encoding EUCJIS src srcdir dest srcdir includes x eucjis ext java gt Converts all files in the directory srcdir ending in eucjis from the EUCJ IS encoding to ASCII and renames them to end in java lt native2ascii encoding EUCJIS src native japanese dest src includes java gt Converts all the files ending in java in the directory native japanese to ASCII placing the results in the directory src The names of the files remain the same 10 29 NetRexxC Description Compiles a NetRexx source tree within the running Ant VM The source and destination directory will be recursively scanned for NetRexx source files to compile Only NetRexx files that have no corresponding class file or where the class file is older than the java file will be compiled Files in the source tree are copied to the destination directory allowing support files to be located properly in the classpath The source files are copied because the NetRexx comp
324. of the build sysclasspath property control how the system classpath ie the classpath in effect when Ant is run affects the behaviour of classpaths in Ant The default behavior varies from Ant to Ant task The values and their meanings are Only the system classpath is used and classpaths specified in build files etc are ignored This situation could be considered as the person running the build file knows more about the environment than the person writing the build file The system classpath is ignored This situation is the reverse of the above The person running the build trusts the build file writer to get the build file right The classpath is concatenated to any specified classpaths at the end This is a compromise where the build file writer has priorit Any specified classpaths are concatenated to the system classpath This is the other form of compromise where the build runner has priority 7 2 Common Attributes of all Tasks All tasks share the following attributes Attribute Description Required id Unique identifier for this task instance can be used to reference this task in No scripts taskname A different name for this task instance will show up in the logging output No description Room for your comments No 7 3 Core Types 7 3 1 Description Description Allows for a description of the project to be specified that will be included in the output of the ant projecthelp command Parameters none Examples
325. og No classpath The classpath containg jars and classes for which lt depend gt should also check No dependencies Parameters specified as nested elements The depend task s classpath attribute is a PATH like structure and can also be set via a nested lt classpath gt element Additionally this task forms an implicit FileSet and supports all attributes of lt fileset gt dir becomes srcdir as well as the nested lt include gt lt exclude gt and lt patternset gt elements Examples lt depend srcdir java dir destdir S build classes cache depcache closure yes gt removes any classes in the build classes directory that depend on out of date classes Classes are considered out of date with respect to the source in the java dir directory using the same mechanism as the lt javac gt task In this example the lt depend gt task caches its dependency information in the depcache directory lt depend srcdir java dir destdir build classes cache depcache closure yes gt lt include name Jjava gt lt excludesfile name java dir build_excludes gt lt depend gt does the same as the previous example but explicitly includes all java files except those that match the list given in java dir build_excludes 10 7 Ant EJB Tasks User Manual by Paul Austin p_d_austin yahoo com Holger Engels hengels innovidata com Tim Fennell tfenne rcn com Martin Gee martin gee
326. oken The starting token to identify keys Yes endtoken The ending token to identify keys Yes bundle Family name of resource bundle Yes bundlelanguage Locale specific language of resource bundle Defaults to default locale s No language bundlecountry Locale specific country of resource bundle Defaults to default locale s No country bundlevariant Locale specific variant of resource bundle Defaults to the default variant of No the country and language being used srcencoding Source file encoding scheme Defaults to system default file encoding No destencoding Destination file encoding scheme Defaults to source file encoding No bundleencoding Resource Bundle file encoding scheme Defaults to source file encoding No forceoverwrite Overwrite existing files even if the destination files are newer Defaults to No no Parameters specified as nested elements fileset FileSets are used to select files that contain keys for which value translated files are to be generated Examples Translate source file encoded in english into its japanese equivalent using a resource bundle encoded in japanese lt translate toDir dest dir ja starttoken endtoken bundle resource BaseResource bundlelanguage ja forceoverwrite yes srcencoding 1S08859_1 estencoding SJIS undleencoding SJIS gt fileset dir sre dir gt lt include name jsp gt lt fileset gt lt translate gt Ao Q
327. oldername force recursion verbose includes The folder to which files are checked out What this precisely means is yes determined by the targetFolderAbsolute param Determines how targetfolder is interpreted that is whether the StarTeam default folder for the project is factored in false or whether targetFolder is a complete mapping to foldername true If no true the target tree will be rooted at targetfolder default folder If false the target tree will be rooted at targetfolder Defaults to false The subfolder in the project from which to check out files Overwrite existing folders if this is set to true Defaults to false Indicates if subfolders should be searched for files to check out Defaults to true Provides progress information Defaults to false Only check out files that match at least one of the patterns in this list no 278 305 no no no no Ant Manual 1 5 4 excludes Examples lt starteam 12 9 2003 7 47 PM Patterns must be separated by spaces Patterns in excludes take precedence over patterns in includes Do not check out files that match at least one of the patterns in this no list Patterns must be separated by spaces Patterns in excludes take precedence over patterns in includes servername STARTEAM gt The minimum serverport 49201 projectname AProject viewname AView username auser password secret targetfolder C 1devibu
328. omparison see below dateFormat Format of dates in fromDate and toDate Used when calculating dates with the No numdays attribute This string uses the formatting rules of SimpleDateFormat Defaults to DateFormat SHORT fromLabel Start label for comparison No toLabel Start label for comparison No numdays The number of days for comparison A output File to write the diff No recursive true or false No style brief codediff default or nofile The default is default No user Name the user whose changes we would like to see No Specifying the time frame There are different ways to specify what time frame you wish to evaluate e Changes between two dates Specify both fromDate and toDate 295 305 Ant Manual 1 5 4 12 9 2003 7 47 PM e Changes before a date Specify toDate e Changes after a date Specify fromDate e Changes X Days before a date Specify toDate and negative numDays e Changes X Days after a date Specify fromDate and numDays Examples lt vsshistory vsspath myProject recursive true fromlabel Releasel toLabel Release2 gt Shows all changes between Releasel and Release2 lt vsshistory vsspath myProject recursive true fromDate 01 01 2001 toDate 31 03 2001 gt Shows all changes between January 1st 2001 and March 31st 2001 in Germany date must be specified according to your locale lt tstamp gt lt format property to tstamp pattern M d yy h mma gt lt tstamp gt lt v
329. on it will be added to the repository Also it will write a comment to the repository for this version of the file lt stcheckin URL STARTEAM 49201 Aproject AView username auser password secret rootstarteamfolder src java rootlocalfolder C dev buildtest co forced true gt lt stcheckin URL STARTEAM 49201 Aproject AView username auser password secret rootstarteamfolder src java gt lt stcheckin URL STARTEAM 49201 Aproject AView username auser password secret rootstarteamfolder src java rootlocalfolder C dev buildtest co src java forced true gt In the preceding three examples assuming that the AProject project has a default folder of C work buildtest co AProject the first example will check in files from a tree rooted at C dev buildtest co the second from a tree rooted at C work buildtest co AProject src java and the third from a tree rooted at C dev buildtest co src java all to a tree rooted at src java 10 42 4 STLabel Description Creates a view label in StarTeam at the specified view The label will be classified by StarTeam as a build label This task will fail if there already exexists in viewname a label with the same name as the label parameter Parameters See also the required common StarTeam parameters Attribute Description Required label The name to be given to the label yes lastbuild The timestamp of the build that will be stored with t
330. ondition gt task See here for the full list Examples 167 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt waitfor maxwait 30 maxwaitunit second gt lt available file errors log gt lt waitfor gt waits up to 30 seconds for a file called errors log to appear lt waitfor maxwait 3 maxwaitunit minute checkevery 500 gt lt http url http localhost myapp index html gt lt waitfor gt waits up to 3 minutes and checks every 500 milliseconds for a web server on localhost to serve up the specified URL lt waitfor maxwait 10 maxwait second gt lt and gt lt socket server dbserver port 1521 gt lt http url http webserver mypage html gt lt and gt lt waitfor gt waits up to 10 seconds for a server on the dbserver machine to begin listening on port 1521 and for the http webserver mypage html web page to become available 9 68 War Description An extension of the Jar task with special treatment for files that should end up in the WEB INF lib WEB INF classes or WEB INF directories of the Web Application Archive The War task is a shortcut for specifying the particular layout of a WAR file The same thing can be accomplished by using the prefix and fullpath attributes of zipfilesets in a Zip or Jar task The extended zipfileset element from the zip task with attributes prefix fullpath and src is available in the War task Parameters Attribute Description Required destfile
331. ools ant Project class depends This fileset could then be used to create a jar lt jar destfile minimal jar gt lt fileset refid reqdClasses gt lt jar gt lt classfileset id reqdClasses dir fclasses dir gt lt rootfileset dir S classes dir includes org apache tools ant Project class gt lt classfileset gt This example constructs the classfileset using all the class with names starting with Project in the org apache tools ant package 7 4 2 Extension Utility type that represents either an available Optional Package formerly known as Standard Extension as described in the manifest of aJAR file or the requirement for such an optional package Note that this type works with extensions as defined by the Optional Package specification For more information about optional packages see the document Optional Package Versioning in the documentation bundle for your Java2 Standard Edition package ls guide extensions versioning html or online at http j ava sun com 2se 1 3 docs quide extensions versioning html 65 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Attributes The extension type supports the following attributes Attribute Description Required extensionName The name of extension yes specificationVersion The version of extension specification Must be in dewey decimal no aka dotted decimal notation 3 2 4 specificationVendor The specification vendor no implementationVers
332. opy todir S dist gt lt fileset dir S src includes images excludes gif gt lt copy gt This copies all files in directories called images that are located in the directory tree defined by src to the destination directory defined by dist but excludes all gif files from the copy lt copy todir S dist gt lt fileset dir src gt lt include name images gt lt exclude name gif gt lt fileset gt lt copy gt 35 305 Ant Manual 1 5 4 12 9 2003 7 47 PM The same as the example above but expressed using nested elements lt delete dir S dist gt lt include name images gt lt exclude name gif gt lt delete gt Deleting the original set of files the delete task can act as an implicit fileset Default Excludes There are a set of definitions that are excluded by default from all directory based tasks They are Ke LK BK LR xx LEX xk SKS xe CVS CVS cvsignore SCCS SCCS vssver scc svn suvn x DS_Store If you do not want these default excludes applied you may disable them with the defaultexcludes no attribute 7 3 3 DirSet DirSets are groups of directories These directories can be found in a directory tree starting in a base directory and are matched by patterns taken from a number of PatternSets DirSets can appear inside tasks that support this feature or at the
333. or characters Ant will convert the separator to the correct character of the current operating system Wherever path like values need to be specified a nested element can be used This takes the general form of lt classpath gt lt pathelement path classpath gt lt pathelement location lib helper jar gt lt classpath gt The location attribute specifies a single file or directory relative to the project s base directory or an absolute filename while the path attribute accepts colon or semicolon separated lists of locations The path attribute is intended to be used with predefined paths in any other case multiple elements with location attributes should be preferred As a Shortcut the lt classpath gt tag supports path and location attributes of its own so lt classpath gt lt pathelement path classpath gt lt classpath gt can be abbreviated to lt classpath path S classpath gt 28 305 Ant Manual 1 5 4 12 9 2003 7 47 PM In addition DirSets FileSets and FileLists can be specified via nested lt dirset gt lt fileset gt and lt filelist gt elements respectively Note The order in which the files building up a FileSet are added to the path like structure is not defined lt classpath gt lt pathelement path classpath gt lt fileset dir lib gt lt include name Jjar gt lt fileset gt lt pathelement location classes gt lt dirset dir build di
334. or of Ant way too many times Tools like Jam took care of this to a great degree but still have yet another format to use and remember Ant is different Instead of a model where it is extended with shell based commands Ant is extended using Java classes Instead of writing shell commands the configuration files are XML based calling out a target tree where various tasks get executed Each task is run by an object that implements a particular Task interface Granted this removes some of the expressive power that is inherent in being able to construct a shell command such as find name foo xec rm but it gives you the ability to be cross platform to work anywhere and everywhere And hey if you really need to execute a shell command Ant has an lt exec gt task that allows different commands to be executed based on the OS it is executing on 13 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 4 Installing Ant 4 1 Getting Ant 4 1 1 Binary Edition The latest stable version of Ant is available from the Ant web page http ant apache org If you like living on the edge you can download the latest version from http cvs apache org builds ant nightly 4 1 2 Source Edition If you prefer the source edition you can download the source for the latest Ant release from http ant apache org srcdownload cgi Again if you prefer the edge you can access the code as it is being developed via CVS The Jakarta website has details on
335. ote tool server format lt servername gt lt port no gt eae attribute is set the tasks will be executed on the specified tool server haltonerror Stop the build process if an error occurs default yes no Parameters specified as nested elements fileset A FileSet specifies the files to import 287 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Example lt vajimport project Test importClasses true gt lt fileset dir import dir gt lt include name com sample class gt lt exclude name com sample test gt lt fileset gt lt vajimport gt This example imports all class files in the directory import dir com sample excluding those in the subdirectory test 10 47 7 The Plugin The tasks are usable within VAJ by running the org apache tools ant Main class but this is quite inconvenient Therefore a small GUI is provided which allows selecting a build file and executing its targets This Plugin is accessible from the VAJ Tools menu see Usage Installation We assume C IBMVJ ava as VAJ install directory If You have installed it elsewhere adapt the pathes below Plugin e Create the directory C IBMVJ aval ide tools org apache tools ant e Expand in that directory all the jars contained in the lib directory of your Ant installation e copy default ini in org apache tools ant taskdefs optional ide to C I BMVJ ava ide tools org apache tools ant default ini e if you want to acces
336. ou are running this task For Unix platforms the default is remove For DOS based systems including Windows the default is add N B One special case is recognized The three characters CR CR LF are regarded as a single EOL Unless this property is specified as asis this sequence will be converted into the specified EOL type Used only in association with the tab attribute see below this boolean No attribute indicates whether the fileset is a set of java source files yes no Defaults to no See notes in section on tab Specifies how tab characters are to be handled Valid values for this No property are add convert sequences of spaces which span a tab stop to tabs asis leave tab and space characters alone remove convert tabs to spaces Default for this parameter is asis N B When the attribute javafiles see above is true literal TAB characters occurring within Java string or character constants are never modified This functionality also requires the recognition of J ava style comments N B There is an incompatibility between this and the previous version in the handling of white space at the end of lines This version does not 110 305 Ant Manual 1 5 4 12 9 2003 7 47 PM remove trailing whitespace on lines tablength TAB character interval Valid values are between 2 and 80 inclusive The No default for this parameter is 8 eof Specifies how DOS end of file control Z characters are to
337. ound Plays a sound file at the end of the build according to whether the build failed or Succeeded plash read in from a text file using the src attribute or from between the enclosing SQL tags askdef Adds a task definition to the current project such that this new task can be used in the Stamp Sets the DSTAMP TSTAMP and TODAY properties in the current project based on the current date and time pedef Adds a data type definition to the current project such that this new type can be used in the current project mlValidate Checks that XML files are valid or only well formed This task uses the XML parser that used by Ant by default but any SAX1 2 parser can be specified if needed 8 1 13 NET Tasks NET Tasks See the documentation describing the NET tasks 8 1 14 Pre process Tasks ANTLR Invokes the ANTLR Translator generator on a grammar file AntStructure Generates a DTD for Ant buildfiles that contains information about all tasks currently known to Ant IContract Instruments Java classes using the Contract DBC preprocessor This task can generate a properties file for iControl a graphical user interface that lets you turn on off assertions lavacc nvokes the JavaCC compiler compiler on a grammar file lavan Generates JNI headers from a J ava class Invokes the Tree preprocessor for the JavaCC compiler compiler It inserts parse tree building actions at various places in the J avaCC source that it generat
338. overriden Examples lt input gt Will pause the build run until return key is pressed when using the default InputHandler the concrete behavior is defined by the InputHandler implementation you use lt input gt Press Return key to continue lt input gt Will display the message Press Return key to continue and pause the build run until return key is pressed again the concrete behavior is implementation dependent lt input message Press Return key to continue 114 305 Ant Manual 1 5 4 12 9 2003 7 47 PM gt Will display the message Press Return key to continue and pause the build run until return key is pressed see above lt input message All data is going to be deleted from DB continue y n validargs y n addproperty do delete gt lt condition property do abort gt lt equals argl n arg2 S do delete gt lt condition gt lt fail if do abort gt Build aborted by user lt fail gt Will display the message All data is going to be deleted from DB continue y n and require y to continue build or n to exit build with following message Build aborted by user lt input message Pleas nter db username addproperty db user gt Will display the message Please enter db username and set the property db user to the value entered by the user 9 36 Jar Description Jars a set of files The basedir attribute is the reference directory
339. oves far more class files The classpath attribute for lt depend gt is optional If it is present depend will check class dependencies against classes and jars on this classpath Any classes which depend on an element from this classpath and which are older than that element will be deleted A typical example where you would use this facility would be where you are building a utility jar and want to make sure classes which are out of date with respect to this jar are rebuilt You should not include jars in this classpath which you do not expect to change such as the JDK runtime jar or third party jars since doing so will just slow down the dependency check This means that if you do use a classpath for the depend task it may be different from the classpath necessary to actually compile your code Performance The performance of the depend task is dependent on a number of factors such as class relationship complexity and how many class files are out of date The decision about whether it is cheaper to just recompile all classes or to use the depend task will depend on the size of your project and how interrelated your classes are Limitations There are some source dependencies which depend will not detect e If the Java compiler optimizes away a class relationship there can be a source dependency without a class dependency e Non public classes cause two problems Firstly depend cannot relate the class file to a source file In the future th
340. p D lt property gt lt value gt use value for given property propertyfile lt name gt load all properties from file with D properties taking precedence inputhandler lt class gt the class which will handle input requests find lt file gt search for buildfile towards the root of the filesystem and use it For more information about logger and listener see Loggers amp Listeners For more information about inputhandler see nputHandler Examples ant runs Ant using the build xml file in the current directory on the default target ant buildfile test xml runs Ant using the test xml file in the current directory on the default target ant buildfile test xml dist runs Ant using the test xml file in the current directory on the target called dist ant buildfile test xml Dbuild build classes dist runs Ant using the test xml file in the current directory on the target called dist setting the build property to the value build classes Files The Ant wrapper script for Unix will source read and evaluate the file antrc before it does anything On Windows the Ant wrapper batch file invokes HOME lantrc_pre bat at the start and HOME antrc_post bat at the end You can use these files for example to set unset environment variables that should only be visible during the execution of Ant See the next section for examples Environment Variables The wrapper scripts use the following environme
341. pathelement path S build dir mergebar jar gt lt mergefiles gt lt addfiles gt lt pathelement path S build dir mac jar gt lt pathelement path build dir pc zip gt lt addfiles gt lt jlink gt Non deprecated alternative to the above lt jar compress false destfile out jar gt lt zipgroupfileset dir S build dir gt lt include name mergefoo jar gt lt include name mergebar jar gt lt zipgroupfileset gt lt fileset dir build dir gt lt include name mac jar gt lt include name pc jar gt lt fileset gt lt jar gt Suppose the file foo jar contains two entries bar class and barnone myClass zip Suppose the path for file foo jar is build tempbuild foo jar The following example will provide the entry tempbuild foo jar in the out jar lt jlink compress false outfile out jar gt lt mergefiles gt lt pathelement path build tempbuild gt lt mergefiles gt lt jlink gt However the next example would result in two top level entries in out jar namely bar class and barnone myClass zip lt jlink compress false outfile out jar gt lt mergefiles gt lt pathelement path build tempbuild foo jar gt lt mergefiles gt lt jlink gt 227 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 10 21 j Probe By Stephane Bailliez Sbailliez imediation com 10 21 1 Introduction This task runs the tools from the J Probe suite For more info
342. pe text html messageFile overview summary html tolist you subject JUnit Test Results TODAY from me gt Sends all files in a directory as attachments lt mimemail message See attached files tolist you subject Attachments from me gt lt fileset dir gt lt include name dist gt lt fileset gt lt mimemail gt 10 27 MParse By Stephane Bailliez Sbailliez imediation com Requirements This task requires Metamata Development environment 2 0 freely available at Metamata Description Invokes the Metamata MParse compiler compiler on a grammar file To use the mparse task set the target attribute to the name of the grammar file to process You also need to specify the directory containing the Metamata installation using the metamatahome attribute so that Ant can find the MParse classes This task only invokes MParse if the grammar file is newer than the generated J ava files MParse assumes that the Java class name of the generated parser is the same as the name of the grammar file less the jj extension For additional information about MParse please consult the online manual available here PDF Parameters Attribute Description Required target The jj grammar file to process It will only be processed if the Yes grammar is newer than the corresponding java file metamatahome The home directory containing the Metamata distribution Yes verbose Enable all messages No debugparser En
343. pend on the out of date classes forcing the re compile of the removed classfiles Typically used in conjunction with the avac task Compiles the specified source file s within the running Ant VM or in another VM if the fork attribute is specified Runs the JSP compiler It can be used to precompile J SP pages for fast initial invocation of 68 305 Ant Manual 1 5 4 12 9 2003 7 47 PM SP pages deployment on a server without the full J DK installed or simply to syntax check the pages without deploying them The avac task can be used to compile the generated Java source For Weblogic JSP compiles see the Wlispc task INetRexxC Compiles a NetRexx source tree within the running Ant VM IRmic Runs the rmic compiler on the specified file s a ee JSP pages using Weblogic s JSP compiler weblogic jspc For non Weblogic J SP compiles see the spC task 8 1 4 Deployment Tasks ServerDeployTask to run a hot deployment tool for vendor specific J 2EE server 8 1 5 Documentation Tasks deprecated use the Javadoc task instead ersion of this tool all three arguments are required to run the Stylebook task 8 1 6 EJB Tasks Task Name Description EJB Tasks See the documentation describing the EJB tasks 8 1 7 Execution Tasks Ant Runs Ant on a supplied buildfile optionally passing properties with possibly new alues This task can be used to build sub projects AntCall Runs another target within the sa
344. pped Ant with the parameters passed to the build script In this case these parameters define an Ant property value and specify the dist target in Ant s own build xml file On most occasions you will not need to explicitly bootstrap Ant since the build scripts do that for you If however the build file you are using makes use of features not yet compiled into the bootstrapped Ant you will need to manually bootstrap Run bootstrap bat Windows or bootstrap sh UNIX to build a new bootstrap version of Ant If you wish to install the build into the current ANT_HOME directory you can use build install Windows build sh install Unix You can avoid the lengthy Javadoc step if desired with build install lite Windows build sh install lite Unix This will only install the bin and 1ib directories Both the install and install lite targets will overwrite the current Ant version in ANT_HOME 4 5 Library Dependencies The following libraries are needed in your CLASSPATH or in the install directory s lib directory if you are using the indicated feature Note that only one of the regexp libraries is needed for use with the mappers You will also need to install the Ant optional jar containing the task definitions to make these tasks available Please refer to the Installing Ant Optional Tasks section above Jar Name Needed For Available At An XSL style task http xml apache org xalan j index html
345. precated Use lt javac gt s nowarn attribute instead 9 39 Javadoc J avadoc2 Description Generates code documentation using the javadoc tool The source directory will be recursively scanned for Java source files to process but only those matching the inclusion rules and not matching the exclusions rules will be passed to the javadoc tool This allows wildcards to be used to choose between package names reducing verbosity and management costs over time This task however has no notion of changed files unlike the javac task This means all packages will be processed each time this task is run In general however this task is used much less frequently This task works seamlessly between different javadoc versions 1 1 1 2 and 1 4 with the obvious restriction that the 1 2 attributes will be ignored if run in a 1 1 VM NOTE since javadoc calls System exit javadoc cannot be run inside the same VM as ant without breaking functionality For this reason this task always forks the VM This overhead is not significant since javadoc is normally a heavy application and will be called infrequently 125 305 Ant Manual 1 5 4 12 9 2003 7 47 PM NOTE the packagelist attribute allows you to specify the list of packages to document outside of the Ant file It s a much better practice to include everything inside the build xml file This option was added in order to make it easier to migrate from regular makefiles where you would use
346. properties Q property Classes dir dir2 A properties Qlasses dir dir2 A property regexp Both to and from define regular expressions If the source file name matches the from pattern the target file name will be constructed from the to pattern using 10 to 9 as back references for the full match 10 or the matches of the subexpressions in parentheses Source files not matching the from pattern will be ignored Note that you need to escape a dollar sign with another dollar sign in Ant The regexp mapper needs a supporting library and an implementation of org apache tools ant util regexp RegexpMatcher that hides the specifics of the library Ant comes with implementations for the java util regex package of JDK 1 4 jakarta regexp and jakarta ORO If you compile from sources and plan to use one of them make sure the libraries are in your CLASSPATH For information about using gnu regexp or gnu rex with Ant see this article This means you need optional jar from the Ant release you are using and one of the supported regular expression libraries Make sure both will be loaded from the same classpath that is either put them into your CLASSPATH ANT_HOME 1ib directory or a nested lt classpath gt element of the mapper you cannot have optional jar in ANT_HOME 1ib and the library in a nested lt classpath gt Ant will choose the regular expression library based on the following algorithm 41 305 Ant Manual 1 5 4 12 9 200
347. ption Required home The directory where J Probe is installed Yes tofile the output filename that will be the result of the name Yes verbose Perform the merge in verbose mode giving details about the snapshot No Default to processing false jpcovmerge collects snapshots using the nested lt FileSet gt element Example of merge lt jpcovmerge home c jprobe tofile merge jpc verbose true gt lt fileset dir snapshots gt lt include name snap jpc gt lt fileset gt 230 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt jpcovmerge gt would run the merge in verbose mode on all snapshot files starting by snap in the directory snapshots The resulting file will be named merge jpc 10 21 4 JPCovReport Description Generate a readable printable report of a snapshot Note that you will need Jakarta Oro in Ant classpath to run the reference feature Parameters Attribute Description Required home The directory where J Probe is intalled Yes format The format of the generated report Must be xml html or text No default to html type The type of report to be generated Must be executive No Default to summary detailed or verydetailed detailed percent A numeric value for the threshold for printing methods Must be No default to 100 between 0 and 100 snapshot The name of the snapshot file that is the source to the report Yes tofile The name of the generated output file Yes includesource Inc
348. quired description Description for ChangeList If none specified it will default to AutoSubmit By No Ant Examples lt p4change description Change Build Number in Script gt 10 30 7 P4Edit Description Open file s for edit P4Change should be used to obtain a new changelist for P4Edit as although P4Edit can open files to the default change P4Submit cannot yet submit it Parameters Attribute Description Required view The filespec to request to edit Yes change An existing changelist number to assign files to No but see above Examples lt p4edit view depot projects projectfoo main src Blah java change p4 change gt 10 30 8 P4Submit Description Submit a changelist usually obtained from P4Change Parameters Attribute Description Required change The changelist number to submit Yes Examples lt p4submit change p4 change gt 249 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 10 30 9 P4Have Description List handy file info reflecting the current client contents Parameters Attribute Description Required None Examples lt p4have gt 10 30 10 P4Label Description Create a new label and set contents to reflect current client file revisions Parameters Attribute Description Required name The name of the label Yes view client view to use for label No desc Label Description No lock Lock the label once created No Examples lt p4label name NightlyBuild DSTAMP S T
349. r gt lt include name apps classes gt lt exclude name apps Test gt lt dirset gt lt filelist refid third party_jars gt lt classpath gt E This builds a path that holds the value of classpath followed by all jar files in the lib directory the classes directory all directories named classes under the apps subdirectory of build dir except those that have the text Test in their name and the files specified in the referenced FileList If you want to use the same path like structure for several tasks you can define them with a lt path gt element at the same level as targets and reference them via their id attribute see References for an example A path like structure can include a reference to another path like structure via nested lt path gt elements lt path id base path gt lt pathelement path classpath gt lt fileset dir lib gt lt include name 3jar gt lt fileset gt lt pathelement location classes gt lt path gt lt path id tests path gt lt path refid base path gt lt pathelement location testclasses gt lt path gt The shortcuts previously mentioned for lt classpath gt are also valid for lt path gt For example lt path id base path gt lt pathelement path classpath gt lt path gt can be written as lt path id base path path classpath gt 29 305 Ant
350. r password secret targetfolder C 1devibuildtestico targetfolderabsolute false gt lt starteam servername STARTEAM serverport 49201 projectname AProject foldername src java viewname AView username auser password secret targetfolder C dev buildtest co src java targetfolderabsolute true gt In the preceding three examples assuming that the AProject project has a default folder of AProject the first example will check the files located in starteam under src java out to a tree rooted at C dev buildtest co the second to a tree rooted at C dev buildtest co AProject src java and the third to a tree rooted at C dev buildtest co src java 10 43 Stylebook Description This executes the apache Stylebook documentation generator Unlike the commandline version of this tool all three arguments are required to run stylebook Note This task depends on external libraries not included in the Ant distribution See Library Dependencies for more information Being extended from lt Java gt all the parent s attributes and options are available Do not set any apart from the classpath as they are not guaranteed to be there in future Parameters Attribute Description Required book the book xml file that the documentation generation starts from Yes skindirectory the directory that contains the stylebook skin Yes targetdirectory the destination directory where the docum
351. ram name module expression ant gt lt param name cvsweb expression http cvs apache org viewcvs gt lt style gt Sample Output lt changelog gt lt entry gt lt date gt 2002 03 06 lt date gt lt time gt 12 00 lt time gt lt author gt Peter Donald lt author gt lt file gt lt name gt org apache myrmidon build AntlibDescriptorTask java lt name gt lt revision gt 1 3 lt revision gt lt prevrevision gt 1 2 lt prevrevision gt lt file gt lt msg gt lt CDATA Use URLs directly rather than go via a FIle This allows temp lates to be stored inside jar gt lt msg gt lt entry gt lt changelog gt 9 19 cvspass Description Adds entries to a cvspass file Adding entries to this file has the same affect as a cvs login command Parameters Attribute Description Required cvsroot the CVS repository to add an entry for Yes password Password to be added to the password file Yes passfile Password file to add the entry to No default is cvspass Examples lt cvspass cvsroot pserver anoncvs cvs apache org home cvspublic password anoncvs gt Adds an entry into the cvspass password file 9 20 CvsTagDiff Description Generates an XML formatted report file of the changes between two tags or dates recorded in a CVS repository Important This task needs cvs on the path If it isn t you will get an error such as error 2 on windows If lt cvs gt doesn t work try to ex
352. rcdir build dir destdir solant ejb dir descriptordir descriptor dir basejarname Address gt lt weblogictoplink destdir S solant ejb dir classpath S java class path keepgeneric false toplinkdescriptor Address xml toplinkdtd file dtdfiles toplink cmp_2_5_1 dtd suffix jar gt lt include name ejb jar xml gt 200 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt exclude name weblogic ejb jar xml gt lt ejbjar gt This final example shows how you would set up ejbjar under Weblogic 6 0 It also shows the use of the lt support gt element to add support files lt ejbjar descriptordir dd dir srcdir build classes server gt lt include name ejb jar xml gt lt exclude name weblogic ejb jar xml gt lt support dir S build classes server gt lt include name class gt lt support gt lt weblogic destdir deployment dir keepgeneric true suffix Jar rebuild false gt lt classpath gt lt pathelement path S build classes server gt lt classpath gt lt wlclasspath gt lt pathelement path weblogic classes gt lt wlclasspath gt lt weblogic gt lt ejbjar gt 10 7 3 4WEBSPHERE ELEMENT The websphere element searches for the websphere specific deployment descriptors and adds them to the final ejb jar file Websphere has two specific descriptors for session beans e ibm e
353. rchain gt elements are used inside the same lt copy gt task all lt filterchain gt elements are processed first followed by lt filterset gt elements Examples Copy a single file lt copy file myfile txt tofile mycopy txt gt Copy a single file to a directory lt copy file myfile txt todir some other dir gt Copy a directory to another directory lt copy todir new dir gt lt fileset dir src_dir gt lt copy gt Copy a set of files to a directory lt copy todir dest dir gt lt fileset dir src_dir gt lt exclude name java gt lt fileset gt lt copy gt lt copy todir dest dir gt lt fileset dir src_dir excludes Java gt lt copy gt Copy a set of files to a directory appending bak to the file name on the fly lt copy todir backup dir gt lt fileset dir src_dir gt lt mapper type glob from to bak gt lt copy gt Copy a set of files to a directory replacing OTI TLE with Foo Bar in all files lt copy todir backup dir gt lt fileset dir src_dir gt lt filterset gt lt filter token TITLE value Foo Bar gt lt filterset gt lt copy gt Unix Note File permissions are not retained when files are copied they end up with the default UMASK permissions instead This is caused by the lack of any means to query or set 92 305 Ant Manual 1 5 4 12 9 2003 7 47 PM file permissions in the curren
354. rder version date label Parameters Attribute Values Required SourceSafe path which specifies the project file s you wish to perform vsspath the action on You should not specify the leading dollar sign it is Yes prepended by Ant automatically usernamel password The username and password needed to get access to VSS Note that you may need to specify both if you have a password login Ant VSS will hang if you leave the password out and VSS does not No accept login without a password localpath Override the working directory and get to the specified path No directory where ss exe resides By default the task expects it to be in the ssdir No PATH serverPath directory where ss ini resides No writable true or false lt default false td gt No 293 305 Ant Manual 1 5 4 12 9 2003 7 47 PM true or false default false Note however that in the SourceSafe UI there is a setting accessed via Tools Options GeneralTab called Act on No iv Paha oe projects recursively If this setting is checked then the recursive attribute is effectively ignored and the get will always be done recursively version a version number to get No only one date a date stamp to get at of these label a label to get for allowed quiet suppress output off by default No autoresponse What to respond with sets the I option By default I is used values No of Y or N will be appended to this Note that only one of version date or
355. red showSuccess a boolean value indicating whether tests should display a message on No success showBanner a boolean value indicating whether a banner should be displayed when No starting testlet engine forceShowTrace a boolean indicating that a stack trace is displayed on any failure No showTrace a boolean indicating that a stack trace is displayed on error but not normal No failure The user can also specify the nested lt classpath gt element which defines classpath in which the task is executed The user also specifies a subele ment per testlet executed which has content that specifies tasklet classname Examples lt test showSuccess false showBanner false showTrace true forceShowTrace true gt lt classpath refid test classpath gt lt testlet gt org foo MyTestlet lt testlet gt lt testlet gt org foo MyOtherTestlet lt testlet gt lt test gt The above will run the testlets org foo MyTestlet and org foo MyOtherTestlet 10 46 Translate Description Identifies keys in files delimited by special tokens and translates them with values read from resource bundles A resource bundle contains locale specific key value pairs A resource bundle is a hierarchical set of property files A bundle name makes up its base family name Each file that makes up this bundle has this name plus its locale For example if the resource bundle name is MyResources the file that contains German text will take the name MyR
356. represents a PATH like structure sourcepath Sets the search path to use as the use domain when looking for unused global declarations The searchpath element represents a PATH like structure fileset 240 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Sets the J ava files to audit via a FILESET structure Whatever the filter is only the files that ends with java will be included for processing Note that the base directory used for the fileset MUST be the root of the source files otherwise package names deduced from the file path will be incorrect Example lt maudit tofile c metamata examples auditexamples audit xml netamatahome c metamata fix yes gt lt classpath gt lt pathelement location c metamata examples auditexamples gt lt classpath gt lt sourcepath gt lt pathelement location c metamata examples auditexamples gt lt sourcepath gt lt fileset dir c metamata examples auditexamples gt lt include name java gt lt fileset gt lt maudit gt This invokes Metamata Audit installed in c metamata on the audit examples and fix automatically the fixable errors Generating a report As a convenience there is an XSL file mmetrics frames xsl that allows you to generate a full framed HTML report of the metrics You can find it in the etc directory of Ant As it uses the Xalan redirect extensions you will need Xalan and Xerces to run it The stylesheet takes an output d
357. res the class files in the build directory The classpath used includes xyz jar and debug information is on Only files under mypackage p1 and mypackage p2 are used All files in and below the mypackage pl testpackage directory are excluded from compilation lt javac srcdir src src2 destdir S build includes mypackage p1 mypackage p2 excludes mypackage pl testpackage classpath xyz jar debug on gt is the same as the previous example with the addition of a second source path defined by the property src2 This can also be represented using nested lt src gt elements as follows lt javac destdir build classpath xyz jar debug on gt lt src path src gt lt src path src2 gt lt include name mypackage p1 gt lt include name mypackage p2 gt lt exclude name mypackage pl testpackage gt lt javac gt If you want to run the javac compiler of a different JDK you should tell Ant where to find the compiler and which version of JDK you will be using so it can choose the correct command line switches The following example executes a JDK 1 1 javac in a new process and uses the correct command line switches even when Ant is running in a Java VM of a different version lt javac srcdir S src 124 305 Ant Manual 1 5 4 12 9 2003 7 47 PM destdir build fork yes executable opt java jdk1 1 bin javac compiler javacl1 1 gt Note If you
358. resent targetdir dest gt lt mapper type glob from java to class gt lt present gt lt none gt lt fileset gt Selects only Java files which do not have equivalent java or class files in the dest directory 7 3 22 14 NOT SELECTOR The lt not gt tag reverses the meaning of the single selector it contains Here is an example of how to use the Not Selector lt fileset dir src includes Java gt lt not gt lt contains text test gt lt not gt lt fileset gt Selects all the files in the src directory that do not contain the string test 59 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 7 3 22 15 OR SELECTOR The lt or gt tag selects files that are selected by any one of the elements it contains It returns as soon as it finds a selector that selects the file so it is not guaranteed to check every selector Here is an example of how to use the Or Selector lt fileset dir basedir gt lt or gt lt depth max 0 gt lt filename name png gt lt filename name gif gt lt filename name jpg gt lt or gt lt fileset gt Selects all the files in the top directory along with all the image files below it 7 3 22 16 SELECTOR REFERENCE The lt selector gt tag is used to create selectors that can be reused through references It is the only selector which can be used outside of any target as an element of the lt project gt tag It can contain only one other selector but
359. ression j compression method Allowable values are none gzip and bzip2 No Default is none Nested Elements The tar task supports nested tarfileset elements These are extended Filesets which in addition to the standard fileset elements support three additional attributes Attribute Description Required mode A 3 digit octal string specify the user group and other modes in No the standard Unix fashion username The username for the tar entry This is not the same as the UID No which is not currently set by the tar task group The groupname for the tar entry This is not the same as the GID No which is not currently set by the tar task prefix If the prefix attribute is set all files in the fileset are prefixed with No that path in the archive 158 305 Ant Manual 1 5 4 12 9 2003 7 47 PM fullpath If the fullpath attribute is set the file in the fileset is written with No that path in the archive The prefix attribute if specified is ignored It is an error to have more than one file specified in such a fileset preserveLeadingSlashes Indicates whether leading s should be preserved in the file No names Default is false Examples lt tar tarfile S dist manual tar basedir htdocs manual gt lt gzip zipfile S dist manual tar gz src dist manual tar gt tars all files in the htdocs manual directory into a file called manual tar in the dist directory then applies the gzip task to compress it
360. ription Blocks execution until a set of specified conditions become true This is intended to be used with the parallel task to synchronize a set of processes The conditions to wait for are defined in nested elements if multiple conditions are specified then the task will wait until all conditions are true If both maxwait and maxwaitunit are not specified the maxwait is 3 minutes 180000 milliseconds If the timeoutproperty attribute has been set a property of that name will be created if the condition didn t come true within the specified time Parameters Attribute Description Required maxwait The maximum amount of time to wait for all the required conditions to No become true before failing the task Defaults to 180000 maxwaitunits maxwaitunit The unit of time that must be used to interpret the value of the maxwait No attribute Defaults to millisecond Valid Values are e millisecond second minute hour day week checkevery The amount of time to wait between each test of the conditions No Defaults to 500 checkeveryunits checkeveryunit The unit of time that must be used to interpret the value of the checkevery No attribute Defaults to millisecond Valid Values are millisecond second minute hour day week timeoutproperty the name of the property to set if maxwait has been exceeded No Nested Elements The available conditions that satisfy the lt waitfor gt task are the same as those for the lt c
361. rmation visit http www sitraka com An evaluation version is available for download if you already don t own it This task has been written using J Probe Suite Server Side 3 0 It is highly recommended to read the J Probe documentation to understand the values of the command line arguments described below This document is less complete than the manual it only gives the basic information and is not intended as a replacement to the manual 10 21 2 JPCoverage Perform code covering functions by comparing source code line execution to the program s source code as a whole Parameters Attribute Description Required home The directory where J Probe is intalled Yes vm Indicates which virtual machine to run Must be one of jdk117 jJdk118 No or java2 1f java2 is specified the user is also required to specify a path default to via javaexe otherwise it will check if the current executing VM is 1 2 and embedded use its java home property to determine its location VM if 1 2 javaexe The path to the java executable No use only for java2 vm applet Run an applet The default is false unless the file under analysis ends with No htm or html default is false seedname Seed name for the temporary snapshot files files will be named seed jpc No seedl jpc seed2 jpc default to snapshot exitprompt Toggles display of the console prompt Press Enter to close this window No always Always displays the prompt never Never di
362. rom behind a firewall lt ftp server ftp nt org remotedir c uploads userid coder 209 305 Ant Manual 1 5 4 12 9 2003 7 47 PM password Javal separator verbose yes lt fileset dir htdocs manual gt lt include name html gt lt fileset gt lt ftp gt Logs in to the Windows based ftp nt org as coder with password javal and uploads all HTML files in the htdocs manual directory to the c uploads directory Progress messages are displayed as each file is uploaded 10 9 2 Getting Files Getting files from an FTP server works pretty much the same way as sending them does The only difference is that the nested filesets use the remotedir attribute as the base directory for the files on the FTP server and the dir attribute as the local directory to put the files into The file structure from the FTP site is preserved on the local machine lt ftp action get server ftp apache org userid anonymous password me myorg com gt lt fileset dir htdocs manual gt lt include name html gt lt fileset gt lt ftp gt Logs in to ftp apache org aS anonymous and recursively downloads all html files from default directory for that user into the htdocs manual directory on the local machine 10 9 3 Deleting Files As you ve probably guessed by now you use nested fileset elements to select the files to delete from the remote FTP server Again the filesets are relative to the remote directory not
363. rootstarteamfolder is used and a status field will appear in the listing Otherwise the status field will not appear includes Only list files that match at least one of the patterns in this list Patterns no must be separated by commas Patterns in excludes take precedence over patterns in includes excludes Do not list files that match at least one of the patterns in this list no Patterns must be separated by commas Patterns in excludes take precedence over patterns in includes label List files dates and statuses as of this label The label must exist in no starteam or an exception will be thrown If not specified the most recent version of each file will be listed recursive Indicates if subfolders should be searched for files to list Defaults to no true Examples lt stlist url WASHINGTON 49201 build username auser password secret The above command might produce the following listing stlist Folder Build Default folder C work build stlist Folder dev Default folder C work build dev stlist Out of dat Sue Developer 1 1 02 7 25 47 PM CST 4368 build xml stlist Missing George Hacker 1 1 02 7 25 49 PM CST 36 Test0l properties stlist Current 1 1 02 7 25 49 PM CST 4368 build2 xml stlist Folder test Default folder C work build dev test 277 305 Ant Manual 1 5 4 stlist Missing 12 9 2003 7 47 PM 1 1 02 7 25 50 PM CST while adding a rootlocalfolder and an excludes para
364. roperties match 0ldProperty replace NewProperty 11 258 305 Ant Manual 1 5 4 12 9 2003 7 47 PM byline true gt replaces occurrences of the property name OldProperty with NewProperty in a properties file preserving the existing value in the file src build properties Parameters specified as nested elements This task supports a nested FileSet element This task supports a nested Regexp element to specify the regular expression You can use this element to refer to a previously defined regular expression datatype instance lt regexp id id pattern expression gt lt regexp refid id gt This task supports a nested Substitution element to specify the substitution pattern You can use this element to refer to a previously defined substitution pattern datatype instance lt substitution id id pattern expression gt lt substitution refid id gt Examples lt replaceregexp byline true gt lt regexp pattern 0ldProperty gt lt substitution expression NewProperty 11 gt lt fileset dir gt lt includes properties gt lt fileset gt lt replaceregexp gt replaces occurrences of the property name OldProperty with NewProperty in a properties file preserving the existing value in all files ending in properties in the current directory lt replaceregexp match s replace flags g byline true gt lt fileset dir html dir includes ht
365. rror attribute specifies how to proceed when an error occurs during the execution of one of the statements The possible values are continue execution only show the error stop execution and commit transaction and abort execution and transaction and fail task Parameters Attribute Description Required driver Class name of the jdbc driver Yes 151 305 Ant Manual 1 5 4 12 9 2003 7 47 PM url Database connection url Yes userid Database user name Yes password Database password Yes src File containing SQL statements Yes unless statements enclosed within tags encoding The encoding of the files containing SQL statements No defaults to default JVM encoding delimiter String that separates SQL statements No default autocommit Auto commit flag for database connection default false No default false print Print result sets from the statements default false No default false showheaders Print headers for result sets from the statements No default true default true output Output file for result sets defaults to System out No print to System out by default append whether output should be appended to or overwrite an No existing file Defaults to false classpath Class path used to load driver No use system classpath classpathref The classpath to use given as a reference to a path No use system classpath defined elsewhere onerror Action to perform when statement fails continue stop No default abort abort rdbms Exe
366. rsion qualifiers Amended documentation this file accordingly 2001 06 14 Now all tasks can access VAJ via Remote Access To Tool API Therefore builds containing VAJ tasks can also be executed from the command line Kudos to Glenn McAllister for describing the concept and providing source code at http www7 software ibm com vad nsf Data Document4366 It is possible to cancel a running build executed from the plugin Improved error handling in the plugin Now all errors should show up either in the log window or in the console 10 47 3 The Tasks At the moment there are three tasks which help integrating the VAJ repository contents into an external build process VA Load lloads specified versions into the workspace VAJ Exportlexports specified packages into the file syste VAJ Importlimports specified files into the workspace These tasks are described in detail below 285 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 10 47 4 VAJLoad Description Loads a specified VAJ project version into the workspace Parameters Attribute Description Required remote name and port of a remote tool server format lt servername gt lt port no gt no If this attribute is set the tasks will be executed on the specified tool server haltonerror Stop the build process if an error occurs default yes no Parameters specified as nested elements vajproject Attribute Description Required name name of the VAJ project to load into the worksp
367. rty file For type date an additional keyword is allowed now type Regard the value as int date or string default No operation or default for all datatypes No for date and int only pattern For int and date type only If present Values will be parsed and No formatted accordingly unit The unit of the value to be applied to date operations Valid No Values are millisecond second minute hour day default week month year This only applies to date types using a operation The rules used when setting a property value are shown below The operation occurs after these rules are considered e f only value is specified the property is set to it regardless of its previous value e f only default is specified and the property previously existed in the property file it is unchanged e If only default is specified and the property did not exist in the property file the property is set to default e If value and default are both specified and the property previously existed in the property file the property is set to value e If value and default are both specified and the property did not exist in the property file the property is set to default Examples The following changes the my properties file Assume my properties look like A comment akey novalue After running the file would now look like Thu Nov 02 23 41 47 EST 2000 akey avalue adate 2000 11 02 23 41 anint 1 formated int
368. s The files and or directories of a number of FileSets are passed as arguments to the system command If you specify a nested mapper and the dest attribute the timestamp of each source file is compared to the timestamp of a target file which is defined by the nested mapper element and searched for in the given dest At least one fileset is required and you must not specify more than one mapper Parameters Attribute Description_______________________ Required he directory where the lt apply gt expects the target files will be placed Yes if you by the command when it is executed specify a nested mapper whether the filenames should be passed on the command line as No default is absolute or relative pathnames relative to the base directory of the corresponding fileset for source files or the dest attribute for target iles whether output should be appended to or overwrite an existing file Defaults to false If you set parallel to false you will probably want to set this one to true he name of a property in which the output of the command should be No stored o resultproperty he name of a property in which the return code of the command N should be stored Only of inte rest if failonerror false If you set parallel to false only the result of the first execution will be stored imeout Stop the command if it doesn t finish within the specified time given in milliseconds 78 305 Ant Manual 1 5 4 12 9 2
369. s srcfileset The nested srcfileset element specifies a FileSet All files included in this fileset will be compared against all files included in all of the targetfileset filesets and targetfilelist filelists Multiple srcfileset filesets may be specified 102 305 Ant Manual 1 5 4 12 9 2003 7 47 PM srcfilelist The nested srcfilelist element specifies a FileList All files included in this filelist will be compared against all files included in all of the targetfileset filesets and targetfilelist filelists Multiple srcfilelist filelists may be specified targetfileset The nested targetfileset element specifies a FileSet All files included in this fileset will be compared against all files included in all of the srcfileset filesets and sourcefilelist filelists and if any are older they are all deleted targetfilelist The nested targetfilelist element specifies a FileList All files included in this filelist will be compared against all files included in all of the srcfileset filesets and sourcefilelist filelists and if any are older they are all deleted Examples lt dependset gt lt srcfilelist dir S dtd dir files paper dtd common dtd gt lt srcfilelist dir S xsl dir files common xsl gt lt srcfilelist dir S basedir files build xml gt lt targetfileset dir S output dir includes html gt lt dependset gt In this ex
370. s selected from a fileset are concatenated is not guaranteed If this is an issue use multiple filesets or consider using filelists filelist FileLists are used to select files to be concatenated The file ordering in the files attribute will be the same order in which the files are concatenated Examples Concatenate a string to a file lt concat destfile README gt Hello World lt concat gt Concatenate a series of files to the console lt concat gt lt fileset dir messages includes important gt lt concat gt Concatenate a single file appending if the destination file exists lt concat destfile NOTES append true gt lt filelist dir notes files note txt gt lt concat gt 87 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Concatenate a series of files overwriting if the destination file exists lt concat destfile docbook dir all sections xml gt lt filelist dir docbook dir sections files introduction xml overview xml gt lt fileset dir docbook dir includes sections xml excludes introduction xml overview xml gt lt concat gt 9 13 Condition Description Sets a property if a certain condition holds true this is a generalization of Available and Uptodate If the condition holds true the property value is set to true by default otherwise the property is not set You can set the value to something other than the default by speci
371. s these additional attributes Attribute Description Required toplinkdescriptor This specifies the name of the TOPLink deployment Yes descriptor file contained in the descriptordir directory toplin kdtd This specifies the location of the TOPLink DTD file This can No defaults to dtd file be a file path or a file URL at This attribute is not required but using a local DTD is www objectpeople com recommended Examples This example shows ejbjar being used to generate deployment jars using a Weblogic EJ B container This example requires the naming standard to be used for the deployment descriptors Using this format will create a ejb jar file for each variation of ejb jar xml that is found in the deployment descriptor directory lt ejbjar srcdir build classes descriptordir descriptor dir gt lt weblogic destdir deploymentjars dir classpath descriptorbuild classpath gt lt include name eJb jar xml gt lt exclude name weblogic xml gt lt ejbjar gt 199 305 Ant Manual 1 5 4 12 9 2003 7 47 PM If weblogic is not in the Ant classpath the following example shows how to specify the location of the weblogic DTDs This example also show the use of a nested classpath element lt ejbjar descriptordir src dir srcdir build classes gt lt weblogic destdir deployment webshop dir keepgeneric true args g keepgenerated S ejbc compiler suffix jar oldCMP
372. s with description to allow the build file developer to distinguish between targets for end users and helper targets Q Is there a sample build file available A Now you can find an example in this manual Q Why does it export my entire workspace when I ve already implicitly selected a project when starting the Tool A This selection does not carry into the buildfile you are using Set the Project name at the beginning of the includes parameter Q When I import Ant into my Workspace get Problems reported Can ignore them 291 305 Ant Manual 1 5 4 12 9 2003 7 47 PM A It depends on the problems reported and what you want to do with Ant Problems you can t ignore e Classes from javax xml parser missing install a compatible parser see installation e Classes from com ibm ivj util missing install the Visual Age IDE Utility feature see installation e Errors in optional tasks you use within your build file Q want to use the same buildfile both within Visual Age and from the command line using my regular Ant environment What do need to be aware of A You have to specifie a remote server via the remote attribute Otherwise the three Visual Age tasks won t work when executing Ant from the command line Q I can export packages from project ABC but not from project XYZ Why A Common reasons are e The project is excluded by the default excludes see attribute defaultexcludes of VAJ Export e When
373. s a registered trademark of MERANT 10 33 RenameExtensions Deprecated This task has been deprecated Use the move task with a glob mapper instead Description Renames files in the srcDir directory ending with the fromExtension string so that they end with the toExtension string Files are only replaced if replace is true See the section on directory based tasks on how the inclusion exclusion of files works and how to write patterns This task forms an implicit FileSet and supports all attributes of lt fileset gt dir becomes srcDir as well as the nested lt include gt lt exclude gt and lt patternset gt elements Parameters Attribute Description Required defaultexcludes indicates whether default excludes should be used or not yes no No Default excludes are used when omitted excludes comma or space separated list of patterns of files that must be excluded No No files except default excludes are excluded when omitted excludesfile the name of a file Each line of this file is taken to be an exclude pattern No fromExtention The string that files must end in to be renamed Yes includes comma or space separated list of patterns of files that must be included No All files are included when omitted includesfile the name of a file Each line of this file is taken to be an include pattern No replace Whether the file being renamed to should be replaced if it already exists No srcDir The starting directory for files t
374. s and port of the SOS server eg 192 168 0 1 8888 SourceSafe project path without the Filename to act upon If no file is specified then act upon the project username __ SourceSafe username o SourceSafe username A r eae E rue or false Status messages are displayed No comment A comment to be applied to all files being checked in Example lt soscheckin username build password build file foobar txt verbose true comment comment abc projectpath SourceRoot projecti sosserverpath serverl 8888 vssserverpath server2 vss srcsafe ini gt 268 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Connects to a SourceOffsite server on server1 8888 with build build as the username password The SourceSafe database resides on a different box server2 amp the VSS database is on a share called vss Checks in only the foobar txt file adding a comment of comment abc Extra status messages will be displayed on screen 10 40 6 SOSCheckOut Description Task to perform CheckOut commands with SOS Parameters Directory which contains soscmd exe Soscmd exe must be in the path if this is not specified es eoo o ee to act upon If no file is specified then act upon the project password SourceSafe password _ __ O O No localpath Override the working directory and get to the specified path No soshome The path to the SourceOffSite home directory __ Mo Example lt soscheckout soscmd usr
375. s false Host name of the SMTP server The default value is No localhost TCP port of the SMTP server The default value is 25 No Specifies the encoding to use for the content of the email No Values are mime uu plain or auto The default value is auto 133 305 elements One of these ora Ant Manual 1 5 4 12 9 2003 7 47 PM subject Email subject line No Parameters specified as nested elements to cc bcc from Adds an email address element It takes the following attributes Attribute Description Required name The display name for the address No address The email address Yes message Specifies the message to include in the email body It takes the following attributes Attribute Description Required src The file to use as the message No mimetype The content type to use for the No message If the src attribute is not specified then text can be added inside the lt message gt element Property expansion will occur in the message whether it is specified as an external file or as text within the lt message gt element Examples lt mail from me tolist you subject Results of nightly build files build log gt Sends an email from me to you with a subject of Results of nightly build and includes the contents of the file build log in the body of the message lt mail mailhost smtp myisp com mailport 1025 subject Test build gt lt from address me myisp com gt lt to address all xyz
376. s is done by placing the property name between and in the attribute value For example if there is a builddir property with the value build then this could be used in an attribute like this builddir classes This is resolved at run time as build classes 6 1 5 Built in Properties Ant provides access to all system properties as if they had been defined using a lt property gt task For example os name expands to the name of the operating system For a list of system properties see the Javadoc of System getProperties In addition Ant has some built in properties 26 305 Ant Manual 1 5 4 basedir ant file ant version ant project name ant java version 6 1 6 Example Buildfile 12 9 2003 7 47 PM he absolute path of the project s basedir as set ith the basedir attribute of lt project gt he absolute path of the buildfile he version of Ant he name of the project that is currently executing t is set in the name attribute of lt project gt he JVM version Ant detected currently it can hold he values 2 1 1 2 L 3 and 1 4 a ct ct B ct ct ct lt project name MyProject default dist basedir gt lt description gt lt description gt simple example build file lt set global properties for this build gt lt property name sr lt property name bu c location src gt ild location build gt lt property name di
377. s not used to specify a directory name for file file and a lt fileset gt IS dir are independent of each other specified WARNING Do not set dir to basedir or the full pathname equivalent unless you truly intend to recursively remove 100 305 Ant Manual 1 5 4 12 9 2003 7 47 PM the entire contents of the current base directory and the base directory itself if different from the current working directory verbose Show the name of each deleted file true false Default is No false when omitted quiet If the specified file or directory does not exist do not display a No diagnostic message unless Ant has been invoked with the verbose or debug switches or modify the exit status to reflect an error When set to true if a file or directory cannot be deleted no error is reported This setting emulates the f option to the Unix rm command Default is false Setting this to true implies setting failonerror to false failonerror Controls whether an error such as a failure to delete a file stops No the build or is merely reported to the screen Only relevant if quiet is false Default is true includeEmptyDirs Set to true to delete empty directories when using filesets No Default is false includes Deprecated Use lt fileset gt Comma or space separated list of No patterns of files that must be deleted All files are relative to the directory specified in dir includesfile Deprecated Use lt
378. s that contain the user specified regular expression matching strings Parameter Type Parameter Value Required regexp Pattern of the substring to be searched for Yes Example This will fetch all those lines that contain the pattern foo lt filterreader classname org apache tools ant filters LineContainsRegExp gt lt param type regexp value foo gt lt filterreader gt Convenience method lt linecontainsregexp gt lt regexp pattern foo gt lt linecontainsregexp gt 7 3 13 PrefixLines Attaches a prefix to every line Parameter Name Parameter Value Required prefix Prefix to be attached to lines Yes Example This will attach the prefix Foo to all lines lt filterreader classname org apache tools ant filters PrefixLines gt lt param name prefix value Foo gt lt filterreader gt Convenience method lt prefixlines prefix Foo gt 7 3 14 ReplaceTokens This filter reader replaces all strings that are sandwiched between begintoken and endtoken with user defined values Parameter Parameter Parameter Value Required Type Name tokenchar begintoken Character marking the beginning of a token Defaults to No tokenchar endtoken Character marking the end of a token Defaults to No Token User defined User defined search String Yes String Example This replaces occurences of the string DATE in the data with today s date and stores it in the property src file replaced lt
379. s this help from the Workbench create the directory C I BMVJ ava ide tools org apache tools ant doc and copy the files VAJ AntTool html toolmenu gif and anttool1 gif to it e VAJ has to be restarted to recognize the new tool e Now if You open the context menu of a project You should see the entry Ant Build in the Tools submenu see Usage e Make sure the tool works as expected Servlets for Remote Tool Access e For a good introduction into the VAJ Remote Tool Access see the great introduction from Glenn McAllister at http www 7 software ibm com vad nsf Data Document4366 It is highly recommended to read this article before doing the installation to understand what you do e insert the following lines into c IBMVJava ide tools com ibm ivj toolserver servlets servlet properties Typically this file is empty If not be careful not to delete the other lines servlet vajload code org apache tools ant taskdefs optional ide VAJLoadServlet servlet vajexport code org apache tools ant taskdefs optional ide VAJExportServlet servlet vajimport code org apache tools ant taskdefs optional ide VAJImportServletName e Expand the Ant libraries ant jar and optional jar contained in the lib directory of your Ant installation to the directory c IBMVJava ide tools com ibm ivj toolserver servlets 288 305 e configure the Remote Access via Window gt Options then choose Remote Access To Tool API as shown in th
380. s to Log4j using the full classname s of the generator of each build event as the category e build started build finished org apache tools ant Project e target started target finished org apache tools ant Target e task started task finished the fully qualified classname of the task e message logged the classname of one of the above so if a task logs a message its classname is the category used and so on All start events are logged as INFO Finish events are either logged as INFO or ERROR depending on whether the build failed during that stage Message events are logged according to their Ant logging level mapping directly to a corresponding Log4j level ant listener org apache tools ant listener Log4jListener 304 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 11 2 6 XmlLogger Writes all build information out to an XML file named log xml or the value of the XmlLogger file property if present when used as a listener When used as a logger it writes all output to either the console or to the value of logfile Whether used as a listener or logger the output is not generated until the build is complete as it buffers the information in order to provide timing information for task targets and the project By default the XML file creates a reference to an XSLT file log xsl in the current directory look in ANT_HOME etc for one of these You can set the property ant XmlLogger stylesheet uri to provide a uri to a style sh
381. s to be passed to the weblogic ejbc tool No Deprecated Defines the location of the ejb jar DTD in the weblogic No class hierarchy This should not be necessary if you have weblogic in your classpath If you do not you should use a nested lt dtd gt element described above If you do choose to use an attribute you should use a nested lt dtd gt element Deprecated Defines the location of the weblogic ejb jar DTD which No covers the Weblogic specific deployment descriptors This should not be necessary if you have weblogic in your classpath If you do not you should use a nested lt dtd gt element described above Deprecated Defines the location of the ejb jar DTD in the weblogic No class hierarchy This should not be necessary if you have weblogic in your classpath If you do not you should use a nested lt dtd gt element described above If this is set to true the new method for locating CMP descriptors will No Defaults be used to false Deprecated This is an antonym for newCMP which should be used No instead 198 305 Ant Manual 1 5 4 12 9 2003 7 47 PM noEJ BC If this attribute is set to true Weblogic s ejbc will not be run on the EJB No jar Use this if you prefer to run ejbc at deployment time ejbcclass Specifies the classname of the ejbc compiler Normally ejbjar No determines the appropriate class based on the DTD used for the EJB The EJB 2 0 compiler featured in weblogic 6 has however been depreca
382. s to false the global build file filters should take place during the copy Note Nested lt filterset gt elements will always be used even if this attribute is not specified or its value is false no or off Ignore the directory structure of the No defaults to false source files and copy all files into the directory specified by the todir attribute Note that you can achieve the same effect by using a flatten mapper includeEmptyDirs Copy any o directories included in No defaults to true the FileSet s failonerror Log a gt message but do not stop No defaults to true the build when the file to copy does not exist Only meaningful when copying a single file verbose Log the files that are being copied No defaults to false encoding The encoding to assume when filter No defaults to default JVM encoding copying the files since Ant 1 5 Parameters specified as nested elements fileset FileSets are used to select sets of files to copy To use a fileset the todir attribute must be set 91 305 Ant Manual 1 5 4 12 9 2003 7 47 PM mapper You can define filename transformations by using a nested mapper element The default mapper used by lt copy gt is the identity mapper filterset FilterSets are used to replace tokens in files that are copied To use a FilterSet use the nested lt filterset gt element filterchain The Copy task supports nested FilterChains If lt filterset gt and lt filte
383. s value set in lt junit gt failureproperty The name of a property to set in the event of a failure errors No are considered failures as well Overrides value set in lt junit gt filtertrace Filter out J unit and Ant stack frames from error and failure stack No default is on traces Overrides value set in lt junit gt todir Directory to write the reports to No default is the current directory if Only run tests if the named property is set No unless Only run tests if the named property is not set No Batchtests can define their own formatters via nested lt formatter gt elements Examples lt junit gt lt test name my test TestCase gt lt junit gt Runs the test defined in my test TestCase in the same VM No output will be generated unless the test fails lt junit printsummary yes fork yes haltonfailure yes gt lt formatter type plain gt lt test name my test TestCase gt lt junit gt Runs the test defined in my test TestCase in a separate VM At the end of the test a one line summary will be printed A detailed report of the test can be found in TEST my test TestCase txt The build process will be stopped if the test fails lt junit printsummary yes haltonfailure yes gt lt classpath gt lt pathelement location S build tests gt lt pathelement path S java class path gt lt classpath gt lt formatter type plain gt lt test name my test TestCase
384. sed to give the server time to come up Another task which is capable of validating that the server is available could be used in place of the sleep task The test harness is then run Once the tests are complete the server is stopped 138 305 Ant Manual 1 5 4 12 9 2003 7 47 PM using wistop in this example allowing both threads to complete The parallel task will also complete at this time and the build will then continue lt parallel gt lt javac gt lt compiler servlet cod gt lt wl3jspc gt lt precompile JSPs gt lt parallel gt This example shows two independent tasks being run to achieve better resource utilization during the build In this instance some servlets are being compiled in one thead and a set of JSPs is being precompiled in another As noted above you need to be careful that the two tasks are independent both in terms of their dependencies and in terms of their potential interactions in Ant s external environment 9 47 Patch Description Applies a diff file to originals requires patch to be on the execution path Parameters Attribute Description Required patchfile the file that includes the diff output Yes originalfile the file to patch No tries to guess it from the diff file backups Keep backups of the unpatched files No quiet Work silently unless an error occurs No reverse Assume patch was created with old and new files No swapped ignorewhitespace Ignore whitespace differenc
385. sejarname attribute Since all generated beans will have the 194 305 Ant Manual 1 5 4 12 9 2003 7 47 PM same name this task should be only used when each descriptor is in its own directory This scheme is most appropriate when you are using multiple beans per jar and only process a single deployment descriptor You typically want to specify the name of the jar and not derive it from the beans in the jar Dependencies In addition to the bean classes ejbjar is able to ad additional classes to the generated ejbjar These classes are typically the support classes which are used by the bean s classes or as parameters to the bean s methods In versions of Ant prior to 1 5 ejbjar used reflection and attempted to add the super classes and super interfaces of the bean classes For this technique to work the bean classes had to be loaded into Ant s JVM This was not always possible due to class dependencies The ejbjar task in Ant releases 1 5 and later uses the jakarta BCEL library to analyze the bean s class files directly rather than loading them into the JVM This also allows ejbjar to add all of the required support classes for a bean and not just super classes In Ant 1 5 a new attribute dependency has been introduced to allow the buildfile to control what additional classes are added to the generated jar It takes three possible values e none only the bean classes and interfaces described in the bean s descriptor are added to the
386. set to true split the JSP text content into a one line per call format There are comments above and below the mapped write calls to localize where in the J SP file each line of text comes from This can lead to a minor performance degradation but it is bound by a linear complexity Without this options all adjacent writes are concatenated into a single write The ieplugin option is used by the lt jsp plugin gt tags If the Java Plug in COM Class 1D you want to use changes then it can be specified here This should not need to be altered uriroot specifies the root of the web application This is where all absolute uris will be resolved from If it is not specified then the first JSP page will be used to derive it To derive it each parent directory of the first JSP page is searched for a WEB INF directory and the directory closest to the JSP page that has one will be used If none can be found then the directory J asperc was called from will be used This only affects pages translated from an explicitly declared J SP file including references to taglibs uribase is used to establish the uri context of relative URI references in the JSP pages If it does not exist then it is derived from the location of the file relative to the declared or derived value of uriroot This only affects pages translated from an explicitly declared JSP file Parameters specified as nested elements This task is a directory based task like javac so the jsp files
387. somewhat hard to control Specifying the output file with destfile seems prudent Also dependency checking only works if destfile is set Description___________ xample Values Attribute refer to should be used or not debug ________ includedebuginformation___________ true default destFile_____ hhameofexe library to create____ example exe docFile_________ k hnameoffilefordocumentation___ doc xml comma or space separated list of patterns of files that must be excluded No files except default excludes are excluded when omitted taken to be an exclude pattern Supported by the CSharp task baseaddress 0x12840000 ailOnError Should a failed compile halt the build true defa ult or false ileAlign set the file alignment Valid values are 512 16384 0 means leave to the compiler ullpaths includes comma or space separated list of patterns of files that must be included All files are included when omitted includeDefaultReferences Flag which when true automatically true default or false includes the common assemblies in dotnet and tells the compiler to link in mscore dll the name of a file Each line of this file is taken to be an include pattern Incremental build flag Avoid till it works true or false default 175 305 Ant Manual 1 5 4 12 9 2003 7 47 PM mainClass name of main class for executables com example project entrypoint a flag which tells the compiler not t
388. splays the prompt default is error Only displays prompt after an error never finalsnapshot Type of snapshot to send at program termination Must be one of No none coverage all default to coverage recordfromstart Must be one of coverage all none If you want Coverage to start No analyzing as soon as the program begins to run use all If not select default to none coverage warnlevel Set warning level 0 3 where O is the least amount of warnings No default to 0 snapshotdir The path to the directory where snapshot files are stored Choose a No directory that is reachable by both the remote and local computers and default to enter the same path on the command line and in the viewer current directory workingdir The physical path to the working directory for the VM No default is current 228 305 Ant Manual 1 5 4 12 9 2003 7 47 PM directory tracknatives Test native methods Note that testing native methods with J ava 2 No disables the JIT default to false classname the name of the class to analyze Yes Nested Elements classpath jpcoverage supports a nested lt classpath gt element that represents a PATH like structure jvmarg Additional parameters may be passed to the VM via nested lt jvmarg gt attributes for example lt jpcoverage home c jprobe classname MyClass gt lt jvmarg value classic gt lt classpath path gt lt jpcoverage gt would run the coverage on
389. src dir id src files gt lt include name java gt lt fileset gt lt pathconvert pathsep property javafiles refid src files gt This example takes the set of files determined by the fileset all files ending in java joins them together separated by commas and places the resulting list into the property javafiles The directory separator is not specified so it defaults to the appropriate character for the current platform Such a list could then be used in another task like javadoc that requires a comma separated list of files 9 49 Property Description Sets a property by name and value or set of properties from file or resource in the project Properties are case sensitive 141 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Properties are immutable whoever sets a property first freezes it for the rest of the build they are most definately not variable There are five ways to set properties e By supplying both the name and value attribute e By supplying both the name and refid attribute e By setting the file attribute with the filename of the property file to load This property file has the format as defined by the file used in the class java util Properties e By setting the resource attribute with the resource name of the property file to load This property file has the format as defined by the file used in the class java util Properties e By setting the environment attribute with a prefix to
390. ssed to the Java No No Virtual Machine used to run the Weblogic instance weblogicMainClass name of the main class for weblogic No No Nested Elements The wlrun task supports nested lt classpath gt and lt wlclasspath gt elements to set the repsective classpaths 191 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Examples This example shows the use of wirun to run a server under Weblogic 5 1 lt wlrun taskname myserver classpath weblogic boot classpath wilclasspath weblogic classes code jars name myserver home weblogic home properties myserver myserver properties gt This example shows wlrun being used to run the petstore server under Weblogic 6 0 lt wlrun taskname petstore classpath weblogic classes name petstoreServer domain petstore home weblogic home password petstorePassword beahome bea home gt 10 7 2 5WLSTOP Description The wlstop task is used to stop a weblogic instance which is currently running To shut down an instance you must supply both a username and a password These will be stored in the clear in the build script used to stop the instance For security reasons this task is therefore only appropriate in a development environment This task works for most version of Weblogic including 6 0 You need to specify the BEA Home to have this task work correctly under 6 0 Parameters Attribute Description Required BEAHome This attribute selects Weblogic 6
391. sshistory vsspath myProject recursive true numDays 14 dateFormat M d yy h mma toDate to tstamp gt Shows all changes in the 14 days before today 10 48 6 VssCheckin Description Task to perform CHECKIN commands to Microsoft Visual SourceSafe Parameters Attribute Values Required vsspath SourceSafe path which specifies the project file s you wish to perform the Yes action on You should not specify the leading dollar sign it is prepended by Ant automatically login usernamel password The username and password needed to get access to No VSS Note that you may need to specify both if you have a password Ant VSS will hang if you leave the password out and VSS does not accept login without a password localpath Override the working directory and get to the specified path No ssdir directory where ss exe resides By default the task expects it to be in the No PATH serverPath directory where srssafe ini resides No writable true or false No recursive true or false No comment Comment to use for the files that where checked in No autoresponse Y N or empty Specify how to reply to questions from VSS No 296 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Examples lt vsscheckin vsspath test test localpath D build comment Modified by automatic build gt Checks in the file s named test in the project test using the local directory D 1 build 10 48 7 VssCheckout Description Task to perform CHE
392. st location dist gt lt target name init gt lt Create the time stamp gt lt tstamp gt lt Create the build directory structure used by compile gt lt mkdir dir build gt lt target gt lt target name comp description lt Compile the lt javac srcdir lt target gt lt target name dist ile depends init compile the source gt Java code from src into S build gt src destdir build gt depends compile description lt Create th lt mkdir dir S di lt Put everyth lt jar jarfile S lt target gt lt target name clea description lt Delete th generate the distribution gt distribution directory gt sti I1B0 gt ing in S build into the MyProject S DSTAMP jar file gt dist 1lib MyProject S DSTAMP jar basedir build gt n clean up gt S build and dist directory trees gt lt delete dir build gt lt delete dir S d lt target gt lt project gt ist gt Notice that we are declaring properties outside any target The lt property gt lt typedef gt and lt taskdef gt tasks are special in that they can be declared outside any target When you do this they are evaluated before any targets are executed No other tasks can be declared outside targets 27 305 Ant Manual 1 5 4 12 9 2003 7 47 PM We have given some targets descriptions this causes the proj
393. st be taken when using multithreading to ensure the tasks within the threads do not interact For example two javac compile tasks which write classes into the same destination directory may interact where one tries to read a class for dependency information while the other task is writing the class file Be sure to avoid these types of interactions within a lt parallel gt task The parallel task has no attributes and does not support any nested elements apart from Ant tasks Any valid Ant task may be embedded within a parallel task including other parallel tasks Note that while the tasks within the parallel task are being run the main thread will be blocked waiting for all the child threads to complete If any of the tasks within the lt parallel gt task fails the remaining tasks in other threads will continue to run until all threads have completed In this situation the parallel task will also fail The parallel task may be combined with the sequential task to define sequences of tasks to be executed on each thread within the parallel block Examples lt parallel gt lt wlrun gt lt sequential gt lt sleep seconds 30 gt lt JUNTE e gt lt wlstop gt lt sequential gt lt parallel gt This example represents a typical pattern for testing a server application In one thread the server is started the wlrun task The other thread consists of a three tasks which are performed in sequence The sleep task is u
394. t rootstarteamfolder src java rootlocalfolder C dev buildtest co src java forced true gt In the preceding three examples assuming that the AProject project has a default folder of C work AProject the first example will check out the tree of files rooted in the src java folder of the AView view of the AProject in the StarTeam repository to a local tree rooted at C dev buildtest co the second to a tree rooted at C work AProject src java since no rootlocalfolder is specified and the third to a tree rooted at C dev buildtest co src java Note also that since the second example does not set forced true only those files which the repository considers out of date will be checked out 10 42 3 STCheckin Description Checks files into a StarTeam project Optionally adds files and in the local tree that are not managed by the repository to its control The includes and excludes attributes function differently from other tasks in Ant Inclusion exclusion by folder is NOT supported Parameters See also the required common StarTeam parameters Attribute Description Required rootstarteamfolder The root of the subtree in the StarTeam repository into which to files will no be checked Defaults to the root folder of the view rootlocalfolder The local folder which will be the root of the tree to which files are no checked out If this is not supplied then the StarTeam default folder 273 305 Ant Manual 1 5 4
395. t No What to respond with sets the I option By default l is used values of Y autorespornise or N will be appended to this Ne Examples lt vsslabel vsspath source aProject login me mypassword 294 305 Ant Manual 1 5 4 12 9 2003 7 47 PM label Releasel gt Labels the current version of the VSS project source aProject with the label Releasel using the username me and the password mypassword lt vsslabel vsspath source aProject myfile txt version 4 label 1 03 004 gt Labels version 4 of the VSS file source aProject myfile txt with the label 1 03 004 If this version already has a label the operation and the build will fail 10 48 5 VssHistory Description Task to perform HISTORY commands to Microsoft Visual SourceSafe Parameters Attribute Values Required vsspath SourceSafe path which specifies the project file s you wish to perform the Yes action on You should not specify the leading dollar sign it is prepended by Ant automatically login username password The username and password needed to get access to No VSS Note that you may need to specify both if you have a password Ant VSS will hang if you leave the password out and VSS does not accept login without a password ssdir directory where ss exe resides By default the task expects it to be in the PATH No serverPath directory where srssafe ini resides No fromDate F See Start date for comparison below pate End date for c
396. t Java runtimes If you need a permission preserving copy function use lt exec executable cp gt instead Windows Note If you copy a file to a directory where that file already exists but with different casing the copied file takes on the case of the original The workaround is to delete the file in the destination directory before you copy it 9 15 Copydir Deprecated This task has been deprecated Use the Copy task instead Description Copies a directory tree from the source to the destination It is possible to refine the set of files that are being copied This can be done with the includes includesfile excludes excludesfile and defaultexcludes attributes With the includes or includesfile attribute you specify the files you want to have included by using patterns The exclude or excludesfile attribute is used to specify the files you want to have excluded This is also done with patterns And finally with the defaultexcludes attribute you can specify whether you want to use default exclusions or not See the section on directory based tasks on how the inclusion exclusion of files works and how to write patterns This task forms an implicit FileSet and supports all attributes of lt fileset gt dir becomes src as well as the nested lt include gt lt exclude gt and lt patternset gt elements Parameters Attribute Description _Required uds comma or epace lt eparaied list of patterns of files that must be include
397. t classpath gt lt pathelement location dist test jar gt lt pathelement path S java class path gt lt classpath gt lt java gt Run the jar using the manifest supplied entry point forking as required and with a maximum memory of 128MB Any non zero return code breaks the build lt java classname test Main gt 119 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt java classname test Main fork yes gt lt sysproperty key DEBUG value true gt lt arg value h gt lt jvmarg value Xrunhprof cpu samples file log txt depth 3 gt lt java gt Note you can not specify the highly deprecated MSJVM jview exe as the JVM as it takes different parameters for other J VMs That JVM can be started from lt exec gt if required 9 38 Javac Description Compiles a Java source tree The source and destination directory will be recursively scanned for Java source files to compile Only Java files that have no corresponding class file or where the class file is older than the java file will be compiled Note Ant uses only the names of the source and class files to find the classes that need a rebuild It will not scan the source and therefore will have no knowledge about nested classes classes that are named different from the source file and so on See the lt depend gt task for dependency checking based on other than just existence modification times When the source files are part of
398. t fileset gt dir becomes basedir as well as the nested lt include gt lt exclude gt and lt patternset gt elements Or you may place within it nested file sets or references to file sets In this case basedir is optional the implicit file set is only used if basedir is set You may use any mixture of the implicit file set with basedir set and optional attributes like includes and optional subelements like lt include gt explicit nested lt fileset gt elements so long as at least one fileset total is specified The ZIP file will only reflect the relative paths of files within each fileset The Zip task and its derivatives know a special form of a fileset named zipfileset that has additional attributes described below The Zip task also supports the merging of multiple zip files into the zip file This is possible through either the src attribute of any nested filesets or by using the special nested fileset zipgroupfileset 171 305 Ant Manual 1 5 4 12 9 2003 7 47 PM The update parameter controls what happens if the ZIP file already exists When set to yes the ZIP file is updated with the files specified New files are added old files are replaced with the new versions When set to no the default the ZIP file is overwritten Please note that ZIP files store file modification times with a granularity of two seconds If a file is less than two seconds newer than the entry in the archive Ant will not consider it newer T
399. t of any new parameters For example if the target doSomethingElse depended on the target init then the antcall of doSomethingElse will call init during the call Of course any properties defined in the antcall task or inherited from the calling target will be fixed and not overridable in the init task or indeed in the doSomethingElse task Parameters 76 305 Ant Manual 1 5 4 12 9 2003 7 47 PM inheritAll If true pass all properties to the new Ant project Defaults to true inheritRefsllf true pass all references to the new Ant project Defaults to false No Note on inheritRefs lt antcall gt will not override existing references even if you set inheritRefs to true As the called build files is the same build file as the calling one this means it will not override any reference set via an id attribute at all The only references that can be inherited by the child project are those defined by nested lt reference gt elements or references defined by tasks directly not using the id attribute Inherited references are not available to top level tasks of the child project Parameters specified as nested elements param Specifies the properties to set before running the specified target See property for usage guidelines reference Used to chose references that shall be copied into the new project optionally changing their id Attribute Description Required refid The id of the reference in the calling project
400. t of patterns of files that must be No included all files are included when omitted includesfile the name of a file each line of this file is taken to be an include No pattern excludes comma or space separated list of patterns of files that must be No excluded no files except default excludes are excluded when omitted excludesfile the name of a file each line of this file is taken to be an exclude No pattern casesensitive Must the file system be treated in a case sensitive way Defaults No to true followsymlinks Shall symbolic links be followed Defaults to true See the note No below Note All files directories for which the canonical path is different from its path are considered symbolic links On Unix systems this usually means the file really is a symbolic links but it may lead to false results on other platforms Examples lt fileset dir server src casesensitive yes gt lt include name java gt 38 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt exclude name Test gt lt fileset gt Groups all files in directory server src that are Java source files and don t have the text Test in their name lt fileset dir S server src casesensitive yes gt lt patternset id non test sources gt lt include name java gt lt exclude name Test gt lt patternset gt lt fileset gt Groups the same files as the above example but also establishes a PatternS
401. t to the remote timestamp if the JVM is Javal 2 or later NB This timestamp facility only works on downloads using the HTTP protocol A username and password can be specified in which case basic slightly encoded plain text authentication is used This is only a secure authentication mechanism over an HTTPS link If you need to go through a firewall use lt setproxy gt to set up the proxy first Parameters Attribute Description Required src the URL from which to retrieve a file Yes dest the file where to store the retrieved file Yes verbose show verbose progress information on off No default false ignoreerrors Log errors but don t treat as fatal No default false usetimestamp conditionally download a file based on the timestamp of the local No default copy HTTP only false username username for BASIC http authentication if password is set password password required if username is set Examples lt get src http ant apache org dest help index html gt Gets the index page of http ant apache org and stores it in the file help index html lt get src http www apache org dist ant KEYS dest KEYS verbose true usetimestamp true gt Gets the PGP keys of Ant s current and past release managers if the local copy is missing or out of date Uses the verbose option for progress information lt get src https insecure bank org statement user 1214 dest statement html
402. te whereas the J Depend tool can be customized to exclude some packages the current jdepend And Task does not have parameters to allow these exclusions Read J Depend specific documentation for that purpose Parameters Attribute Description Required outputfile The output file name If not set the output is printed on the standard No output format The format to write the output in The default is text the alternative is No xml fork Run the tests in a separate VM No default is off haltonerror Stop the build process if an error occurs during the jdepend analysis No default is off timeout Cancel the operation if it doesn t finish in the given time measured in No milliseconds Ignored if fork is disabled jvm The command used to invoke the Java Virtual Machine default is java The No default command is resolved by java lang Runtime exec Ignored if fork is java disabled dir The directory to invoke the VM in Ignored if fork is disabled No classpathrefthe classpath to use given as reference to a PATH defined elsewhere No Nested Elements jdepend supports two nested elements lt classpath gt and lt sourcespath gt that represent PATH like structures lt sourcespath gt is used to define the paths of the source code to analyze Examples 224 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt jdepend classpathref base path gt lt sourcespath gt lt pathelement location src gt lt sourcespath gt
403. te the default framed report in the directory report html 10 24 MMetrics Stephane Bailliez Sbailliez imediation com Requirements This task requires Metamata Development environment 2 0 Webgain Quality Analyzer 2 0 An evaluation version is available at Webgain Though you will not be able to use Metrics from the command line if you do not have a registered version You also need a TRaX compliant processor such as Xalan 2 x via JAXP 1 1 Description Invokes the Metamata Metrics WebGain Quality Analyzer source code analyzer on a set of Java files mmetrics will compute the metrics of a set of Java files and write the results to an XML file As a convenience a stylesheet is given in etc directory so that an HTML report can be generated from the XML file Parameters Attribute Description Required metamatahome The home directory containing the Metamata distribution Yes tofile The XML were the resulting metrics will be written to Yes granularity Metrics granularity of the source files Must be either files compilation Yes units types types and compilation units or methods methods types and compilation units maxmemory Set the maximum memory for the J VM this is a convenient way to set the No mx or Xmx argument Nested elements For specifying the source code to analyze you can either use a path or fileset elements though a single path element is preferred see note below jvmarg Additional parameters m
404. teN is the attribute name and valueN is the value for this attribute There is a set of built in tasks along with a number of optional tasks but it is also very easy to write your own All tasks share a task name attribute The value of this attribute will be used in the logging messages generated by Ant Tasks can be assigned an id attribute lt taskname id taskID gt where taskname is the name of the task and taskID is a unique identifier for this task You can refer to the corresponding task object in scripts or other tasks via this name For example in scripts you could do lt SCript sas gt taskl setFoo bar lt script gt to set the foo attribute of this particular task instance In another task written in Java you can access the instance via project getReference task1 Note If task1 has not been run yet then it has not been configured ie no attributes have been set and if it is going to be configured later anything you ve done to the instance may be overwritten Note Future versions of Ant will most likely not be backward compatible with this behaviour since there will likely be no task instances at all only proxies 6 1 4 Properties A project can have a set of properties These might be set in the buildfile by the property task or might be set outside Ant A property has a name and a value the name is case sensitive Properties may be used in the value of task attributes Thi
405. ted includesfile the name of a file each line of this file is taken to be an include pattern You can specify more than one include file by using a nested includesfile elements excludes comma or space separated list of patterns of files that must be excluded no files except default excludes are excluded when omitted excludesfile the name of a file each line of this file is taken to be an exclude pattern You can specify more than one exclude file by using a nested excludesfile elements Parameters specified as nested elements include and exclud Each such element defines a single pattern for files to include or exclude Attribute Description Required 52 305 Ant Manual 1 5 4 12 9 2003 7 47 PM name the pattern to in exclude Yes if Only use this pattern if the named property is set No unless Only use this pattern if the named property is not set No includesfile and excludesfil If you want to list the files to include or exclude external to your build file you should use the includesfile excludesfile attributes or elements Using the attribute you can only specify a single file of each type while the nested elements can be specified more than once the nested elements also support if unless attributes you can use to test the existence of a property Attribute Description Required name the name of the file holding the patterns to in exclude Yes if Only read this file if the named property is set No unl
406. ted manifest the manifest file to use No 104 305 Ant Manual 1 5 4 12 9 2003 7 47 PM update indicates whether to update or overwrite the destination file if it No already exists Default is false duplicate behavior when a duplicate file is found Valid values are add No preserve and fail The default value is add Nested elements metainf The nested metainf element specifies a FileSet All files included in this fileset will end up in the META INF directory of the ear file If this fileset includes a file named MANIFEST MF the file is ignored and you will get a warning Example lt ear destfile build dir myapp ear appxml src dir metadata application xml gt lt fileset dir build dir includes jar war gt lt ear gt 9 26 Echo Description Echoes a message to the current loggers and listeners which means System out unless overridden A level can be specified which controls at what logging level the message is filtered at The task can also echo to a file in which case the option to append rather than overwrite the file is available and the level option is ignored Parameters Attribute Description Required message the message to echo Yes unless data is included in a character section within this element file the file to write the message to No append Append to an existing file No default is false level Control the level at which this message is reported No def
407. ted VAJ project e An entry field for the Ant XML buildfile with a browse button The full qualified filename including the directory is needed here e A list with tasks specified in the buildfile Until your first save of the build info described later this list will be empty When loading a build file by the Re Load button this list is filled with all tasks which have a description attribute The task you select in this list will be executed when pressing the Execute button e A pulldown box for specifying the log level e Four buttons Two of them have already described The other are the Stop button to cancel a running build and the third one is just the Close button to exit our small tool 290 305 Ant Manual 1 5 4 12 9 2003 7 47 PM e Note that the build is canceled on the next console output after pressing the Stop button not directly after pressing it After you have set up your buildprocess you might find it useful to save the data you ve just entered so we implemented an option to save it to the repository into your selected project Make sure that you have an open edition of your project before selecting Save Buildlnfo To Repository from the File menu Now your information is saved to this edition of your project and will be loaded automatically the next time you start Ant Build If you have closed the log window accidentally it can be reopened with the Log item in the File menu and if you want to know who develop
408. ted in version 7 When using with version 7 this attribute should be set to weblogic ejbc to avoid the deprecation warning jvmargs Any additional arguments to be passed to the Virtual Machine running No weblogic ejbc tool For example to set the memory size this could be jvmargs Xmx128m jvmdebuglevel Sets the weblogic StdoutSeverityLevel to use when running the Virtual No Machine that executes ejbc Set to 16 to avoid the warnings about EJ B Home and Remotes being in the classpath outputdir If set ejbc will be given this directory as the output destination rather No than a jar file This allows for the generation of exploded jars The weblogic nested element supports three nested elements The first two lt classpath gt and lt wlclasspath gt are used to set the respective classpaths These nested elements are useful when setting up class paths using reference Ids The last lt sysproperty gt allows Java system properties to be set during the compiler run This turns out to be necessary for supporting CMP EJB compilation in all environments 10 7 3 3TOPLINK FOR WEBLOGIC ELEMENT DEPRECATED The toplink element is no longer required Toplink beans can now be built with the standard weblogic element as long as the newCMP attribute is set to true The TopLink element is used to handle beans which use Toplink for the CMP operations It is derived from the standard weblogic element so it supports the same set of attributes plu
409. ted with Linux Solaris amp Windows2000 266 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 10 40 2 The Tasks get Retrieves a read only copy of the specified project or file soslabel Assigns a label to the specified project succi n Updates VSS with changes made to a checked out file or project and unlocks the VSS gt gt master copy Retrieves a read write copy of the specified project or file locking the VSS master copy 10 40 3 SOSGet Description Task to perform GET commands with SOS Parameters Attribute dema Directory which contains soscmd exe Soscmd exe must be in the path if this is not specified Wssserverpathpath to the srcsafe ini eg server vss srcsafe ini sosserverpathladdress port of the SOS server eg 192 168 0 1 8888 brojectpath SourceSafe project path without the fle filename to act upon If no file is specified then act upon the project localpath Override the working directory and get to the specified path No verbose version ja version number to get Only works with the GetFile command___ N label fa label version to get Only works with the GetProject command_____ Verbose_ rue or false Status messages are displayed SN rue or false Only works with the GetProje ct command Example lt sosget verbose true recursive true username build password build localpath tmp projectpath SourceRoot projecti sosserverpath 192 168 10 6 8888 vssserverpath d
410. tension desired file extension to be used for the targets If not No specified the default is html style name of the stylesheet to use given either relative to the Yes project s basedir or as an absolute path DEPRECATED can be specified as a path relative to the basedir attribute of this task as well classpath the classpath to use when looking up the XSLT processor No classpathref the classpath to use given as reference to a path defined No elsewhere force Recreate target files even if they are newer than their No default is corresponding source files or the stylesheet false processor name of the XSLT processor to use Permissible values are No 155 305 Ant Manual 1 5 4 12 9 2003 7 47 PM trax for a TraX compliant processor ie J AXP interface implementation such as Xalan 2 or Saxon xslp for the XSL P processor xalan for the Apache XML Xalan version 1 processor the name of an arbitrary XSLTLiaison class Defaults to trax followed by xalan and then xslp in that order The first one found in your class path is the one that is used DEPRECATED XSL P and xalan are deprecated and no more supported includes comma or space separated list of patterns of files that must No be included All files are included when omitted includesfile the name of a file Each line of this file is taken to be an include No pattern excludes comma or space separated list of patterns of files that must No be excluded No files
411. ters Attribute Description Re uiirel file The path to take the basename of property The name of the property to set suffix The suffix to remove from the resulting basename specified either with or No without the Examples lt basename property jar filename file lib jarfile gt will set jar filename to myjar jar if lib jarfile is defined as either a full path filename eg usr local lib myjar jar a relative path filename eg 1ib myjar jar ora simple filename eg myjar jar lt basename property cmdname file D usr local foo exe suffix exe gt will set cmdname to foo lt property environment env gt lt basename property temp dirname file S env TEMP gt will set temp dirname to the last directory element of the path defined for the TEMP environment variable 9 7 BuildNumber Description This is a basic task that can be used to track build numbers It will first attempt to read a build number from a file by default build number in the current directory then set the property build number to the value that was read in or to 0 if no such value It will then increment the number by one and write it back out to the file See the PropertyFile task if you need finer control over things such as the property name or the number format 82 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Parameters Attribute Description Required file The file to rea
412. th a class and method attribute Attribute Description Required 231 305 Ant Manual 1 5 4 12 9 2003 7 47 PM class The class mask as a simple regular expression No default to method The method mask as a simple regular expression No default to Example of report lt jpcovreport home c jprobe snapshot merge jpc format xml tofile result xml gt lt sourcepath path src gt lt reference gt lt classpath path bin classes gt lt filters gt lt include class com mycompany gt lt exclude class com mycompany MyClass method test gt lt filters gt lt reference gt lt jpcovreport gt would generate the report of the file merge jpc and write it to result xml using the source path src As well it will modify the result xml by analyzing all classes in the bin classes that are port of the package com mycompany except the method that start by test from the class MyClass Recommendation If you generate your main code and your testcases in a separate directory say bin classes and test classes You should mostly end up with a reference such as lt reference gt lt classpath path bin classes gt lt reference gt With such a reference your XML report will be cleaned up against parasite classes from your testcases that as a common practice generally match the exact package structure of the class you exercise HTML reports You will find in Ant etc directory a s
413. that a At least one of file must be in order to be selected Default is no limit the two max The maximum number of directory levels below the base directory that a file can be and still be selected Default is no limit Here is an example of how to use the Depth Selector lt fileset dir doc path includes gt lt depth max 1 gt lt fileset gt Selects all files in the base directory and one directory below that 7 3 22 7 FILENAME SELECTOR The lt filename gt tag acts like the lt include gt and lt exclude gt tags within a fileset By using a selector instead however one can combine it with all the other selectors using whatever selector container is desired The lt filename gt selector is case sensitive Attribute Description Required name The name of files to select The name parameter can contain the standard Ant Yes wildcard characters casesensitive Whether to pay attention to case when looking at file names Default is No true negate Whether to reverse the effects of this filename selection therefore emulating No an exclude rather than include tag Default is false Here is an example of how to use the Filename Selector 56 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt fileset dir doc path includes gt lt filename name css gt lt fileset gt Selects all the cascading style sheet files 7 3 22 8PRESENT SELECTOR The lt present gt tag selects files that
414. the WAR file to create Yes warfile Deprecated name of the file to create use destfile instead No webxml The deployment descriptor to use WEB INF web xml Yes unless update is set to true basedir the directory from which to jar the files No compress Not only store data but also compress them defaults to true No encoding The character encoding to use for filenames inside the archive No Defaults to UTF8 It is not recommended to change this value as the created archive will most likely be unreadable for J ava otherwise filesonly Store only file entries defaults to false No 168 305 Ant Manual 1 5 4 12 9 2003 7 47 PM includes comma or space separated list of patterns of files that must be No included All files are included when omitted includesfile the name of a file Each line of this file is taken to be an include No pattern excludes comma or space separated list of patterns of files that must be No excluded No files except default excludes are excluded when omitted excludesfile the name of a file Each line of this file is taken to be an exclude No pattern defaultexcludes indicates whether default excludes should be used or not No yes no Default excludes are used when omitted manifest the manifest file to use No update indicates whether to update or overwrite the destination file if it No already exists Default is false duplicate behavior when a duplicate file is found Valid values are add
415. the build failed three times if the fun property is set to true If the target is a dependency of an initialization target that other targets depend on the fun done property prevents the target from being executed more than once lt target name fun if fun unless fun done gt lt sound gt lt success source intranet sounds success gt lt fail source intranet sounds failure gt lt sound gt lt property name fun done value true gt lt target gt randomly selects a sound file to play when the build succeeds or fails 10 40 SourceOffSite Tasks User Manual by Jesse Stockall Version 1 1 2002 01 23 10 40 1 Introduction These tasks provide an interface to the Microsoft Visual SourceSafe SCM via SourceGear s SourceOffSite product SourceOffSite is an add on to Microsoft s VSS that allows remote development teams and tele commuters that need fast and secure read write access to a centralized SourceSafe database via any TCP IP connection SOS provides Linux Solaris amp Windows clients The org apache tools ant taskdefs optional sos package consists of a simple framework to support SOS functionality as well as some Ant tasks encapsulating frequently used SOS commands Although it is possible to use these commands on the desktop they were primarily intended to be used by automated build systems These tasks have been tested with SourceOffSite version 3 5 1 connecting to VisualSourceSafe 6 0 The tasks have been tes
416. the descriptordir namespace genericjarsuffix A generic jar is generated as an intermediate step in build the No defaults to weblogic deployment jar The suffix used to generate the generic jar generic jar file is not particularly important unless it is desired to keep the generic jar file It should not however be the same as the suffix setting suffix String value appended to the basename of the deployment descriptor No defaults to to create the filename of the J Boss EJB jar file jar keepgeneric This controls whether the generic file used as input to ejbc is retained No defaults to false 10 7 3 2 WEBLOGIC ELEMENT The weblogic element is used to control the weblogic ejbc compiler for generating weblogic EJB jars Prior to Ant 1 3 the method of locating CMP descriptors was to use the ejbjar naming convention So if your ejb jar was called Customer ejb jar xml your weblogic descriptor was called Customer weblogic ejb jar xml and your CMP descriptor had to be Customer weblogic cmp rdbms jar xml In addition the lt type storage gt element in the weblogic descriptor had to be set to the standard name META NF weblogic cmp rdbms jar xml as that is where the CMP descriptor was mapped to in the generated jar There are a few problems with this scheme It does not allow for more than one CMP descriptor to be defined in a jar and it is not compatible with the deployment descriptors generated by some tools In Ant 1 3
417. the new modification time of the file in the No format MM DD YYYY HH MM AM_or_PM If both millis and datetime are omitted the current time is assumed Examples lt touch file myfile gt creates myfile if it doesn t exist and changes the modification time to the current time lt touch file myfile datetime 06 28 2000 2 02 pm gt creates myfile if it doesn t exist and changes the modification time to Jun 28 2000 2 02 pm 14 02 for those used to 24 hour times lt touch datetime 09 10 1974 4 30 pm gt lt fileset dir src_dir gt lt touch gt changes the modification time to Oct 09 1974 4 30 pm of all files and directories found in src_dir 9 63 Tstamp Description Sets the DSTAMP TSTAMP and TODAY properties in the current project By default the DSTAMP property is in the format yyyyMMdd TSTAMP is in the format hhmm and TODAY is in the format MMMM dd yyyy Use the nested lt format gt element to specify a different format These properties can be used in the build file for instance to create time stamped filenames or used to replace placeholder tags inside documents to indicate for example the release date The best place for this task is probably in an initialization target Parameters Attribute Description Required prefix Prefix used for all properties set The default is no prefix No Nested Elements The Tstamp task supports a lt format gt nested element that allows a property to be set
418. this option of javadoc The packages listed in packagelist are not checked so the task performs even if some packages are missing or broken Use this option if you wish to convert from an existing makefile Once things are running you should then switch to the regular notation DEPRECATION the javadoc2 task simply points to the javadoc task and it s there for back compatibility reasons Since this task will be removed in future versions you are strongly encouraged to use javadoc instead In the table below 1 1 means available if your current Java VM is a 1 1 VM 1 2 for either 1 2 or 1 3 and 1 4 for a 1 4 Java VM 1 2 means any VM of at least version 1 2 Parameters Attribute sourcepath sourcepathref sourcefiles destdir maxmemory packagenames packageList classpath Bootclasspath classpathref bootclasspathref Extdirs Overview access Public Protected Package Private Old Description Specify where to find source files Specify where to find source files by reference to a PATH defined elsewhere Comma separated list of source files Destination directory for output files Max amount of memory to allocate to the javadoc VM Comma separated list of package files with terminating wildcard The name of a file containing the packages to process Specify where to find user class files Override location of class files loaded by the bootstrap class loader Specify where to find user class files by refer
419. ties Classes dir dir2 A properties Classes dir dir2 A properties flatten The target file name is identical to the source file name with all leading directory information stripped off Both to and from will be ignored Examples lt mapper type flatten gt Source file name Target file name A java A java foo bar B java B java C properties C properties Classes dir dir2 A properties A properties merge The target file name will always be the same as defined by to from will be ignored Examples lt mapper type merge to archive tar gt 40 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Source file name Target file name A java archive tar foo bar B java archive tar C properties archive tar Classes dir dir2 A properties archive tar glob Both to and from define patterns that may contain at most one For each source file that matches the from pattern a target file name will be constructed from the to pattern by substituting the in the to pattern with the text that matches the in the from pattern Source file names that don t match the from pattern will be ignored Examples lt mapper type glob from java to java bak gt Source file name Target file name A java A java bak foo bar B java foo bar B java bak C properties ignored Classes dir dir2 A properties ignored lt mapper type glob from C ies to Q y gt Source file name Target file name A java ignored foo bar B java ignored C
420. ties specified Yes only if property attribute of using nested lt replacefilter gt elements are drawn lt replacefilter gt is used replacefilterfile valid property file Each property will be treated as No 145 305 Ant Manual 1 5 4 12 9 2003 7 47 PM a replacefilter where token is the name of the property and value is the properties value includes comma or space separated list of patterns of files No that must be included All files are included when omitted includesfile the name of a file Each line of this file is taken to No be an include pattern excludes comma or space separated list of patterns of files No that must be excluded No files except default excludes are excluded when omitted excludesfile the name of a file Each line of this file is taken to No be an exclude pattern defaultexcludes indicates whether default excludes should be used No or not yes no Default excludes are used when omitted Examples lt replace file src index html token value wombat gt replaces occurrences of the string with the string wombat in the file S src index html Parameters specified as nested elements This task forms an implicit FileSet and supports all attributes of lt fileset gt as well as the nested lt include gt lt exclude gt and lt patternset gt elements If either the text you want to replace or the replacement text cross line boundaries you can use nested elements
421. tions Look at the source for your platform s invocation script for details 4 4 Building Ant To build Ant from source you can either install the Ant source distribution or checkout the ant module from CVS Once you have installed the source change into the installation directory Set the JAVA_HOME environment variable to the directory where the J DK is installed See Installing Ant for examples on how to do this for your operating system Make sure you have downloaded any auxiliary jars required to build tasks you are interested in These should either be available on the CLASSPATH or added to the lib directory See Library Dependencies for a list of jar requirements for various features Note that this will make the auxiliary jars available for the building of Ant only For running Ant you will still need to make the jars available as described under Installing Ant Your are now ready to build Ant build Ddist dir lt directory_to_contain_Ant_distribution gt dist Windows 16 305 Ant Manual 1 5 4 12 9 2003 7 47 PM build sh Ddist dir lt directory_to_contain_Ant_distribution gt dist Unix This will create a binary distribution of Ant in the directory you specified The above action does the following e If necessary it will bootstrap the Ant code Bootstrapping involves the manual compilation of enough Ant code to be able to run Ant The bootstrapped Ant is used for the remainder of the build steps e Invokes the bootstra
422. tions in your CLASSPATH environment variable 3 Do neither of the above and instead specify their locations using a lt classpath gt element in the build file See the FAQ for details Tests are defined by nested test or batchtest tags see nested elements Parameters Attribute Description Required printsummary Print one line statistics for each testcase Can take the values on off No default and withOutAndErr withOutAndErr is the same as on but also includes jis off the output of the test as written to System out and System err fork Run the tests in a separate VM No default is off haltonerror Stop the build process if an error occurs during the test run No default is off errorproperty The name of a property to set in the event of an error No haltonfailure Stop the build process if a test fails errors are considered failures as No default well is off failureproperty The name of a property to set in the event of a failure errors are No considered failures as well filtertrace Filter out J unit and Ant stack frames from error and failure stack No default traces is on timeout Cancel the individual tests if they don amp apos t finish in the given time No measured in milliseconds Ignored if fork is disabled maxmemory Maximum amount of memory to allocate to the forked VM Ignored if No fork is disabled jvm The command used to invoke the J ava Virtual Machine default is No default java The command is resolved
423. tle gt lt bottom gt lt CDATA lt i gt Copyright amp 169 2000 Dummy Corp All Rights Reserved lt i gt gt lt bottom gt lt tag name todo scope all description To do gt lt group title Group 1 Packages packages com dummy test a gt lt group title Group 2 Packages packages com dummy test b com dummy test c gt lt link offline true href http java sun com products jdk 1 2 docs api packagelistLoc C tmp gt lt link href http developer java sun com developer products xml docs api gt lt javadoc gt 9 40 LoadFile Description Load a text file into a single property Unless an encoding is specified the encoding of the current locale is used Parameters Attribute Description Required srcFile source file Yes property property to save to Yes encoding encoding to use when loading the file No failonerror Whether to halt the build on failure No default true The LoadFile task supports nested FilterChains 131 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Examples lt loadfile property message srcFile message txt gt Load file message txt into property message an lt echo gt can print this lt loadfile property encoded file srcFile loadfile xml encoding 1S0 8859 1 gt Load a file using the latin 1 encoding lt loadfile property optional value srcFile optional txt failonerror false gt
424. to the current date and time in a given format The date time patterns are as defined in the Java SimpleDateFormat class The format element also allows offsets to be applied to the time to generate different time values Attribute Description Required property The property to receive the date time string in the given pattern Yes pattern The date time pattern to be used The values are as defined by the Java Yes SimpleDateFormat class 162 305 Ant Manual 1 5 4 12 9 2003 7 47 PM timezone The timezone to use for displaying time The values are as defined by the Java No TimeZone class offset The numeric offset to the current time No unit The unit of the offset to be applied to the current time Valid Values are No millisecond second minute hour day week month year locale The locale used to create date time string The general form is language No country variant but either variant or variant and country may be omitted For more information please refer to documentation for the Locale class Examples lt tstamp gt sets the standard DSTAMP TSTAMP and TODAY properties according to the default formats lt tstamp gt lt format property TODAY_UK pattern d MMMM yyyy locale en gt lt tstamp gt sets the standard properties as well as the property TODAY_UK with the date time pattern d MMMM yyyy using English locale eg 21 May 2001 lt tstamp gt lt format property touch time pattern MM dd yyy
425. to perform its execution if or unless a property has been set This allows for example better control on the building process depending on the state of the system java version OS command line property defines etc To make a target sense this property you should add the if or unless attribute with the name of the property that the target should react to Note Ant will only check whether the property has been set the value doesn t matter A property set to the empty string is still an existing property For example lt target name build module A if module A present gt lt target name build own fake module A unless module A present gt In the first example if the module A present property is set to any value the target will be run In the second example if the module A present property is set again to any value the target will not be run If no if and no unless attribute is present the target will always be executed The optional description attribute can be used to provide a one line description of this target which is printed by the projecthelp command line option Targets without such a description are deemed internal and will not be listed unless either the verbose or debug option is used It is a good practice to place your tstamp tasks in a so called initialization target on which all other targets depend Make sure that target is always the first one in the depends list of the other tar
426. to refine the set of files that are being jlinked This can be done with the includes includesfile excludes excludesfile and defaultexcludes attributes on the addfiles and mergefiles nested elements With the includes or includesfile attribute you specify the files you want to have included by using patterns The exclude or excludesfile attribute is used to specify the files you want to have excluded This is also done with patterns And finally with the defaultexcludes attribute you can specify whether you want to use default exclusions or not See the section on directory based tasks on how the inclusion exclusion of files works and how to write patterns The patterns are relative to the base directory Parameters Attribute Description Required 226 305 Ant Manual 1 5 4 12 9 2003 7 47 PM outfile the path of the output file Yes compress whether or not the output should be compressed true yes or on No result in compressed output If omitted output will be uncompressed inflated mergefiles files to be merged into the output if possible At least one of addfiles files to be added to the output mergefiles or addfiles Examples The following will merge the entries in mergefoo jar and mergebar jar into out jar mac jar and pc jar will be added as single entries to out jar lt jlink compress false outfile out jar gt lt mergefiles gt lt pathelement path S build dir mergefoo jar gt lt
427. to true if the timestamp of the target file s is more recent than the timestamp of the corresponding source file s You can set the value to something other than the default by specifying the value attribute If a lt srcfiles gt element is used without also specifying a lt mapper gt element the default behavior is to use a merge mapper with the to attribute set to the value of the targetfile attribute Normally this task is used to set properties that are useful to avoid target execution depending on the relative age of the specified files 165 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Parameters Attribute Description Required property The name of the property to set Yes value The value to set the property to No defaults to true srcfile The file to check against the target file s Yes unless a nested lt srcfiles gt element is present targetfile The file for which we want to determinethe Yes unless a nested lt mapper gt element is status present Parameters specified as nested elements srcfiles The nested lt srcfiles gt element allows you to specify a set of files to check against the target file s Note You can specify either the srcfile attribute or nested lt srcfiles gt elements but not both mapper The nested lt mapper gt element allows you to specify a set of target files to check for being up to date with respect to a set of source files Examples lt uptodate property xmlBuild notReq
428. tors FileSelector classpath The classpath to use in order to load the custom selector class If neither this No classpath nor the classpathref are specified the class will be loaded from the classpath that Ant uses classpathref A reference to a classpath previously defined If neither this reference nor the No classpath above are specified the class will be loaded from the classpath that Ant uses Here is how you use lt custom gt to use your class as a selector lt fileset dir mydir includes gt lt custom classname com mydomain MySelector gt lt param name myattribute value myvalue gt lt custom gt lt fileset gt A number of core selectors can also be used as custom selectors by specifying their attributes using lt param gt elements These are e Contains Selector with classname org apache tools ant types selectors ContainsSelector e Date Selector with classname org apache tools ant types selectors DateSelector e Depth Selector with classname org apache tools ant types selectors DepthSelector e Filename Selector with classname org apache tools ant types selectors FilenameSelector e Size Selector with classname org apache tools ant types selectors SizeSelector Here is the example from the Depth Selector section rewritten to use the selector through lt custom gt lt fileset dir doc path includes gt lt custom classname org apache tools ant types selectors DepthSelector gt
429. ts to define the files for this task and refer to lt fileset gt s defined elsewhere arg Command line arguments should be specified as nested lt arg gt elements See Command line arguments srcfile By default the file names of the source files will be added to the end of the command line If you need to place it somewhere different use a nested lt srcfile gt element between your lt arg gt elements to mark the insertion point targetfile lt targetfile gt is similar to lt srcfile gt and marks the position of the target filename on the command line If omitted the target filenames will not be added to the command line at all This element can only be specified if you also define a nested mapper and the dest attribute env It is possible to specify environment variables to pass to the system command via nested lt env gt elements See the description in the section about exec Examples lt apply executable l1s gt lt arg value 1 gt lt fileset dir tmp gt lt patternset gt lt exclude name txt gt lt patternset gt lt fileset gt 79 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt fileset refid other files gt lt apply gt invokes 1s 1 adding the absolute filenames of all files below tmp not ending in txt and all files of the FileSet with id other files to the command line lt apply executable somecommand parallel false gt lt arg value argl gt lt srcfile gt lt
430. tstamp gt lt loadfile srcfile S srce file property S src file replaced gt lt filterchain gt lt filterreader classname org apache tools ant filters ReplaceTokens gt lt param type token name DATE value TODAY gt 47 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt filterreader gt lt filterchain gt lt loadfile gt Convenience method lt tstamp gt lt loadfile srcfile S src file property S src file replaced gt lt filterchain gt lt replacetokens gt lt token key DATE value TODAY gt lt replacetokens gt lt filterchain gt lt loadfile gt 7 3 15 Strip avaComments This filter reader strips away comments from the data using Java syntax guidelines This filter does not take in any parameters Example lt loadfile srcfile S java src file property S java src file nocomments gt lt filterchain gt lt filterreader classname org apache tools ant filters StripJavaComments gt lt filterchain gt lt loadfile gt Convenience method lt loadfile srcfile S java src file property S java src file nocomments gt lt filterchain gt lt stripjavacomments gt lt filterchain gt lt loadfile gt 7 3 16 StripLineBreaks This filter reader strips away specific characters from the data supplied to it Parameter Name Parameter Value Required linebreaks Characters that are to be stripped out Defaults to r n
431. tylesheet called coverage frames xsl This file can be used to generate a framed report a la javadoc similar to the one for J Unit It needs either Xalan 1 2 2 or Xalan 2 x Xalan 1 2 2 you must have xalan jar and bsf jar in your classpath lt style processor xalan in reports xml results xml out reports html dummy file style S ant home etc coverage frames xsl gt lt param name output dir expression basedir reports html gt lt style gt Xalan 2 x note the parameter without single quote lt style processor trax in reports xml results xml out reports html dummy file style S ant home etc coverage frames xsl gt lt param name output dir expression basedir reports html gt lt style gt 232 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 10 22 J Unit Description This task runs tests from the JUnit testing framework The latest version of the framework can be found at http www junit org This task has been tested with J Unit 3 0 up to J Unit 3 8 1 it won t work with versions prior to J Unit 3 0 Note This task depends on external libraries not included in the Ant distribution See Library Dependencies for more information Note You must have junit jar and the class files for the lt junit gt task in the same classpath You can do one of 1 Put both junit jar and the optional tasks jar file in ANT_HOME lib 2 Do not put either in ANT_HOME lib and instead include their loca
432. udes includesfile excludes excludesfile and defaultexcludes attributes Patterns provided through the includes or includesfile attributes specify files to be included Patterns provided through the exclude or excludesfile attribute specify files to be excluded Additionally default exclusions can be specified with the defaultexcludes attribute See the section on directory based tasks for details of file inclusion exclusion patterns and their usage This task forms an implicit FileSet and supports all attributes of lt fileset gt dir becomes srcdir as well as the nested lt include gt lt exclude gt and lt patternset gt elements The output file is only written if it is a new file or if it differs from the existing file This prevents spurious rebuilds based on unchanged files which have been regenerated by this task 109 305 Ant Manual 1 5 4 Parameters Attribute srcDir destDir includes includesfile excludes excludesfile defaultexcludes eol cr javafiles tab 12 9 2003 7 47 PM Description Required Where to find the files to be fixed up Yes Where to place the corrected files Defaults to srcDir replacing the original No file comma or space separated list of patterns of files that must be included No All files are included when omitted the name of a file Each line of this file is taken to be an include pattern No comma or space separated list of patterns of files that must be exclud
433. uired targetfile deploy xmlClasses jar gt lt srcfiles dir src xml includes dtd gt lt uptodate gt sets the property xmlBuild notRequired to true if the deploy xmlClasses jar file is more up to date than any of the DTD files in the src xm1 directory This can be written as lt uptodate property xmlBuild notRequired gt lt srcfiles dir S src xml includes dtd gt lt mapper type merge to deploy xmlClasses jar gt lt uptodate gt as well The xm1Build notRequirea property can then be used in a lt target gt tag s unless attribute to conditionally run that target For example running the following target lt target name xmlBuild depends chkXmlBuild unless xmlBuild notRequired gt lt target gt will first run the chkXm1Buila target which contains the lt uptodate gt task that determines whether xm1Build notRequired gets set The property named in the unless attribute is then checked for being set not set If it did get set ie the jar file is up to date then the xmlBuild target won t be run The following example shows a single source file being checked against a single target file lt uptodate property isUpToDate 166 305 Ant Manual 1 5 4 12 9 2003 7 47 PM srcfile usr local bin testit targetfile build flagfile gt sets the property isUpToDate to true if usr local bin testit is newer than S build flagfile 9 67 Waitfor Desc
434. ult on No Examples lt rename src foo jar dest S name version jar gt Renames the file foo jar to name S version jar assuming name and version being predefined properties If a file named name S version jar already exists it will be removed prior to renaming foo jar 9 52 Replace Description Replace is a directory based task for replacing the occurrence of a given string with another string in selected file If you want to replace a text that crosses line boundaries you must use a nested lt replacetoken gt element The output file is only written if it differs from the existing file This prevents spurious rebuilds based on unchanged files which have been regenerated by this task Parameters Attribute Description Required file file for which the token should be replaced dir The base directory to use when replacing a token Exactly one of the two in multiple files encoding The encoding of the files upon which replace No defaults to default J VM operates encoding token the token which must be replaced Yes unless a nested replacetoken element or the replacefilterfile attribute is used value the new value for the token When omitted an No empty string is used summary Indicates whether a summary of the replace No by default no summary is operation should be produced detailing how many produced token occurrences and files were processed propertyFile valid property file from which proper
435. ument for the chmod command See the section on directory based tasks on how the inclusion exclusion of files works and how to write patterns This task holds an implicit FileSet and supports all of FileSet s attributes and nested elements directly More FileSets can be specified using nested lt fileset gt elements Parameters Attribute Description Required k changed nested lt fileset gt be changed perm the new permissions includes comma or space separated list of patterns of files that must No be included excludes comma or space separated list of patterns of files that must No be excluded No files except default excludes are excluded when omitted defaultexcludesjindicates whether default excludes should be used or not No yes no Default excludes are used when omitted parallel process all specified files using a single chmod command No Defaults to true type One of file dir or both If set to file only the permissions of No default is file plain files are going to be changed If set todir only the directories are considered Examples lt chmod file S dist start sh perm ugotrx gt makes the start sh file readable and executable for anyone on a UNIX system lt chmod dir S dist bin perm ugo rx includes sh gt makes all sh files below dist bin readable and executable for anyone on a UNIX system lt chmod perm gtw gt lt fileset dir shared sources1 gt
436. ur own tasks to the system See also Writing your own task Parameters Attribute Description Required name the name of the task Yes unless file or resource have been specified classname the full class name implementing the task Yes unless file or resource have been specified file Name of the property file to load taskname classname pairs from No resource Name of the property resource to load taskname classname pairs No from classpath the classpath to use when looking up classname or resource No classpathref Reference to a classpath to use when looking up classname or No resource loaderRef the name of the loader that is used to load the class constructed No from the specified classpath Use this to allow multiple tasks types to be loaded with the same loader so they can call each other introduced in ant1 5 Parameters specified as nested elements classpath 160 305 Ant Manual 1 5 4 12 9 2003 7 47 PM Taskdef s classpath attribute is a PATH like structure and can also be set via a nested classpath element Examples lt taskdef name myjavadoc classname com mydomain JavadocTask gt makes a task called myjavadoc available to Ant The class com mydomain JavadocTask implements the task 9 61 Tempfile Description This task sets a property to the name of a temporary file Unlike the Java1 2 method to create a temporary file this task does work with Javal 1 It does not actually create the temporary
437. usersfile Property file that contains name value pairs mapping user IDs and No names that should be used in the report in place of the user ID daysinpast Sets the number of days into the past for which the change log No information should be retrieved start The earliest date from which change logs are to be included in the No report end The latest date to which change logs are to be included in the report No Parameters specified as nested elements user The nested lt user gt element allows you to specify a mapping between a user ID as it appears on the CVS server and a name to include in the formatted report Anytime the specified user ID has made a change in the repository the lt author gt tag in the report file will include the name specified in displayname rather than the user ID Attribute Description Required 96 305 Ant Manual 1 5 4 12 9 2003 7 47 PM displayname The name to be used in the CVS change log report Yes userid The userid of the person as it exists on the CVS server Yes Examples lt cvschangelog dir dve network destfile changelog xml gt Generates a change log report for all the changes that have been made under the dve network directory It writes these changes into the file changelog xml lt cvschangelog dir dve network dest file changelog xml daysinpast 10 gt Generates a change log report for any changes that were made under the dve network directory in the past 10 days It writ
438. uus reconfigure on the project ANTCCM_TEST BMO_ 1 10 5 5 CCMCreateTask Description Create a Continuus task Parameters Attribute Values Required comment Specify a comment No platform Specify the target platform No ccmdir path to the ccm executable file required if it is not on the PATH No resolver Specify the resolver No release Specify the CCM release No subsystem Specify the subsystem No task Specify the task number used to checkin the file may use default No Examples lt ccmcreatetask resolver user name release ANTCCM_TEST comment blahblah gt Creates a task for the release ANTCCM_TEST with the current user as the resolver for this task 10 6 Depend A task to manage J ava class file dependencies Description The depend task works by determining which classes are out of date with respect to their source and then removing the class files of any other classes which depend on the out of date classes To determine the class dependencies the depend task analyses the class files of all class files passed to it Depend does not parse your source code in any way but relies upon the class references encoded into the class files by the compiler This is generally faster than parsing the Java source To learn more about how this information is obtained from the class files please refer to th Java Virtual Machine Specification e Since a class dependencies only change when the class itself changes
439. ventions Parameters Attribute command executable dir os output append outputproperty resultpro perty timeout failonerror failifexecutionfails newenvironment vmlauncher Description the command to execute with all command line arguments deprecated use executable and nested lt arg gt elements instead the command to execute without any command line arguments the directory in which the command should be executed list of Operating Systems on which the command may be executed If the current OS s name is contained in this list the command will be executed The OS s name is determined by the Java Virtual machine and is set in the os name system property the file to which the output of the command should be redirected whether output should be appended to or overwrite an existing file Defaults to false the name of a property in which the output of the command should be stored the name of a property in which the return code of the command should be stored Only of interest if failonerror false Stop the command if it doesn t finish within the specified time given in milliseconds Stop the buildprocess if the command exits with a returncode other than 0 Defaults to false Stop the build if we can t start the program Defaults to true Do not propagate old environment when new environment variables are specified Run command using the Java VM s execution facilities where available If set t
440. w of any additional archive sites please report them to the lists 12 305 Ant Manual 1 5 4 12 9 2003 7 47 PM 3 Introduction This is the manual for version 1 5 4 of Apache Ant If your version of Ant as verified with ant version is older or newer than this version then this is not the correct manual set Please use the documentation appropriate to your current version Also if you are using a version older than the most recent release we recommend an upgrade to fix bugs as well as provide new functionality Apache Ant is a Java based build tool In theory it is kind of like make without make s wrinkles 3 1 Why Why another build tool when there is already make gnumake nmake jam and others Because all those tools have limitations that Ant s original author couldn t live with when developing software across multiple platforms Make like tools are inherently shell based they evaluate a set of dependencies then execute commands not unlike what you would issue on a shell This means that you can easily extend these tools by using or writing any program for the OS that you are working on however this also means that you limit yourself to the OS or at least the OS type such as Unix that you are working on Makefiles are inherently evil as well Anybody who has worked on them for any time has run into the dreaded tab problem Is my command not executing because have a space in front of my tab said the original auth
441. wing directory layout ant bin contains launcher scripts lib contains Ant jars plus necessary dependencies docs contains documentation ant2 a brief description of ant2 requirements images various logos for html documentation manual Ant documentation a must read 14 305 Ant Manual 1 5 4 12 9 2003 7 47 PM etc contains xsl goodies to create an enhanced report from xml output of various tasks migrate your build files and get rid of deprecated warning and more Only the bin and 1ib directories are required to run Ant To install Ant choose a directory and copy the distribution file there This directory will be known as ANT_ HOME Windows 95 Windows 98 Windows ME Note e On these systems the script used to launch Ant will have problems if ANT_HOME is a long filename i e a filename which is not of the format known as 8 3 This is due to limitations in the OS s handling of the for batch file statement It is recommended therefore that Ant be installed in a short 8 3 path such as C Ant e On these systems you will also need to configure more environment space to cater for the environment variables used in the Ant lauch script To do this you will need to add or update the following line in the config sys file shell c command com c p e 32768 4 3 1 Setup Before you can run ant there is some additional set up
442. wish to compile only source files located in certain packages below a common root use the include exclude attributes or lt include gt lt exclude gt nested elements to filter for these packages Do not include part of your package structure in the srcdir attribute or nested lt src gt elements or Ant will recompile your source files every time you run your compile target See the Ant FAQ for additional information Note If you are using Ant on Windows and a new DOS window pops up for every use of an external compiler this may be a problem of the JDK you are using This problem may occur with all JDKs lt 1 2 J ikes Notes Jikes supports some extra options which can be set be defining the properties shown below prior to invoking the task The setting for each property will be in affect for all lt javac gt tasks throughout the build The Ant developers are aware that this is ugly and inflexible expect a better solution in the future All the options are boolean and must be set to true or yes to be interpreted as anything other than false By default build compiler warnings is true while all others are false Property Description Default build compiler emacs Enable emacs compatible error messages false build compiler fulldepend Enable full dependency checking see false the F switch in the Jikes manual build compiler pedantic Enable pedantic warnings false build compiler warnings Don t disable warning messages true De
443. work throughput is limited Alternatively you can do the following 1 Copy web app_2_2 dtd onto your local disk somewhere either in the filesystem or even embedded inside a jar or zip file on the classpath 2 Create an lt xmlcatalog gt with a lt dtd gt element whose location attribute points to the file 3 Success The XML processor will now use the local copy instead of calling out to the internet XMLCatalogs can appear inside tasks that support this feature or at the same level as target i e as children of project for reuse across different tasks e g XML Validation and XSLT Transformation The XML Validate task uses XMLCatalogs for entity resolution The XSLT Transformation task uses XMLCatalogs for both entity and URI resolution XMLCatalogs are specified as either a reference to another XMLCatalog defined previously in a build file or as a list of dtd or entity locations A separate classpath for entity resolution may be specified inline via nested classpath elements otherwise the system classpath is used for this as well XMLCatalogs can also be nested inside other XMLCatalogs For example a Superset XMLCatalog could be made by including several nested XMLCatalogs that referred to other previously defined XMLCatalogs Currently only lt dtd gt and lt entity gt elements may be specified inline these roughly correspond to OASIS catalog entry types PUBLIC and URI respectively 7 3 23 1ENTITY DTD URI RESOLUTIO
444. xcludes takes precedence over includes files named index html will not be checked in by this command lt stcheckin URL STARTEAM 49201 Aproject AView username auser password secret rootlocalfolder C dev buildtest co rootstarteamfolder src java includes htm html xcludes index forced true recursive false gt This example is like the previous one but will only check in files from C dev buildtest co because of the turning off of the recursive attribute lt stcheckin URL STARTEAM 49201 Aproject AView username auser password secret rootlocalfolder C dev buildtest co rootstarteamfolder src java includes version txt forced true recursive false gt This example is like the previous one but will only check only in one file C dev buildtest co version txt to the StarTeam folder src java lt stcheckin URL STARTEAM 49201 Aproject AView username auser password secret rootlocalfolder C dev buildtest co rootstarteamfolder src java includes version java forced true recursive false addUncontrolled true 275 305 Ant Manual 1 5 4 12 9 2003 7 47 PM comment Fix Bug 667 gt This example is like the previous one but will only check only in one file C dev buildtest co version java to the StarTeam folder src java Because the addUncontrolled attribute has been set if StarTeam does not already control this file in this locati
445. y hh mm aa offset 5 unit hour gt lt tstamp gt Creates a timestamp in the property touch time 5 hours before the current time The format in this example is suitable for use with the lt touch gt task The standard properties are set also lt tstamp prefix start gt Sets three properties with the standard formats prefixed with start start DSTAMP start TSTAMP and start TODAY 9 64 Typedef Description Adds a data type definition to the current project such that this new type can be used in the current project Two attributes are needed the name that identifies this data type uniquely and the full name of the class including the packages that implements this type You can also define a group of data types at once using the file or resource attributes These attributes point to files in the format of Java property files Each line defines a single data type in the format 163 305 Ant Manual 1 5 4 12 9 2003 7 47 PM typename fully qualified java classname Typedef should be used to add your own types to the system Data types are things like paths or filesets that can be defined at the project level and referenced via their ID attribute Custom data types usually need custom tasks to put them to good use Parameters Attribute Description Required name the name of the data type Yes unless file or resource have been specified classname the full class name implementing the data type Yes unless
446. y the files you want to have excluded This is also done with patterns And finally with the defaultexcludes attribute you can specify whether you want to use default exclusions or not See the section on directory based tasks on how the inclusion exclusion of files works and how to write patterns This task forms an implicit FileSet and supports all attributes of lt fileset gt dir becomes base as well as the nested lt include gt lt exclude gt and lt patternset gt elements 147 305 Ant Manual 1 5 4 12 9 2003 7 47 PM It is possible to use different compilers This can be selected with the build rmic property or the compiler attribute There are three choices e sun the standard compiler of the J DK e kaffe the standard compiler of Kaffe e weblogic The miniRMI project contains a compiler implementation for this task as well please consult miniRMI s documentation to learn how to use it Parameters Attribute base classname filtering sourcebase stubversion classpath classpathref includes includesfile excludes excludesfile defaultexcludes verify iiop iiopopts idl idlopts debug includeAntRuntime includeJ avaRuntime extdirs compiler Parameters specified as nested elements Description the location to store the compiled files the class for which to run rmic indicates whether token filtering should take place Pass the keepgenerated flag to rmic and move the generated source
447. y where the checked out files should be placed No default is project s basedir ej Pa CORR suppress informational messages A eas only don t change any files No default to false output the file to direct standard output from the command No default output to ANT Log as MSG_INFO the file to direct standard error from the command No default error to ANT Log as MSG WARN o Gea to append output error when redirecting to a file No default to false eo ae used by CVS to communicate with the server No default port 2401 A cess file to read passwords from No default file cvspass ailonerror Stop the build process if the command exits with a return code No other than 0 Defaults to false Examples lt cvs cvsRoot pserver anoncvs cvs apache org home cvspublic package ant dest S ws dir gt checks out the package module ant from the CVS repository pointed to by the cvsRoot attribute and stores the files in ws dir lt cvs dest ws dir command update gt updates the package module that has previously been checked out into ws dir lt cvs command q diff u N output patch txt gt silently q creates a file called patch txt which contains a unified u diff which includes new files added via cvs add N and can be used as input to patch The equivalent using lt commandline gt elements is lt cvs output patch gt lt commandline gt lt argument value
448. yenv TERM Note that if you supply a property name with a final One of these it will not be doubled ie environment myenv will still allow access of When not using environment variables through myenv PATH and myenv TERM This the name functionality is currently only implemented on select platforms Feel free attribute to send patches to increase the number of platforms this functionality is supported on Note also that properties are case sensitive even if the environment variables on your operating system are not e g it will be env Path not env PATH on Windows 2000 classpath the classpath to use when looking up a resource No classpathref the classpath to use when looking up a resource given as reference to a No 142 305 Ant Manual 1 5 4 12 9 2003 7 47 PM lt path gt defined elsewhere prefix Prefix to apply to properties loaded using file or resource A is No appended to the prefix if not specified Parameters specified as nested elements classpath Property s classpath attribute is a PATH like structure and can also be set via a nested classpath element Examples lt property name foo dist value dist gt sets the property foo dist to the value dist lt property file foo properties gt reads a set of properties from a file called foo properties lt property resource foo properties gt reads a set of properties from a resource called foo properties Note that you can ref

Apache Ant 1.5.4 Manual

Contents

Download Pdf Manuals

Related Search

Related Contents