Apache Jakarta and Beyond: A Java Programmeramp;#039;s Introduction [Electronic resources] نسخه متنی

2.8. Built-In Tasks

Ant comes equipped with many useful tasks, too many to list comprehensively here. The following list includes several of the most common that are likely to appear in any realistic build file, as well as several others that give a flavor for what Ant can do out of the box.

2.8.1. AntCall

AntCall invokes one target from another. While Ant can always figure out the order in which targets should be invoked, based on dependency information, there may be logical relationships between targets that cannot be described in terms of dependencies. In those cases, targets can explicitly call each other via the AntCall task.

Attributes:

target: The name of the target within the same build file to invoke. Required.

Example:

<project default="callOther">
<target name="other">
<echo message="I have been called"/>
</target>
<target name="callOther">
<antcall target="other"/>
</target>
</project>

Produces the following output

callOther:
other:
[echo] I have been called

Note that the other task is announced just as if Ant had invoked it directly.

2.8.2. Copy

Copy copies a file or directory. Copy is one of may tasks Ant provides that manipulate files. As the name implies, Copy can copy a single file to another file, or a file into a directory, or a whole FileSet from one place to another, preserving the directory structure.

Attributes:

file: The name of a file to copy. Required, unless a nested fileset is provided.

tofile: The name of the copied file. This attribute is only valid when copying a single file.

todir: The name of the directory into which the file or file set should be copied. One of tofile or todir must be provided.

Example:

<target name="copyFile">
<copy file="images/gaz.jpg" tofile="image1.jpg"/>
</target>
<target name="copyDir">
<copy todir="image_backup">
<fileset dir="images"/>
</copy>
</target>

The copyFile target will copy images/gaz.jpg to image1.jpg in the current directory. copyDir will copy every file in the images directory to the image_backup directory.

2.8.3. Delete

Delete deletes files or directories. Conceptually this is much like the Copy task except it deletes files. Most build files will have a target called "clean" that deletes all generated files. That target will often consist of a series of Delete tasks: one to delete class files, another to delete generated documentation, and so on.

Attributes:

file: The file to delete.

dir: The directory to delete. Either file, dir, or a nested fileset must be provided.

Example:

<target name="deleteFile">
<delete file="image1.jpg"/>
</target>
<target name="cleanDir">
<delete>
<fileset dir="image_backup"/>
</delete>
</target>

deleteFile and deleteDir will delete the files copied by the copyFile and copyDir tasks, respectively. Note that deleteDir deletes the contents of the image_backup directory but does not remove the directory itself.

2.8.4. Exec

Exec runs an external program. There are rare occasions where a build file may need to run a program to accomplish its task. For example, an automated build system might need to page the lead programmer when a build fails. There will be a program on the system to send pages, which may be impractical to port to Java.

Attributes:

executable: The name of the program to run, possibly including the full path to the program if it is in a nonstandard place. Required.

Arguments to the program are provided by special nested elements called arg.arg takes several forms; see the Ant documentation for details. The most common form includes all the arguments as a single line because they would be typed at a command prompt. For example, the hypothetical page operation might look like

<exec executable="/usr/local/pager/bin/page">
<arg line="-text 'build failed' -target=lead@company.com"/>
</exec>

2.8.5. Get

Get retrieves a file from a URL. There are many reasons why a build file might need to do this: It may need to download the latest version of a jar file, include the current version of an image as a resource, or even grab the source it is about to compile.

Attributes:

src: The URL. Required.

dest: The name of the file in which the retrieved data should be stored. Required.

Example:

<target name="getSlash">
<get src="http://www.slash.dot.org/" dest="181"/>
</target>

will grab the current home page from www.slash.dot.org and save it as 181 in the current directory.

2.8.6. Jar

Jar creates a Java archive file. Ant provides tasks to create numerous kinds of archive files, but jars are certainly the most common. At a minimum any of these tasks will need to know the name of the file to create and the set of files to store. jar also includes special options to build manifests; see the Ant documentation for details.

Attributes:

destfile: The name of the file to create. Required.

basedir: The top-level directory to include in the archive. With no other arguments an archive containing this directory and all subdirectories will be created. Required, unless a nested fileset is provided.

Includes:

A space-separated list of files, directories, or patterns to include, just as in the includes attribute of the fileset element.

Excludes:

A space-separated list of files, directories, or patterns to exclude, just as in the excludes attribute of the fileset element.

Many tasks follow this pattern of allowing a combination of basedir, includes, and excludes as attributes. Such tasks are called

implicit filesets. All of the following are equivalent:

<jar destfile="src.jar" basedir="." includes="**/*java"/>
<jar destfile="src.jar">
<filset dir="." includes="**/*java"/>
</jar>
<jar destfile="src.jar">
<filset dir=".">
<include="**/*java"/>
</fileset>
</jar>

All of these will create a file called src.jar containing the Java files from any directory within the current one. The notable feature of jar files is that they have a special directory called META-INF containing information about what is in the file. If the src.jar file were exampled by running the command unzip -t src.jar, the output would be as follows:

Archive: src.jar
testing: META-INF/               OK
testing: META-INF/MANIFEST.MF    OK
testing: example_dir/            OK
testing: example_dir/src/        OK
testing: example_dir/src/package1/   OK
testing: example_dir/src/package1/autogen/   OK
testing: example_dir/src/package1/autogen/table1.java   OK
testing: example_dir/src/package1/autogen/table2.java   OK
testing: example_dir/src/package1/class1.java   OK
testing: example_dir/src/package1/class2.java   OK
testing: example_dir/src/package2/   OK
testing: example_dir/src/package2/class3.java   OK

Notice all the files and directories are present, along with the special META-INF directory that the jar task has created automatically.

2.8.7. Java

Java runs a Java program either within the virtual machine in which Ant is running or externally. The motivation for this task is similar to that for the Exec task. Sometimes it may be necessary to run some Java code that would be too difficult to turn into a task.

Attributes:

classname: The name of the class to run. This class must define a public static void main(String[]) method.

jar: The name of the jar to run. One of classname or jar must be provided.

fork: Whether to run the program in a separate VM. Defaults to false.

Example:

<target name="hello">
<java classname="com.awl.toolbook.chapter02.Hello"/>
</target>

will produce

hello:
[java] Hello, world

Note that the output is preceded by the task name.

2.8.8. Javac

Javac compiles Java files. The set of files to compile comprises a fileset, which may be specified either explicitly with a nested fileset element or implicitly by naming a top-level directory and specifying includes and excludes as attributes.

Note that Ant will not compile every file in the resulting fileset, only those that have been updated since the last time they were compiled. This can occasionally cause confusion when compiling files that reside on a remote server. If the clocks on the server and local machine are out of sync, Ant may generate messages about the source files having been modified in the future, or it may not recognize that files have been modified.

Attributes:

srdir: The top-level source directory. Required.

destdir: The directory into which class files should be written. Defaults to srcdir.

includes: The set of files, directories, or patterns to include.

excludes: The set of files, directories, or patterns to exclude.

classpath: The classpath to use for compilation.

classpathref: A reference to a classpath defined elsewhere in the file.

Example:

<target name="compile">
<javac srcdir="src"/>
</target>

will compile all the Java files in the example used throughout this chapter. Ant will report this as follows:

compile:
[javac] Compiling 5 source files
BUILD SUCCESSFUL

Any compilation errors will be reported and will cause the build to fail.

2.8.9. Javadoc

Javadoc generates javadoc-style documentation. The javadoc generator contains a huge number of options for how to format and construct documentation. See the documentation for javadoc or Ant for details.

Attributes:

destdir: The directory into which generated documentation should be written.

classpath: The classpath to use to resolve references found in classes.

classpathref: A reference to a classpath defined elsewhere in the file.

sourcepath: The path of source files for which documentation should be generated.

sourcepathref: A reference to a path element defined elsewhere in the file.

sourcefiles: A list of individual files for which documentation should be generated. One of sourcepath, sourcepathref, sourcefiles or a nested fileset must be provided.

Example:

<target name="buildDocs">
<javadoc destdir="docs"
packagenames="package1,package2"
sourcepath="src"/>
</target>

will generate documentation for all classes in the package1 and package2 packages.

2.8.10. A More Complete Example

Listing 2.3 shows a simple but complete build file as might be used for the hypothetical project used in this chapter.

Listing 2.3. A complete build file

<project default="compile">
<target name="buildJar" depends="compile, copy">
<jar destfile="project.jar"
basedir="deploy"
manifest="mainClass"/>
</target>
<target name="compile" depends="setup">
<javac srcdir="src" destdir="deploy"/>
</target>
<target name="setup">
<mkdir dir="deploy"/>
</target>
<target name="copy">
<copy todir="deploy/images">
<fileset dir="images"/>
</copy>
</target>
<target name="buildDocs">
<javadoc destdir="docs"
packagenames="package1,package2"
sourcepath="src"/>
</target>
<target name="clean">
<delete>
<fileset dir="deploy"/>
<fileset dir="src">
<include name="**/*.class"/>
</fileset>
</delete>
</target>
</project>

The ultimate goal of this build file is to prepare a jar file containing the compiled code along with the images that are presumably used or displayed by the program. This process happens in several steps.

The default target is compile, because that is what developers spend the most time doing. Here the javac task builds class files in a separate directory, deploy, which is used to hold all the files that make up the finished program. It would also be possible to copy all the class files after they had been compiled.

Another target called copy uses the copy task to move the images into the same deploy directory.

Once all the files are in place the jar file can be assembled, which is done by the buildJar target. Here a manifest attribute is used, which names a file to use as the MANIFEST.MF in the special META-INF directory. The mainClass file contains a single line:

Main-Class: package1 class1

Placing this line in the manifest enables the resulting jar file to be executablein other words, that user could run java -jar project.jar and the main() method of the package1.class1 class would be invoked.