Ant: The Definitive Guide 125 target (all, String, N) The name of the target to invoke in the new project. If omitted, the new project's default target is invoked. Content 0 n nested <property> elements (all) Passes a property to the new build process. Example Usage Invoke the default target on util_buildfile.xml in the current directory: <ant antfile="util_buildfile.xml"/> Invoke the clean target on build.xml in the gui directory: <ant dir="gui" target="clean"/> Invoke another buildfile, passing a new value for the builddir property. The value is explicitly set to utiloutput even if the property was defined elsewhere in the calling buildfile: <ant antfile="util_buildfile.xml"> <property name="builddir" value="utiloutput"/> </ant> See Also See the property task for allowable attributes on nested <property> elements. antcall all org.apache.tools.ant.taskdefs.CallTarget Invokes a target in the current buildfile. Properties are passed to the new target using nested <param> elements. An investigation of the Ant source code reveals that antcall instantiates and calls the ant task using the current buildfile. This means that a new project instance is created and properties work the same as they do for ant. Attributes inheritall (1.4, boolean, N) Defines how properties are propagated to the new target. Defaults to true, meaning all properties in the current build process are inherited by the new target. Prior to Ant 1.4, Ant: The Definitive Guide 126 this was the only behavior. When false, properties set by users on the command line are the only ones passed to the new target. target (all, String, Y) The name of the target to call. Content 0 n nested <param> elements (all) Passes a property to the new build process. Each <param> element is implemented using the same class as the property task; all property attributes are applicable. Example Usage Call the cleandir target and specify the dir-to-clean property: <target name="clean"> <antcall target="cleandir"> <param name="dir-to-clean" value="javadocs"/> </antcall> </target> Delete a directory specified by the dir-to-clean property: <target name="cleandir"> <delete dir="${dir-to-clean}"/> </target> See Also See the property task for allowable attributes on nested <param> elements. antstructure all org.apache.tools.ant.taskdefs.AntStructure Creates a DTD for Ant buildfiles Creates an XML Document Type Definition (DTD) for Ant buildfiles. This uses Java reflection to determine allowable attributes and content for all tasks. Since the underlying Ant task API does not indicate which attributes are required, the DTD marks all attributes as #IMPLIED. 1 Attributes 1 In DTDs, #IMPLIED means optional. Ant: The Definitive Guide 127 output (all, File, Y) The name of the DTD file to generate. Content None. Example Usage Create project.dtd in the current directory: <target name="createdtd"> <antstructure output="project.dtd"/> </target> apply 1.3, 1.4 org.apache.tools.ant.taskdefs.Transform Executes a system command. As of Ant 1.4, the deprecated execon task is merely an alias for apply. Unlike the exec task, this task requires a nested <fileset> specifying one or more files and directories as arguments to the command. Attributes dest (1.3, 1.4, File, *) The destination directory for any target files generated by the command. dir (1.3, 1.4, File, N) The working directory for the command. executable (1.3, 1.4, String, Y) The name of the command to execute. Does not include command-line arguments. failonerror (1.3, 1.4, boolean, N) If true, the build fails when the command returns anything other than 0. Defaults to false. newenvironment (1.3, 1.4, boolean, N) If true, do not propagate existing environment variables to the new process. Defaults to false. os (1.3, 1.4, String, N) Ant: The Definitive Guide 128 A list of operating systems this task applies to. Executes only if the list contains a string matching the return value from System.getProperty("os.name"). output (1.3, 1.4, File, N) A file to redirect the command output to. outputproperty (1.4, String, N) The name of a property that stores the command output. parallel (1.3, 1.4, boolean, N) If true, the command is executed once, passing all files as arguments. If false, the command is executed once for each file. Defaults to false. skipemptyfilesets (1.4, boolean, N) If true, do not execute the command if no source files are found, or if source files are up-to-date with respect to destination files. Defaults to false. timeout (1.3, 1.4, int, N) The number of milliseconds to wait before stopping the command. Waits infinitely if not specified. type (1.3, 1.4, Enum, N) Determines if names of plain files or directories are sent to the command. Allowable values are file, dir, or both. Defaults to file. vmlauncher (1.4, boolean, N) Specifies whether to attempt using the JVM's built-in command launcher, rather than an antRun script. Defaults to true. dest is required if you specify a nested <mapper>. Content 0 n nested <arg> elements (1.3, 1.4) Defines command-line arguments. 0 n nested <env> elements (1.3, 1.4) Specifies environment variables to pass to the command. 1 n nested <fileset> elements (1.3, 1.4) Ant: The Definitive Guide 129 Specifies which files and directories are passed as arguments to the command. Unless the <srcfile> element is specified, files are appended to the end of the command line. 0,1 nested <mapper> elements (1.3, 1.4) When defined, compares timestamps of target files to timestamps of source files. 0,1 nested <srcfile> elements (1.3, 1.4) When present, controls where files specified by the <fileset> elements are placed on the command line. The <srcfile> element does not have any attributes, and is placed between the appropriate <arg> elements. 0,1 nested <targetfile> elements (1.3, 1.4) This element is only allowed when a <mapper> element and the destdir attribute are specified. It has no attributes, and is used to mark the position of target filenames on the command line. It works the same as the <srcfile> element. Example Usage Show the contents of build.xml using the type command — only if running Windows 2000: <! Set vmlauncher="false", otherwise this fails when using JDK 1.4beta1 on Windows 2000 > <apply executable="type" vmlauncher="false" os="Windows 2000"> <fileset dir="."> <include name="build.xml"/> </fileset> </apply> See Also See the exec task for another way to execute system commands, particularly when you do not want to pass a list of filenames to the command. See Chapter 4 for more information on <arg>, <env>, <fileset>, and <mapper>. available all org.apache.tools.ant.taskdefs.Available Conditionally sets a property if a resource is available at runtime. The resource can be a class, file, directory, or Java system resource. If the resource is present, the property is set to true, or whatever the optional value attribute is set to. Otherwise, the property is not set. Attributes Ant: The Definitive Guide 130 classname (all, String, *) A Java class name to look for, such as com.oreilly.book.Author. classpath (all, Path, N) The classpath to use when looking up a class name or resource. classpathref (all, Reference, N) A reference to a classpath defined elsewhere in the buildfile. file (all, File, *) The name of a file to look for. filepath (1.4, Path, N) The path of the file. property (all, String, Y) The name of the property this task sets if the resource is found. resource (all, String, *) A Java resource to look for. For more information on what constitutes a resource, see the various getResource( ) methods in java.lang.ClassLoader. type (1.4, String, N) Specifies what the file attribute represents. In Ant 1.4, legal values are "file" or "dir". If not specified, the file attribute represents either a file or directory. value (all, String, N) The value assigned to the property if the resource is found. Defaults to "true". One of classname, file, or resource is required. Content 0,1 nested <classpath> elements (all) Path element used in place of the classpath attribute. 0,1 nested <filepath> elements (1.4) Ant: The Definitive Guide 131 Path element used in place of the filepath attribute. Example Usage The following example sets the Servlet23.present property to true if Version 2.3 or later of the Java servlet API is available on the classpath: <available classname="javax.servlet.ServletRequestWrapper" property="Servlet23.present"/> This works because the javax.servlet.ServletRequestWrapper class was not included in earlier versions of the servlet API. chmod all org.apache.tools.ant.taskdefs.Chmod Changes permissions on one or more files, just like the Unix chmod command. This task only works on Unix platforms. Attributes defaultexcludes (all, boolean, N) Determines whether to use default excludes, as described in Chapter 4 under "FileSet DataType." Defaults to true. dir (all, File, *) The directory holding files whose permissions will be changed. excludes (all, String, N) A comma-separated list of file patterns to exclude. These are in addition to the default excludes. excludesfile (all, File, N) The name of a file containing one exclude pattern per line. file (all, File, *) The name of a file or directory to change permissions on. includes (all, String, N) Ant: The Definitive Guide 132 A comma-separated list of file patterns to include. includesfile (all, File, N) The name of a file containing one include pattern per line. parallel (all, boolean, N) If true, change permissions of all files using a single chmod command. Defaults to true. perm (all, String, Y) The new permissions to apply, such as g+w. type (all, Enum, N) Determines if names of plain files or directories are sent to the command. Allowable values are file, dir, or both. Defaults to file. Exactly one of dir or file must be specified, or at least one nested <fileset> element. Content 0 n nested patternset elements: <exclude> , <include> , <patternset> (all); <excludesfile> , <includesfile> (1.4) Used in place of their corresponding attributes, these specify the set of included and excluded source files. 0 n nested <fileset> elements (all) Specifies which files and directories are passed as arguments to the command. Example Usage Change the permissions to read-only (444) for all HTML files in the JavaDoc output tree: <chmod perm="444"> <fileset dir="${javadocs}"> <include name="**/*.html"/> </fileset> </chmod> condition 1.4 Ant: The Definitive Guide 133 org.apache.tools.ant.taskdefs.ConditionTask Sets a property if a condition is true. This task combines basic Boolean expressions with the available and uptodate tasks. Attributes property (1.4, String, Y) The name of a property to set if the condition is true. If the condition is false, the property is not set. value (1.4, String, N) The value assigned to the property if the condition is true. Defaults to true. Content The following elements are considered to be conditions. Exactly one condition must be nested directly within this task. These, in turn, may contain other nested conditions as outlined here. <not> Contains exactly one nested condition, negating its result. Does not have any attributes. <and> Contains any number of nested conditions, evaluating to true if all nested conditions are true. Conditions are evaluated left-to-right, and evaluation stops if a condition evaluates to false. 2 Does not have any attributes. <or> Contains any number of nested conditions, evaluating to true if any nested condition is true. Conditions are evaluated left-to-right, and evaluation stops when a condition evaluates to true. 3 Does not have any attributes. <available> Identical to the available task, except its property and value attributes are ignored. <uptodate> Identical to the uptodate task, except its property and value attributes are ignored. 2 This is the same behavior as Java's && operator. 3 This is the same behavior as Java's || operator. [...]... N) The algorithm used to generate the entry keypass (all, String, *) The password used to protect the private key keysize (all, String, N) The size of the generated key keystore (all, String, N) The name of the keystore file Defaults to keystore in the user's home directory 153 Ant: The Definitive Guide sigalg (all, String, N) The algorithm used to sign the certificate storepass (all, String, Y) The. .. configuration using the ANT_ OPTS environment variable (as explained in Chapter 2) before running Ant 155 Ant: The Definitive Guide gunzip all org.apache.tools .ant. taskdefs.GUnzip Expands a GZip file The file is only expanded if the destination file does not exist or is older than the source file Attributes dest (all, String, N) The destination file or directory name If omitted, dest defaults to the directory... 138 Ant: The Definitive Guide The password to add Content None Example Usage This example adds the anttester password to the cvspass file in the current user's home directory: See Also The cvs task delete all org.apache.tools .ant. taskdefs.Delete Deletes one or more files and directories This is the most dangerous task in Ant. .. 154 Ant: The Definitive Guide See Also See the documentation included with Sun's Java Development Kit for the keystore commandline program get all org.apache.tools .ant. taskdefs.Get Retrieves a file from a URL Attributes dest (all, File, Y) The local name to store the file as ignoreerrors (all, boolean, N) If true, log errors but do not abort the build Defaults to false src (all, URL, Y) The URL of the. .. outside of the Java and Ant build environment The apply task requires a nested , specifying a list of files and directories passed as arguments to the system command The exec task differs in that it does not allow this nested Attributes command (1.1, CommandLine, *) The command to execute, including arguments Deprecated as of Ant 1.2 1 45 Ant: The Definitive Guide dir (all, File, N) The. .. true 142 Ant: The Definitive Guide earfile (1.4, File, Y) Specifies the name of the EAR file to create encoding (1.4, String, N) Specifies the character encoding for filenames inside the EAR file Defaults to UTF-8 The Ant specification warns that changing this attribute probably renders the EAR file unusable by Java excludes (1.4, String, N) A comma-separated list of file patterns to exclude These are... org.apache.tools .ant. taskdefs.Exit Throws a BuildException, causing the current build to fail Attributes message (all, String, N) Specifies the message displayed when this task executes Content Text content (1.4) Ant 1.4 adds the ability to specify nested text This is useful when the message spans multiple lines 148 Ant: The Definitive Guide Example Usage The following example aborts the build without... in the source file, not including the @ characters 149 Ant: The Definitive Guide value (all, String, *) The text to substitute in place of @token@ The @ characters are not preserved You must specify either the filtersfile attribute, or both token and value Content None Example Usage Let's start with the following source file: // %COPYRIGHT! /** * @version @VERSION@ */ public class Hello { } We want... dir="${builddir}" includes="*.jar,*.war"/> See Also See the jar task The implementation class for ear extends from jar's implementation class echo all org.apache.tools .ant. taskdefs.Echo Writes a message to the Ant log or a file The verbosity defaults to Project.MSG_WARN, which means that messages appear on the console 144 Ant: The Definitive Guide Attributes append (all, boolean, N) If true, append... this case, Ant displays the following message, where 104 is the line number in the buildfile of the line invoking fail: BUILD FAILED C:\cvsdata \ant\ mysamples\build.xml:104: No message The following call to fail results in a message being displayed The message is specified between the and tags Java version ${java.version} is not allowed! The next example produces the same results . inherited by the new target. Prior to Ant 1.4, Ant: The Definitive Guide 126 this was the only behavior. When false, properties set by users on the command line are the only ones passed to the new. Ant: The Definitive Guide 1 25 target (all, String, N) The name of the target to invoke in the new project. If omitted, the new project's default target. password (1.4, String, Y) Ant: The Definitive Guide 139 The password to add. Content None. Example Usage This example adds the anttester password to the .cvspass file in the current user's