Developing a build.xml File for Building Struts Applications Using Ant

Developing a build.xml File for Building Struts Applications Using Ant

This section is based on the strutsANT.zip file that's included on the CD-ROM accompanying this book. Other sections of this chapter use different archives.

A good Ant build file enables you to build as much or as little of the application as you want. It also lets you pick up where you left off without repeating steps. And ”if you want to ”it should let you delete everything (hopefully except your source files!) and start over from scratch.

In reality, Ant build files can be created to do virtually anything you can write a program for. People all over the world have added tasks to Ant to do anything that's commonly needed. If all else fails, Ant is completely extendable by using Java to write your own tasks .

This chapter, however, sticks with the basics of how to build a Struts application. Listing 20.1 is the build file used in this sample application. Don't worry about understanding every line right now; each part of it is explained as you progress through this section. The name of the build file is build.xml because this is the default name that Ant looks for if you just type ant without specifying a particular build file by name.

Listing 20.1 The Ant Build File for the Hello World! Sample Application ( build.xml )

 <project name="billing" default="help" basedir="."> <!-- ===================== Property Definitions =========================== -->     <!--          All properties should be defined in this section.          Any host-specific properties should be defined          in the build.properties file.          In this app, the following properties are defined in build.properties:         o  tomcat.home     - the home directory of your Tomcat installation         o  webapps.home    - the place to copy the war file to deploy it     -->   <property file="build.properties" />   <property name="app.home"          value="." />   <property name="app.name"          value="strutsANT" />   <property name="javadoc.pkg.top"   value="ch20" />   <property name="src.home"          value="${app.home}/src"/>   <property name="lib.home"          value="${app.home}/lib"/>   <property name="object.home"       value="${app.home}/object"/>   <property name="deploy.home"       value="${app.home}/deploy"/>   <property name="doc.home"          value="${app.home}/doc"/>   <property name="web.home"          value="${app.home}/web"/>   <property name="build.home"        value="${app.home}/build"/>   <property name="build.classes"     value="${build.home}/WEB-INF/classes"/>   <property name="build.lib"         value="${build.home}/WEB-INF/lib"/> <!-- ==================== Compilation Classpath =========================== -->     <!--          This section creates the classpath for compilation.     -->   <path id="compile.classpath">     <!-- The object files for this application -->     <pathelement location="${object.home}"/>     <!-- The lib files for this application -->     <fileset dir="${lib.home}">       <include name="*.jar"/>       <include name="*.zip"/>     </fileset>     <!-- All files/jars that Tomcat makes available -->     <fileset dir="${tomcat.home}/lib">       <include name="*.jar"/>     </fileset>     <fileset dir="${tomcat.home}/common/lib">       <include name="*.jar"/>     </fileset>     <pathelement location="${tomcat.home}/classes"/>     <pathelement location="${tomcat.home}/common/classes"/>   </path> <!-- ==================== Build Targets below here========================= --> <!-- ==================== "help" Target =================================== -->     <!--          This is the default ant target executed if no target is specified.          This helps avoid users just typing 'ant' and running a          default target that may not do what they are anticipating...     -->  <target name="help" >    <echo message="Please specify a target! [usage: ant &lt;targetname&gt;]" />    <echo message="Here is a list of possible targets: "/>    <echo message="  clean-all.....Delete build dir, all .class and war files"/>    <echo message="  prepare.......Creates directories if required" />    <echo message="  compile.......Compiles source files" />    <echo message="  build.........Build war file from .class and other files"/>    <echo message="  deploy........Copy war file to the webapps directory" />    <echo message="  javadoc.......Generates javadoc for this application" />  </target> <!-- ==================== "clean-all" Target ============================== -->    <!--           This target should clean up any traces of the application           so that if you run a new build directly after cleaning, all           files will be replaced with what's current in source control    -->  <target name="clean-all" >     <delete dir="${build.home}"/>     <delete dir="${object.home}"/>     <delete dir="${deploy.home}"/>     <!-- can't delete directory if Tomcat is running -->     <delete dir="${webapps.home}/${app.name}" failonerror="false"/>     <!-- deleting the deployed .war file is fine even if Tomcat is running -->     <delete dir="${webapps.home}/${app.name}.war" />     <!-- delete the javadoc -->     <delete dir="${doc.home}"/>  </target> <!-- ==================== "prepare" Target ================================ -->     <!--           This target is executed prior to any of the later targets           to make sure the directories exist. It only creates them           if they need to be created....           Other, similar, preparation steps can be placed here.     -->   <target name="prepare">     <echo message="Tomcat Home = ${tomcat.home}" />     <echo message="webapps Home = ${webapps.home}" />     <mkdir dir="${object.home}"/>     <mkdir dir="${deploy.home}"/>     <mkdir dir="${doc.home}"/>     <mkdir dir="${doc.home}/api"/>     <mkdir dir="${build.home}"/>     <mkdir dir="${build.home}/WEB-INF" />     <mkdir dir="${build.home}/WEB-INF/classes" />     <mkdir dir="${build.home}/WEB-INF/lib" />   </target> <!-- ==================== "compile" Target ================================ -->     <!--           This only compiles java files that are newer           than their corresponding .class files.      -->   <target name="compile" depends="prepare" >     <javac srcdir="${src.home}" destdir="${object.home}" debug="yes" >         <classpath refid="compile.classpath"/>     </javac>   </target> <!-- ==================== "build" Target ================================== -->     <!--           This target builds the war file for the application           by first building the directory structure of the           application in ${build.home} and then creating the           war file using the ant <war> task      -->   <target name="build" depends="compile" >     <!-- Copy all the webapp content (jsp's, html, tld's, xml, etc. -->     <!-- Note that this also copies the META-INF directory -->     <copy    todir="${build.home}">       <fileset dir="${web.home}"/>     </copy>     <!-- Now, copy all the Java class files -->     <copy    todir="${build.home}/WEB-INF/classes">       <fileset dir="${object.home}"/>     </copy>     <!-- Now, copy all the properties files, etc that go on the classpath -->     <copy    todir="${build.home}/WEB-INF/classes">       <fileset dir="${src.home}">          <include name="**/*.properties" />          <include name="**/*.prop" />       </fileset>     </copy>     <!-- Now, copy all the jar files we need -->     <copy    todir="${build.home}/WEB-INF/lib">       <fileset dir="${lib.home}" />     </copy>     <!-- Create the <war> file -->     <jar jarfile="${deploy.home}/${app.name}.war"          basedir="${build.home}"/>   </target> <!-- ==================== "deploy" Target ================================= -->     <!--          This target simply copies the war file from the deploy          directory into the Tomcat webapp directory.      -->   <target name="deploy" depends="build" >     <!-- Copy the contents of the build directory -->     <copy todir="${webapps.home}"  file="${deploy.home}/${app.name}.war" />   </target> <!-- ==================== "doc" Target ==================================== -->     <!--          This task creates javadoc. It is dependent upon only the          'compile' target so it is not executed in a normal build.          As a result, the target needs to be run on its own.     -->   <target name="javadoc" depends="compile">       <javadoc sourcepath = "${src.home}"                   destdir = "${doc.home}/api"              packagenames = "${javadoc.pkg.top}.*"/>   </target> </project> 

The following items summarize each section of the build.xml file:

• Property definitions ” To make build files more flexible, it's customary to define all directories using properties; for example, src.home . The value of src.home is then retrieved later using the notation ${src.home} . In addition, properties can be read in from a file. The approach demonstrated here is to have the build file contain only relative directory references and have any host-specific or hard-coded directory parameters read in from a file. An example of a property that isn't an alias for a directory is app.name , which is the name of the Web app this file builds. Also, remember these properties can't be changed after they're set; Ant doesn't provide variables .

• Compilation classpath ” Classpaths are built in Ant using <classpath> elements in the build file. This <classpath> definition demonstrates a number of ways of adding elements to the classpath for compiling.

• Build Targets section ” Ant runs by building targets. All targets in the file are defined below this section. Ant builds a target by executing the tasks within the target. Targets are built in order based on the depends attribute of the target: Ant traces back through the depends attributes of every target and then builds all the targets in the correct order (more on this in the following items).

• help target ” This is the default target for the build file; that is, the target that's executed if no specific target is given on the command line when you run Ant. All this target does is print out the available targets in the build file. This is recommended because it's common for people to simply type ant at the command line without thinking, and execute whatever the default target is (even if the default target deletes everything and initiates a total rebuild from scratch). This way, it requires the person to indicate on the command line the specific target to be built.

• clean-all target ” This target is executed if you want to remove all .class and archive files and initiate a complete rebuild from scratch. An alternative approach is to define multiple clean targets ( clean-object , clean-archives , clean-source , and so on) and then have the clean-all target simply refer to each of them in its depends attribute. This enables you to either selectively clean individual targets or clean everything at once.

• prepare target ” This target performs steps to initialize the build process, including creating any directories that may have been removed by the clean-all target. It's best to consolidate all directory creation activities to this section because doing so simplifies maintenance and reduces errors that can creep into the build process over time.

• compile target ” This target compiles all Java files. Note that as with many Ant tasks, the <javac> task performs its operations conditionally; it compiles only Java files that need it. Ant compiles a Java file only if there is no class file for it already or if the timestamp on the Java file is newer than the timestamp on the .class file (that is, the class file is out of date).

• build target ” This target assembles everything into a build directory in the structure required to build the WAR file for deployment. After everything is copied , it executes the <jar> task to create a .war file archive for deployment. (There also exists an Ant <war> task for this purpose ”either approach works.)

• deploy target ” This target simply takes the WAR file created by the build target and copies it to the webapps directory of your application server to deploy it. If your application server runs on a different host than the one you perform your builds on, the Ant <ftp> task might be useful for you to perform deployments with.

• doc target ” This target builds the documentation for this application. Although for this sample application this consists of generating Javadoc for the application, it's also common to generate other documentation as well. For example, the Ant <style> task is often used with XML and XSL files to generate HTML-based docs for an online reference to the application.

Now that you've got a directory structure for developing your application and an Ant build file for building and compiling, it's time to focus on the more "extreme" elements of this chapter: how to make integrated and ongoing testing a part of your everyday development cycle.