Ant

I would not be exaggerating by claiming that Ant (ant.apache.org) is perhaps the single most important and widely used tool in the world of Java today! Therefore, mastering this tool is the key to rapid Java development. So, it is no surprise that I'm covering this tool directly after the JDK section, because I consider Ant the most vital tool to install after you are done with the basic Java setup.

By now you probably realize the important role Ant plays in Java development. We will use Ant extensively in this book! For example, we will use it to build our application, deploy it, run various Java programs, create our database, run our tests, and more.

Ant was originally developed by James Duncan Davidson, from the Open Source Program Office at Sun Microsystems. Ant is a cross-platform build tool that eliminates a lot of complexities and quirks that can be found in tools such as Unix make. Instead of using shell commands proprietary to the operating system, Ant uses XML files to specify various tasks. Ant is a highly extensible tool, mainly because of the huge market of builtin and external (open source and commercial) tasks available for Ant, which makes it so powerful. In addition, you can easily write your own custom extensions.

Given that Ant itself is developed in Java, it is portable, and according to the Ant website, it has been tested on various Unix systems, Microsoft Windows, Mac OS X, and others. The ant.apache.org website provides ample (and up-to-date) information on how to get Ant set up on your system; if you do not already have Ant installed on your system, you should go ahead and do so at this point.

When you do have Ant set up successfully, you should be able to run the ant command without specifying the full path. That is, the ant command should be in your path because the remainder of our book will reference ant without the full path. For example, if you typed ant -version on the command line, you would see something similar to what is shown in Figure 4.2.

Figure 4.2. Testing the ant setup by running ant -version.

A Simple Ant Build File

Ant, by default, expects a build.xml file in the current directory, if you do not provide the ant command with any arguments. Let's try out a sample build.xml file; you might recall the following tiny Ant script from earlier in this book. It provides a target that executes the echo task:

<?xml version="1.0"?> <project name="HelloTest" default="printmessage"> <target name="printmessage"> <echo message="Hello world!"/> </target> </project>

For example, if we saved this minimal XML code in a file named build.xml and in the same directory type ant, the command and its output would look as follows:

> ant Buildfile: build.xml printmessage: [echo] Hello world! BUILD SUCCESSFUL Total time: 0 seconds

A Comprehensive Ant Build File

"Hello world" examples are good, but let's move toward building a comprehensive Ant build script for our sample application.

Note

This book's downloadable code shows the complete build script for our sample application, build.xml, along with local.properties, a file used by build.xml to load some external properties. Both of these files will be placed in the top-level directory, timex/.

Note that the use of local.properties here demonstrates a handy way of having different property files for different configuration management environments such as development, test, staging, and production.

Ant Concepts

Before we inspect our build.xml file step-by-step, let's review some basic concepts about Ant.

The key concepts in Ant include a project, properties, targets, tasks, and elements. Properties are variables you can set for the ant session. Targets contain blocks of XML code that get executed in the form of tasks. Tasks are the actual executables, such as the built-in javac task. Tasks in turn can contain elements (for example, dirset or fileset).

Step-by-Step Walkthrough

Now, we will review the key targets in our build.xml file, but first, let's look at a graphical representation of this file, shown in Figure 4.3. You may also want to review Figure 4.1 one more time before we begin this walkthrough, because our Ant build script is closely tied to this development directory structure.

Figure 4.3. Hierarchical view of our Ant build.xml file.

The first XML element that must appear in an Ant file is project, as shown here:

<project name="timex" basedir="." default="build">

The next few lines essentially set internal variables (properties) for our script. Most of these properties are related to the various source and destination directories we will use, as shown in this excerpt (notice how we can use internal variables, surrounded by a dollar sign and braces; for example, ${dist.dir}):

<property name="appname" value="timex" /> <property name="lib.dir" value="lib" /> <property name="war.dir" value="build/timex" /> <property name="war.file" value="${dist.dir}/${appname}.war" /> <property name="webinf.dir" value="${war.dir}/WEB-INF" />

After the properties are set up, the script sets up the classpath, which is used by various other tasks in the file. The classpath essentially includes two sets of files: all the .jar files in our lib/ directory and the compiled class files under build/timex/WEB-INF/classes/, as shown next:

<path        description="Master CLASSPATH for this script">     <fileset dir="${lib.dir}">         <include name="*.jar" />     </fileset>     <pathelement location="build/timex/WEB-INF/classes/" /> </path>

The next target in our build script, init, ensures that certain output directories (under build/) are created in order for other tasks in our build script to be successful (note, this is accomplished using the depends attribute in other targets):

<target name="init" description="Setup for build script">     <mkdir dir="${class.dir}" />     <mkdir dir="${libs.dir}" />     <mkdir dir="${jsp.dir}" /> </target>

Our updateweb, updatelib, deleteconfig, and updateconfig targets basically copy or delete web and library-related files to the destination directory.

The next interesting target is compile, which compiles .java files in src/java/ to .class files under build/timex/WEB-INF/classes/, as demonstrated here:

<target name="compile" description="Compiles .java files to WAR directory">     <javac srcdir="${src.dir}" destdir="${class.dir}" debug="true"            failonerror="true" classpathref="master-classpath" /> </target>

Our dist target creates a WAR file and deploys it to the pathname the internal variable ${war.file} points to (that is, dist/timex.war). An interesting thing to note about this target is the use of the war task and fileset element (known as an Ant type). The war task creates a .war file; the fileset type can be used to specify an individual file or a group of files (using include and exclude pattern sets). Examples of both the war task and the fileset element are shown here:

<war destfile="${war.file}" webxml="${src.dir}/conf/web.xml">     <fileset dir="${war.dir}">         <include name="**/*.*" />         <exclude name="**/web.xml" />         <exclude name="**/test/*.class" />         <exclude name="**/*mock*.jar" />     </fileset> </war>

The other notable targets include deploy, clean, and test. The deploy target copies the .war file to a destination directory (we will use it to deploy to an Apache Tomcat webapps directory). The clean target deletes files from the destination directory. We will use the test target later in the chapter.

Ant Task Categories

The following are some of the tasks we used in our build.xml file:

• Archive tasks such as war

• Compile tasks (that is, javac)

• File tasks such as copy, delete, move, and others

• Miscellaneous tasks such as echo

• Property tasks for setting internal variables

Other built-in tasks worth exploring include the following categories:

• Audit/coverage tasks

• Deployment tasks

• Documentation tasks

• Execution tasks

• Mail tasks

• Preprocess tasks

• Property tasks

• Remote tasks

As I mentioned earlier, we will use Ant to build and deploy our web archive (.war) file. In the next chapters, we will continue to use the command line for working with Ant. However, when we look at Eclipse in Chapter 8, "The Eclipse Phenomenon!," we will switch to using Ant within Eclipse (shown in Figure 4.4), which makes editing and running the (same) Ant build.xml much easier!

Figure 4.4. The Ant view in Eclipse.

We will also look at a few more handy tasks in Chapter 10, "Beyond the Basics." Again, entire books are dedicated to Ant, so as you might guess, I have merely scratched the surface here. However, the idea in this book is to get you going rapidly. If you have the need or interest to explore further, you can find ample information online and in print for all the technologies I have covered in this book.