cab

The <cab> task allows you to generate a CAB file. The <cab> task is a front end of the Microsoft utility, cabarc executable. As a result, the carbarc tool should be present in your system path to enable you to use this task. The mandatory attributes of the <cab> task are:

• cabfile: Specifies the name of the created CAB file.

• basedir: Specifies the directory from where the archive will be built.

The optional attributes of the <cab> task are:

• verbose: Shows the output from the cabarc utility if the attribute value is set to true. The default attribute value is false.

• compress: Specifies whether the contents of the file will be compressed. The default attribute value is true.

• options: Allows you to set additional command-line options for the cabarc tool.

• includes: Allows you to specify a comma-separated list of file patterns that need to be included in the archive. All files are included when you do not specify this attribute.

• excludes: Specifies a comma-separated list of file patterns that need to be excluded from the archive.

The following example shows how to use the <cab> task to package the class files for the ie_applet.cab applet:

<cab cabfile="${lib}/ie_applet.cab" 
  basedir="${build}" 
  includes="**/*.class"/>

depend

The <depend> task is a preprocessor of the compilation stage. When the compilation process starts, the <javac> process decides which classes to compile by finding out which class files are not present or which source files have changed since the last compilation.

For example, when you make changes to a base class father.java, this prevents the super classes, son.java and daughter.java, from operating properly. Using the standard compilation methods, you may only be able to compile father.java, leaving the other two classes unaffected. This may cause run time errors because the two classes, son and daughter, will be making calls to methods that may or may not exist. The <depend> task makes sure that these types of dependencies are caught and fixed before you start compiling. The mandatory attribute of the <depend> task is srcDir, which identifies the directory where the source files exist. For multiple source locations, you can use the standard <include>, <exclude>, and <patternset> inner elements.

The optional attributes of the <depend> task are:

• destDir: Specifies the upper-level directory of the class files.

• cache: Caches dependency information to decrease the lookup time if you specify this attribute.

• closure: Specifies whether the <depend> task should search all the affected classes. The default attribute value is false, which signifies the removal of all the indirectly dependent classes.

• dump: Specifies whether dependency information is entered in the debug log.

• classpath: Specifies the list of JAR files and classes against which the <depend> task needs to check dependencies.

You need to use the <depend> task carefully. This task catches class dependencies for most builds but it is not reliable. For large projects, the extra time used for finding the dependency tree may be longer than the actual time needed for recompilation.

echoproperties

The <echoproperties> task allows you to view all the properties currently present in the project or store them in a file. This task allows you to debug build files. The syntax to make a simple call is:

<echoproperties prefix="ant"/> 

The above syntax filters the properties with the help of the prefix attribute. The screen only shows the properties that start with the Ant prefix. The optional attributes of the <echoproperties> task are:

• prefix: Specifies a filter for the echoed properties.

• destfile: Specifies the name of the file that will receive the list of properties. The format of this file is the same as the style that java.utils.Property supports.

• failonerror: Determines if the build as a whole will fail if something goes wrong with the output to the file.

The <echoproperties> task is useful for developing the Ant build file. You can easily take snapshots of your build at various phases for later examination. As a result, it is better to prefix all your variables with a known string to differentiate them from system-defined properties.

ftp

The <ftp> task is an optional task that allows you to integrate a newly developed JAR file with your build file. The <ftp> task is a type of wrapper of the ftp class available in the Netcomponents suite. This task assumes the presence of specific libraries, which are not included in the Ant distribution, such as commons-net.jar. By default, the <ftp> task uses the standard UNIX file system syntax for remote servers. The main ftp commands available are get, put, del, list, chmod, and mkdir. The mandatory attribute of the <ftp> task is server, which specifies the remote address of the FTP server to which you are connecting.

The optional attributes of the <ftp> task are:

• userid: Specifies the user name or login id for the FTP server.

• password: Specifies the password for the user name to validate the login.

• port: Specifies the port number of the FTP server to which you are connecting. The default attribute value is 21.

• remotedir: Specifies the name of the remote directory on the FTP server.

• binary: Specifies the binary mode for sending the files. You can transmit the files as ASCII files by setting the attribute value to no. The default attribute value is yes.

• action: Specifies the FTP command to perform specific actions, such as send, put, get, list, del, chmod, mkdir, and rmdir. The attribute value is set to send, by default.

• verbose: Shows the progress information. The default attribute value is no.

• depends: Sends only new or modified files if the attribute value is set to yes.

• separator: Specifies the separator to be used for files and directories. You need to specify the separator when you know that the remote server does not follow the standard UNIX file system syntax. The attribute value is set to the UNIX style, by default.

• umask: Sets the default file permissions as soon as you create a file on the remote server. This attribute applies to only UNIX operating systems.

• chmod: Changes the file permissions of existing or new files. You can use this attribute with only UNIX operating systems. You need to use the chmod attribute for each file if you use the put action.

• listing: Specifies the name of the file that will receive the file listings.

• ignoreNoncriticalErrors: Sets a flag to decide whether or not to continue if a non-critical error code occurs during directory creation on a remote server. Remote servers, such as Wu-ftp, generate these errors. The default attribute value is no.

• skipFailedTransfers: Specifies whether a failed flag will halt the processing of the remaining files to be moved while moving a list of files. The attribute value is set to false, by default.

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

Listing 3-6: Using the FTP Task

<ftp server="ftp.apache.org"
port="2121"
remotedir="/abc/xyz"
userid="user"
password="pwd"
depends="yes"
binary="no"
>
<fileset dir="cat/set">
<include name="**/*.html"/>
</fileset>
</ftp>

The listing logs on to ftp.apache.org at port 2121 using the login-id user name and the pwd password in text mode. All new or changed HTML files in the cat/set directory are uploaded to the abc/xyz directory.

propertyfile

The <propertyfile> task allows you to use property files in applications outside the build process. This task is a wrapper for the standard java.util.Properties class. The <propertyfile> task is useful for storing the run time values of a specific Ant build. When used with the <input> task, the <propertyfile> task provides a convenient interface to automatically update important configuration files.

The mandatory attribute of the <propertyfile> task is file, which specifies the location of the file to be edited or created. The optional attribute of the <propertyfile> task is header, which specifies a header for the file.

Listing 3-7 shows how to create a property with a number of attributes:

Listing 3-7: Creating a Simple Property File

<propertyfile file="ant.property" comment="Creating a property example"> 
<entry key="developer1" value="Don"/> 
<entry key="developer2" value="Allen"/> 
<entry key="developer3" value="John"/> 
<entry key="developer4" value="Linda"/> 
</propertyfile> 

The above listing creates the ant.property file with the following contents:

#Creating a property example 
#Sat Nov 06 20:07:39 BST 2004 
author1=Don 
author2=Allen 
author3=John
author4=Linda 

A number of nested <entry> elements may exist inside the <propertyfile> task. Each <entry> element signifies a key/pair value in the property file. The mandatory attribute available for the <entry> element is key, which specifies the name of the key for this entry.

The optional attributes of the <entry> element are:

• value: Specifies the value of the entry. If the operation is addition or subtraction, this is the value you will add or subtract.

• default: Specifies that the value does not exist in the file. This is the default value.

• type: Specifies the type of the data field. The valid values are int, date, or string. String is the default attribute value.

• operation: Specifies the operation that will occur on the value attribute. Valid values are +, -, and =. - is the only value for date and int fields of the type attribute. The default attribute value is =.

• pattern: Specifies the mask that the data appears in if the type attribute is int or date.

• unit: Specifies the unit of addition or subtraction for operations that involve date fields. The valid values are millisecond, second, minute, hour, day, week, month, and year. The default unit is day.

You can perform arithmetic operations on data for a specified key. For example, you need to calculate the number of times you built a particular project and the date of the last build. As a result, you need to create a file and when the task is called, you read in the number of builds and increment the value by 1.

Listing 3-8 shows how to record builds:

Listing 3-8: Tracking Builds

<target name="propertyfile-stats"> 
<propertyfile file="ant.stats" comment="Number of builds"> 
<entry key="stats.compile" default="1" value="1" operation="+" type="int"/> 
<entry key="stats.lastbuild" value="now" type="date"/> 
</propertyfile> 
</target> 

The above listing shows how to record builds. stats.lastbuild plugs in the current date using the special keyword now. The now keyword only works if the attribute type is equal to date.

The listing generates the following file:

#Number of builds 
#Mon Nov 06 20:21:29 BST 2004 
stats.lastbuild=2004/11/06 20\:21 
stats.compile=4

The target searches the stats.compile key. If the stats.compile key is not present, the target defaults to value 1. If the stats.compile exists, the target sets the type to int and then performs the + operation on the stats.compile, adding the number specified in the value attribute.

javacc

Java Compiler Compiler (JavaCC) is a tool that helps generate language compilers. The <javacc> task manages the build process of the JavaCC tool, assuming that the JavaCC tool is already installed on the computer. As a result, this task needs to know the path of the JavaCC installation on the system so that the <javacc> task can locate the essential class files to finish the operation. The mandatory attributes of the <javacc> task are:

• target: Specifies the name of the grammar file to be compiled.

• javacchome: Specifies the location of the JavaCC installation.

The optional attributes of the <javacc> task are:

• outputdirectory: Specifies the directory that will store the resulting files. The default value is the directory that contains the grammar file.

• buildparser: Sets the flag for JavaCC BUILD_PARSER.

• buildtokenmanager: Sets the flag for JavaCC BUILD_TOKEN_MANAGER.

• cachetokens: Sets the flag for JavaCC CACHE_TOKENS.

• choiceambiguitycheck: Sets the integer value of JavaCC CHOICE_AMBIGUITY_CHECK.

• commontokenaction: Sets the flag for JavaCC COMMON_TOKEN_ACTION.

• debuglookahead: Sets the flag for JavaCC DEBUG_LOOKAHEAD.

• debugparser: Sets the flag for JavaCC DEBUG_PARSER.

• debugtokenmanager: Sets the flag for JavaCC DEBUG_TOKEN_MANAGER.

• errorreporting: Sets the flag for JavaCC ERROR_REPORTING.

• forcelacheck: Sets the flag for JavaCC FORCE_LA_CHECK.

• ignorecase: Sets the flag for JavaCC IGNORE_CASE.

• javaunicodeescape: Sets the flag for JavaCC JAVA_UNICODE_ESCAPE.

• lookahead: Sets the integer value for JavaCC LOOKAHEAD.

• optimizetokenmanager: Sets the flag for JavaCC OPTIMIZE_TOKEN_MANAGER.

• otherambiguitycheck: Sets the integer value for JavaCC OTHER_AMBIGUITY_CHECK.

• sanitycheck: Sets the flag for JavaCC SANITY_CHECK.

• static: Sets the flag for JavaCC STATIC.

• unicodeinput: Sets the flag for UNICODE_INPUT.

• usercharstream: Sets the flag for USER_CHAR_STREAM.

• usertokenmanager: Sets the flag for USER_TOKEN_MANAGER.

For example, the following tag invokes the <javacc> task on src/Parser.jj. The static option is set to true. You write the output to the build/src directory, as follows:

<javacc
target="src/Parser.jj"
outputdirectory="build/src"
javacchome="c:/program files/JavaCC"
static="true"/>

jjtree

The <jjtree> task acts as a preprocessor for JavaCC grammar files. The <jjtree> task inserts parse tree-building actions at various places in the JavaCC source that the <jjtree> task generates. You run the output of <jjtree> using JavaCC to create the parser. The mandatory attributes of the <jtree> task are:

• target: Specifies the JavaCC grammar file to be compiled.

• javacchome: Specifies the path of the JavaCC installation.

The optional attributes of the <jjtree> task are:

• outputdirectory: Specifies the directory to store the created files. The default value is the directory where the grammar file is stored.

• buildnodefiles: Sets the JJTree BUILD_PARSER flag.

• multi: Sets the JJTree flag.

• nodedefaultvoid: Sets the JJTree NODE_DEFAULT_VOID flag.

• nodefactory: Sets the JJTree NODE MULTI _FACTORY flag.

• nodepackage: Sets the JJTree NODE_PACKAGE string.

• nodeprefix: Sets the JJTree NODE_PREFIX string.

• nodescopehook: Sets the JJTree NODE_SCOPE_HOOK flag.

• nodeuserparser: Sets the JJTree NODE_USES_PARSER flag.

• static: Sets the JJTree STATIC flag.

• visitor: Sets the JJTree VISITOR flag.

• visitorexception: Sets the JJTree VISTOR_EXECPTION string.

For example, you can use the <jjtree> task to preprocess your files before sending them for compilation, as shown in the following code:

<jjtree 
target="${src}cfParser.jjt" 
javacchome="${javacchome}" 
outputdirectory="${src}"/> 
<javacc 
target="${src}cfParser.jj" 
javacchome="${javacchome}" 
outputdirectory="${src}" 
ignorecase="true"/>

javah

The <javah> task is a wrapper of the javah utility that is included with JDK. You can use the javah utility to generate the header and stub files for Java Native Interface (JNI). The mandatory attributes of the <javah> task are:

• class: Specifies a comma-separated list of fully qualified classes that will be processed.

• outputfile: Specifies the name of the file for the resulting headers.

• destdir: Specifies the directory where JavaH will save the header or stub files.

The optional attributes of the <javah> task are:

• force: Specifies the JavaH flag to ensure that all the output files are written.

• old: Allows the old JDK 1.0 header files to be generated.

• stubs: Informs JavaH flag to generate C code from the Java object file when the old attribute is set.

• verbose: Specifies a flag for JavaH to generate output as it processes each file.

• classpath: Specifies the classpath to be used.

• bootclasspath: Specifies the location of the bootstrap class files.

• extdirs: Specifies the location of the extensions directory.

To use the <javah> task, you need to specify certain parameters, as shown:

<javah destdir="${src}/c" class="ant.samplejavah"/> 

To process several class files, you can use the inner element tag <class> to specify the class names, as shown:

<javah destdir="${src}/c"> 
<class="ant.samplejavah"/> 
</javah>

jspc

The main function of the <jspc> task is to compile Java Server Pages (JSP) into Java source files so that you can compile them later using <javac>. This provides rapid validation of the JSP page without needing to invoke the JSP page using a Web browser or operate on computers that cannot execute the page properly.

The <jspc> task uses the JSP compiler from Tomcat4 to download and extract the jasper-compiler.jar and jasper-runtime.jar files. You need to position these files in your classpath or the /lib/ directory inside the Ant installation.

The mandatory attributes of the <jspc> task are:

• destdir: Identifies the location of the directory that will store the Java source files.

• srcdir: Identifies the location of the directory that contains the JSP pages.

The optional attributes of the <jspc> task are:

• verbose: Specifies the use of verbosity levels for output.

• compiler: Specifies the class name of the JSP compiler.

• package: Specifies the name of the package for the generated Java source files.

• ieplugin: Specifies modifications in the Java Component Object Model (COM) class ID if you are using the <jsp:plugin> tag on the JSP page.

• mapped: Specifies the flag to generate separate write() calls for each line of HTML text on the JSP page.

• classpath: Specifies the classpath for the JSP compiler.

• classpathref: Specifies the reference to classpath information.

• failonerror: Specifies a flag to stop the task if an error occurs. The default attribute action is to stop.

• uribase: Specifies the location of the extensions directory.

• uriroot: Indicates the root directory from where Uniform Resource Indicator (URI) files need to be resolved.

Listing 3-9 shows a sample JSP page:

Listing 3-9: Sample JSP Page

<html> 
<head> 
<title>JSP Sample Page</title> 
</head> 
<body bgcolor=#0000ff> 
<h4>JSP Sample Page</h4> 
<p> 
request.getRequestURI() = <%=request.getRequestURI()%><br> 
request.getServletPath() = <%=request.getServletPath()%><br> 
request.getRealPath("/") = <%=request.getRealPath("/")%><br> 
</body> 
</html> 

The above listing shows a sample JSP page that makes explicit calls to interfaces in the servlet Application Programming Interface (API). As a result, you need to either specify the servlet.jar file in the classpath attribute or store the JAR file in the /lib/ directory of the Ant installation.

To compile the JSP page into a Java source file, use the following code:

<jspc srcdir="." destdir="."> 
<include name="**/*.jsp" /> 
</jspc> 

The <jspc> task employs the regular directory features of Ant to recover the list of files it needs to process. The <jspc> task functions in the same way as the <javac> task. The task decides which files to compile using the timestamps of each file.

After compiling the JSP page, the compiled .java files will be stored in the directory specified in the destdir attribute. You can then execute the files using the <javac> task.

setproxy

The <setproxy> task allows you to set proxy settings for the JVM in which the Ant task is running. The optional attributes of the <setproxy> task are:

• proxyHost: Specifies the name of the proxy to be used for HTTP/FTP requests. If the attribute value is blank, a disabled proxy occurs. The attribute type is string.

• proxyPort: Specifies the port number of proxyHost. The default attribute value is 80. The attribute type is integer.

• socksProxyHost: Specifies the name of the socks proxy server. The attribute type is string.

• socksProxyPort: Specifies the port number of the socks Proxy server. The default attribute value is 1,080. The attribute type is integer.

• nonProxyHosts: Specifies a bar (|)-separated list of hosts to avoid the proxy. The attribute type is string.

For example, if the proxy server is running at proxy.mydomain.com on port 8040, the syntax to use the nonProxyHosts task is:

<setproxy proxyHost="proxy.mydomain.com" proxyPort="8040"/>

telnet

The <telnet> task allows you to interact with distant Telnet servers. This task also helps log on to a system to restart a process after performing an upload using an FTP task. You can use this task to test a specific Simple Object Access Protocol (SOAP) request or a basic HTTP server. The mandatory attribute of the <telnet> task is server, which specifies the remote address of the Telnet server to which you are connecting.

The optional attributes of the <telnet> task are:

• userid: Specifies the user name for the Telnet server.

• password: Specifies the password for the user name.

• port: Specifies the port number of the Telnet server to which you are connecting. The default attribute value is 23.

• initialCR: Passes a Carriage Return to the server after connecting to the Telnet server. The default attribute value is no.

• timeout: Specifies the time to wait for a response from the server. The unit of time is seconds.

The nested elements available with the <telnet> task are <read> and <write>. They manage communication with the remote server. Their descriptions are:

• <read>: Listens for a return string and waits for a specific time before aborting.

• <write>: Transmits a line of text to the server.

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

Listing 3-10: Using the Telnet Task

<target name="apache-resume">
<telnet userid="administrator" password="administrator"
server="yourserver.yourdomain.com">
<read timeout="10" string="$"/>
<write echo="false">/usr/local/apache/bin/apachesc3 resume </write>
<read timeout="10" string="$"/>
</telnet>
</target>

The above listing shows a simple logging procedure on a Linux machine. The code triggers the apachesc3 resume script to restart Apache.

xmlvalidate

The <xmlvalidate> task uses the SAX parser that comes with Ant to check for errors in a specified XML file or a set of XML files. The optional attributes of the <xmlvalidate> task are:

• file: Specifies the file in which you run the task. You can also specify the set of files with a nested fileset element.

• lenient: Checks the file to see if it is properly constructed if the attribute is set to true.

• classname: Specifies the class name of the parser to be used.

• classpathref: Specifies the classpath information of the alternative parser. You can also use the classpath-nested element to define the alternative parser.

• failonerror: Reports an error.

• warn: Shows the parser warnings.

For example, in the following code, you can call the <xmlvalidate> task by specifying the abc.xml XML file:

<xmlvalidate file="abc.xml"/>