ant

The main purpose of the <ant> task is to execute Ant on a build file. This task helps run subproject tasks. The optional attributes of the <ant> task are:

• antfile: Specifies the name of the build file to be used. The build.xml file is the default file.

• dir: Specifies the name of the directory to be used as the basedir for the new project. The current directory is the default directory.

• inheritAll: Transfers all the properties of the current project to the new project if the inheritAll attribute is set to true. The default attribute value is true.

• inheritRefs: Transfers all references to data types in the current project to the new project if the inheritRefs property is set to true. The default attribute value is false.

• output: Specifies the name of the file to which you write output. The default attribute value is the System.out file.

• target: Executes the target in the specified Ant file. The default attribute value is the default target in the build file.

You can use property elements to specify a property for a project, as shown:

<ant antfile = "build.xml">
<property name = "param 1" value = "version 1.x"/>
<property file = "project/default.properties"/>
</ant>

For example, to prevent the properties set in the parent project from overriding the properties set in the new project, the syntax of the <ant> task is:

<ant inheritAll="false">

antcall

The <antcall> task allows you to request another target from the current target. The difference between the <ant> task and the <antcall> task is that the target that you call should be in the same build file. The mandatory attribute of the <antcall> task is target, which specifies the name of the target to be executed. The optional attributes of the <antcall> task are:

• inheritAll: Transfers all the properties of the current project to the new project if the inheritAll property is set to true. The default attribute value is true.

• inheritRefs: Transfers all the references of the current project to the new project if the inheritRefs property is set to true. The default attribute value is false.

antstructure

The <antstructure> task allows you to generate a Document Type Definition (DTD) for Ant build files. The <antstructure> task consists of information about the existing Ant tasks and lists all the attributes of each task. The mandatory attribute of the <antstructure> task is output, which specifies the name of the file to which you output the DTD.

For example, to produce output for the DTD of a text file, the syntax is:

<antstructure output="abc.txt"/>

A limitation of the <antstructure> task is that it occasionally produces invalid DTD because Ant allows task developers to describe random elements, which can result in duplication of filenames.

available

The <available> task allows you to verify whether resources, such as class, file, and directory, in Ant and the resources in the Java Virtual Machine (JVM) are available. The property specified in the property attribute of the <available> task is set to true if the resource is available. The mandatory attributes of the <available> task are:

• classname: Specifies the name of the class to verify its availability in the class path. This attribute is mandatory if you do not specify the file attribute or the resource attribute.

• file: Specifies the name of the file to verify its availability. This attribute is mandatory if you do not specify the classname attribute or the resource attribute.

• property: Specifies the name of the property to be set.

• resource: Specifies the name of the resource in the JVM to check its availability. This attribute is mandatory if you do not specify the classname attribute or the file attribute.

The optional attributes of the <available> task are:

• classpath: Specifies the class path to be used when checking the availability of a class.

• filepath: Specifies the file path to be used when checking the availability of a file.

• ignoresystemclasses: Ignores the Ant run time classes for the classname attribute if the attribute is set to true. The default attribute value is false.

• type: Specifies whether you are searching a file or a directory. If you do not specify this attribute, the task will be successful whether you locate a file or a directory.

• value: Specifies a value to which the property attribute will be set if the resource is available. The default attribute value is true.

For example, to check the availability of a class, use the <available> task. When executed, the following code will set the availableClass property to true:

<available property="availableClass" 
classname="org.apache.tools.ant.taskdefs.Available"/> 

The following code shows how to use the <available> task to determine whether or not to execute a target:

<target name = "availableTest">
<available property = "resourcesAvailable" file="info.xml"/>
</target>
<target name ="executetarget" depends ="availableTest" if="resourcesAvailable">
</target>   

This above example shows that the execution of the executetarget target will occur only if the resourcesAvailable property is set.

basename

You can use the <basename> task to determine the last element in a specified path. The last element can be a relative, absolute, or a simple filename. When you locate the last element, the <basename> task assigns it to the property specified in the property attribute. The mandatory attributes of the <basename> task are:

• file: Specifies the path of the file.

• property: Specifies the name of the property to be set.

The optional attribute of the <basename> task is:

• suffix: Removes the suffix of a file by specifying the suffix of that file with or without a period (.).

For example, the following code sets the batchfile property of the abc.bat file:

<basename property="batchfile" suffix="bat" file="abc.bat"/>

buildnumber

The <buildnumber> task helps locate build numbers. This task uses a file to retrieve the current build number. The <buildnumber> task reads a number from a file, such as build.number, and rewrites that number after incrementing it by one. The optional attribute of the <buildnumber> task is the file that specifies the name of the file containing the build number.

For example, to attain the build number of the abc.txt file and increment its value by one, the syntax is:

<buildnumber file="abc.txt"/>

If the abc.txt file does not exist, the <buildnumber> task will create it and set the build number to 0.

checksum

The <checksum> task allows you to produce checksums for a set of files using an algorithm. This task also allows you to verify a checksum. The mandatory attribute of the <checksum> task is file, which specifies the name of the file for which to generate the checksum. You need not specify the name of the file if you have specified the fileset in the task.

The optional attributes of the <checksum> task are:

• algorithm: Specifies the algorithm to be used to produce the checksum value. The default attribute value is MD5.

• fileext: Specifies the file extension to be used for the generated checksum file. The default attribute value is the name of the current algorithm. The value of the fileext attribute appends to the existing filename.

• property: Assigns the checksum value to the property specified in this attribute. You use the property attribute to specify one file. If you do not set the verifyproperty attribute of the <checksum> task, the property attribute specifies the name of the property to be set with the generated checksum value. If you set the verifyproperty attribute, the property attribute specifies the checksum for comparison and not a name of the property, which contains the generated checksum. You cannot specify the property attribute when you are using the fileext attribute or when the number of files for which you need to generate the checksum is greater than 1.

• provider: Specifies the provider of the checksum algorithm that you use for checksum calculation.

• forceoverwrite: Specifies that the existing files will be overwritten if the attribute value is set to yes. The attribute value is no, by default.

• verifyproperty: Specifies the name of the property whose value is set to true or false depending on whether the generated checksums match the existing ones. When this attribute is set to true, you do not write the generated checksum to a file or a property. Instead, you use the content of the file or the property to check against the generated checksum.

For example, to generate the checksum for each file specified in the fileset, which includes the abc.txt and xyz.txt files, and store the checksum in the subsequent file with the MD5 extension, the syntax is:

<checksum>
<fileset dir="bar">
<include name="abc.txt"/>
<include name="xyz.txt"/>
</fileset>
</checksum>

chmod

The <chmod> task allows you to change the permission of a file, a directory, or a set of files, in a UNIX system. You need to specify the value of the permission attribute in UNIX style, such as ugo+rwx. The mandatory attributes of the <chmod> task are:

• dir: Specifies the name of a directory that holds the files whose permissions need to be changed. This attribute is mandatory if you have not specified the file attribute or the fileset within the <chmod> task.

• file: Specifies the name of the file or directory whose permissions you have to change. This attribute is mandatory if you have not specified the directory or the fileset in the <chmod> task.

• perm: Indicates the new permissions to be applied.

The optional attributes of the <chmod> task are:

• excludes: Specifies a comma-separated list of file patterns to be excluded.

• includes: Specifies a comma-separated list of file patterns to be included. The default attribute value is to include all files.

• parallel: Processes all the specified files in one chmod command if the property is set to true. The attribute value is true, by default.

• type: Specifies the Ant data types, such as file, dir, or both, which you can use in the <chmod> task. The attribute value is file, by default. The permissions are applied only to files if the type is specified as file and to directories if the type is specified as dir.

For example, to provide the write permission to an end user and a group for the abc.txt file, the syntax is:

<chmod file="abc.txt" perm="ug+w"/>

concat

The <concat> task concatenates a group of files to an output file. If the file does not exist, the <concat> task creates the destination file. This task also allows the concatenation of a string to a file or a console. You specify the files to be concatenated using paths, filesets, or filelists. The optional attributes of the <concat> task are:

• append: Appends rather than overwrites a destination file if the value of the attribute is set to no and the destination file is present. The attribute value is no, by default.

• destfile: Specifies the name of the destination file for the concatenated stream. The default destination is the console.

• encoding: Specifies the encoding for the input files. The default value of the attribute is the default character encoding of the operating system running on the computer.

For example, to create a text file that contains the contents of all the .txt files in the misc directory, the syntax is:

<concat destfile="abc.txt">
<fileset dir="misc" includes="*.txt"/>
</concat>

For example, the following code adds a string to a file. If the file does not exist, the code creates the file and then adds the string.

<concat destfile ="abc.log">Added String </concat> 

condition

The <condition> task allows you to set the property specified by the property attribute by applying specific conditions using nested elements. The value is set to true, by default, if the condition is true. If the condition is false, no value is set for the property. The mandatory attribute of the <condition> task is property, which specifies the name of the property to be set. The optional attribute of the <condition> task is value, which specifies the value to provide to the property if the condition evaluates to true. The default setting is true.

Listing 3-1 shows how to set the extModule property:

Listing 3-1: Setting the extModule Property

<condition property="extModule">
<and> 
<available file="abc.txt">
<not> 
<os family="Linux"/> 
</not>
</and>
</condition>

The above listing shows how to set the extModule property if the abc.txt file exists. The listing also specifies that the operating system should not be Linux.

copy

The <copy> task allows you to copy files from one directory to another. By default, you can only copy files if the destination file is older than the source file or if the destination file does not exist. If you use filters, you can only copy text files using the <copy> task. Using the <copy> task with filters corrupts the binary files. This is applicable for both the implicit filters of the fileset and the explicitly specified filters of the copy task. The mandatory attributes of the <copy> task are:

• file: Specifies the name of the source file. You have to specify the file attribute if the <copy> task does not contain any specified fileset elements.

• tofile: Specifies the name of the destination file. You have to specify the tofile attribute if the file attribute is specified and the todir attribute is not specified.

• todir: Specifies the name of the destination directory. You can use the todir attribute with the file attribute. It is possible to use the todir attribute with nested <fileset> elements if:
  
  

  • The set of files is greater than 1

  • The dir attribute is specified in the <fileset>

  • The file attribute is specified

  
  

The optional attributes of the <copy> task are:

• filtering: Allows filtering while copying files if you set the attribute value to true. You can use nested <filterset> elements regardless of the attribute value. The default attribute value is false.

• flatten: Ignores the directory structure and copies all the files in the source fileset to the destination directory if you set the attribute value to true. The default attribute value is false.

• includeemptydirs: Ignores empty directories if the value of the property is set to false. The default attribute value is true.

• overwrite: Overwrites the existing files if the value of the attribute is set to true. To avoid overwriting the existing files if the version of the existing file is new, you can set the value of the attribute to false. The default attribute value is false.

• verbose: Logs the files when copying them if the value of the attribute is set to true. The default attribute value is false.

The syntax to copy the abc.txt file to the misc directory is:

<copy file="abc.txt" toDir="misc"/>

For example, the following code will copy files with the .html extension from the abc directory to the xyz directory:

<copy todir = "${xyz}">
<fileset dir = "${abc}">
<include name = "**/*.html"/>
</fileset>
</copy>

cvs

The <cvs> task allows you to use a cvs repository in your Ant project. This task allows you to automate version control tasks. The <cvs> task provides the capability to use any valid cvs command, such as tagging a release, extracting a specific set of files, and maintaining a constant method of performing tasks throughout a project. You need to install cvs on your computer to use this task. The optional attributes of the <cvs> task are:

• command: Specifies the command that you want to run. The value of this attribute can be any cvs command. The default attribute value is checkout.

• compression: Specifies the use of compression. If you set the compression attribute value to true, the compressionlevel attribute is set to 3. The default attribute value is false.

• compressionlevel: Indicates the level of compression to be used. Valid values of the level of compression are between 1 and 9. Any other value means compression = false.

• cvsroot: Specifies the value of the CVSROOT variable.

• cvsrsh: Specifies the value of the CVS_RSH variable.

• date: Uses the most recent revision no later than the specified date, if the date is specified.

• dest: Specifies the name of the destination directory for checked out files. The default attribute value is the basedir of the project.

• error: Specifies the name of the file that will store the resultant errors. The default attribute value is Ant log file and the default error written in the file is MSG_WARN.

• noexec: Delivers a report without making any changes to the files if the value is set to true. The default attribute value is false.

• output: Specifies the name of the file that contains the output. The default attribute value is Ant log file and the default message written in the file is MSG_INFO.

• package: Specifies the name of the package/module to be examined.

• passfile: Specifies the name of the file from which to read passwords. The default attribute value is ~/.cvspass.

• port: Specifies the port number that CVS uses to communicate with the server. The default attribute value is 2,401.

• quiet: Restrains the output from the executed command. The default attribute value is false.

• tag: Specifies the name of the tag of the package or module to be examined.

The syntax to update the selected files and pass them to the destination directory is:

<cvs command="update" dest="${abc}"/> 

For example, the following code extracts the abc.pkg package into the destination directory:

<cvs cvsroot=":pserver:Don@ant.com:/home/xyz" package="abc.pkg" dest = "${xyz}
"/>cvstagdiff

cvstagdiff

The <cvstagdiff> task produces an XML report that lists the changes made to the files in a cvs repository between two dates or tags. The mandatory attributes of the <cvstagdiff> task are:

• destfile: Specifies the name of the produced report file.

• enddate: Specifies the end date from which the changes in the XML report are to be included in the report. This attribute is mandatory if the endtag attribute is not specified.

• endtag: Specifies the end tag from which the changes in the XML report are to be included in the report. This attribute is mandatory if the enddate attribute is not specified.

• startdate: Specifies the start date from which the changes in the XML report are to be included in the report. This attribute is mandatory if the starttag attribute is not specified.

• starttag: Identifies the start tag from which changes in the XML report are to be included in the report. This attribute is mandatory if the startdate attribute is not specified.

For example, to report the differences between the files tagged Ant_14 and Ant_141 in the jakarta-ant package, the syntax is:

<cvstagdiff cvsRoot=":pserver:anoncvs@cvs.apache.org:/home/cvspublic" 
destfile="tagdiff.xml" 
package="jakarta-ant" 
startTag="Ant_14" 
endTag="Ant_141" 
/>

delete

The <delete> task allows you to remove files. This task allows you to remove class files before a new build. The mandatory attributes of the <delete> task are:

• dir: Specifies the name of the directory from which you need to remove files. This attribute is mandatory if you have not specified the file attribute and the fileset elements in the <delete> task.

• file: Specifies the name of the file to be deleted. This attribute is mandatory if you have not specified the dir attribute and the fileset elements in the <delete> task.

The optional attributes of the <delete> task are:

• defaultexcludes: Specifies that default excludes should not be used if the attribute value is set to false. The attribute value is set to true, by default.

• excludes: Excludes a comma-separated list of file patterns.

• failonerror: Stops the build when an error occurs if the attribute value is set to true. If you set the attribute value to false, the attribute only reports the error on the screen. The attribute value is set to true, by default.

• includes: Includes a comma-separated list of file patterns if the attribute value is set to true. The default attribute value is to include all files.

• includeemptydirs: Includes empty directories if the attribute value is set to true. The default attribute value is true.

• quiet: Avoids the reporting of errors when a file or directory cannot be deleted if the attribute value is set to true. The default attribute value is false.

• verbose: Outputs the name of each deleted file if the attribute value is set to true. The default attribute value is false.

The syntax to delete the abc.txt file is:

<delete file="abc.txt"/>

For example, the following code deletes the abc directory and all the files and subdirectories within the directory:

<delete dir = ‘abc’/>

The following code deletes files that do not have the .html extension in the abc directory:

<delete>
<fileset dir = "${abc}" excludes ="**\*.html"/>
</delete> 

exec

The <exec> task allows you to run a system command. Ant forks a new process to execute this task and you cannot use the new process to read input. You can provide input to the process with the help of the input and inputstring attributes of the <exec> task. If you specify the os attribute, the command will execute only if you run Ant on that operating system. The mandatory attributes of the <exec> task are:

• executable: Specifies the command to be executed without any command-line arguments.

• command: Specifies the command to run and includes all the command-line arguments. This attribute is mandatory if the executable attribute does not exist. You need to avoid this attribute because this attribute is obsolete. Instead of the command attribute, you should use the executable attribute and nested arguments.

The optional attributes of the <exec> task are:

• append: Appends the output to the existing file instead of overwriting the file, if the value is set to true. The attribute value is set to false, by default.

• dir: Identifies the directory in which you need to run the command.

• failifexecutionfails: Causes the build process to stop if the program cannot start when the attribute value is set to true. The default attribute value is true.

• failonerror: Stops the build process if the command exits with a return code other than 0 if the attribute is set to true. The default attribute value is false.

• newenvironment: Prevents the use of old environment variables with the occurrence of new environment variables if the attribute value is set to true. The default attribute value is false.

• output: Specifies the name of the file that stores the output. If you do not redirect the error stream to a file or a property, the error stream will also be included in the file that stores the output.

• outputproperty: Specifies the name of the property that stores the output.

• resultproperty: Specifies the name of the property that stores the return code.

• timeout: Indicates the time, in milliseconds, within which the execution of the command stops if it is not complete.

• vmlauncher: Specifies that the command will run using JVM execution if the attribute value is set to true. If you set the attribute value to false, the command uses the operating system’s shell, either directly or through the antRun scripts. On some operating systems, the vmlauncher attribute provides access to features not available using the JVM. For example, in Windows, you can execute scripts instead of interpreters. The default attribute value is false.

• os: Specifies the operating system on which you can execute the command attribute.

• input: Specifies a file from which you obtain the executed command’s standard input.

• inputstring: Specifies a string that operates as input for the executed command.

For example, to execute the build.bat batch file in the abc directory with the output displayed in the output.log file in Windows 2003, the syntax is:

<exec dir="abc" executable="cmd.exe" os="Windows 2003" output="output.log"> 
<arg line="build.bat"/> 
</exec>

echo

The <echo> task allows you to show a message in the standard output or a file. The <echo> task can also provide extra information to an interactive Ant end user. The mandatory attribute of the <echo> task is message, which specifies the output message. This attribute is mandatory if the body of the tag does not contain any message.

The optional attributes of the <echo> task are:

• append: Appends the output to the end of the file and prevents overwriting if the attribute value is set to true and a file attribute value is specified. The default attribute value is false.

• file: Specifies the name of the file to which you direct the output.

• level: Specifies the level of reporting the message. The valid values are debug, error, info, verbose, and warning. The default attribute value is warning.

For example, to view the text message, Welcome to Ant, in the standard output, the syntax is:

<echo message="Welcome to Ant"/> 

get

The <get> task allows you to retrieve a file from a specified URL. You can also use this task to download an external resource. The mandatory attributes of the <get> task are:

• dest: Specifies the destination of the retrieved file.

• src: Indicates the source URL from which to retrieve the file.

The optional attributes of the <get> task are:

• ignoreerrors: Logs the errors without stopping the execution of the task until there are no more errors, if the attribute value is set to true.

• password: Specifies the password for basic HTTP authentication. You need to specify the password attribute with the username attribute.

• username: Specifies the user name for basic HTTP authentication. You need to specify the username attribute with the password attribute.

• usetimestamp: Downloads the file using HTTP only if the timestamp on the remote file is newer than that on the local version, if the attribute value is true. The default attribute value is false.

The syntax to obtain a file at a particular URL and save it as the abc.xml file is:

<get src="http://www.sams.com/ant/data/chapters.xml"
dest="abc.xml"/>

gunzip

The <gunzip> task allows you to extract the gzip files where the source file is gunzipped only if the destination file does not exist or is older than the source file. By default, the name of the destination file is the same as that of the source file but without the .gz extension. The mandatory attribute of the <gunzip> task is src, which specifies the name of the file that you want to decompress. The optional attribute of the <gunzip> task is dest, which specifies the name of the destination file or directory.

The syntax to extract the abc.tar.gz zipped file is:

<gunzip src="abc.tar.gz"/>

gzip

The <gzip> task allows you to compress a file. This task creates the zipped version of the source file with the same filename but with the .gz extension. The <gzip> task creates the zipped file only if the zipped file is not present or if it is older than the source file. The mandatory attributes of the <gzip> task are:

• src: Specifies the name of the file to be gzipped.

• zipfile: Specifies the name of the destination file.

The syntax to zip the abc.tar file is:

<gzip src="abc.tar" zipfile="somefile.tar.gz"/>

fail

The <fail> task allows you to exit the current build. It also allows you to specify a message that will show when the build exits. The optional attributes of the <fail> task are:

• if: Specifies that the build will fail only if the property specified in this attribute exists.

• message: Specifies the message that will show when the build exits.

• unless: Specifies that the build will fail only if the property specified in this attribute does not exist.

For example, the following code causes the build to exit and reports the line number at which the build exited:

<fail/>

If the build file is stored at E:\ant\, the output of the above code will be:

E:\ant\build.xml:165: No message

You can set the message using either of the following two techniques:

<fail message="Failure Message"/>
or
<fail> 
multiple lines 
failure
message 
</fail>

input

The <input> task provides user interaction in a build. This task allows you to send a message to prompt for input, sets valid values to execute the validation process, and allows the end user to create a property from the value that the end user inputs. You cannot override an existing property using the <input> task. Ant will ignore any such attempt to override an existing property. The optional attributes of the <input> task are:

• addproperty: Specifies the name of the property to be created using end user specified input.

• message: Shows the message as a prompt for input.

• validargs: Specifies a comma-separated list of values that can be valid input arguments. Ant rejects any input not defined in this attribute. There is no validation, by default.

For example, the following code sets the validargs attribute to y and n. You set the message prompt in the form of the query message asking whether or not to exit. The query message will continue to prompt unless the end user enters the validarg attribute’s y or n value. The addproperty attribute sets the value of the exit property according to the value input:

<input validarg="y,n" addproperty="exit"> 
Do you wish to exit? 
</input>

jar

The <jar> task allows you to form JAR files that you can use to set distributions and backups. The mandatory attribute of the <jar> task is destfile, which specifies the name of the JAR file to be created.

The optional attributes of the <jar> task are:

• basedir: Specifies the name of the directory in which the files to be included in the JAR file are located.

• compress: Compresses the files in the JAR file if the attribute value is true. This applies to the entire archive and not only to the updated files. The attribute value is set to true, by default.

• defaultExcludes: Specifies whether or not to use the default excludes. If the attribute value is set to true, you can use the default excludes. The default attribute value is yes.

• duplicate: Specifies the option if you locate a duplicate file. The valid options are add, preserve, and fail. The default attribute value is add.

• encoding: Specifies the character encoding you can use for filenames inside the archive. The default attribute value is Unicode Transformation Format-8 (UTF-8). You should not change the default attribute value because Java will not be able to read the created archive.

• excludes: Excludes a comma-separated list of file patterns.

• manifest: Specifies the name of the file to be used as the manifest.

• filesetmanifest: Specifies the option when a manifest file is present in zipfileset or zipgroupfileset. The valid options are:
  
  

  • merge: Merges all the manifests and any other specified manifests.

  • mergewithoutmain: Merges everything but the main section of the manifests.

  • skip: Does not merge any manifest.

  
  

• attribute value of filesetmanifest is set to skip, by default.

• filesOnly: Stores only file entries if the attribute is set to true. The default attribute value is false.

• includes: Includes a comma-separated list of file patterns. The default attribute value is to include all files.

• index: Forms an index list if the attribute value is true. This attribute is valid for JDK 1.3 and later. You form an index list to increase the speed of class loading. The default attribute value is false.

• update: Specifies that the JAR file will be updated if the attribute value is set to true. If you set the attribute value to false, the JAR file will be overwritten. The default attribute value is false.

• whenempty: Specifies the behavior if no matching files exist. The valid values are skip, create, and fail. The attribute value is set to create, by default.

The syntax to form a JAR file that contains all the files in the source directory is:

<jar destfile="abc.jar" basedir="source"/>

The following example shows how to use a nested <metainf> element to state the files to be included in the Meta-Inf directory and a nested <include> element to specify the files for the JAR main directory:

<jar destfile ="test.jar" basedir = "source" manifest=".\misc\manifest.mf">
<include name ="com/dir/**/*.class"/>
<metainf dir = ".">
<include name="*.xml"/> 
</metainf> 
</jar>

java

The <java> task runs a Java class within the running Ant JVM or forks a new JVM, if specified. A class that calls System.exit() will terminate the JVM running the Ant process. If you do not want the existing JVM to terminate or when you use the <java> task to execute JAR files, it is necessary to set fork equal to true. It is also essential to fork executable jars so that Ant can run them.

Ant manages regular input when employing the <java> task. As a result, you cannot interact with the forked Virtual Machine (VM). The only way to interact with the forked VM is using the input and the inputstring attributes of the <java> task. In Ant 1.6, any attempt to read input in the forked VM will receive an EOF (-1). The mandatory attributes of the <java> task are:

• classname: Specifies the name of the Java class to be executed. This attribute is mandatory if you have not specified the jar attribute.

• jar: Specifies the name of the JAR to be executed. You need to include a main-class entry in the manifest. You also need to set the fork attribute to true if you select this attribute. This attribute is mandatory if you do not use the classname attribute.

The optional attributes of the <java> task are:

• append: Prevents overwriting and appends the output to the current file if the attribute value is set to true. The default attribute value is false.

• args: Specifies the command-line arguments to be passed to the executing class. Ant 1.6 specifies this parameter as a nested element.

• classpath: Specifies the class path to be used. Its default value is the Ant home environment variable, which is the location at which you execute Ant. In Ant 1.6 or later, the classpath attribute can also be set using a nested classpath element.

• classpathref: Specifies the classpath supplied as a reference to a defined path.

• dir: Indicates the location of the directory to which to call the forked JVM. You need to ignore this attribute value in case the fork is set to false.

• failonerror: Causes the build process to stop if the executing Java class returns with a return code other than 0, if you enable the attribute value. The attribute is disabled, by default, which means that the return code of the Java class is ignored, by default. Alternatively, you can set the resultproperty attribute of the <java> task to the name of the property where the return code is stored. When you set the failonerror attribute to true, the only possible value of the resultproperty attribute is 0. Ant treats any nonzero response as an error and exits the build.

• Resultproperty: Specifies the name of a property in which the return code of the command needs to be stored. This attribute is valid only if the failonerror attribute is set to false and if the fork attribute is set to true.

• fork: Performs class execution in a JVM other than the current JVM if the attribute is enabled. By default, the attribute value is disabled.

• jvm: Specifies the command to invoke JVM. The value of the attribute is Java, by default. The command is determined by java.lang.Runtime.exec(). JVM ignores the command if the fork attribute is disabled.

• jvmargs: Identifies the arguments to pass to the forked JVM. The default attribute value is Java.

• maxmemory: Specifies the maximum amount of memory to allocate to the forked JVM. JVM ignores the value if the fork attribute is disabled.

• newenvironment: Stops the use of old environment variables with the occurrence of new environment variables if the value is set to true and the fork attribute is enabled. The default attribute value is false.

• output: Specifies the name of a file to which you write output from the executed class. If redirection of the error stream does not occur to a file or a property, the error stream will appear in this output.

• timeout: Specifies the maximum time for waiting before terminating the command if the command does not execute completely until then. You need to use this attribute when the fork attribute is set to true.

• input: Specifies a file from which you acquire the executed command’s standard output.

• inputstring: Specifies a string that provides input data for the executed command.

For example, the following code executes the com.ant.antTest class with the class path:

<java classname="com.ant.antTest"> 
<classpath> 
<pathelement location="${build}"/> 
<pathelement location="${jarpath}jsdk.jar"/> 
</classpath> 
</java> 

javac

The <javac> task allows you to compile Java source files. The<javac> task runs the Java compiler on a set of Java source files in the source and destination directories. Compilation will occur only with Java classes that do not have a corresponding .class file or where the class file is older than the .java file. This task does not analyze source code or perform logical dependency analysis. For example, Ant does not know if subclasses need compiling after any modifications that may occur in the source code of a base class.

Ant allows you to employ an alternative compiler to execute the <javac> task. You can specify an alternative compiler by either setting the global build.compiler property, which will affect all <javac> tasks throughout the build, or by setting the compiler attribute specific to the current <javac> task. The mandatory attribute of the <javac> task is srcdir, which specifies the name of the directory containing the source files that you need to compile. To compile only the source files located in specific packages below a common root, use the include/exclude attributes or the <include>/<exclude> nested elements to filter these packages.

The optional attributes of the <javac> task are:

• bootclasspath: Specifies the path of the bootstrap classes to be used.

• classpath: Specifies the class path to be used.

• compiler: Specifies a compiler, other than the default compiler for the current JVM, to be used. This overrides the build.compiler property.

• debug: Specifies whether you need to compile the source attribute with debug information. The default attribute value is false. If this attribute is set to false, -g:none will be passed at the command line for the compilers that support it. Other compilers will not contain any command-line arguments. If the attribute value is set to true, the value of the debuglevel attribute determines the command-line argument.

• debuglevel: Specifies the valid attribute values depending on the –g command-line switch are none, or a comma-separated list of keywords, such as line, vars, and source. The default attribute value is none. All implementations except Ant versions >= 1.2 will ignore this attribute. If you do not enable the debug attribute, the Java compiler will ignore this attribute.

• destdir: Specifies the target directory for the created class files. The default attribute value is the current directory.

• encoding: Specifies encoding for the source files.

• excludes: Eliminates a comma-separated list of files.

• extdirs: Specifies a substitute location for installed extensions, which overrides the default location.

• failonerror: Halts the build process if compilation is not successful if the attribute is enabled. The attribute value is set to true, by default.

• fork: Specifies whether to execute javac using the JDK compiler externally. The default attribute value is false.

• includeantruntime: Specifies whether to include Ant run time libraries. The default attribute value is true.

• includejavaruntime: Specifies whether to include default run time libraries from the executing VM. The default attribute value is false.

• includes: Includes a comma-separated list of file patterns. The default value is to include all files.

• listfiles: Shows the list of files that you want to compile if the attribute value is true. The attribute value is set to false, by default.

• memoryinitialsize: Specifies the original size of memory for the VM. The default attribute value is the standard VM memory setting.

• Memorymaximumsize: Specifies the maximum size of memory for the VM. The default value is the standard VM memory setting.

• nowarn: Generates no warnings if the value is set to true. The default setting is false.

• optimize: Specifies whether the source attribute needs to be compiled with optimization. The default attribute value is false.

• source: Specifies that support will be enabled for declarations if you set the attribute value to 1.4.

• sourcepath: Specifies the source path you can use. The default attribute value is the value of the srcdir attribute.

• verbose: Enables the verbose output if the attribute value is set to true. The default attribute value is false.

The compilers available for execution of the <javac> task are:

• Classic: The standard compiler of JDK 1.1/1.2.

• Modern: The standard compiler of JDK 1.3/1.4.

• Jikes: The Jikes compiler. You can set Jikes as the default compiler if you set the JIKES_HOME environment variable to the location of the Jikes compiler.

• Jvc: The command-line compiler from Microsoft's Software Development Kit (SDK) for Java and Visual J++.

• Kjc: The Kopi compiler.

• Gcj: The gcj compiler from GNU’s Not UNIX (GNU).

• Symantec (Sj): The Symantec Java compiler.

• Extjavac: A classic or modern compiler in a separate JVM.

The syntax to compile the source files contained in the $(host) directory using the ${dest} class path and storing the resultant files in the ${dest} directory is:

<javac src="${host}" destdir="${dest}" classpath="${dest}"/> 

For example, the following code compiles all files in the ${src} directory and stores the compiled files in the ${build} directory:

<javac srcdir="${src}"
destdir="${build}"
includes="package1/p1/**,package1/p2/**"
excludes="package1/p1/testpackage/**"
classpath="xyz.jar"
debug="on"
/>

The above code compiles the package1/p1 and package1/p2 files. The files that are not compiled are the files in the package1/p1/testpackage and in its subdirectory.

loadFile

The <loadfile> task allows you to load the contents of a text file to a property specified in the property attribute. The mandatory attributes of the <loadFile> task are:

• property: Sets the property with the contents of the file.

• srcfile: Specifies the name of the file to load.

The optional attributes of the <loadFile> task are:

• encoding: Specifies the encoding to use when loading the file.

• failonerror: Halts the build process when an error occurs if the attribute value is true. The default attribute value is true.

The syntax to load the contents of the abc.txt file to the property bar is:

<loadfile srcfile="abc.txt" property="bar"/> 

In this case, if the file does not exit, the build process will stop.

mail

The <mail> task allows you to send Simple Mail Transfer Protocol (SMTP) e-mail messages. You can send the files contained in the message body as attachments and logs in the e-mail message. You transmit the attachments using nested fileset elements. The mandatory attributes of the <mail> task are:

• from: Specifies the e-mail address of the sender.

• message: Specifies the message to send in the body of the e-mail message. The <mail> task ignores the message attribute if you have specified the files attribute.

• messagefile: Specifies the file that contains content for the e-mail message body.

The optional attributes of the <mail> task are:

• encoding: Specifies the encoding to use for the e-mail message. The valid values are mime, plain, and auto. The default attribute value is auto.

• failonerror: Halts the build process if an error occurs if the attribute value is true. The default attribute value is set to true.

• files: Specifies a comma-separated list of files to send as attachments in the e-mail message.

• mailhost: Specifies the name of the host of the SMTP mail server. The default attribute value is localhost.

• messagemimetype: Specifies the Multipurpose Internet Mail Extensions (MIME) type message. The default value is text/plain.

• subject: Specifies the value of the subject field of the e-mail message.

• tolist: Specifies a comma-separated list of e-mail addresses of the receivers.

• bcclist: Specifies a comma-separated list of e-mail addresses of receivers to whom you send Blank Carbon Copies (BCCs) of the message.

• cclist: Specifies a comma-separated list of e-mail addresses of receivers to whom you send Carbon Copies (CCs) of the message.

For example, to send an e-mail message to multiple recipients, where the e-mail message contains the contents of the abc.log file in the message body, the code is:

<mail from="john@ant.com" 
to="smith@ant.com, andy@ant.com, brown@ant.com" 
files="abc.log"/>

mkdir

The <mkdir> task allows you to build a new directory in the file system. This task allows you to create all the directories that do not currently exist in the file system but exist in the provided path. The mandatory attribute of the <mkdir> task is Dir, which helps specify the directory that you want to create.

The syntax to create the project/abc/xyz directory is:

<mkdir dir = "project/abc/xyz"/>

In this syntax, if the project and abc directories do not exist, the <mkdir> task creates these directories.

move

The <move> task allows you to move a file or a set of files to a different directory. The <move> task also allows you to rename a file using the file and tofile attributes. If a file of the same name already exists, the new file overwrites the existing file. The mandatory attributes of the <move> task are:

• file: Specifies the name of the file to move.

• tofile: Specifies the destination file.

• todir: Specifies the destination directory.

The optional attributes of the <move> task are:

• filtering: Allows filtering when moving the file if the attribute value is set to true.

• flatten: Ignores the directory structure if the attribute value is set to true. You can move all the files present in the source fileset to the source directory. The default attribute value is false.

• includeemptydirs: Ignores empty directories if the attribute value is set to false. The default attribute value is true.

• overwrite: Overwrites existing files without setting any conditions. The default attribute value is true. If the attribute value is false, the exiting files will be overwritten only if they are older than the new files.

For example, you can move the build.log file to the directory that the repository property specifies, as shown:

<move file = "build.log" todir = "${repository}"/> 

The following code will move all the files contained in the src/directory directory to the dest/dir directory and maintain the directory structure:

<move todir = "dest/directory"> 
<fileset dir = "src/dir"/> 
</move> 

The following code will move all the files with the .src extension from the src directory to the dest directory and rename them by appending .dest to the filename:

<move todir = "src" > 
<fileset dir = "dest" > 
<include name = "**/*.src"/> 
</fileset> 
<mapper type = "glob" from = "*" to = "*.dest" /> 
</move>

parallel and sequential

The <parallel> and <sequential> tasks are container tasks that allow you to execute sets of tasks in parallel or in sequence. A <parallel> task results in the execution of each nested task within its own thread. A <sequential> task results in the execution of nested tasks one after the other. The <parallel> task helps utilize resources to the maximum by executing the independent tasks in parallel, which decreases build time.

The primary use of the <sequential> task is to support the sequential execution of a subset of tasks within the <parallel> task. You can embed any valid Ant task in the <sequential> task. The <sequential task> has no attribute and does not support any nested element apart from Ant tasks.

Listing 3-2 shows how to use the <parallel> task:

Listing 3-2: Using the Parallel Task

<parallel> 
<antcall target="startserver"/> 
<sequential> 
<sleep seconds="15"/> 
<antcall target="testserver"/> 
<antcall target="stopserver"/> 
</sequential> 
</parallel>

The above listing shows how a server can run in one thread when you run the test control in another thread.

property

The <property> task allows you to define your own properties. A property is overridden if it is set by a parent project and started with the <REF> Ant task or if it is set by the end user. The mandatory attributes of the <property> task are:

• location: Sets the property to the absolute filename of the specified file. You need to calculate an absolute path relative to basedir if you do not specify the absolute path.

• refid: Specifies a reference to another object from which the value is to be sourced.

• value: Specifies the value to set the property.

• environment: Specifies a prefix that provides access to operating system-specific environment variables. Not all operating systems support this attribute.

• file: Specifies the name of the property file that mentions the properties to be set.

• resource: Specifies the resource name of the property file that mentions the properties to be set.

The optional attributes of the <property> task are:

• classpath: Specifies the classpath to be used to look up the resource if specifying a value for the resource attribute.

• name: Specifies the name of the property that you should set.

• prefix: Specifies a prefix to be applied to properties loaded using the file or resource attributes.

For example, the following code allocates the build.log value to the log property:

<property name="log" value="build.log"/> 

The following code uses the location attribute to set the logfullpath property to the absolute path of the build.log file. If the base directory is c:\ant, the value of the logfullpath property will be c:\ant\build.log, as follows:

<property name="logfullpath" location="build.log"/> 

The following code shows how to set properties in your project using a properties file:

<property file="myproj.properties"/> 

record

The <record> task allows you to form and maintain build listeners that send their output to a file. Each recorder is associated with a file that is its unique identifier. Successive calls to the <record> task with the same filename allow you to start and stop logging and modify the logging level. The recorder provides the ability to log all the build messages throughout a build, or for a particular task, by starting and stopping the recorder correctly. The mandatory attribute of the <record> task is name, which specifies the name of the log file.

The optional attributes of the <record> task are:

• action: Specifies the start or stop state. The default attribute value is the current state. The default value of the attribute is start if this call is the first call for the log file.

• append: Appends the existing log file and prevents overwriting if the attribute value is set to true. The default attribute value is false.

• emacsmode: Deletes the banners if the attribute value is true. It is similar to Ant's emacs command-line switch. The default attribute value is false.

• loglevel: Sets the level of logging for this build listener. The valid values are debug, error, info, verbose, and warn. The default attribute value is the current level.

For example, the following code will create the error.log file if it does not exist. If this file exists, the code will overwrite the current file.

<record name="error.log" action="start" loglevel="error"/> 

If you enter the following code after executing the previous code, the code will change the logging level to build:

<record name="error.log" loglevel="build"/> 

The following code will stop the setup of logging:

<record name="error.log" action="stop"/>

replace

The <replace> task allows you to change a specific string with a new value inside a set of files. The task allows you to toggle the value of a specific string in the source code for test-level and production-level distributions. The file or dir attribute is necessary with the <replace> task. The mandatory attributes of the <replace> task are:

• dir: Identifies the directory containing the files to be located and changed.

• file: Identifies the file to be located and changed.

• token: Specifies the string to be changed.

The optional attributes of the <replace> task are:

• excludes: Eliminates a comma-separated list of file patterns.

• includes: Includes a comma-separated list of file patterns. The attribute value is set to include all files, by default.

• replacefilterfile: Specifies the name of a properties file to be employed as a set of replacement filters. The property specifies a token and you use the property value as the new value of the token.

• summary: Generates a summary of the number of replacements and the number of files searched if the attribute value is set to true. The default attribute value is false.

• value: Specifies the string to replace each token occurrence. The attribute value is set to empty string ("") by default.

For example, the following code shows the nested elements at the simplest level. The code will replace all occurrences of the Error string with the string run in all files in the directory ${dest}:

<replace dir="${dest}"> 
<replacetoken>@Error@</replacetoken> 
<replacevalue>@run@</replacevalue> 
</replace> 

sleep

The <sleep> task allows you to pause the build process for a specified time. The <sleep> task time is the sum of values, such as hours, minutes, seconds, milliseconds, and failonerror. You can also provide a negative value in the attribute but the total time must be positive. When you include sleep without any attribute, it yields the CPU time to another thread or process. The optional attributes of the <sleep> task are:

• hours: Indicates the number of hours to sleep.

• minutes: Indicates the number of minutes to sleep.

• seconds: Indicates the number of seconds to sleep.

• milliseconds: Indicates the number of milliseconds to sleep.

• failonerror: Stops the build if an error occurs and if the value is true. The default value is true.

The syntax to pause the build for two minutes is:

<sleep minutes= "2" /> 

sql

The <sql> task allows you to execute SQL statements on a database using Java Database Connectivity (JDBC). You can either specify the SQL statements within the tag or using an external source file. The mandatory attributes of the <sql> task are:

• driver: Specifies the class name of the JDBC driver.

• password: Specifies the password for the database.

• src: Specifies the name of a file that consists of the SQL statements to be executed.

• url: Specifies the URL for the database connection.

• userid: Specifies the user name for the database.

The optional attributes of the <sql> task are:

• append: Appends the output to the existing file instead of overwriting the file if the attribute value is set to true. The default attribute value is false.

• autocommit: Specifies the commit process of SQL statements. The SQL statements are executed and committed separately if the attribute value is set to true. If the attribute value is set to false, all the statements are executed simultaneously. The default attribute value is false.

• classpath: Specifies the class path to use for loading the driver if the system class path does not exist.

• delimiter: Specifies a string to separate SQL statements. The default attribute value is a semi-colon (;).

• encoding: Specifies the encoding of the files that consist of SQL statements. The default attribute value is the JVM default encoding.

• onerror: Specifies the action to be executed when an error occurs. The valid options with onerror are:
  
  

  • continue: Shows the error.

  • stop: Halts the execution and commits the transaction.

  • abort: Terminates the execution and the transaction. This is the default option.

  
  

• output: Specifies the name of the output file. The default file is System.out.

• print: Prints the results from the SQL statements if the attribute value is set to true. The default attribute value is false.

• rdbms: Executes only if the task is connected to a Relational Database Management System (RDBMS) if the attribute value is true.

• showheaders: Specifies whether or not to show the headers from the result sets. The default attribute value is true.

• version: Specifies an RDBMS version under which the task will execute.

Listing 3-3 shows how to use the <sql> task:

Listing 3-3: Using the SQL Task

<sql driver="org.gjt.mm.mysql.Driver" 
url="jdbc:mysql://mysql.ant/Ant" 
userid="guest" 
password="guest" 
classpath="C:\jars\mysql.jar" 
autocommit="true" 
rdbms="mysql" 
print="true"> 
select name, address from table 
</sql>

The above listing shows how to run the select command and view the results in the standard output.

style

The <style> task allows you to automate the application of a stylesheet to an XML document using a specified Extensible Stylesheet Language Transformation (XSLT) processor. You can use the <style> task with an individual XML document by specifying the in and out attributes, or with multiple files by specifying the fileset attributes.

The <style> task needs the installation of external libraries based on the selection of a processor. For example, Apache's XML Xalan processor requires the Xalan JAR in addition to the Ant optional JAR. When you use Xalan 2, set the processor attribute to trax, which is the interface of Xalan 2.

The mandatory attributes of the <style> task are:

• destdir: Specifies the destination directory for the output files.

• style: Specifies the name of the stylesheet to be used. To specify the name as a relative path, you need to specify it relative to the project basedir and not the task basedir.

The optional attributes of the <style> task are:

• basedir: Identifies the base directory from which to locate the source XML files. The default attribute value is the base directory of the project.

• classpath: Specifies the class path to be used to find XSLT processor classes.

• defaultexcludes: Prevents the use of default excludes if the attribute value is set to false. The default attribute value is true.

• excludes: Specifies a comma-separated list of file patterns that need to be excluded. The default attribute value is not to exclude any files.

• extension: Specifies the extension of the target files. The default attribute value is .html.

• force: Generates new target files if the attribute value is set to true. The default attribute value is false.

• in: Specifies the name of an XML document that you want to process.

• includes: Includes a comma-separated list of file patterns. The default attribute value is to include all files.

• out: Specifies the name of the output file for the processed file.

• outputtype: Specifies the output method.

• processor: Specifies the processor to be used.

For example, the following code generates the web.html file by applying the design.xsl stylesheet to the web.xml XML document:

<style in="web.xml" out="web.html" style="design.xsl"/> 

tar

The <tar> task allows you to create tar archives. When building the tar archive, avoid specifying the same files multiple times because this includes the files in the archive several times. The mandatory attribute of the <tar> task is destfile, which specifies the name of the created tar file.

The optional attributes of the <tar> task are:

• basedir: Specifies the base directory from which to tar the files.

• compression: Specifies the method of compression to be used. The valid values are none, gzip, and bzip2. The default attribute value is none.

• defaultexcludes: Specifies that the default excludes will not be used if the attribute value is set to false. The default attribute value is true.

• excludes: Excludes a comma-separated list of file patterns.

• includes: Specifies a comma-separated list of file patterns to be included. The default attribute value is to include all files.

• longfile: Specifies actions for long filenames with sizes greater than 100 characters. The valid attribute values are truncate, fail, warn, omit, and gnu. The attribute value is set to warn, by default.
  
  

  • truncate: Trims the paths whose sizes are greater than 100 characters to a 100-character limit. This may result in information loss.

  • fail: Causes the failure of the task.

  • omit: Excludes the file from the tar.

  • gnu: Generates a tar file that is a GNU tar, which means that all files will retain the full path. The tar file can only be untarred using the GNU tar.

  • warn: Generates a warning for each file that exceeds the limits.

  
  

The syntax to build the abc.tar tar file, which consists of all the files present in the src directory is:

<tar tarfile="abc.tar" basedir="src"/>

Listing 3-4 shows how to write the docs/readme.txt file as the /usr/doc/ant/README file into the archive:

Listing 3-4: Using the Tar Task

<tar destfile="${basedir}/docs.tar">
<tarfileset dir="${dir.src}/docs"
fullpath="/usr/doc/ant/README"
preserveLeadingSlashes="true">
<include name="readme.txt"/>
</tarfileset>
<tarfileset dir="${dir.src}/docs"
prefix="/usr/doc/ant"
preserveLeadingSlashes="true">
<include name="*.html"/>
</tarfileset>
</tar>

The above listing writes the docs/readme.txt file as /usr/doc/ant/README into the archive. All *.html files in the docs directory are prefixed by /usr/doc/ant.

taskdef

The <taskdef> task allows you to create custom tasks for use within the build file. You need to provide a unique name to the custom task and specify the classname attribute that will implement the custom task. The mandatory attributes of the <taskdef> task are:

• name: Specifies the name of the task.

• classname: Specifies the name of the class that implements the task.

The optional attributes of the <taskdef> task are:

• classpath: Specifies the class path to be used to locate the class that implements the task.

• file: Specifies the name of the property file from which to load name or classname pairs.

• loaderref: Specifies a name of a loader that you need to use to load the class. You can use the loaderref attribute to allow multiple tasks to be loaded within the same loader and allow them to call each other.

• resource: Specifies the name of the property resource from which to load name or classname attributes.

For example, the following code loads the ant.start.StartTask class and makes it accessible using the sampletask task:

<taskdef name="sampletask" classname="ant.start.StartTask"/> 

The following code loads the tasks described in the loadtasks.txt properties file, where you need to specify each property as <name> =<classname>.

<taskdef file="loadtasks.txt"/> 

The following code defines a task named mydoc and the class that implements it is com.domain.JavadocTask:

<taskdef name="mydoc" classname="com.domain.JavadocTask"/>

typedef

The <typedef> task allows you to specify custom data types that you want to use inside a project. The mandatory attributes of the <typedef> task are:

• name: Specifies the name of the data type. This attribute is mandatory unless the file or the resource attribute is specified.

• classname: Specifies the name of the class that implements the data type. This attribute is mandatory unless the file or the resource attribute is specified.

The optional attributes of the <typedef> task are:

• classpath: Specifies the class path to be used when loading the class specified by the classname attribute.

• file: Specifies the name of the file that contains name or classname attributes.

• loaderref: Specifies a loader that helps load the class. This attribute helps load multiple tasks with the same loader, permitting them to call each other.

• resource: Specifies the resource from where to load name or classname attributes.

The syntax to describe a new type, abctype, from the org.aw.data.myCustomClass class is:

<typedef name="abctype" classname="org.aw.data.myCustomClass"/> 

uptodate

The <uptodate> task allows you to set a property if the target file is newer than the source file. The mandatory attributes of the <uptodate> task are:

• property: Specifies the name of the property to be set.

• srcfile: Specifies the name of the source file. You can also specify it as a nested element.

• targetfile: Specifies the name of the target file. You can also specify it as a nested element.

The optional attribute of the <uptodate> task is value, which specifies the value of the property. The default attribute value is true.

For example, the following code sets the doJar property if the last modified date of the src.jar file is later than all the class files specified in the <srcfiles> element:

<uptodate property="doJar" targetfile="src.jar"> 
<srcfiles dir="classes" includes="**/*.class"/> 
</uptodate>

The following code checks a source file against a target file and sets the property to isUpToDate:

<uptodate property="isUpToDate"
            srcfile="/usr/local/bin/testit"
            targetfile="${build}/.flagfile"/>war

war

The <war> task allows you to collect a Web Archive (WAR) file. WAR is a file format that allows you to deploy Web applications. The mandatory attributes of the <war> task are:

• destfile: Specifies the name of the WAR file.

• webxml: Specifies the file for the deployment descriptor.

The optional attributes of the <war> task are:

• basedir: Specifies the name of the directory in which the files to jar are located.

• compress: Compresses the files if the attribute value is set to true. The attribute value is set to true, by default.

• defaultexcludes: Specifies that default excludes will be used if the attribute value is set to true. The attribute value is set to true, by default.

• encoding: Specifies the character encoding to be used for filenames within the archive. The default attribute value is UTF8.

• excludes: Specifies a comma-separated list of file patterns to be excluded.

• filesonly: Specifies that only file entries will be stored if the attribute value is set to true. The default attribute value is false.

• includes: Specifies a comma-separated list of file patterns to be included. The attribute value is set to include all files, by default.

• manifest: Specifies the name of the file to be deployed as the manifest.

• update: Specifies the action to be performed if the file exists. To update the file and prevent overwriting, the attribute value is set to true.

Listing 3-5 shows how to use the <war> task:

Listing 3-5: Using the War Task

<war warfile="abc.war" webxml="xyz.xml"> 
<fileset dir="${classes}"> 
<include name="com\sams\ant\client\**"/> 
</fileset> 
<fileset dir="${websrc}"/> 
<classes dir="${classes}"> 
<include name="com\sams\ant\server\**"/> 
</classes> 
<lib dir="${jars}"> 
<include name="mysql.jar"/> 
</lib> 
</war> 

The above listing shows how to create a WAR file with a specific directory structure. The listing generates the abc.war WAR file, with the following directory structure:

• WEB-INF/classes: Contains all the files in the ${classes}\com\sams\ant\server directory.

• WEB-INF/lib: Contains the mysql.jar file from the ${jars} directory.

• WEB-INF: Contains web.xml, which is a renamed copy of xyz.xml.

In the listing, WEB-INF/classes contain all the files in the ${classes}\com\sams\ant\server directory.

The root directory in the created WAR file will contain all the files from the ${websrc} and ${classes}\com\sams\ant\client directories.