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:

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.

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.