Using Ant for Building J2EE Applications

Ant is an open source Java-based build tool developed by the Apache Foundation and is similar to GNU's make utility. Ant consists of several built-in tasks for compiling and executing Java applications, building archives, as well as performing file and directory manipulations. These tasks make Ant a very useful tool for building J2EE applications. In this section, you learn some Ant basics, look at some built-in Ant tasks , and then examine how to write Ant scripts to build J2EE applications.

For complete documentation on Ant, the following site is a very useful reference:

http://jakarta.apache.org/ant

Ant Basic Concepts

WebLogic Server 7.0 bundles Ant version 1.4. The script that invokes Ant is located in the %BEA_HOME%\weblogic700\server\bin directory. This script executes the Java class org.apache.tools.ant.Main . To invoke the Ant utility, this directory must be in your path .

The syntax for using the Ant utility is as follows :

 ant [  options  ] [  target  [  target2  [  target3  ] ...]]

The various options that can be passed to the Ant utility are

help: Prints all the available options.
projecthelp: Prints project help information.
version: Prints the version information and exits.
quiet: Be extra quiet. This is opposite of verbose and, when used, the utility prints whether or not the build was successful.
verbose: By default, the Ant utility prints out some information. With this option, it prints out extra information.
debug: Prints debugging information.
emacs: Produces logging information without adornments.
logfile < file >: Uses given file for log.
logger < classname >: The class that is to perform logging.
listener < classname >: Adds an instance of class as a project listener.
buildfile < file >: Uses given build file.
D< property >=< value >: Uses value for given property.
find < file >: Searches for build file toward the root of the file system and uses it.

Ant searches for a build file to determine what tasks need to be performed. By default, Ant looks for a file named build.xml in the current directory. If you need to use a build file with a different name, you can specify its name explicitly using the -buildfile argument. For example:

 ant -buildfile ejbBuildFile.xml

Understanding the Ant Build File

The Ant build file is an XML document that describes the tasks to be performed by the Ant utility. You may use a simple text editor with XML highlighting or an XML editor to create and edit the build file. The Ant installation contains a JAXP-compliant parser that's used to parse the build file.

Let's use the following simple build file to examine its different attributes and properties:

 <?xml version="1.0"?> <project name="example" default="compile" basedir ="."> <property name="srcDir" value="."/> <property name="targetDir" value="build"/> <target name="init"> <mkdir dir="${targetDir}"/> </target> <target name="compile" depends="init"> <javac srcdir="${srcDir}" destdir="${targetDir}"/> </target> </project>

Because Ant build files are XML documents, the first line declares the version of XML in use. The next line defines the root element of the build file; that is, the <project> element. The <project> element contains one or more <target> elements, and each <target> element can contain one or more Ant tasks. Ant tasks are simply Java classes that can be invoked from the build file to perform specific actions. These classes provide the task implementation and should be present in the Ant classpath. Several basic tasks, such as java, javac , and others, are prepackaged with the Ant utility. Some of the built-in tasks available with the utility are described in the next section, "Built-in Ant Tasks."

In this way, the build file is arranged in a hierarchy. The <project> element has three attributes:

name: Defines the name of the project.
default: Specifies the default target to execute if one isn't specified on the command line.
basedir: Identifies the base directory from which any relative paths in the project are calculated. If not specified, the parent directory of the build file is used.

The next two lines specify two <property> elements. The <property> elements enable you to declare user -defined variables that can be used anywhere in the context of the project. A project can have a set of properties defined using the <property> element. The value of a property can be referenced using the notation ${ property-name } . The build file defines properties with the names srcDir and targetDir . The values of these properties can be referenced as ${srcDir} and ${targetDir} in the build file. The <property> element can also be used to get access to environment variables by declaring the following property:

 <property environment="env"/>

You can then access the values of the environment variables CLASSPATH and PATH as ${env.CLASSPATH} or ${env.PATH} .

The next line defines a <target> element named init . The <target> element contains a sequence of Ant tasks. It has a name attribute so that it can be called from elsewhere in the build file. The name attribute is the only required attribute of the <target> element. In this case, the target contains a file and directory manipulation Ant task called mkdir . This is a predefined Ant task, and here it's used to create the build directory.

The next three lines define another target element named compile . This target element has a new attribute called depends . This attribute enables you to specify other targets that can be executed before executing the tasks in the body of this target. In this case, because of the depends attribute, the init target will be executed before the compile target. The compile target contains a predefined task called javac . The task has two attributes, srcdir and destdir , that get their values from the project properties defined on the third and fourth lines of the build file.

This build file causes javac to be executed on all the .java files in the directory specified by the srcDir project property. The resultant .class files are placed in the directory specified by the targetDir project property.

We can use Ant and the build file we just created to compile a Java file by following these steps:

Create a temp directory named antTest .
Write a simple HelloWorld.java program in the antTest directory.
Copy the build.xml file to the antTest directory.
Set the required environment variables by running one of the following scripts:
```
   
```
```
  domain\setWLSEnv.cmd (Windows)  
```
```
   
```
```
  domain\setWLSEnv.sh (Unix)  
```
This correctly sets the PATH and CLASSPATH variables.
Run the Ant script by typing ant on the command line.
Ant will find the build.xml in the current directory, create a directory called build , compile the HelloWorld.java file, and place it in the build directory.

Built-in Ant Tasks

The basic Ant utility is packaged with many built-in Ant tasks. Some of the common core tasks are

Tasks for compiling and executing Java applications: <javac> , <java> , and <javadoc>
Archive creation tasks: <jar> , <war> , and <ear>
File and directory manipulation tasks: <copy> , <delete> , <mkdir> , <move> , <touch> , and <tstamp>

Let's look at the most common Ant tasks that will help you in creating build scripts for J2EE applications.

`javac`

The javac Ant task compiles the javac source code; that is, the .javac files. This task is smart in the sense that the compilation happens only if the .javac file has a more recent timestamp than its corresponding .class file.

The following are two examples of using the javac task:

[View full width]

 <javac srcdir="myProject\source" destdir="myProject\classes"\> <javac srcdir="myProject\source" destdir="myProject\classes" excludes="myPackage/**"  classpath="myClasses.jar"\>

The srcdir attribute specifies the location of the source java files. The destdir attribute specifies the location to which the source files will be compiled.

Some additional attributes of the javac task are

includes: A comma-delimited list of files that must be included; wildcards are allowed
excludes: A comma-delimited list of files that must be excluded; wildcards are allowed
classpath: The classpath passed on to the Java compiler to be used while compiling
debug: Used to print extra debugging information
verbose: Used to print extra general information
deprecation : Used to print information about deprecated classes and methods while compiling

`java`

The java task executes a specified Java class. The class may execute within the same JVM as the Ant utility or a new JVM, depending on the value of the fork attribute.

The following are two examples of using the java task:

 <java classname="mypackage.HelloWorld"/> <java classname="mypackage.HelloWorld" classpath="myClasses.jar" fork="yes"/>

In the second example, the fork attribute is set to yes , so the HelloWorld program will execute in a different JVM instance from the Ant utility. If the attribute were set to no , the program would be run in the same JVM instance. In this case, be careful that the class does not have a System.exit() because that will terminate the execution of Ant.

Some of the other attributes that can be passed to the java Ant task are

maxmemory: The maximum amount of memory that can be allocated to the forked JVM
output: Redirects the standard output to a given file

While running a Java program, in most cases, we pass arguments to the JVM as well as command-line arguments to the program. We also need to pass system properties required by the Java class. This also can be done in the Ant java task as follows:

 <java classname="mypackage.HelloWorld" fork="yes"> <arg value="-help"/> <jvmarg value="-Xms=16m"/> <sysproperty key="worldName" value="earth"/> </java>

The <arg> element supplies command-line arguments to the Java program. The <jvmarg> element provides command-line arguments to the JVM. The <sysproperty> element supplies the system properties to the Java class while executing.

`jar`

The jar task archives a set of files and may update existing archives or replace them depending on the attributes passed to the task.

The following are some examples of creating a Java archive:

 <jar jarfile="myProject.jar" basedir="myProject"> <jar jarfile="myProject.jar" basedir="myProject" update="yes"> <jar jarfile="myProject.jar" basedir="myProject" excludes="*.html" compress="true">

Some other attributes for the jar task include

includes: Includes a list of files that must be included. Wildcards are allowed.
excludes: A comma-delimited list of files that must be excluded. Wildcards are allowed.
Manifest: The manifest file to use.
Whenempty: If an empty archive is created, or the creation is skipped , or if the creation of archive fails, the build is halted.

The File and Directory Manipulation Ant Tasks

The Ant utility also provides built-in Ant tasks for carrying out operations on files and directories such as copying files, creating and deleting directories, and so forth.

The following are examples of a few such tasks:

 <copy file="myweb.xml" tofile="${build}/WEB-INF/web.xml"/> <copy file="weblogic.xml" todir="${build}/WEB-INF" overwrite="yes"/> <mkdir dir="${build}/images"/> <delete dir="${build}/>

In the preceding examples, build is defined as a project property. Therefore, its value is specified in the script as ${build} .

Besides these Ant tasks that can be used to build any Java project, Ant also bundles some tasks that are specific to building J2EE applications. The following section describes two such useful tasks: war and ear .

Creating a Web Application Archive Using the `war` Ant Task

The war Ant task can be used to archive a set of files into the standard J2EE web application format. The war task contains attributes and elements specific to building a Web application archive. Some of these elements are

webxml: This attribute defines the file to be used as the web.xml deployment descriptor and copies it as web.xml into the WEB-INF dir of the archive.
manifest: This attribute defines the file to be used as the manifest file and copies it as META-INF\MANIFEST.MF of the archive.
<lib>: Specifies the files to be copied into the WEB-INF\lib directory using this element.
<classes>: Specifies the files to be copied into the WEB-INF\classes directory using this element.

The following is an example of creating a Web application archive:

 <?xml version="1.0"?> <project name="example" default="buildWar" basedir="."> <target name="buildWar"> <war warfile="myWebApp.war" webxml="dd/myWeb.xml" manifest="manifest.txt"> <lib dir="./libraries"/> <classes dir="./classes"/> <fileset dir="." includes="*.html,*.jsp"/> <zipfileset dir="." prefix="images" includes="*.gif,*.jpg"/> <zipfileset dir="." prefix="WEB-INF" includes="weblogic.xml"/> </war> </target> </project>

The <fileset> element defines a collection of resources relative to the base directory. Here, the <fileset> is used to include all the JSPs and HTML pages in the root directory of the Web application. The <zipfileset> element is an extension of the <fileset> element with extra attributes that are useful in the context of archiving tasks. The prefix attribute of the <zipfileset> element is prepended to each entry in the output archive. Here, the output archive will have GIF and JPG files prefixed with images\ and the weblogic.xml file prefixed with WEB-INF\; that is, WEB-INF\weblogic.xml .

Creating an Enterprise Application Archive Using the `ear` Ant Task

The ear Ant task archives a set of files into the standard J2EE enterprise application format. The appxml attribute defines the file that is to be used as the application.xml deployment descriptor.

The following is an example of creating an enterprise archive:

 <ear earfile="myEnterpriseApp.ear" basedir="myproject" appxml="myApp.xml" includes="*.jar,*.war"/>