Recipe 4.2 Using Ant Targets


Problem

You want to create target elements for developing web applications with an Ant build file.

Solution

Create one or more target elements as child elements of a project element. Make sure the target s have the required name attribute and value.

Discussion

An Ant build file is an XML file ”in other words, a plaintext file that includes elements and attributes. Example 4-1 shows an Ant file that echoes a message to the console. As mentioned in the introduction, Ant files execute Java code behind the scenes. The way you control the desired actions of your build file is by arranging one or more target elements inside the project root element.

Example 4-1. An Ant build file that echoes a console message
 <project name="Cookbook" default="echo-message" basedir=".">  <target name="echo-message"           description="Echoing a message to the console">         <echo message="Hello from the first Ant file"/>     </target>  </project> 

Ant files have one project root element, which must have a default attribute and value. The default attribute specifies the target that runs if no other targets are identified on the command line. The name and basedir attributes are optional. The name attribute, as you might have guessed, gives the project element a descriptive name. The basedir attribute specifies the directory by which paths that are referred to in the file are calculated. Its default value is the directory containing the build file.

What are targets? They are groups of tasks , represented in Ant by a target element. Targets group one or more tasks (which are in turn represented by a task element) into logical and named units of control, similar to Java methods .

Tasks include actions that compile Java files (the javac task), copy files from one location to another ( copy ), and create JAR or WAR files (aptly named jar and war ). For instance, the echo-message target in Example 4-1 calls the echo task.

The target's name in Example 4-1 is echo-message , which is just a name that I created for it. A target's description attribute is optional, as are three other attributes: depends , if , and unless . I'll explain the purpose of depends shortly; the if and unless attributes allow the conditional execution of targets.

As long as Ant is properly set up on your computer, here is what the command-line sequence for executing this example build.xml file might look like:

 H:\book\cookbook\sec1\sec1_3>ant Buildfile: build.xml echo-message:      [echo] Hello from the first Ant file. BUILD SUCCESSFUL Total time: 3 seconds 

First, the XML file with the project root element is saved with the filename build.xml . Then the user changes to the directory that contains this file and types ant , without any options. Ant then looks for a file called build.xml in the current directory and runs the project's default target (in Example 4-1, the echo-message target).

You can give the build file a name other than build.xml , but then you need to run Ant with the -buildfile option:

 ant -buildfile dev.xml 

Most build files involve several targets that execute in a certain sequence to initiate Java development tasks. Example 4-2 demonstrates the depends attribute. This example shows how to execute several targets in a specified sequence.

Example 4-2. Using the depends target attribute to launch a sequence of targets
 <project name="Cookbook" default="echo-message" basedir=".">     <target name="init">         <property name="name" value="Bruce Perry"/>     </target>     <target name="show-props" depends="init">         <echo message=           "The 'name' property value is: ${name}"/>         <echo message=           "OS name and version is: ${os.name} ${os.version} "/>         <echo message=           "Your Java home is: ${java.home} "/>     </target>     <target name="echo-message" depends="show-props">         <echo message=           "Hello from the first Ant file in directory: ${basedir}"/>     </target> </project> 

This time, instead of just one target, the project element has several nested targets. The echo-message target is still the default target, but its behavior has changed due to the value of its depends attribute. This optional attribute specifies the name of one or more Ant targets that must be executed prior to the current target. In other words, the echo-message target specifies, "I depend on the show-props target, so execute it before me." The show-props target, however, also has a depends attribute that indicates a reliance on the init target. As a result, this build file establishes a sequence for executing its targets: init show-props echo-message .

The result of running the prior build file at the command line is shown here:

 H:\book\cookbook\sec1\sec1_3>ant Buildfile: build.xml init: show-props:      [echo] The 'name' property value is: Bruce Perry      [echo] OS name and version is: Windows NT 4.0      [echo]  Your Java home is: h:\jdk1.3.1_02\jre echo-message:      [echo] Hello from the first Ant file in directory:             H:\book\cookbook\sec1\sec1_3 BUILD SUCCESSFUL Total time: 2 seconds 

Here is what this build file accomplishes:

  1. The init target first creates a name property that contains the value "Bruce Perry". The target uses the property task to accomplish this. Recall that tasks do the real work in Ant; targets are simply grouping elements that call one or more tasks.

  2. The show-props target then echoes the values of the name property (created by the init target) and three built-in properties: os.name , os.version , and java.home .

  3. The echo-message target issues its message to the console and returns the value of the basedir property. All of the targets use the echo task to deliver their messages.

Note that the name property would not be set if the init target was never executed. If the show-props target is defined as seen here, there will be problems:

 <target name="show-props">  . . . </target> 

However, it is properly defined as follows :

 <target name="show-props" depends="init">   . . . </target> 

Without the depends attribute, the init target would never be executed, because the build file's execution sequence would look like show-props echo-message . The name property would never be given a value.

Ant build files are usually much more complex than these examples, which is more of a testament to Ant's power than evidence of poor design. Chapter 2 shows how to deploy individual servlets and web applications with more extensive Ant files.

See Also

Recipe 4.1 on downloading and setting up Ant; Recipe 4.3 on including Tomcat JAR files in the Ant classpath; Recipe 4.4 on compiling a servlet with Ant; Recipe 4.5 on creating a JAR file with Ant; Recipe 4.7 and Recipe 4.8 on starting and stopping Tomcat with Ant; Recipe 2.1 and Recipe 2.6 on deploying web applications using Ant; the Ant manual section on the property task: http://ant.apache.org/manual/CoreTasks/property.html; the Ant manual segment on targets : http://ant.apache.org/manual/using.html#targets; the Apache Ant manual index page: http://ant.apache.org/manual/index.html; the Apache Ant Project: http://ant.apache.org .



Java Servlet & JSP Cookbook
Java Servlet & JSP Cookbook
ISBN: 0596005725
EAN: 2147483647
Year: 2004
Pages: 326

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net