Developing for the Web with Ant, Part 1

O'Reilly Book Excerpts: Ant: The Definitive Guide, Second Edition

Developing for the Web with Ant, Part 1

Editor's note: In part one of this two-part excerpt from Ant: The Definitive Guide, 2nd Edition, author Steve Holzner covers packaging web applications. And stay tuned for part two next week, which covers the tasks for deploying web apps, including get, serverdeploy, and scp.

Developing for the Web is bread and butter for Ant developers. There is a wide spectrum of tasks at your disposal: Chapter 4 introduced packaging and deploying applications--including Web applications--with the move, copy, ftp, telnet, sshexec, and mail tasks, but Ant offers more. This chapter covers the tasks specifically designed for packaging Web applications, such as war, cab, ear, and jspc, and for deploying them, such as get, serverdeploy, and scp. I'll cover the custom Ant tasks targeted to specific servers such as deploy, reload, and undeploy. And there's more to come: Chapter 9 covers the many optional Enterprise JavaBeans (EJB) tasks Ant supports.

Creating WAR Archives

The war task is an extension of the jar task, and it compresses Web applications into .war files, with special handling for files that should end up in the WEB-INF/lib, WEB-INF/classes or WEB-INF directories on the server. For example, say you have this directory layout after you build your project:

war
|____output
|        login.class
|        logout.class
|        
|____source
     |    login.xml
     |    
     |____html
              welcome.xml

The build file in Example 8-1 will create the .war file you need to deploy this application, placing the .class files in the WEB-INF/classes directory, renaming login.xmlweb.xml and placing it in WEB-INF, and so on.

Example 8-1. Creating a war file (ch08/war/build.xml)

<?xml version="1.0" encoding="UTF-8" ?>

<project default="main" basedir=".">

   <property name="bin" value="output" />     
   <property name="src" value="source" />     
        <target name="main">

             <war destfile="login.war" webxml="${src}/login.xml">
               <fileset dir="${src}/html"/>
               <classes dir="${bin}"/>

             </war>
        </target>
</project>

Here's what this build file looks like at work:

%ant
Buildfile: build.xml

main:
      [war] Building war: /home/steven/ant/ch08/war/login.war

BUILD SUCCESSFUL
Total time: 2 seconds

That creates the .war file. Besides packaging the files specified, Ant supplies a default manifest file, Manifest.mf, in the resulting .war file, which contains these contents:

Manifest-Version: 1.0
Ant-Version: Apache Ant 1.6.1
Created-By: 1.4.2_03-b02 (Sun Microsystems Inc.)

After you create your .war file, you can deploy it by copying it to your web server's deployment directory, such as to the webapps directory in Tomcat.

The attributes of the war task appear in Table 8-1.

TIP: The war task is a shortcut for specifying the particular layout of a .war file. The same thing can be accomplished using the prefix and fullpath attributes of zipfilesets in a zip or jar task.

Table 8-1. The war task's attributes

Attribute	Description	Required	Default
`basedir`	Specifies the source directory for files to include in the compressed file.	No
`compress`	Specifies you want to not only store data but compress it.	No	`true`
`defaultexcludes`	Specifies if you want to use default excludes or not. Set to `yes`/`no`.	No	Default excludes are used.
`destfile`	Specifies the WAR file you want to create.	Exactly one of `destfile` or `warfile`.
`duplicate`	Specifies what to do if a duplicate file is found. Valid values are `add`, `preserve`, and `fail`.	No	`add`
`encoding`	Specifies the character encoding to use for filenames in the WAR file.	No	`UTF8`
`excludes`	Specifes the patterns matching files to exclude, as a comma- or space-separated list.	No
`excludesfile`	Specifes the name of a file where each line is a pattern matching files to exclude.	No
`filesonly`	Specifies you want to store only file entries.	No	`false`
`includes`	Specifes the patterns matching files to include, as a comma- or space-separated list.	No
`includesfile`	Specifes the name of a file where each line is a pattern matching files to include.	No
`keepcompression`	Preserves the compression as it has been in archives you're compressing instead of using the compress attribute. Available since Ant 1.6.	No	`false`
`manifest`	Specifies the manifest file to use in the compressed file.	No
`update`	Specifies whether you want to update or overwrite the target file if it exists.	No	`false`
`warfile`	Deprecated. Use `destfile`. Specifies the WAR file you want to create.	Exactly one of `destfile` or `warfile`.
`webxml`	Specifies the deployment descriptor you want to use. Will be deployed to WEB-INF/web.xml.	Yes, unless `update` is set to true.

The war task can contain elements like fileset and zipfileset to specify what files to include in the .war file. This task can contain these elements to specify where you want various files to go:

Files contained in the webinf element end up in WEB-INF
Files contained in the classes element end up in WEB-INF/classes
Files contained in the lib element end up in WEB-INF/lib
Files contained in the metainf files end up in META-INF

Creating CAB Files

The cab task creates Microsoft .cab archive files, and you use this task as you would the jar or zip tasks. The .cab files are the .NET equivalent of .war files, packaging .NET applications for server deployment. This task works in Windows using the external cabarc tool (this tool comes from Microsoft), which must be in your executable path.

I'm not going to spend much time on this task because the Microsoft Visual Studio IDE has many powerful integrated build tools and wizards that create .cab files; most Microsoft developers do not need Ant to solve their build problems. Here's a quick example using the Ant cab task:

<cab cabfile="${deploy}/app.cab" basedir="${output}" />

TIP: You can get a free copy of the Microsoft C# command-line compiler, csc, if your version of Windows doesn't have it. Install the .NET Framework's Software Development Kit (SDK), which you can find at http://msdn.microsoft.com/downloads. The csc compiler is included.

The attributes of the cab task appear in Table 8-2.

Table 8-2. The cab task's attributes

Attribute	Description	Required	Default
`basedir`	Specifies the directory to archive files from.	No
`cabfile`	Specifies the name of the cab file you want to create.	Yes
`compress`	Specifies you want to not only store data but compress it.	No	`yes`
`defaultexcludes`	Specifies if you want to use default excludes or not. Set to `yes`/`no`.	No	Default excludes are used.
`excludes`	Specifes the patterns matching files to exclude, as a comma- or space-separated list.	No
`excludesfile`	Specifes the name of a file where each line is a pattern matching files to exclude.	No
`includes`	Specifes the patterns matching files to include, as a comma- or space-separated list.	No
`includesfile`	Specifes the name of a file where each line is a pattern matching files to include.	No
`options`	Specifies any additional command-line options you want to pass to the `cabarc` tool.	No
`verbose`	Specifies you want full (verbose) output. Set to `yes` or `no`.	No	`no`

You can use nested fileset elements to specify the files to be included in the archive. As with other Ant tasks, this task forms an implicit FileSet and supports all attributes of the fileset element (dir becomes basedir) as well as the nested include, exclude and patternset elements.

Steve Holzner is the author of O'Reilly's upcoming Eclipse: A Java Developer's Guide.