\documentclass{book}
\usepackage{fancyhdr}
\usepackage{makeidx}
% enable showidx to make the indexes appear in the margin.
%\usepackage{showidx}
\usepackage[dvips]{graphicx}
\usepackage[dvips]{color}
\usepackage{supertabular}
\usepackage{multirow}
\usepackage{lastpage}
\makeindex
\pagestyle{fancy}
\marginparwidth=30mm
\newcounter{countrules}
\newcounter{countrecs}
\newcounter{countgen}
\newcounter{countstyle}
\newcounter{countallow}
\addtolength{\headwidth}{\marginparsep}
\addtolength{\headwidth}{\marginparwidth}
\renewcommand{\chaptermark}[1]{\markboth{#1}{}}
\renewcommand{\sectionmark}[1]{\markright{\thesection\ #1}}
\fancyhf{}
\fancyhead[LO]{\bfseries\rightmark}
\fancyhead[RE]{\bfseries\leftmark}
\fancyhead[LE,RO]{\bfseries\thepage}

\fancypagestyle{plain}{%
  \fancyhead{} % get rid of headers
  \renewcommand{\headrulewidth}{0pt} % and the line
}

%\oddsidemargin=0cm
%\evensidemargin=0cm

\def\apmdescription{{\bf Description}\hfil\break}
\def\apmseverity{\hfil\break{\bf Severity}\hfil\break}
\def\apmanecdotalevidence{\hfil\break{\bf Anecdotal Evidence}\hfil\break}
\def\apmsymptoms{\hfil\break{\bf Symptoms}\hfil\break}
\def\apmcauses{\hfil\break{\bf Causes}\hfil\break}
\def\apmexceptions{\hfil\break{\bf Exceptions}\hfil\break}
\def\apmexamples{\hfil\break{\bf Examples}\hfil\break}
\def\apmcompliance{\hfil\break{\bf Compliance}\hfil\break}

\begin{document}
% ***************************** titlepage *******************************
\title{Apache Ant 1.5.3 Manual \\
\vspace{7 mm}
Version 0.1\\
\vspace{1 cm}
\small{Andrew Peter Marlow}}

\pagenumbering{roman}
\maketitle

\vfil\eject

\normalsize{\copyright\ 2000-2003 Apache Software Foundation. All rights Reserved.}

This is the manual for version 1.5.3 of Apache Ant. If your version of
Ant (as verified with {\tt ant -version}) is older or newer than this
version then this is not the correct manual set. Please use the
documentation appropriate to your current version. Also, if you are
using a version older than the most recent release, we recommend an
upgrade to fix bugs as well as provide new functionality

This document should be distributed as part of the Apache source distribution.

Linux is a trademark of Linus Torvalds\hfil\break
UNIX is a trademark of Bell Laboratories\hfil\break

\tableofcontents
\vfil\eject

\pagenumbering{arabic}

\cfoot{\thepage\ of \pageref{LastPage}}

\chapter{Introduction}

Apache Ant is a Java-based build tool. In theory, it is kind of like
make, without make's wrinkles.

Why?  \hfil\break
Why another build tool when there is already make, gnumake,
nmake, jam, and others? Because all those tools have limitations that
Ant's original author couldn't live with when developing software
across multiple platforms. Make-like tools are inherently shell-based:
they evaluate a set of dependencies, then execute commands not unlike
what you would issue on a shell. This means that you can easily extend
these tools by using or writing any program for the OS that you are
working on; however, this also means that you limit yourself to the
OS, or at least the OS type, such as Unix, that you are working on.

Makefiles are inherently evil as well. Anybody who has worked on them
for any time has run into the dreaded tab problem. "Is my command not
executing because I have a space in front of my tab?!!" said the
original author of Ant way too many times. Tools like Jam took care of
this to a great degree, but still have yet another format to use and
remember.

Ant is different. Instead of a model where it is extended with
shell-based commands, Ant is extended using Java classes. Instead of
writing shell commands, the configuration files are XML-based, calling
out a target tree where various tasks get executed. Each task is run
by an object that implements a particular Task interface.

Granted, this removes some of the expressive power that is inherent in
being able to construct a shell command such as `find . -name foo
-exec rm {}`, but it gives you the ability to be cross-platform - to
work anywhere and everywhere. And hey, if you really need to execute a
shell command, Ant has an {\tt <exec>}
task that allows different commands
to be executed based on the OS it is executing on.

\chapter{Getting, Installing and Building Ant}

\section{Getting Ant}

\subsection{Binary Edition}

The latest stable version of Ant is available from the
Ant web page\hfil\break
{\tt http://ant.apache.org/}. 
If you like living on the edge, you can
download the latest version from\hfil\break
{\tt http://cvs.apache.org/builds/ant/nightly/}.

\subsection{Source Edition}

If you prefer the source edition, you can download the source for the
latest Ant release from 
{\tt http://ant.apache.org/srcdownload.cgi}.
Again, if you prefer the edge, you can access the code as it is being
developed via CVS. The Jakarta website has details on accessing
CVS. Please checkout the ant module. See the section Building Ant on
how to build Ant from the source code. You can also access the Ant CVS
repository on-line.

\section{System Requirements}

Ant has been used successfully on many platforms, including Linux, commercial flavours of Unix such as Solaris and HP-UX, Windows 9x and NT, Novell Netware 6 and MacOS X. 
To build and use Ant, you must have a JAXP-compliant XML parser installed and available on your classpath.

The binary distribution of Ant includes the latest version of the
Apache Xerces2 XML parser. Please see 
{\tt http://java.sun.com/xml/} for
more information about JAXP. If you wish to use a different
JAXP-compliant parser, you should remove 
{\tt xercesImpl.jar} and
{\tt xml-apis.jar} from Ant's lib directory. You can then either put the
jars from your preferred parser into Ant's lib directory or put the
jars on the system classpath.

For the current version of Ant, you will also need a JDK installed on
your system, version 1.1 or later. Some tasks work better on post-1.1
systems; some tasks only work on Java 1.2 and successors. A future
version of Ant -Ant 2.0- will require JDK 1.2 or later, though Ant 1.x
strives to retain 1.1 compatibility.

Note: The Microsoft JVM/JDK is not adequate on its own, although the
MS compiler is supported.

Note {\tt \#}2: If a JDK is not present, only the JRE runtime, then many
tasks will not work.

\section{Installing Ant}

The binary distribution of Ant consists of the following directory layout: 

\begin{verbatim}
  ant
   +--- bin  // contains launcher scripts
   |
   +--- lib  // contains Ant jars plus necessary dependencies
   |
   +--- docs // contains documentation
   |      +--- ant2    // a brief description of ant2 requirements
   |      |
   |      +--- images  // various logos for html documentation
   |      |
   |      +--- manual  // Ant documentation (a must read ;-)
   |
   +--- etc // contains xsl goodies to:
            //   - create an enhanced report from xml output of various tasks.
            //   - migrate your build files and get rid of 'deprecated' warning
            //   - ... and more ;-)
\end{verbatim}

Only the bin and lib directories are required to run Ant. To install
Ant, choose a directory and copy the distribution file there. This
directory will be known as {\tt ANT\_HOME}.

\hfil\break
{\bf Windows 95, Windows 98 and Windows ME Note:}\hfil\break

{\em On these systems, the script used to launch Ant will have problems if
{\tt ANT\_HOME} is a long filename (i.e. a filename which is not of the
format known as ``8.3''). This is due to limitations in the OS's
handling of the "for" batch-file statement. It is recommended,
therefore, that Ant be installed in a short, 8.3 path, 
such as~{\tt C:${\backslash}$Ant}}.

On these systems you will also need to configure more environment
space to cater for the environment variables used in the Ant launch
script. To do this, you will need to add or update the following line
in the {\tt config.sys} file

\begin{verbatim}
shell=c:\command.com c:\ /p /e:32768
\end{verbatim}

\subsection{Setup}

Before you can run ant there is some additional set up you will need
to do:

\begin{itemize}
\item Add the bin directory to your path. 

\item Set the {\tt ANT\_HOME} environment variable to the directory where you
installed Ant. On some operating systems the ant wrapper scripts can
guess {\tt ANT\_HOME} (Unix dialects and Windows NT/2000) - but it is better
to not rely on this behavior.

\item Optionally, set the {\tt JAVA\_HOME}
environment variable (see the Advanced
section below). This should be set to the directory where your JDK is
installed.
\end{itemize}

Note: Do not install Ant's ant.jar file into the lib/ext directory of
the JDK/JRE. Ant is an application, whilst the extension directory is
intended for JDK extensions. In particular there are security
restrictions on the classes which may be loaded by an extension.

\subsection{Optional Tasks}

Ant supports a number of optional tasks. An optional task is a task
which typically requires an external library to function. The optional
tasks are packaged together with the core Ant tasks.

The external libraries required by each of the optional tasks is
detailed in the Library Dependencies section. These external libraries
may either be placed in Ant's lib directory, where they will be picked
up automatically, or made available on the system CLASSPATH
environment variable.

\subsection{MS-Windows}

Assume Ant is installed in {\tt c:${\backslash}$ant}. 
The following sets up the environment:

\begin{verbatim}
set ANT_HOME=c:\ant
set JAVA_HOME=c:\jdk1.2.2
set PATH=%PATH%;%{\tt ANT\_HOME}%\bin
\end{verbatim}

\subsection{Unix (bash)}

Assume Ant is installed in {\tt /usr/local/ant}. 
The following sets up the environment:

\begin{verbatim}
export ANT_HOME=/usr/local/ant
export JAVA_HOME=/usr/local/jdk-1.2.2
export PATH=${PATH}:${ANT_HOME}/bin
\end{verbatim}

\subsection{Unix (csh)}

\begin{verbatim}
setenv ANT_HOME /usr/local/ant
setenv JAVA_HOME /usr/local/jdk-1.2.2
set path=( $path ANT_HOME/bin )
\end{verbatim}

\subsection{Advanced}

There are lots of variants that can be used to run Ant. What you need
is at least the following:

\begin{itemize}
\item The classpath for Ant must contain ant.jar and any jars/classes needed
for your chosen JAXP-compliant XML parser.

\item When you need JDK functionality (such as for the javac task or the
rmic task), then for JDK 1.1, the classes.zip file of the JDK must be
added to the classpath; for JDK 1.2 or JDK 1.3, tools.jar must be
added. The scripts supplied with Ant, in the bin directory, will add
the required JDK classes automatically, if the {\tt JAVA\_HOME} environment
variable is set.

\item When you are executing platform-specific applications, such as the
exec task or the cvs task, the property 
{\tt ant.home} must be set to the
directory containing where you installed Ant. Again this is set by the
Ant scripts to the value of the {\tt ANT\_HOME} environment variable.
\end{itemize}

The supplied ant shell scripts all support an 
{\tt ANT\_OPTS} environment
variable which can be used to supply extra options to ant. Some of the
scripts also read in an extra script stored in the users home
directory, which can be used to set such options. Look at the source
for your platform's invocation script for details.

\section{Building Ant}

To build Ant from source, you can either install the Ant source
distribution or checkout the ant module from CVS.

Once you have installed the source, change into the installation
directory.

Set the {\tt JAVA\_HOME} environment variable to the directory where the JDK
is installed. See Installing Ant for examples on how to do this for
your operating system.

Make sure you have downloaded any auxiliary jars required to build
tasks you are interested in. These should either be available on the
{\tt CLASSPATH} or added to the lib directory.
See Library Dependencies (section~\ref{libdepend}
for a list of jar requirements for various features. Note that this will
make the auxiliary jars available for the building of Ant only. For
running Ant you will still need to make the jars available as
described under Installing Ant.

Your are now ready to build Ant:

\begin{verbatim}
build -Ddist.dir=<directory_to_contain_Ant_distribution> dist    (Windows)

build.sh -Ddist.dir=<directory_to_contain_Ant_distribution> dist    (Unix)
\end{verbatim}
This will create a binary distribution of Ant in the directory you specified.

The above action does the following:

\begin{itemize}
\item If necessary it will bootstrap the Ant code. Bootstrapping involves
the manual compilation of enough Ant code to be able to run Ant. The
bootstrapped Ant is used for the remainder of the build steps.

\item Invokes the bootstrapped Ant with the parameters passed to the build
script. In this case, these parameters define an Ant property value
and specify the "dist" target in Ant's own build.xml file.
\end{itemize}

On most occasions you will not need to explicitly bootstrap Ant since
the build scripts do that for you. If however, the build file you are
using makes use of features not yet compiled into the bootstrapped
Ant, you will need to manually bootstrap. Run bootstrap.bat (Windows)
or bootstrap.sh (UNIX) to build a new bootstrap version of Ant.

If you wish to install the build into the current {\tt ANT\_HOME} directory,
you can use:\hfil\break
{\tt build install} (Windows)\hfil\break
{\tt build.sh install} (Unix)\hfil\break
You can avoid the lengthy Javadoc step, if desired, with: \hfil\break
{\tt build install-lite} (Windows)\hfil\break
{\tt build.sh install-lite} (Unix)\hfil\break
This will only install the bin and lib directories. 
Both the install and install-lite targets will overwrite the current
Ant version in {\tt ANT\_HOME}.

\section{Library Dependencies}
\label{libdepend}

The following libraries are needed in your 
{\tt CLASSPATH} or in the install
directory's lib directory if you are using the indicated feature. Note
that only one of the regexp libraries is needed for use with the
mappers. You will also need to install the Ant optional jar containing
the task definitions to make these tasks available. Please refer to
the Installing Ant / Optional Tasks section above.

\indent\hbox{\hskip -5.5cm}\vbox{\vskip 1mm
\vbox{\vskip -3mm
\begin{tabular}{|p{2.7 cm}|p{2.3 cm}|p{10.5 cm}|} \hline
{\bf Jar Name} & {\bf Needed for} & {\bf Available at} \\ \hline
An XSL transformer like Xalan or XSL:P &
  style task &
  {\tt http://xml.apache.org/xalan-j/index.html} for Xalan.
  XSL:P used to live at {\tt http://www.clc-marketing.com/xslp/}, but the link
  doesn't work any longer and we are not aware of a replacement site. \\ \hline

jakarta-regexp-1.2.jar &
regexp type with mappers &
{\tt jakarta.apache.org/regexp/} \\ \hline

junit.jar & junit tasks & {\tt www.junit.org} \\ \hline

xalan.jar & junitreport.task & {\tt xml.apache.org} \\ \hline

stylebook.jar & stylebook task & CVS repository of 
{\tt xml.apache.org} \\ \hline

testlet.jar & {\bf deprecated} test task &
Build from the gzip compress tar archive in 
{\tt http://avalon.apache.org/historiccvs/testlet/} \\ \hline

antlr.jar & antlr task & {\tt www.antlr.org} \\ \hline

bsf.jar & script task &
{\tt oss.software.ibm.com/developerworks/projects/bsf} \\ \hline

netrexx.jar & netrexx task &
{\tt www2.hursley.ibm.com/netrexx} \\ \hline

js.jar & javascript with script task &
{\tt www.mozilla.org/rhino} \\ \hline

jpython.jar & python with script task &
{\tt www.jpython.org} \\ \hline

jacl.jar and tcljava.jar & TCL with script task &
{\tt www.scriptics.com/java} \\ \hline

BeanShell JAR(s) & BeanShell with script task &
{\tt www.beanshell.org} \\ \hline

netcomponents.jar & ftp and telnet tasks &
{\tt www.savarese.org/oro/downloads} \\ \hline

bcel.jar & classfileset data type, JavaClassHelper 
used by the ClassConstants filter reader and optionally used by 
ejbjar for dependency determination  &
{\tt jakarta.apache.org/bcel/} \\ \hline

mail.jar & Mail task with Mime encoding, and 
the MimeMail task & {\tt http://java.sun.com/products/javamail/} \\ \hline

activation.jar & Mail task with Mime encoding, and the MimeMail task 
& {\tt http://java.sun.com/products/javabeans/glasgow/jaf.html} \\ \hline

jdepend.jar & jdepend task &
{\tt http://www.clarkware.com/software/JDepend.html} \\ \hline

\end{tabular}
}}

\section{Platform Specific Issues}

\subsection{Unix}

You should use a GNU version of tar to untar the ant source tree, if
you have downloaded this as a tar file.

\begin{itemize}
\item Ant does not preserve file permissions when a file is copied, moved or
archived. Use {\tt <chmod>} to set permissions, and when creating a tar
archive, use the mode attribute of 
{\tt <tarfileset>} to set the permissions
in the tar file.

\item Ant is not symbolic link aware in moves, deletes and when recursing
down a tree of directories to build up a list of files. Unexpected
things can happen.
\end{itemize}

\subsection{Microsoft Windows}

Windows 9x (win95, win98, win98SE and winME) has a batch file system
which does not work fully with long file names, so we recommend that
ant and the JDK are installed into directories without spaces, and
with 8.3 filenames. The Perl and Python launcher scripts do not suffer
from this limitation.

All versions of windows are usually case insensitive, although mounted
file systems (Unix drives, Clearcase views) can be case sensitive
underneath, confusing patternsets.

Ant can often not delete a directory which is open in an Explorer
window. There is nothing we can do about this short of spawning a
program to kill the shell before deleting directories.

\subsection{Apple MacOS X}

MacOS X is the first of the Apple platforms that Ant supports
completely; it is treated like any other Unix.

\subsection{Novell Netware}

To give the same level of sophisticated control as Ant's startup
scripts on other platforms, it was decided to make the main ant
startup on NetWare be via a Perl Script, "runant.pl". This is found in
the bin directory (for instance - bootstrap${\backslash}$bin
or dist${\backslash}$bin).

One important item of note is that you need to set up the following to
run ant:

\begin{itemize}
\item CLASSPATH - put ant.jar, xercesImpl.jar, xml-apis.jar and any other
needed jars on the system classpath.

\item {\tt ANT\_OPTS} - On NetWare, 
{\tt ANT\_OPTS} needs to include a parameter of the form, 
"-envCWD=ANT\_HOME", with {\tt ANT\_HOME}
being the fully expanded location of
Ant, not an environment variable. This is due to the fact that the
NetWare System Console has no notion of a current working directory.

\end{itemize}

It is suggested that you create up an ant.ncf that sets up these
parameters, and calls perl {\tt ANT\_HOME/dist/bin/runant.pl}

The following is an example of such an NCF file(assuming ant is
installed in 'sys:/apache-ant/'):

\begin{verbatim}
   envset CLASSPATH=SYS:/apache-ant/bootstrap/lib/ant.jar
   envset CLASSPATH=$CLASSPATH;SYS:/apache-ant/lib/xercesImpl.jar 
   envset CLASSPATH=$CLASSPATH;SYS:/apache-ant/lib/xml-apis.jar 
   envset CLASSPATH=$CLASSPATH;SYS:/apache-ant/lib/optional/junit.jar 
   envset CLASSPATH=$CLASSPATH;SYS:/apache-ant/bootstrap/lib/optional.jar 

   setenv ANT_OPTS=-envCWD=sys:/apache-ant 
   envset ANT_OPTS=-envCWD=sys:/apache-ant 
   setenv ANT_HOME=sys:/apache-ant/dist/lib 
   envset ANT_HOME=sys:/apache-ant/dist/lib 

   perl sys:/apache-ant/dist/bin/runant.pl 
\end{verbatim}

Ant works on JVM version 1.3 or higher. You may have some luck running
it on JVM 1.2, but serious problems have been found running Ant on JVM
1.1.7B. These problems are caused by JVM bugs that will not be fixed.

JVM 1.3 is supported on Novell NetWare versions 5.1 and higher.

\subsection{Other platforms}

Support for other platforms is not guaranteed to be complete, as
certain techniques to hide platform details from build files need to
be written and tested on every particular platform. Contributions in
this area are welcome.

\chapter{Using Ant}
\section{Writing a Simple Buildfile}

Ant's buildfiles are written in XML. Each buildfile contains one
project and at least one (default) target. Targets contain task
elements. Each task element of the buildfile can have an id attribute
and can later be referred to by the value supplied to this. The value
has to be unique. (For additional information, see the Tasks section
below.)

\section{Projects}
A project has three attributes:

\begin{tabular}{|l|p{7 cm}|c|} \hline
{\bf Attribute} & {\bf Description} & {\bf Required} \\ \hline
name      & the name of the project. & No \\ \hline
default   & the default target to use when no target is supplied. & Yes. \\ \hline
basedir   & the base directory from which all path calculations are done.
This attribute might be overridden by setting the "basedir" property 
beforehand. When this is done, it must be omitted in the project tag.
If neither the attribute nor the property have been set, 
the parent directory of the buildfile will be used. & No \\ \hline
\end{tabular}

Optionally, a description for the project can be provided as a
top-level {\tt <description>} element (see the description type).

Each project defines one or more targets. A target is a set of tasks you want to be executed. When starting Ant, you can select which target(s) you want to have executed. When no target is given, the project's default is used.

\section{Targets}

A target can depend on other targets. You might have a target for
compiling, for example, and a target for creating a distributable. You
can only build a distributable when you have compiled first, so the
distribute target depends on the compile target. Ant resolves these
dependencies.

It should be noted, however, that Ant's depends attribute only
specifies the order in which targets should be executed - it does not
affect whether the target that specifies the dependency(s) gets
executed if the dependent target(s) did not (need to) run.

Ant tries to execute the targets in the depends attribute in the order
they appear (from left to right). Keep in mind that it is possible
that a target can get executed earlier when an earlier target depends
on it:
\begin{verbatim}
<target name="A"/>
<target name="B" depends="A"/>
<target name="C" depends="B"/>
<target name="D" depends="C,B,A"/>
\end{verbatim}
Suppose we want to execute target D. From its depends attribute, you
might think that first target C, then B and then A is executed. Wrong!
C depends on B, and B depends on A, so first A is executed, then B,
then C, and finally D.

A target gets executed only once, even when more than one target
depends on it (see the previous example).

A target also has the ability to perform its execution if (or unless)
a property has been set. This allows, for example, better control on
the building process depending on the state of the system (java
version, OS, command-line property defines, etc.). To make a target
sense this property, you should add the if (or unless) attribute with
the name of the property that the target should react to. Note: Ant
will only check whether the property has been set, the value doesn't
matter. A property set to the empty string is still an existing
property. For example:
\begin{verbatim}
<target name="build-module-A" if="module-A-present"/>
<target name="build-own-fake-module-A" unless="module-A-present"/>
\end{verbatim}
In the first example, if the module-A-present property is set (to any
value), the target will be run. In the second example, if the
module-A-present property is set (again, to any value), the target
will not be run.

If no if and no unless attribute is present, the target will always be
executed.

The optional description attribute can be used to provide a one-line
description of this target, which is printed by the -projecthelp
command-line option. Targets without such a description are deemed
internal and will not be listed, unless either the -verbose or -debug
option is used.

It is a good practice to place your tstamp tasks in a so-called
initialization target, on which all other targets depend. Make sure
that target is always the first one in the depends list of the other
targets. In this manual, most initialization targets have the name
"init".

A target has the following attributes:

\begin{tabular}{|l|p{7 cm}|c|} \hline
{\bf Attribute} & {\bf Description} & {\bf Required} \\ \hline
name            & the name of the target. & Yes  \\ \hline
depends         & a comma-separated list of names of targets on which 
this target depends. & No \\ \hline
if              & the name of the property that must be set in 
order for this target to execute. & No  \\ \hline

unless          & the name of the property that must not be
set in order for this target to execute. & No  \\ \hline

description     & a short description of this target's function. & No \\ \hline
\end{tabular}

A target name can be any alphanumeric string valid in the encoding of
the XML file. The empty string "" is in this set, as is comma "," and
space " ". Please avoid using these, as they will not be supported in
future Ant versions because of all the confusion they cause. IDE
support of unusual target names, or any target name containing spaces,
varies with the IDE.

Targets beginning with a hyphen such as "-restart" are valid, and can
be used to name targets that should not be called directly from the
command line.

\section{Tasks}
A task is a piece of code that can be executed.

A task can have multiple attributes (or arguments, if you prefer). The
value of an attribute might contain references to a property. These
references will be resolved before the task is executed.

Tasks have a common structure:
\begin{verbatim}
<name attribute1="value1" attribute2="value2" ... />
\end{verbatim}
where name is the name of the task, attributeN is the attribute name, and valueN is the value for this attribute.

There is a set of built-in tasks, along with a number of optional
tasks, but it is also very easy to write your own.

All tasks share a task name attribute. The value of this attribute
will be used in the logging messages generated by Ant.

Tasks can be assigned an id attribute: 
\begin{verbatim}
<taskname id="taskID" ... />
\end{verbatim}
where taskname is the name of the task, and taskID is a unique identifier for this task. You can refer to the corresponding task object in scripts or other tasks via this name. For example, in scripts you could do: 
\begin{verbatim}
<script ... >
  task1.setFoo("bar");
</script>
\end{verbatim}
to set the foo attribute of this particular task instance. In another task (written in Java), you can access the instance via project.getReference("task1"). 
Note1: If "task1" has not been run yet, then it has not been configured (ie., no attributes have been set), and if it is going to be configured later, anything you've done to the instance may be overwritten. 

Note2: Future versions of Ant will most likely not be
backward-compatible with this behaviour, since there will likely be no
task instances at all, only proxies.

\section{Properties}

A project can have a set of properties. These might be set in the
buildfile by the property task, or might be set outside Ant. A
property has a name and a value; the name is
case-sensitive. Properties may be used in the value of task
attributes. This is done by placing the property name between "\$\{" and
"\}" in the attribute value. For example, if there is a "builddir"
property with the value "build", then this could be used in an
attribute like this: \$\{builddir\}/classes. This is resolved at run-time
as build/classes.

\section{Built-in Properties}

Ant provides access to all system properties as if they had been
defined using a {\tt <property> task}. For example, \${os.name} expands to
the name of the operating system.

For a list of system properties see the Javadoc of 
{\tt System.getProperties}. 

In addition, Ant has some built-in properties:
\begin{verbatim}
basedir             the absolute path of the project's basedir (as set
                    with the basedir attribute of <project>).
ant.file            the absolute path of the buildfile.
ant.version         the version of Ant
ant.project.name    the name of the project that is currently executing;
                    it is set in the name attribute of <project>.
ant.java.version    the JVM version Ant detected; currently it can hold
                    the values "1.1", "1.2", "1.3" and "1.4".
\end{verbatim}
\section{Example Buildfile}

\begin{verbatim}
<project name="MyProject" default="dist" basedir=".">
    <description>
        simple example build file
    </description>
  <!-- set global properties for this build -->
  <property name="src" location="src"/>
  <property name="build" location="build"/>
  <property name="dist"  location="dist"/>

  <target name="init">
    <!-- Create the time stamp -->
    <tstamp/>
    <!-- Create the build directory structure used by compile -->
    <mkdir dir="${build}"/>
  </target>

  <target name="compile" depends="init"
        description="compile the source " >
    <!-- Compile the java code from ${src} into ${build} -->
    <javac srcdir="${src}" destdir="${build}"/>
  </target>

  <target name="dist" depends="compile"
        description="generate the distribution" >
    <!-- Create the distribution directory -->
    <mkdir dir="${dist}/lib"/>

    <!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file -->
    <jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}"/>
  </target>

  <target name="clean"
        description="clean up" >
    <!-- Delete the ${build} and ${dist} directory trees -->
    <delete dir="${build}"/>
    <delete dir="${dist}"/>
  </target>
</project>
\end{verbatim}
Notice that we are declaring properties outside any target. The
{\tt <property>}, {\tt <typedef>}
and {\tt <taskdef>} tasks are special in that they can
be declared outside any target. When you do this they are evaluated
before any targets are executed. No other tasks can be declared
outside targets.  We have given some targets descriptions; this causes
the projecthelp invocation option to list them as public targets with
the descriptions; the other target is internal and not listed.

Finally, for this target to work the source in the src subdirectory
should be stored in a directory tree which matches the package
names. Check the {\tt <javac>} task for details.

\section{Token Filters}

A project can have a set of tokens that might be automatically
expanded if found when a file is copied, when the filtering-copy
behavior is selected in the tasks that support this. These might be
set in the buildfile by the filter task.

Since this can potentially be a very harmful behavior, the tokens in
the files must be of the form @token@, where token is the token name
that is set in the {\tt <filter>} task. 
This token syntax matches the syntax
of other build systems that perform such filtering and remains
sufficiently orthogonal to most programming and scripting languages,
as well as with documentation systems.

Note: If a token with the format @token@ is found in a file, but no
filter is associated with that token, no changes take place;
therefore, no escaping method is available - but as long as you choose
appropriate names for your tokens, this should not cause problems.

Warning: If you copy binary files with filtering turned on, you can
corrupt the files. This feature should be used with text files only.

\section{Path-like Structures}

You can specify PATH- and CLASSPATH-type references using both ":" and
";" as separator characters. Ant will convert the separator to the
correct character of the current operating system.

Wherever path-like values need to be specified, a nested element can
be used. This takes the general form of:
\begin{verbatim}
    <classpath>
      <pathelement path="${classpath}"/>
      <pathelement location="lib/helper.jar"/>
    </classpath>
\end{verbatim}

The location attribute specifies a single file or directory relative
to the project's base directory (or an absolute filename), while the
path attribute accepts colon- or semicolon-separated lists of
locations. The path attribute is intended to be used with predefined
paths - in any other case, multiple elements with location attributes
should be preferred.

As a shortcut, the {\tt <classpath>} tag supports path and location
attributes of its own, so:

\begin{verbatim}
    <classpath>
      <pathelement path="${classpath}"/>
    </classpath>
\end{verbatim}
can be abbreviated to:
\begin{verbatim}
    <classpath path="${classpath}"/>
\end{verbatim}

In addition, DirSets, FileSets, and FileLists can be specified via
nested {\tt <dirset>}, 
{\tt <fileset>}, and {\tt <filelist>} elements,
respectively. Note: The order in which the files building up a FileSet
are added to the path-like structure is not defined.
\begin{verbatim}
    <classpath>
      <pathelement path="${classpath}"/>
      <fileset dir="lib">
        <include name="**/*.jar"/>
      </fileset>
      <pathelement location="classes"/>
      <dirset dir="${build.dir}">
        <include name="apps/**/classes"/>
        <exclude name="apps/**/*Test*"/>
      </dirset>
      <filelist refid="third-party_jars">
    </classpath>
\end{verbatim}

This builds a path that holds the value of \$\{classpath\}, followed by
all jar files in the lib directory, the classes directory, all
directories named classes under the apps subdirectory of \$\{build.dir\},
except those that have the text Test in their name, and the files
specified in the referenced FileList.

If you want to use the same path-like structure for several tasks, you
can define them with a {\tt <path>} element at the same level as targets,
and reference them via their id attribute - see References for an
example.

A path-like structure can include a reference to another path-like
structure via nested {\tt <path>} elements:

\begin{verbatim}
    <path id="base.path">
      <pathelement path="${classpath}"/>
      <fileset dir="lib">
        <include name="**/*.jar"/>
      </fileset>
      <pathelement location="classes"/>
    </path>

    <path id="tests.path">
      <path refid="base.path"/>
      <pathelement location="testclasses"/>
    </path>
\end{verbatim}

The shortcuts previously mentioned for 
{\tt <classpath>} are also valid for
{\tt <path>}. For example:
\begin{verbatim}
    <path id="base.path">
      <pathelement path="${classpath}"/>
    </path>
\end{verbatim}
can be written as: 
\begin{verbatim}
    <path id="base.path" path="${classpath}"/>
\end{verbatim}

\section{Command-line Arguments}

Several tasks take arguments that will be passed to another process on
the command line. To make it easier to specify arguments that contain
space characters, nested arg elements can be used.

Attribute Description Required 
value a single command-line argument; can contain space characters. Exactly one of these. 
file The name of a file as a single command-line argument; will be replaced with the absolute filename of the file. 
path A string that will be treated as a path-like string as a single command-line argument; you can use ; or : as path separators and Ant will convert it to the platform's local conventions. 
line a space-delimited list of command-line arguments. 

It is highly recommended to avoid the line version when possible. Ant
will try to split the command line in a way similar to what a (Unix)
shell would do, but may create something that is very different from
what you expect under some circumstances.

Examples
\begin{verbatim}
  <arg value="-l -a"/>
\end{verbatim}
is a single command-line argument containing a space character.
\begin{verbatim}
  <arg line="-l -a"/>
\end{verbatim}
represents two separate command-line arguments.
\begin{verbatim}
  <arg path="/dir;/dir2:\dir3"/>
\end{verbatim}
is a single command-line argument with the 
value ${\backslash}$dir;${\backslash}$dir2;${\backslash}$dir3 on
DOS-based systems and /dir:/dir2:/dir3 on Unix-like systems.

\section{References}

The id attribute of the buildfile's elements can be used to refer to
them. This can be useful if you are going to replicate the same
snippet of XML over and over again - using a 
{\tt <classpath>} structure
more than once, for example.

The following example:
\begin{verbatim}
<project ... >
  <target ... >
    <rmic ...>
      <classpath>
        <pathelement location="lib/"/>
        <pathelement path="${java.class.path}/"/>
        <pathelement path="${additional.path}"/>
      </classpath>
    </rmic>
  </target>

  <target ... >
    <javac ...>
      <classpath>
        <pathelement location="lib/"/>
        <pathelement path="${java.class.path}/"/>
        <pathelement path="${additional.path}"/>
      </classpath>
    </javac>
  </target>
</project>
\end{verbatim}
could be rewritten as:
\begin{verbatim}
<project ... >
  <path id="project.class.path">
    <pathelement location="lib/"/>
    <pathelement path="${java.class.path}/"/>
    <pathelement path="${additional.path}"/>
  </path>

  <target ... >
    <rmic ...>
      <classpath refid="project.class.path"/>
    </rmic>
  </target>

  <target ... >
    <javac ...>
      <classpath refid="project.class.path"/>
    </javac>
  </target>
</project>
\end{verbatim}

All tasks that use nested elements for PatternSets, FileSets or
path-like structures accept references to these structures as well.

\chapter{Running Ant}

\section{Command Line}

If you've installed Ant as described in the Installing Ant section,
running Ant from the command-line is simple: just type ant.

When no arguments are specified, Ant looks for a build.xml file in the
current directory and, if found, uses that file as the build file and
runs the target specified in the default attribute of the 
{\tt <project>} tag. 
To make Ant use a build file other than build.xml, use the
command-line option -buildfile file, where file is the name of the
build file you want to use.

If you use the -find [file] option, Ant will search for a build file first in the current directory, then in the parent directory, and so on, until either a build file is found or the root of the filesystem has been reached. By default, it will look for a build file called build.xml. To have it search for a build file other than build.xml, specify a file argument. Note: If you include any other flags or arguments on the command line after the -find flag, you must include the file argument for the -find flag, even if the name of the build file you want to find is build.xml. 
You can also set properties on the command line. This can be done with the -Dproperty=value option, where property is the name of the property, and value is the value for that property. If you specify a property that is also set in the build file (see the property task), the value specified on the command line will override the value specified in the build file. Defining properties on the command line can also be used to pass in the value of environment 
variables - just pass -DMYVAR=\%MYVAR\% (Windows) 
or {\tt -DMYVAR=\$MYVAR} (Unix) to Ant. 
You can then access these variables inside your build file 
as {\tt \$\{MYVAR\}}. You can also access environment 
variables using the property task's environment attribute. 

Options that affect the amount of logging output by Ant are: -quiet,
which instructs Ant to print less information to the console;
-verbose, which causes Ant to print additional information to the
console; and -debug, which causes Ant to print considerably more
additional information.

It is also possible to specify one or more targets that should be
executed. When omitted, the target that is specified in the default
attribute of the project tag is used.

The -projecthelp option prints out a list of the build file's
targets. Targets that include a description attribute are listed as
"Main targets", those without a description are listed as
"Subtargets", then the "Default" target is listed.

\section{Command-line Options Summary}

\begin{verbatim}
ant [options] [target [target2 [target3] ...]]
Options:
  -help                  print this message
  -projecthelp           print project help information
  -version               print the version information and exit
  -diagnostics           print information that might be helpful to
                         diagnose or report problems.
  -quiet, -q             be extra quiet
  -verbose, -v           be extra verbose
  -debug                 print debugging information
  -emacs                 produce logging information without adornments
  -logfile <file>        use given file for log
    -l     <file>                ''
  -logger <classname>    the class which is to perform logging
  -listener <classname>  add an instance of class as a project listener
  -buildfile <file>      use given buildfile
    -file    <file>              ''
    -f       <file>              ''
  -D<property>=<value>   use value for given property
  -propertyfile <name>   load all properties from file with -D
                         properties taking precedence
  -inputhandler <class>  the class which will handle input requests
  -find <file>           search for buildfile towards the root of the
                         filesystem and use it
\end{verbatim}
For more information about -logger and -listener see Loggers and Listeners. 

For more information about -inputhandler see InputHandler. 

\subsection{Examples}

ant
runs Ant using the build.xml file in the current directory, on the
default target.

ant -buildfile test.xml
runs Ant using the test.xml file in the current directory, on the default target.

ant -buildfile test.xml dist
runs Ant using the test.xml file in the current directory, on the target called dist.

ant -buildfile test.xml -Dbuild=build/classes dist
runs Ant using the test.xml file in the current directory, on the target called dist, setting the build property to the value build/classes.

\section{Files}

The Ant wrapper script for Unix will source (read and evaluate) the file ~/.antrc before it does anything. On Windows, the Ant wrapper batch-file
invokes {\tt \%HOME\%${\backslash}$antrc\_pre.bat} at the start and
\%HOME\%${\backslash}$antrc\_post.bat at the end. 
You can use these files, for example, to set/unset environment
variables that should only be visible during the execution of Ant. See
the next section for examples.

\section{Environment Variables}

The wrapper scripts use the following environment
variables (if set):

\begin{itemize}
\item JAVACMD - full path of the Java executable. Use this to invoke a
different JVM than {\tt JAVA\_HOME}/bin/java(.exe).

\item {\tt ANT\_OPTS} - command-line arguments that should be passed to the JVM. For example, you can 
define system properties or set the maximum Java heap size here. 

\item {\tt ANT\_ARGS} - Ant command-line arguments. For example, set {\tt ANT\_ARGS} to point to a different logger, include a listener, and to include the -find flag. Note: If you include -find in {\tt ANT\_ARGS}, you should include the name of the build file to find, even if the file is called build.xml. 
\end{itemize}

\section{Cygwin Users}

The Unix launch script that come with Ant works correctly with
Cygwin. You should not have any problems launching Ant form the Cygwin
shell. It is important to note however, that once Ant is runing it is
part of the JDK which operates as a native Windows application. The
JDK is not a Cygwin executable, and it therefore has no knowledge of
the Cygwin paths, etc. In particular when using the 
{\tt <exec>} task,
executable names such as "/bin/sh" will not work, even though these
work from the Cygwin shell from which Ant was launched. You can use an
executable name such as "sh" and rely on that command being available
in the Windows path.

\section{Running Ant via Java}

If you have installed Ant in the do-it-yourself way, Ant can be started with:
\begin{verbatim}
java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]
\end{verbatim}

These instructions actually do exactly the same as the ant command.
The options and target are the same as when running Ant with the ant
command. This example assumes you have set your classpath to include:

\begin{itemize}
\item ant.jar 
\item jars/classes for your XML parser 
\item the JDK's required jar/zip files 
\end{itemize}

\chapter{Ant Tasks}

Given the large number of tasks available with Ant, it may be
difficult to get an overall view of what each task can do. The
following tables provide a short description of each task and a link
to the complete documentation.

\section{Overview of Ant Tasks}

\subsection{Archive Tasks}
\begin{supertabular}{|l|p{10cm}|}  \hline
\tablehead{Task Name & Description \\ \hline}
Task Name & Description \\ \hline
BUnzip2 & Expands a file packed using GZip or BZip2. \\ \hline
 
BZip2 & Packs a file using the GZip or BZip2 algorithm. This task does not do
any dependency checking; the output file is always generated \\ \hline
 
Cab &
Creates Microsoft CAB archive files. 
It is invoked similar to the Jar or Zip tasks. 
This task will work on Windows using the external 
cabarc tool (provided by Microsoft), which must be 
located in your executable path. \\ \hline
 
Ear & An extension of the Jar task with special treatment 
for files that should end up in an Enterprise Application archive. \\ \hline
 
GUnzip & Expands a GZip file. \\ \hline
 
GZip & GZips a set of files. \\ \hline
 
Jar & Jars a set of files. \\ \hline
 
Jlink &
{\em Deprecated}. 
Use the zipfileset and zipgroupfileset attributes of the 
Jar or Zip tasks instead. \\ \hline
 
Manifest & Creates a manifest file. \\ \hline
 
Rpm & Invokes the rpm executable to build a Linux installation file. 
This task currently only works on Linux or other Unix platforms
with RPM support. \\ \hline
 
SignJar & Signs a jar or zip file with the
javasign command-line tool. \\ \hline
 
Tar & Creates a tar archive. \\ \hline
 
Unjar & Unzips a jarfile.\\ \hline
 
Untar & Untars a tarfile. \\ \hline
 
Unwar & Unzips a warfile. \\ \hline
 
Unzip & Unzips a zipfile. \\ \hline
 
War & An extension of the Jar task with special 
treatment for files that should end up in the WEB-INF/lib, 
WEB-INF/classes, or WEB-INF directories of 
the Web Application Archive. \\ \hline
 
Zip & Creates a zipfile.\\ \hline
\end{supertabular}

\subsection{Audit/Coverage Tasks}

\begin{supertabular}{|l|p{9cm}|}  \hline
\tablehead{Task Name & Description  \\ \hline}

JDepend & Invokes the JDepend parser. This parser "traverses a set of
Java source-file directories and generates design-quality metrics for
each Java package". \\ \hline
 
JProbe & These tasks run the tools from the JProbe suite. This task was
written using JProbe Suite Server Side 3.0. \\ \hline
 
MMetrics & Computes the metrics of a set of Java source files, using the
Metamata Metrics/WebGain Quality Analyzer source-code analyzer, and
writes the results to an XML file. \\ \hline
 
Maudit & Performs static analysis on a set of Java source-code and
byte-code files, using the Metamata Metrics/WebGain Quality Analyzer
source-code analyzer. \\ \hline
\end{supertabular}

\subsection{Compile Tasks}
\begin{tabular}{|l|p{9cm}|}  \hline
Task Name & Description  \\ \hline

Depend & Determines which classfiles are out-of-date with respect to
their source, removing the classfiles of any other classes that depend
on the out-of-date classes, forcing the re-compile of the removed
classfiles. Typically used in conjunction with the Javac task. \\ \hline
 
Javac & Compiles the specified source file(s) within the running (Ant)
VM, or in another VM if the fork attribute is specified. \\ \hline
 
JspC & Runs the JSP compiler. It can be used to precompile JSP pages for
fast initial invocation of JSP pages, deployment on a server without
the full JDK installed, or simply to syntax-check the pages without
deploying them. The Javac task can be used to compile the generated
Java source. (For Weblogic JSP compiles, see the Wljspc task.) \\ \hline
 
NetRexxC & Compiles a NetRexx source tree within the running (Ant) VM. \\ \hline
 
Rmic & Runs the rmic compiler on the specified file(s). \\ \hline
 
Wljspc & Compiles JSP pages using Weblogic's JSP compiler,
weblogic.jspc. (For non-Weblogic JSP compiles, see the JspC 
task. \\ \hline
\end{tabular}

\subsection{Deployment Tasks}
\begin{tabular}{|l|p{9cm}|}  \hline
Task Name & Description  \\ \hline
ServerDeploy & Task to run a "hot" deployment tool 
for vendor-specific J2EE server.  \\ \hline
\end{tabular}

\subsection{Documentation Tasks}
\begin{tabular}{|l|p{9cm}|}  \hline
Task Name & Description  \\ \hline

Javadoc/Javadoc2 & Generates code documentation using the javadoc
tool. The Javadoc2 task is deprecated; use the Javadoc task instead. \\ \hline
 
Stylebook & Executes the Apache Stylebook documentation
generator. Unlike the command-line version of this tool, all three
arguments are required to run the Stylebook task. \\ \hline
\end{tabular}

\subsection{EJB Tasks}
\begin{tabular}{|l|p{9cm}|}  \hline
Task Name & Description  \\ \hline

EJB Tasks & (See the documentation describing the EJB tasks.) \\ \hline
\end{tabular}

\subsection{Execution Tasks}
\begin{supertabular}{|l|p{11cm}|}  \hline
\tablehead{Task Name & Description  \\ \hline}

Ant & Runs Ant on a supplied buildfile, optionally passing properties
(with possibly new values). This task can be used to build
sub-projects. \\ \hline
 
AntCall & Runs another target within the same buildfile, optionally
passing properties (with possibly new values). \\ \hline
 
Apply/ExecOn & Executes a system command. When the os attribute is
specified, the command is only executed when Ant is run on one of the
specified operating systems. \\ \hline
 
Dependset & This task compares a set of source files with a set of
target files. If any of the source files is newer than any of the
target files, all the target files are removed. \\ \hline
 
Exec & Executes a system command. When the os attribute is specified,
the command is only executed when Ant is run on one of the specified
operating systems. \\ \hline
 
Java & Executes a Java class within the running (Ant) VM, or in another
VM if the fork attribute is specified. \\ \hline
 
Parallel & A container task that can contain other Ant tasks. Each
nested task specified within the {\tt <parallel>} tag will be executed
in its own thread. \\ \hline
 
Sequential & A container task that can contain other Ant tasks. The
nested tasks are simply executed in sequence. Its primary use is to
support the sequential execution of a subset of tasks within the
{\tt <parallel>} tag. \\ \hline
 
Sleep & A task for suspending execution for a specified period of
time. Useful when a build or deployment process requires an interval
between tasks. \\ \hline
 
Waitfor & Blocks execution until a set of specified conditions become
true. This task is intended to be used with the Parallel task to
synchronize a set of processes. \\ \hline 
\end{supertabular}

\subsection{File Tasks}
\begin{supertabular}{|l|p{9cm}|}  \hline
\tablehead{Task Name & Description  \\ \hline}

Checksum & Generates a checksum for a file or set of files. This task
can also be used to perform checksum verifications. \\ \hline
 
Chmod & Changes the permissions of a file or all files inside the
specified directories. Currently, it has effect only under Unix. The
permissions are also UNIX style, like the arguments for the chmod
command. \\ \hline

Concat & Concatenates multiple files into a single one or to Ant's
logging system. \\ \hline
 
Copy & Copies a file or Fileset to a new file or directory. \\ \hline
 
Copydir & {\em Deprecated}. Use the Copy task instead. \\ \hline
 
Copyfile & {\em Deprecated}. Use the Copy task instead. \\ \hline
 
Delete & Deletes either a single file, all files and sub-directories in
a specified directory, or a set of files specified by one or more
FileSets. \\ \hline
 
Deltree & {\em Deprecated}. Use the Delete task instead. \\ \hline
 
Filter & Sets a token filter for this project, or reads multiple token
filters from a specified file and sets these as filters. Token filters
are used by all tasks that perform file-copying operations. \\ \hline
 
FixCRLF & Modifies a file to add or remove tabs, carriage returns,
linefeeds, and EOF characters. \\ \hline
 
Get & Gets a file from a URL. \\ \hline
 
Mkdir & Creates a directory. Non-existent parent directories are
created, when necessary. \\ \hline
 
Move & Moves a file to a new file or directory, or a set(s) of file(s)
to a new directory. \\ \hline
 
Patch & Applies a "diff" file to originals.\\ \hline
 
Rename & {\em Deprecated}. Use the Move task instead. \\ \hline
 
RenameExtensions & {\em Deprecated}. 
Use the Move task with a glob mapper instead. \\ \hline
 
Replace & Replace is a directory-based task for replacing the occurrence
of a given string with another string in selected file. \\ \hline
 
ReplaceRegExp & Directory-based task for replacing the occurrence of a
given regular expression with a substitution pattern in a file or set
of files. \\ \hline
 
Tempfile & Generates a name for a new temporary file and sets the
specified property to that name. \\ \hline
 
Touch & Changes the modification time of a file and possibly creates it
at the same time. \\ \hline
\end{supertabular} 

\subsection{Java2 Extensions Tasks}

\begin{tabular}{|l|p{11cm}|}  \hline
Task Name & Description  \\ \hline

Jarlib-available & Check whether an extension is present in a FileSet or
an ExtensionSet. If the extension is present, the specified property
is set. \\ \hline
 
Jarlib-display & Display the "Optional Package" and "Package
Specification" information contained within the specified jars. \\ \hline
 
Jarlib-manifest & Task to generate a manifest that declares all the
dependencies in manifest. The dependencies are determined by looking
in the specified path and searching for Extension/"Optional Package"
specifications in the manifests of the jars. \\ \hline
 
Jarlib-resolve & Try to locate a jar to satisfy an extension, and place
the location of the jar into the specified property. \\ \hline

\end{tabular}  

\subsection{Logging Tasks}
\begin{tabular}{|l|p{11cm}|}  \hline
Task Name & Description  \\ \hline
Record & Runs a listener that records the logging output of the
build-process events to a file. Several recorders can exist at the
same time. Each recorder is associated with a file. \\ \hline
\end{tabular}  

\subsection{Mail Tasks}
\begin{tabular}{|l|p{9cm}|}  \hline
Task Name & Description  \\ \hline

Mail & A task to send SMTP email. \\ \hline
 
MimeMail & {\em Deprecated}. Use the Mail task instead. \\ \hline
\end{tabular}  

\subsection{Miscellaneous Tasks}
\begin{tabular}{|l|p{11.5cm}|}  \hline
Task Name & Description  \\ \hline

Echo & Echoes text to System.out or to a file. \\ \hline
 
Fail & Exits the current build by throwing a BuildException, optionally
printing additional information. \\ \hline
 
GenKey & Generates a key in keystore. \\ \hline
 
Input & Allows user interaction during the build process by displaying a
message and reading a line of input from the console. \\ \hline
 
Script & Executes a script in a BSF-supported language. \\ \hline
 
Sound & Plays a sound file at the end of the build, according to whether
the build failed or succeeded. \\ \hline
 
Splash & Displays a splash screen. \\ \hline
 
Sql & Executes a series of SQL statements via JDBC to a
database. Statements can either be read in from a text file using the
src attribute, or from between the enclosing SQL tags. \\ \hline
 
Taskdef & Adds a task definition to the current project, such that this
new task can be used in the current project. \\ \hline
 
TStamp & Sets the DSTAMP, TSTAMP, and TODAY properties in the current
project, based on the current date and time. \\ \hline
 
Typedef & Adds a data-type definition to the current project, such that
this new type can be used in the current project. \\ \hline
 
XmlValidate & Checks that XML files are valid (or only
well-formed). This task uses the XML parser that is currently used by
Ant by default, but any SAX1/2 parser can be specified, if needed. \\ \hline
 
\end{tabular}  

\subsection{.NET Tasks}

\begin{tabular}{|l|p{11cm}|}  \hline
Task Name & Description  \\ \hline
.NET Tasks & (See the documentation describing the .NET tasks.) \\ \hline
 
\end{tabular}  

\subsection{Pre-process Tasks}

\begin{supertabular}{|l|p{11cm}|}  \hline
\tablehead{\hline Task Name & Description  \\ \hline}

ANTLR & Invokes the ANTLR Translator generator on a grammar file. \\ \hline
 
AntStructure & Generates a DTD for Ant buildfiles that contains
information about all tasks currently known to Ant. \\ \hline
 
IContract & Instruments Java classes using the iContract DBC
preprocessor. This task can generate a properties file for iControl, a
graphical user interface that lets you turn on/off assertions. \\ \hline
 
JavaCC & Invokes the JavaCC compiler-compiler on a grammar file. \\ \hline
 
Javah & Generates JNI headers from a Java class. \\ \hline
 
JJTree & Invokes the JJTree preprocessor for the JavaCC
compiler-compiler. It inserts parse-tree building actions at various
places in the JavaCC source that it generates. The output of JJTree is
run through JavaCC to create the parser. This task only invokes JJTree
if the grammar file is newer than the generated JavaCC file. \\ \hline
 
MParse & Invokes the Metamata MParse compiler-compiler on a grammar file. \\ \hline
 
Native2Ascii & Converts files from native encodings to ASCII with
escaped Unicode. A common usage is to convert source files maintained
in a native operating system encoding to ASCII, prior to compilation. \\ \hline
 
Translate & Identifies keys in files, delimited by special tokens, and
translates them with values read from resource bundles. \\ \hline
 
Xslt/Style & Processes a set of documents via XSLT. \\ \hline
 
\end{supertabular}  

\subsection{Property Tasks}
\begin{tabular}{|l|p{11cm}|}  \hline
Task Name & Description  \\ \hline

Available & Sets a property if a specified file, directory, class in the
classpath, or JVM system resource is available at runtime. \\ \hline
 
Basename & Sets a property to the last element of a specified path.  \\ \hline
 
BuildNumber & Task that can be used to track build numbers.  \\ \hline
 
Condition & Sets a property if a certain condition holds true - this is
a generalization of Available and Uptodate. \\ \hline
 
Dirname & Sets a property to the value of the specified file up to, but
not including, the last path element. \\ \hline
 
Echoproperties &  Lists the current properties. \\ \hline
 
LoadFile &  Loads a file into a property. \\ \hline
 
LoadProperties & Load a file's contents as Ant properties. This task is
equivalent to using {\tt <property file="..."/>} except that it supports
nested {\tt <filterchain>} elements, and it cannot be specified outside a
target. \\ \hline
 
PathConvert & Converts a nested path, path reference, filelist
reference, or fileset reference to the form usable on a specified
platform and/or to a list of items separated by the specified
separator and stores the result in the specified property. \\ \hline
 
Property & Sets a property (by name and value), or set of properties
(from a file or resource) in the project. \\ \hline
 
PropertyFile & Creates or modifies property files. Useful when wanting
to make unattended modifications to configuration files for
application servers and applications. Typically used for things such
as automatically generating a build number and saving it to a build
properties file, or doing date manipulation. \\ \hline
 
Uptodate & Sets a property if a given target file is newer than a set of
source files. \\ \hline
 
XmlProperty & Loads property values from a valid XML file. \\ \hline
 
\end{tabular}  

\subsection{Remote Tasks}
\begin{tabular}{|l|p{11cm}|}  \hline
Task Name & Description  \\ \hline

FTP & Implements a basic FTP client that can send, receive, list, and
delete files, and create directories. \\ \hline
 
Telnet & Task to automate a remote telnet session. This task uses nested
{\tt <read>} and {\tt <write>} tags to indicate strings to wait for and specify
text to send. \\ \hline
 
setproxy & Sets Java's web proxy properties, so that tasks and code run
in the same JVM can have through-the-firewall access to remote web 
sites. \\ \hline 
\end{tabular}  

\subsection{SCM Tasks}
\begin{tabular}{|l|p{7.5cm}|}  \hline
Task Name & Description  \\ \hline

Cvs & Handles packages/modules retrieved from a CVS repository. \\ \hline
 
CvsChangeLog & Generates an XML report of the changes recorded in a CVS
repository. \\ \hline
 
CVSPass & Adds entries to a .cvspass file. Adding entries to this file
has the same affect as a cvs login command. \\ \hline
 
CvsTagDiff & Generates an XML-formatted report file of the changes
between two tags or dates recorded in a CVS repository. \\ \hline
 
ClearCase & Tasks to perform the ClearCase cccheckin, cccheckout,
ccuncheckout, and ccupdate commands. \\ \hline
 
Continuus/Synergy & Tasks to perform the Continuus ccmcheckin,
ccmcheckout, ccmcheckintask, ccmreconfigure, and ccmcreateTask
commands. \\ \hline
 
Microsoft Visual SourceSafe &
Tasks to perform the Visual SourceSafe vssget, vsslabel, vsshistory,
vsscheckin, vsscheckout, vssadd, vsscp, and vsscreate commands. \\ \hline
 
Perforce & Tasks to perform the Perforce p4sync, p4change, p4edit,
p4submit, p4have, p4label, p4counter, p4reopen, p4revert, and p4add
commands. \\ \hline
 
Pvcs & Allows the user extract the latest edition of the source code
from a PVCS repository. \\ \hline
 
SourceOffSite & Tasks to perform the SourceOffSite sosget, soslabel,
soscheckin, and soscheckout commands. \\ \hline
 
StarTeam & Tasks to perform the StarTeam stcheckout, stcheckin, stlabel,
and stlist commands. The Starteam task is deprecated; use STCheckout
instead. \\ \hline
 
\end{tabular}  

\subsection{Testing Tasks}
\begin{tabular}{|l|p{8.5cm}|}  \hline
Task Name & Description  \\ \hline

Junit & Runs tests from the Junit testing framework. This task has been
tested with JUnit 3.0 up to JUnit 3.7; it won't work with versions
prior to JUnit 3.0. \\ hline
 
JunitReport & Merges the individual XML files generated by the Junit
task and applies a stylesheet on the resulting merged document to
provide a browsable report of the testcases results. \\ \hline
 
Test & Executes a unit test in the org.apache.testlet framework. \\ \hline 
\end{tabular}  

\subsection{Visual Age for Java Tasks}

\begin{tabular}{|l|p{6.5cm}|}  \hline
Task Name & Description  \\ \hline

Visual Age for Java Tasks & (See the documentation describing the Visual
Age for Java tasks.) \\ \hline
\end{tabular}   

\section{Core Tasks}

\subsection{Ant}
\subsubsection{Description}

Runs Ant on a supplied buildfile. This can be used to build subprojects.

When the antfile attribute is omitted, the file "build.xml" in the
supplied directory (dir attribute) is used.

If no target attribute is supplied, the default target of the new
project is used.

By default, all of the properties of the current project will be
available in the new project. Alternatively, you can set the
inheritAll attribute to false and only "user" properties (i.e., those
passed on the command-line) will be passed to the new project. In
either case, the set of properties passed to the new project will
override the properties that are set in the new project (See also the
property task).

You can also set properties in the new project from the old project by
using nested property tags. These properties are always passed
regardless of the setting of inheritAll. This allows you to
parameterize your subprojects.

References to data types can also be passed to the new project, but by
default they are not. If you set the inheritrefs attribute to true,
all references will be copied, but they will not override references
defined in the new project.

Nested {\tt <reference>} elements can also be used to copy references from
the calling project to the new project, optionally under a different
id. References taken from nested elements will override existing
references in the new project.

Inherited references are not available to top level tasks of the child project.

\subsubsection{Parameters}
\begin{tabular}{|l|p{8cm}|c|} \hline
Attribute      & Description     & Required \\ \hline
antfile        & the buildfile to use. Defaults to "build.xml". 
                 This file is expected to be a filename relative to 
                 the dir attribute given.  & No \\ \hline

    dir        &  the directory to use as a basedir for the new Ant project. 
                  Defaults to the current project's basedir, 
                  unless inheritall has been set to false, 
                  in which case it doesn't have a default value. 
                  This will override the basedir setting of the called project.  & No \\ \hline
   target      &  the target of the new Ant project that should be executed. 
                  Defaults to the new project's default target.  & No \\ \hline
    output     &  Filename to write the ant output to. 
                  This is relative to the value of the dir attribute if
                  it has been set or to the base directory of the current
                  project otherwise. & No  \\ \hline
   inheritAll  &  If true, pass all properties to the new Ant project. 
                  Defaults to true. &  No  \\ \hline
   inheritRefs &  If true, pass all references to the new Ant project. 
                  Defaults to false.  & No \\ \hline
\end{tabular}

\subsubsection{Parameters specified as nested elements}

{\bf property}\hfil\break

See the description of the property task. Note that the refid
attribute points to a reference in the calling project, not in the new one.

{\bf reference}\hfil\break

Used to chose references that shall be copied into the new project,
optionally changing their id.

\begin{tabular}{|l|p{5cm}|c|} \hline
Attribute      & Description     & Required \\ \hline
refid &  The id of the reference in the calling project.  & Yes  \\ \hline
   torefid & The id of the reference in the new project.  &
               No, defaults to the value of refid. \\ \hline
\end{tabular}

\subsubsection{Basedir of the new project}

The basedir value of the new project is affected by the two attributes
dir and inheritall, see the following table for details:

\begin{tabular}{|l|c|p{7cm}|} \hline
dir  attribute &  inheritAll attribute &  new project's basedir \\ \hline
    value provided &  true &  value of dir attribute \\ \hline
    value provided &  false &  value of dir attribute \\ \hline
    omitted & true &  basedir of calling project 
                      (the one whose build file contains the {\tt <ant>} task). \\ \hline
    omitted & false & basedir attribute of the <project> element of the new project \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
  <ant antfile="subproject/subbuild.xml" dir="subproject" target="compile"/>

  <ant dir="subproject"/>

  <ant antfile="subproject/property_based_subbuild.xml">
    <property name="param1" value="version 1.x"/>
    <property file="config/subproject/default.properties"/>
  </ant>

  <ant inheritAll="false" antfile="subproject/subbuild.xml">
    <property name="output.type" value="html"/>
  </ant>
\end{verbatim}
The build file of the calling project defines some {\tt <path>} elements like this:
\begin{verbatim}
  <path id="path1">
    ...
  </path>
  <path id="path2">
    ...
  </path>
\end{verbatim}
and the called build file (subbuild.xml) also defines a {\tt <path>} with the
id path1, but path2 is not defined:
\begin{verbatim}
  <ant antfile="subbuild.xml" inheritrefs="true"/>
\end{verbatim}
will not override subbuild's definition of path1, but make the
parent's definition of path2 available in the subbuild.
\begin{verbatim}
  <ant antfile="subbuild.xml"/>
\end{verbatim}
as well as
\begin{verbatim}
  <ant antfile="subbuild.xml" inheritrefs="false"/>
\end{verbatim}
will neither override path1 nor copy path2.
\begin{verbatim}
  <ant antfile="subbuild.xml" inheritrefs="false">
    <reference refid="path1"/>
  </ant>
\end{verbatim}
will override subbuild's definition of path1.
\begin{verbatim}
  <ant antfile="subbuild.xml" inheritrefs="false">
    <reference refid="path1" torefid="path2"/>
  </ant>
\end{verbatim}
will copy the parent's definition of path1 into the new project using the id path2

\subsection{AntCall}
\subsubsection{Description}

Call another target within the same build-file optionally specifying
some properties (param's in this context)

By default, all of the properties of the current project will be
available in the new project. Alternatively, you can set the
inheritAll attribute to false and only "user" properties (i.e., those
passed on the command-line) will be passed to the new project. In
either case, the set of properties passed to the new project will
override the properties that are set in the new project (See also the
property task).

You can also set properties in the new project from the old project by
using nested param tags. These properties are always passed regardless
of the setting of inheritAll. This allows you to parameterize your
subprojects.

Nested {\tt <reference>} elements can be used to copy references from the
calling project to the new project, optionally under a different id.
References taken from nested elements will override existing
references in the new project.

When a target is invoked by antcall, all of its dependent targets will
also be called within the context of any new parameters. For example.
if the target "doSomethingElse" depended on the target "init", then
the antcall of "doSomethingElse" will call "init" during the call. Of
course, any properties defined in the antcall task or inherited from
the calling target will be fixed and not overridable in the init task
-or indeed in the "doSomethingElse" task.

\subsubsection{Parameters}
\begin{tabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
target & The target to execute. & Yes \\ \hline
inheritAll & If true, pass all properties to the new Ant project. Defaults to true. & No \\ \hline
inheritRefs & If true, pass all references to the new Ant project. Defaults to false. & No \\ \hline
\end{tabular}

\subsubsection{Note on inheritRefs}

{\tt <antcall>} will not override existing references, even if you set
inheritRefs to true. As the called build files is the same build file
as the calling one, this means it will not override any reference set
via an id attribute at all. The only references that can be inherited
by the child project are those defined by nested {\tt <reference>} elements
or references defined by tasks directly (not using the id attribute).

Inherited references are not available to top level tasks of the child project.

\subsubsection{Parameters specified as nested elements}

{\bf param}\hfil\break

Specifies the properties to set before running the specified target.
See property for usage guidelines.  

{\bf reference}\hfil\break

Used to chose references that shall be copied into the new project,
optionally changing their id.

\begin{tabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
refid     & The id of the reference in the calling project. & Yes \\ \hline
torefid   & The id of the reference in the new project. & No, defaults to the value of refid. \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
  <target name="default">
    <antcall target="doSomethingElse">
      <param name="param1" value="value"/>
    </antcall>
  </target>

  <target name="doSomethingElse">
    <echo message="param1=${param1}"/>
  </target>
\end{verbatim}
Will run the target 'doSomethingElse' and echo 'param1=value'.
\begin{verbatim}
  <antcall ... >
    <reference refid="path1" torefid="path2"/>
  </antcall>
\end{verbatim}
will copy the parent's definition of path1 into the new project using the id path2.

\subsection{AntStructure}
\subsubsection{Description}
Generates a DTD for Ant buildfiles which contains information about
all tasks currently known to Ant.

Note that the DTD generated by this task is incomplete, you can always
add XML entities using {\tt <taskdef>} or {\tt <typedef>}. See here for a way to
get around this problem.

This task doesn't know about required attributes, all will be listed as {\tt \#}IMPLIED.

\subsubsection{Parameters}
\begin{tabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
output & file to write the DTD to & Yes \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
<antstructure output="project.dtd"/>
\end{verbatim}

\subsection{Apply/{\em ExecOn}}

{\em The name execon is deprecated and only kept for backwards compatibility.}

\subsubsection{Description}

Executes a system command. When the os attribute is specified, then
the command is only executed when Ant is run on one of the specified
operating systems.

The files and/or directories of a number of FileSets are passed as
arguments to the system command.

If you specify a nested mapper and the dest attribute, the timestamp
of each source file is compared to the timestamp of a target file
which is defined by the nested mapper element and searched for in the
given dest.

At least one fileset is required, and you must not specify more than one mapper.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{2.2cm}|} \hline
\tablehead{Attribute      & Description     & Required \\ \hline}
Attribute      & Description     & Required \\ \hline
executable &  the command to execute without any command line arguments.  & Yes \\ \hline
dest & the directory where the <apply> expects the target files will be placed 
by the command, when it is executed. & Yes, if you specify a nested mapper \\ \hline
dir & the directory in which the command should be executed. & No \\ \hline
relative & whether the filenames should be passed on the command 
line as absolute or relative pathnames (relative to the base directory of the corresponding fileset for source files or the dest attribute for target files). & No, default is false \\ \hline
os & list of Operating Systems on which the command may be executed. & No \\ \hline
output & the file to which the output of the command should be redirected. & No \\ \hline
append & whether output should be appended to or overwrite an existing file. 
   Defaults to false. If you set parallel to false, you will probably want to
   set this one to true. & No \\ \hline
outputproperty & the name of a property in which the output of the command should be stored. & No \\ \hline
resultproperty & the name of a property in which the return code of the command should be stored. Only of interest if failonerror=false. If you set parallel to false, only the result of the first execution will be stored. & No \\ \hline
timeout & Stop the command if it doesn't finish within the specified time (given in milliseconds). & No \\ \hline
failonerror & Stop the buildprocess if the command exits with a returncode other than 0. & No \\ \hline
failifexecutionfails & Stop the build if we can't start the program. Defaults to true. & No \\ \hline
skipemptyfilesets & Don't run the command, if no source files have been found or are newer than their corresponding target files. & No, default is false \\ \hline
parallel & Run the command only once, appending all files as arguments. If false, command will be executed once for every file. Defaults to false. & No \\ \hline
type & One of file, dir or both. If set to file, only the names of plain files will be sent to the command. If set to dir, only the names of directories are considered. & No, default is file \\ \hline
newenvironment & Do not propagate old environment when new environment variables are specified. & No, default is false \\ \hline
vmlauncher & Run command using the Java VM's execution facilities where available. If set to false the underlying OS's shell, either directly or through the antRun scripts, will be used. Under some operating systems, this gives access to facilities not normally available through the VM including, under Windows, being able to execute scripts, rather than their associated interpreter. If you want to specify the name of the executable as a relative path to the directory given by the dir attribute, it may become necessary to set vmlauncher to false as well. & No, default is true \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf fileset}\hfil\break

You can use any number of nested {\tt <fileset>} elements to define the
files for this task and refer to {\tt <fileset>}s defined elsewhere.

{\bf arg}\hfil\break

Command line arguments should be specified as nested {\tt <arg>} elements.
See Command line arguments.

{\bf srcfile}\hfil\break

By default the file names of the source files will be added to the end
of the command line. If you need to place it somewhere different, use
a nested {\tt <srcfile>} element between your <arg> elements to mark the
insertion point.

{\bf targetfile}\hfil\break

{\tt <targetfile>} is similar to {\tt <srcfile>} and marks the position of the
target filename on the command line. If omitted, the target filenames
will not be added to the command line at all. This element can only be
specified, if you also define a nested mapper and the dest attribute.

{\bf env}\hfil\break

It is possible to specify environment variables to pass to the system
command via nested {\tt <env>} elements. See the description in the section
about exec

{\bf Examples}\hfil\break
\begin{verbatim}
<apply executable="ls">
  <arg value="-l"/>
  <fileset dir="/tmp">
    <patternset>
      <exclude name="**/*.txt"/>
    </patternset>
  </fileset>
  <fileset refid="other.files"/>
</apply>
\end{verbatim}
invokes ls -l, adding the absolute filenames of all files below /tmp
not ending in .txt and all files of the FileSet with id other.files to
the command line.
\begin{verbatim}
<apply executable="somecommand" parallel="false">
  <arg value="arg1"/>
  <srcfile/>
  <arg value="arg2"/>
  <fileset dir="/tmp"/>
</apply>
\end{verbatim}
invokes somecommand arg1 SOURCEFILENAME arg2 for each file in /tmp
replacing SOURCEFILENAME with the absolute filename of each file in
turn. If parallel had been set to true, SOURCEFILENAME would be
replaced with the absolute filenames of all files separated by spaces.
\begin{verbatim}
<apply executable="cc" dest="src/C" parallel="false">
  <arg value="-c"/>
  <arg value="-o"/>
  <targetfile/>
  <srcfile/>
  <fileset dir="src/C" includes="*.c"/>
  <mapper type="glob" from="*.c" to="*.o"/>
</apply>
\end{verbatim}
invokes {\tt cc -c -o TARGETFILE SOURCEFILE} for each .c file that is newer
than the corresponding .o, replacing TARGETFILE with the absolute
filename of the .o and SOURCEFILE with the absolute name of the {\tt .c} file.

\subsection{Available}

\subsubsection{Description}

Sets a property if a resource is available at runtime. This resource
can be a file, a directory, a class in the classpath, or a JVM system resource.

If the resource is present, the property value is set to true by
default; otherwise, the property is not set. You can set the value to
something other than the default by specifying the value attribute.

Normally, this task is used to set properties that are useful to avoid
target execution depending on system parameters.

\subsubsection{Parameters}
\begin{supertabular}{|l|p{7cm}|c|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
property & The name of the property to set. & Yes \\ \hline
value & The value to set the property to. Defaults to "true". & No \\ \hline
classname & The class to look for in the classpath. & Yes \\ \hline
file & The file to look for. & Yes \\ \hline
resource & The resource to look for in the JVM. & Yes \\ \hline
classpath & The classpath to use when looking up classname or resource. & No \\ \hline
filepath & The path to use when looking up file. & No \\ \hline
classpathref & The classpath to use, given as a reference to a path defined elsewhere. & No \\ \hline
type & The type of file to look for, either a directory (type="dir") or a file (type="file"). If not set, the property will be set if the name specified in the file attribute exists as either a file or a directory. & No \\ \hline
ignoresystemclasses & Ignore Ant's runtime classes, using only the specified classpath. Only affects the "classname" attribute. Defaults to "false" & No \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf classpath}\hfil\break

Available's classpath attribute is a path-like structure and can also
be set via a nested {\tt <classpath>} element.

{\bf filepath}\hfil\break

Available's filepath attribute is a path-like structure and can also
be set via a nested {\tt <filepath>} element.

\subsubsection{Examples}
\begin{verbatim}
  <available classname="org.whatever.Myclass" property="Myclass.present"/>
\end{verbatim}  
 sets the Myclass.present property to the value "true" if the class
org.whatever.Myclass is found in Ant's classpath.
\begin{verbatim}
<property name="jaxp.jar" value="./lib/jaxp11/jaxp.jar"/>
<available file="${jaxp.jar}" property="jaxp.jar.present"/>
\end{verbatim}
sets the jaxp.jar.present property to the value "true" if the file
./lib/jaxp11/jaxp.jar is found.
\begin{verbatim}
<available file="/usr/local/lib" type="dir" property="local.lib.present"/>
\end{verbatim}
sets the local.lib.present property to the value "true" if the
directory /usr/local/lib is found.
\begin{verbatim}
...in project ...
<property name="jaxp.jar" value="./lib/jaxp11/jaxp.jar"/>
<path id="jaxp" location="${jaxp.jar}"/>
...in target ...
<available classname="javax.xml.transform.Transformer" 
  classpathref="jaxp" property="jaxp11.present"/>
\end{verbatim}
sets the jaxp11.present property to the value "true" if the class
javax.xml.transform.Transformer is found in the classpath referenced
by jaxp (in this case, ./lib/jaxp11/jaxp.jar).
\begin{verbatim}
<available property="have.extras" resource="extratasks.properties">
  <classpath>
    <pathelement location="/usr/local/ant/extra.jar/>
  </classpath>
</available>
\end{verbatim}
sets the have.extras property to the value "true" if the resource-file
extratasks.properties is found.

\subsection{Basename}

\subsubsection{Description}

Task to determine the basename of a specified file, optionally minus a
specified suffix.

When this task executes, it will set the specified property to the
value of the last path element of the specified file. If file is a
directory, the basename will be the last directory element. If file is
a full-path, relative-path, or simple filename, the basename will be
the simple file name, without any directory elements.

\subsubsection{Parameters}
\begin{tabular}{|l|p{7cm}|c|} \hline
Attribute & Description & Required \\ \hline
file & The path to take the basename of. & Yes \\ \hline
property & The name of the property to set. & Yes \\ \hline
suffix & The suffix to remove from the resulting basename (specified either with or without the "."). & No \\ \hline
\end{tabular}

\hfil\break

\subsubsection{Examples}

\begin{verbatim}  
  <basename property="jar.filename" file="${lib.jarfile}"/>
\end{verbatim}  
will set jar.filename to myjar.jar, 
if lib.jarfile is defined as either a full-path filename 
(eg., /usr/local/lib/myjar.jar), a relative-path 
filename (eg., lib/myjar.jar), or a simple filename (eg., myjar.jar).
\begin{verbatim}  
  <basename property="cmdname" file="D:/usr/local/foo.exe" suffix=".exe"/>
\end{verbatim}  
will set cmdname to foo.
\begin{verbatim}  
  <property environment="env"/>
  <basename property="temp.dirname" file="${env.TEMP}"/>
\end{verbatim}  
will set temp.dirname to the last directory element of the path
defined for the TEMP environment variable.

\subsection{BuildNumber}

\subsubsection{Description}

This is a basic task that can be used to track build numbers.

It will first attempt to read a build number from a file (by default,
build.number in the current directory), then set the property
build.number to the value that was read in (or to 0, if no such
value). It will then increment the number by one and write it back out
to the file. (See the PropertyFile task if you need finer control over
things such as the property name or the number format.)

\subsubsection{Parameters}
\begin{tabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
file & The file to read and write the 
build number from/to. & No; defaults to "build.number" \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
  <buildnumber/>
\end{verbatim}
Read, increment, and write a build number to the default file, build.number.
\begin{verbatim}
  <buildnumber file="mybuild.number"/>
\end{verbatim}
Read, increment, and write a build number to the file mybuild.number.

\subsection{BUnzip2}

\subsubsection{Description}
Expands a file packed using GZip or BZip2.

If dest is a directory the name of the destination file is the same as
src (with the ".gz" or ".bz2" extension removed if present). If dest
is omitted, the parent dir of src is taken. The file is only expanded
if the source file is newer than the destination file, or when the
destination file does not exist.

\subsubsection{Parameters}

\begin{tabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
src & the file to expand. & Yes \\ \hline
dest & the destination file or directory. & No \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
<gunzip src="test.tar.gz"/>
\end{verbatim}
expands test.tar.gz to test.tar
\begin{verbatim}
<bunzip2 src="test.tar.bz2"/>
\end{verbatim}
expands test.tar.bz2 to test.tar
\begin{verbatim}
<gunzip src="test.tar.gz" dest="test2.tar"/>
\end{verbatim}
expands test.tar.gz to test2.tar
\begin{verbatim}
<gunzip src="test.tar.gz" dest="subdir"/>
\end{verbatim}
expands test.tar.gz to subdir/test.tar (assuming subdir is a directory).

\subsection{BZip2}
\subsubsection{Description}

Packs a file using the GZip or BZip2 algorithm. The output file is
only generated if it doesn't exist or the source file is newer.

\subsubsection{Parameters}
\begin{tabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
src & the file to gzip/bzip. & Yes \\ \hline
zipfile & the destination file. & Yes \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
<gzip src="test.tar" zipfile="test.tar.gz"/>

<bzip2 src="test.tar" zipfile="test.tar.bz2"/>
\end{verbatim}

\subsection{Checksum}

\subsubsection{Description}

Generates checksum for files. This task can also be used to perform
checksum verifications.

\subsubsection{Parameters}
\subsubsection{Parameters}
\begin{supertabular}{|l|p{6cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}

file & The file to generate checksum for. & One of either file or at
least one nested fileset element. \\ \hline

algorithm & Specifies the algorithm to be used to compute the
checksum. Defaults to "MD5". Other popular algorithms like "SHA" may
be used as well. & No \\ \hline

provider & Specifies the provider of the algorithm. & No \\ \hline

fileext & The generated checksum file's name will be the original
filename with "." and fileext added to it. Defaults to the algorithm
name being used. & No \\ \hline

property & This attribute can mean two different things, it depends on
the presence of the verifyproperty attribute.
{\bf If you don't set the verifyproperty attribute}, 
property specifies the name of the property to be set with the generated
checksum value.
{\bf If you set the verifyproperty attribute}, property specifies the checksum you
expect to be generated (the checksum itself, not a name of a property
containing the checksum).
This cannot be specified when fileext is being used or when the number
of files for which checksums is to be generated is greater than 1. &
No \\ \hline

forceoverwrite & Overwrite existing files even if the destination
files are newer. Defaults to "no". & No \\ \hline

verifyproperty & Specifies the name of the property to be set with
"true" or "false" depending upon whether the generated checksum
matches the existing checksum. When this is set, the generated
checksum is not written to a file or property, but rather, the content
of the file or property is used to check against the generated
checksum. & No \\ \hline

readbuffersize & The size of the buffer )in bytes) to use when reading
a file. Defaults to "8192" - you may get a better performance on big
files if you increase this value. & No \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf fileset}\hfil\break

FileSets are used to select files to generate checksums for.

\subsubsection{Examples}

{\bf Example 1}\hfil\break

\begin{verbatim}
<checksum file="foo.bar"/>
\end{verbatim}
Generates a MD5 checksum for foo.bar and 
stores the checksum in the destination file foo.bar.MD5. foo.bar.MD5 is 
overwritten only if foo.bar is newer than itself.

{\bf Example 2}\hfil\break

\begin{verbatim}
<checksum file="foo.bar" forceOverwrite="yes"/>
\end{verbatim}
Generates a MD5 checksum for foo.bar and stores the checksum in
foo.bar.MD5. If foo.bar.MD5 already exists, it is overwritten.

{\bf Example 3}\hfil\break
\begin{verbatim}
<checksum file="foo.bar" property="foobarMD5"/>
\end{verbatim}
Generates a MD5 checksum for foo.bar and stores it in the Project Property foobarMD5.

{\bf Example 4}\hfil\break
\begin{verbatim}
<checksum file="foo.bar" verifyProperty="isMD5ok"/>
\end{verbatim}
Generates a MD5 checksum for foo.bar, compares it against foo.bar.MD5
and sets isMD5ok to either true or false, depending upon the result.

{\bf Example 5}\hfil\break
\begin{verbatim}
<checksum file="foo.bar" algorithm="SHA" fileext="asc"/>
\end{verbatim}
Generates a SHA checksum for foo.bar and stores the checksum in the
destination file foo.bar.asc. foo.bar.asc is overwritten only if
foo.bar is newer than itself.

{\bf Example 6}\hfil\break
\begin{verbatim}
<checksum file="foo.bar" property="${md5}" verifyProperty="isEqual"/>
\end{verbatim}
Generates a MD5 checksum for foo.bar, compares it against the value of
the property md5, and sets isEqual to either true or false, depending
upon the result.

{\bf Example 7}\hfil\break
\begin{verbatim}
<checksum>
  <fileset dir=".">
    <include name="foo*"/>
  </fileset>
</checksum>
\end{verbatim}
Works just like Example 1, but generates a .MD5 file for every file
that begins with the name foo.

{\bf Example 8}\hfil\break
\begin{verbatim}
<condition property="isChecksumEqual">
  <checksum>
    <fileset dir=".">
      <include name="foo.bar"/>
    </fileset>
  </checksum>
</condition>
\end{verbatim}
Works like Example 4, but only sets isChecksumEqual to true, if the
checksum matches - it will never be set to false. This example
demonstrates use with the Condition task.

Note: When working with more than one file, if condition and/or
verifyproperty is used, the result will be true only if the checksums
matched correctly for all files being considered.

\subsection{Chmod}
\subsubsection{Description}

Changes the permissions of a file or all files inside specified
directories. Right now it has effect only under Unix. The permissions
are also UNIX style, like the argument for the chmod command.

See the section on directory based tasks, on how the
inclusion/exclusion of files works, and how to write patterns.

This task holds an implicit FileSet and supports all of FileSet's
attributes and nested elements directly. More FileSets can be
specified using nested <fileset> elements.

\subsubsection{Parameters}

\begin{tabular}{|p{3cm}|p{6cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline

\begin{tabular}{p{3cm}}
file \\ \hline
dir \\
\end{tabular}

&
\begin{tabular}{p{5.5cm}}
the file or single directory of which the permissions must be changed. \\ \hline
the directory which holds the files whose permissions must be changed. \\
\end{tabular}

& exactly one of the two or nested {\tt <fileset>} elements. \\ \hline

perm & the new permissions. & Yes \\ \hline

includes & comma- or space-separated list of patterns of files that
must be included. & No \\ \hline

excludes & comma- or space-separated list of patterns of files that must be 
excluded. No files (except default excludes) are excluded when omitted. & No \\ \hline

defaultexcludes & indicates whether default excludes should be used or 
not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline

parallel & process all specified files using a single chmod command. Defaults to true. & No \\ \hline

type & One of file, dir or both. If set to file, only the permissions of plain files are going to be changed. If set to dir, only the directories are considered. & No, default is file \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
<chmod file="${dist}/start.sh" perm="ugo+rx"/>
\end{verbatim}
makes the "start.sh" file readable and executable for anyone on a UNIX system.
\begin{verbatim}
    <chmod dir="${dist}/bin" perm="ugo+rx" includes="**/*.sh"/>
\end{verbatim}
makes all ".sh" files below \$\{dist\}/bin readable and executable for anyone on a UNIX system.
\begin{verbatim}
<chmod perm="g+w">
  <fileset dir="shared/sources1">
    <exclude name="**/trial/**"/>
  </fileset>
  <fileset refid="other.shared.sources"/>
</chmod>
\end{verbatim}
makes all files below shared/sources1 (except those below any
directory named trial) writable for members of the same group on a
UNIX system. In addition all files belonging to a FileSet with id
other.shared.sources get the same permissions.

\subsection{Concat}

\subsubsection{Description}

Concatenates a file, or a series of files, to a single file or the
console. The destination file will be created if it does not exist,
though the the append attribute may be used to alter this behavior.

FileSets and/or FileLists are used to select which files are to be
concatenated. There is no singular 'file' attribute to specify a
single file to cat -- a fileset or filelist must also be used in these
cases.

\subsubsection{Parameters}
\begin{tabular}{|l|p{9cm}|c|} \hline
Attribute & Description & Required \\ \hline
destfile & The destination file for the concatenated stream. If not specified the console will be used instead. & No \\ \hline
append & Specifies whether or not the file specified by 'destfile' should be overwritten.
Defaults to "no". & No \\ \hline
encoding & Specifies the encoding for the input files. Please 
see\hfil\break http://java.sun.com/products/jdk/1.2/docs/guide/
internat/encoding.doc.html for 
a list of possible values. Defaults to the platform's default character encoding. & No \\ \hline
\end{tabular}

\subsubsection{Parameters specified as nested elements}

{\bf fileset}\hfil\break

FileSets are used to select files to be concatenated. Note that the
order in which the files selected from a fileset are concatenated is
not guaranteed. If this is an issue, use multiple filesets or consider
using filelists.

{\bf filelist}\hfil\break

FileLists are used to select files to be concatenated. The file
ordering in the files attribute will be the same order in which the
files are concatenated.

\subsubsection{Examples}

Concatenate a string to a file:

\begin{verbatim}
  <concat destfile="README">Hello, World!</concat>
\end{verbatim}      

Concatenate a series of files to the console:
\begin{verbatim}
  <concat>
    <fileset dir="messages" includes="*important*"/>
  </concat>
\end{verbatim}      

Concatenate a single file, appending if the destination file exists:
\begin{verbatim}
  <concat destfile="NOTES" append="true">
    <filelist dir="notes" files="note.txt"/>
  </concat>
\end{verbatim}      

Concatenate a series of files, overwriting if the destination file exists:
\begin{verbatim}
  <concat destfile="${docbook.dir}/all-sections.xml">
    <filelist dir="${docbook.dir}/sections" 
         files="introduction.xml,overview.xml"/>
    <fileset dir="${docbook.dir}" 
         includes="sections/*.xml" 
         excludes="introduction.xml,overview.xml"/>
  </concat>
\end{verbatim}

\subsection{Condition}

\subsubsection{Description}

Sets a property if a certain condition holds true - this is a
generalization of Available and Uptodate.

If the condition holds true, the property value is set to true by
default; otherwise, the property is not set. You can set the value to
something other than the default by specifying the value attribute.

Conditions are specified as nested elements, you must specify exactly one condition.

\subsubsection{Parameters}

\begin{tabular}{|l|l|c|} \hline
Attribute & Description & Required \\ \hline
property & The name of the property to set. & Yes \\ \hline
value & The value to set the property to. Defaults to "true". & No \\ \hline
\end{tabular}

\subsubsection{Parameters specified as nested elements}

All conditions to test are specified as nested elements, for a complete list see here.

Examples
\begin{verbatim}
  <condition property="javamail.complete">
    <and>
      <available classname="javax.activation.DataHandler"/>
      <available classname="javax.mail.Transport"/>
    </and>
  </condition>
\end{verbatim}
sets the property javamail.complete if both the JavaBeans Activation 
Framework and JavaMail are available in the classpath.
\begin{verbatim}
  <condition property="isMacOsButNotMacOsX">
    <and>
      <os family="mac"/>

      <not>
        <os family="unix"/>

      </not>
    </and>
  </condition>
\end{verbatim}
sets the property isMacOsButNotMacOsX if the current operating system is
MacOS, but not MacOS X - which Ant considers to be in the Unix family as well.
\begin{verbatim}
  <condition property="isSunOSonSparc">
    <os name="SunOS" arch="sparc"/>

  </condition>
\end{verbatim}  
sets the property isSunOSonSparc if the current operating system is
SunOS and if it is running on a sparc architecture.

\subsection{Supported conditions}

These are the nested elements that can be used as conditions in the
<condition> and <waitfor> tasks.

\subsubsection{not}

The {\tt <not>} element expects exactly one other condition to be nested
into this element, negating the result of the condition. It doesn't
have any attributes and accepts all nested elements of the condition
task as nested elements as well.

\subsubsection{and}

The {\tt <and>} element doesn't have any attributes and accepts an arbitrary
number of conditions as nested elements - all nested elements of the
condition task are supported. This condition is true if all of its
contained conditions are, conditions will be evaluated in the order
they have been specified in the build file.

The {\tt <and>} condition has the same shortcut semantics as the Java \&\&
operator, as soon as one of the nested conditions is false, no other
condition will be evaluated.

\subsubsection{or}

The {\tt <or>} element doesn't have any attributes and accepts an arbitrary
number of conditions as nested elements - all nested elements of the
condition task are supported. This condition is true if at least one
of its contained conditions is, conditions will be evaluated in the
order they have been specified in the build file.

The {\tt <or>} condition has the same shortcut semantics as the Java ||
operator, as soon as one of the nested conditions is true, no other
condition will be evaluated.

\subsubsection{available}

This condition is identical to the Available task, all attributes and
nested elements of that task are supported, the property and value
attributes are redundant and will be ignored.

\subsubsection{uptodate}

This condition is identical to the Uptodate task, all attributes and
nested elements of that task are supported, the property and value
attributes are redundant and will be ignored.

\subsubsection{os}

Test whether the current operating system is of a given type. Each
defined attribute is tested and the result is true only if all the
tests succeed.

\begin{tabular}{|l|l|c|} \hline
Attribute & Description & Required \\ \hline
family & The name of the operating system family to expect. & No \\ \hline
name & The name of the operating system to expect. & No \\ \hline
arch & The architecture of the operating system to expect. & No \\ \hline
version & The version of the operating system to expect. & No \\ \hline
\end{tabular}

Supported values for the family attribute are:

\begin{itemize}
\item windows (for all versions of Microsoft Windows)
\item dos (for all Microsoft DOS based operating systems including Microsoft Windows and OS/2)
\item mac (for all Apple Macintosh systems)
\item unix (for all Unix and Unix-like operating systems)
\item netware (for Novell NetWare)
\item os/2 (for OS/2)
\item win9x for Microsoft Windows 95 and 98
\item z/os for z/OS and OS/390
\end{itemize}

\subsubsection{equals}

Tests whether the two given Strings are identical

\begin{tabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
arg1 & First string to test. & Yes \\ \hline
arg2 & Second string to test. & Yes \\ \hline
casesensitive & Perform a case sensitive comparision. Default is true. & No \\ \hline
trim & Trim whitespace from arguments before comparing them. Default is false. & No \\ \hline
\end{tabular}

\subsubsection{isset}

Test whether a given property has been set in this project.

\begin{tabular}{|l|l|c|} \hline
Attribute & Description & Required \\ \hline
property & The name of the property to test. & Yes \\ \hline
\end{tabular}

\subsubsection{checksum}

This condition is identical to the Checksum task, all attributes and
nested elements of that task are supported, the property and overwrite
attributes are redundant and will be ignored.

\subsubsection{http}

The http condition checks for a valid response from a web server of
the specified url. By default, HTTP responses errors of 400 or greater
are viewed as invalid.

\begin{tabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
url & The full URL of the page to request. The web server must return a status code below the value of errorsBeginAt & Yes. \\ \hline
errorsBeginAt & The lowest HTTP response code that signals an error; by default '400'; server errors, not-authorized, not-found and the like are detected & No \\ \hline
\end{tabular}

\subsubsection{socket}

The socket condition checks for the existence of a TCP/IP listener at
the specified host and port.

\begin{tabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
server & The DNS name or IP address of the server. & Yes. \\ \hline
port & The port number to connect to. & Yes. \\ \hline
\end{tabular}

\subsubsection{filesmatch}

Test two files for matching. Nonexistence of either file results in
"false". This test does a byte for byte comparision, so test time
scales with byte size. NB: if the files are different sizes , one of
them is missing or the filenames match the answer is so obvious the
detailed test is omitted.

\begin{tabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
file1 & First file to test & Yes. \\ \hline
file2 & Second file to test & Yes. \\ \hline
\end{tabular}

\subsubsection{contains}

Tests whether a string contains another one.

\begin{tabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
string & The string to search in. & Yes \\ \hline
substring & The string to search for. & Yes \\ \hline
casesensitive & Perform a case sensitive comparision. Default is true. & No \\ \hline
\end{tabular}

\subsubsection{istrue}

Tests whether a string equals any of the ant definitions of true, that
is "true","yes", or "on"

\begin{supertabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
value & value to test & Yes \\ \hline
\end{supertabular}

\begin{verbatim}
    <istrue value="${someproperty}"/>
    <istrue value="false"/>
\end{verbatim}

\subsubsection{isfalse}

Tests whether a string is not true, the negation of <istrue>

\begin{supertabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
value & value to test & Yes \\ \hline
\end{supertabular}

\begin{verbatim}
    <isfalse value="${someproperty}"/>
    <isfalse value="false"/>
\end{verbatim}

\subsection{Copy}

\subsubsection{Description}

Copies a file or FileSet to a new file or directory. By default, files
are only copied if the source file is newer than the destination file,
or when the destination file does not exist. However, you can
explicitly overwrite files with the overwrite attribute.

FileSets are used to select a set of files to copy. To use a
{\tt <fileset>}, the todir attribute must be set.

Note: If you employ filters in your copy operation, you should limit
the copy to text files. Binary files will be corrupted by the copy
operation. This applies whether the filters are implicitly defined by
the filter task or explicitly provided to the copy operation as
filtersets

\subsubsection{Parameters}

\begin{supertabular}{|l|p{6cm}|p{4cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}

file & The file to copy. & Yes, unless a nested {\tt <fileset>} element is used. \\ \hline

preservelastmodified &
Give the copied files the same last modified time as the original source
files. (Note: Ignored on Java 1.1) & No; defaults to false. \\ \hline

\begin{tabular}{l}
tofile \\ \hline
todir \\ \hline
\end{tabular} &

\begin{tabular}{p{5.7cm}}
The file to copy to. \\ \hline
The directory to copy to. \\ \hline
\end{tabular} &

With the {\tt file} attribute, either {\tt tofile} or {\tt todir} can be used. 
With nested {\tt <fileset>} elements, if the set of files is greater than 1, 
or if only the dir attribute is specified in the {\tt <fileset>}, or if the 
file attribute is also specified, then only todir is allowed.
\\ \hline

overwrite & Overwrite existing files even if the destination files are 
newer. & No; defaults to false. \\ \hline

filtering & Indicates whether token filtering using the global build-file 
filters should take place during the copy. Note: Nested {\tt <filterset>}
elements will always be used, even if this attribute is not specified, 
or its value is false (no, or off). No; defaults to false.
flatten Ignore the directory structure of the source files, and copy all
files into the directory specified by the todir attribute. 
Note that you can achieve the same effect by using a flatten 
mapper. & No; defaults to false. \\ \hline

includeEmptyDirs & Copy any empty directories included in the 
FileSet(s). & No; defaults to true. \\ \hline

failonerror & Log a warning message, but do not stop the build,
when the file to copy does not exist. Only meaningful when copying
a single file. & No; defaults to true. \\ \hline

verbose & Log the files that are being copied. & No; defaults to false. \\ \hline

encoding & The encoding to assume when filter-copying the files. 
since Ant 1.5. & No - defaults to default JVM encoding \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf fileset}\hfil\break

FileSets are used to select sets of files to copy. To use a fileset, 
the todir attribute must be set.

{\bf mapper}\hfil\break

You can define filename transformations by using a nested mapper
element. The default mapper used by {\tt <copy>} is the identity mapper.

{\bf filterset}\hfil\break

FilterSets are used to replace tokens in files that are copied. To use
a FilterSet, use the nested {\tt <filterset>} element.

{\bf filterchain}\hfil\break

The Copy task supports nested FilterChains.

If {\tt <filterset>} and {\tt <filterchain>} elements are used 
inside the same {\tt <copy>} task, 
all {\tt <filterchain>} elements are processed first followed
by {\tt <filterset>} elements.

\subsubsection{Examples}

{\bf Copy a single file}\hfil\break
\begin{verbatim}
  <copy file="myfile.txt" tofile="mycopy.txt"/>
\end{verbatim}
{\bf Copy a single file to a directory}\hfil\break
\begin{verbatim}
  <copy file="myfile.txt" todir="../some/other/dir"/>
\end{verbatim}
{\bf Copy a directory to another directory}\hfil\break
\begin{verbatim}
  <copy todir="../new/dir">
    <fileset dir="src_dir"/>
  </copy>
\end{verbatim}
{\bf Copy a set of files to a directory}\hfil\break
\begin{verbatim}
  <copy todir="../dest/dir">
    <fileset dir="src_dir">
      <exclude name="**/*.java"/>
    </fileset>
  </copy>

  <copy todir="../dest/dir">
    <fileset dir="src_dir" excludes="**/*.java"/>
  </copy>
\end{verbatim}
{\bf Copy a set of files to a directory, appending .bak to the file name on the fly}\hfil\break
\begin{verbatim}
  <copy todir="../backup/dir">
    <fileset dir="src_dir"/>
    <mapper type="glob" from="*" to="*.bak"/>
  </copy>
\end{verbatim}
{\bf Copy a set of files to a directory, replacing @TITLE@ with Foo Bar in all files.}\hfil\break
\begin{verbatim}
  <copy todir="../backup/dir">
    <fileset dir="src_dir"/>
    <filterset>
      <filter token="TITLE" value="Foo Bar"/>
    </filterset>
  </copy>
  \end{verbatim}
Unix Note: File permissions are not retained when files are copied;
  they end up with the default UMASK permissions instead. This is
  caused by the lack of any means to query or set file permissions in
  the current Java runtimes. If you need a permission-preserving copy
  function, use {\tt <exec executable="cp" ... >} instead.

Windows Note: If you copy a file to a directory where that file
already exists, but with different casing, the copied file takes on
the case of the original. The workaround is to delete the file in the
destination directory before you copy it.

\subsection{Copydir}

{\em Deprecated}\hfil\break

This task has been deprecated. Use the Copy task instead.

\subsubsection{Description}

Copies a directory tree from the source to the destination.

It is possible to refine the set of files that are being copied. This
can be done with the includes, includesfile, excludes, excludesfile
and defaultexcludes attributes. With the includes or includesfile
attribute you specify the files you want to have included by using
patterns. The exclude or excludesfile attribute is used to specify the
files you want to have excluded. This is also done with patterns. And
finally with the defaultexcludes attribute, you can specify whether
you want to use default exclusions or not. See the section on
directory based tasks, on how the inclusion/exclusion of files works,
and how to write patterns.

This task forms an implicit FileSet and supports all attributes of
{\tt <fileset>} (dir becomes src) as well as the nested {\tt <include>},
{\tt <exclude>} and {\tt <patternset>} elements.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
src & the directory to copy. & Yes \\ \hline
dest & the directory to copy to. & Yes \\ \hline
includes & comma- or space-separated list of patterns of files that must be included. All files are included when omitted. & No \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & No \\ \hline
excludes & comma- or space-separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & No \\ \hline
defaultexcludes & indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline
filtering & indicates whether token filtering should take place during the copy & No \\ \hline
flatten & ignore directory structure of source directory, copy all files into a single directory, specified by the dest attribute (default is false). & No \\ \hline
forceoverwrite & overwrite existing files even if the destination files are newer (default is false). & No \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
  <copydir src="${src}/resources"
           dest="${dist}"
  />
\end{verbatim}
copies the directory ${src}/resources to ${dist}.
\begin{verbatim}
  <copydir src="${src}/resources"
           dest="${dist}"
           includes="**/*.java"
           excludes="**/Test.java"
  />
\end{verbatim}
copies the directory ${src}/resources to ${dist} recursively. All java files are copied, except for files with the name Test.java.
\begin{verbatim}
  <copydir src="${src}/resources"
           dest="${dist}"
           includes="**/*.java"
           excludes="mypackage/test/**"/>
\end{verbatim}           
copies the directory ${src}/resources to ${dist}
 recursively. All java files are copied, except for the
 files under the mypackage/test directory.

\subsection{Copyfile}

{\em Deprecated}\hfil\break

This task has been deprecated. Use the Copy task instead.

\subsubsection{Description}

Copies a file from the source to the destination. The file is only
copied if the source file is newer than the destination file, or when
the destination file does not exist.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
src & the filename of the file to copy. & Yes \\ \hline
dest & the filename of the file where to copy to. & Yes \\ \hline
filtering & indicates whether token filtering should take place during the copy & No \\ \hline
forceoverwrite & overwrite existing files even if the destination files are newer (default is false). & No \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
<copyfile src="test.java" dest="subdir/test.java"/>

<copyfile src="${src}/index.html" dest="${dist}/help/index.html"/>
\end{verbatim}

\subsection{Cvs}

\subsubsection{Description}

Handles packages/modules retrieved from a CVS repository.

When doing automated builds, the get task should be preferred over the 
checkout command, because of speed.

\subsubsection{Parameters}

\begin{tabular}{|l|p{6cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
command & the CVS command to execute. No, default "& checkout". \\ \hline
compression & true or false - if set to true, this is the same as compressionlevel="3" No. Defaults to & false. \\ \hline

compressionlevel & A number between 1 and 9 (corresponding to possible
values for CVS' -z{\tt \#}argument). Any other value is treated as
compression="false" & No. Defaults to no compression. \\ \hline

cvsRoot & the CVSROOT variable. & No \\ \hline
cvsRsh & the CVS\_RSH variable. & No \\ \hline

dest & the directory where the checked out files should be placed. & No,
default is project's basedir. \\ \hline

package & the package/module to check out. & No \\ \hline
tag & the tag of the package/module to check out. & No \\ \hline
date & Use the most recent revision no later than the given date & No \\ \hline
quiet & suppress informational messages. & No, default "false" \\ \hline

noexec & report only, don't change any files. & No, default to "false" \\ \hline

output & the file to direct standard output from the command. & No, default output to ANT Log as MSG\_INFO. \\ \hline
error & the file to direct standard error from the command. & No, default error to ANT Log as MSG\_WARN. \\ \hline
append & whether to append output/error when redirecting to a file. & No, default to "false". \\ \hline
port & Port used by CVS to communicate with the server. & No, default port 2401. \\ \hline
passfile & Password file to read passwords from. & No, default file ~/.cvspass. \\ \hline
failonerror & Stop the build process if the command exits with a return code other than 0. Defaults to false & No \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
  <cvs cvsRoot=":pserver:anoncvs@cvs.apache.org:/home/cvspublic"
       package="ant"
       dest="${ws.dir}"
  />
\end{verbatim}
checks out the package/module "ant" from the CVS repository pointed to by the 
cvsRoot attribute, and stores the files in "\$\{ws.dir\}".
\begin{verbatim}
  <cvs dest="${ws.dir}" command="update"/>
\end{verbatim}
updates the package/module that has previously been checked out into "\$\{ws.dir\}".
\begin{verbatim}
  <cvs command="-q diff -u -N" output="patch.txt"/>
\end{verbatim}
silently (-q) creates a file called patch.txt which contains a unified
(-u) diff which includes new files added via "cvs add" (-N) and can be
used as input to patch. The equivalent, using {\tt <commandline>} elements, is:
\begin{verbatim}
<cvs output="patch">
    <commandline>
        <argument value="-q"/>
        <argument value="diff"/>
        <argument value="-u"/>
        <argument value="-N"/>
    </commandline>
</cvs>
\end{verbatim}
or:
\begin{verbatim}
<cvs output="patch">
    <commandline>
        <argument line="-q diff -u -N"/>
    </commandline>
</cvs>
\end{verbatim}
You may include as many {\tt <commandline>} elements as you like. Each will
inherit the failonerror, compression, and other "global" parameters
from the {\tt <cvs>} element.
\begin{verbatim}
  <cvs command="update -A -d"/>
\end{verbatim}
Updates from the head of repository ignoring sticky bits (-A) and
creating any new directories as necessary (-d).

Note: the text of the command is passed to cvs "as-is" so any cvs
options should appear before the command, and any command options
should appear after the command as in the diff example above. See the
cvs manual for details, specifically the Guide to CVS commands

\subsection{CvsChangeLog}

\subsubsection{Description}

Generates an XML-formatted report file of the change logs recorded in a CVS repository.

\subsubsection{Parameters}

\begin{tabular}{|l|p{6cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
dir & The directory from which to run the CVS log command. & No; defaults to \$\{basedir\}. \\ \hline
destfile & The file in which to write the change log report. & Yes \\ \hline
usersfile & Property file that contains name-value pairs mapping user IDs and names that should be used in the report in place of the user ID. & No \\ \hline
daysinpast & Sets the number of days into the past for which the change log information should be retrieved. & No \\ \hline
start & The earliest date from which change logs are to be included in the report. & No \\ \hline
end & The latest date to which change logs are to be included in the report. & No \\ \hline
\end{tabular}

\subsubsection{Parameters specified as nested elements}

{\bf user}\hfil\break

The nested {\tt <user>} element allows you to specify a mapping between a
user ID as it appears on the CVS server and a name to include in the
formatted report. Anytime the specified user ID has made a change in
the repository, the {\tt <author>} tag in the report file will include the
name specified in displayname rather than the user ID.

\begin{tabular}{|l|p{6cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
displayname & The name to be used in the CVS change log report. & Yes \\ \hline
userid & The userid of the person as it exists on the CVS server. & Yes \\ \hline
\end{tabular}
\subsubsection{Examples}
\begin{verbatim}
  <cvschangelog dir="dve/network"
                destfile="changelog.xml"
  />
\end{verbatim}
Generates a change log report for all the changes that have been made
under the dve/network directory. It writes these changes into the file
changelog.xml.
\begin{verbatim}
  <cvschangelog dir="dve/network"
                destfile="changelog.xml"
                daysinpast="10"
  />
\end{verbatim}
Generates a change log report for any changes that were made under the dve/network directory in the past 10 days. It writes these changes into the file changelog.xml.
\begin{verbatim}
  <cvschangelog dir="dve/network"
                destfile="changelog.xml"
                start="20 Feb 2002"
                end="20 Mar 2002"
  />
\end{verbatim}
Generates a change log report for any changes that were made between February 20, 2002 and March 20, 2002 under the dve/network directory. It writes these changes into the file changelog.xml.
\begin{verbatim}
  <cvschangelog dir="dve/network"
                destfile="changelog.xml"
                start="20 Feb 2002"
  />
\end{verbatim}
Generates a change log report for any changes that were made after February 20, 2002 under the dve/network directory. It writes these changes into the file changelog.xml.
\begin{verbatim}
  <cvschangelog dir="dve/network"
                destfile="changelog.xml"/>
       <user displayname="Peter Donald" userid="donaldp"/>
  </cvschangelog>
\end{verbatim}
Generates a change log report for all the changes that were made under
the dve/network directory, substituting the name "Peter Donald" in the
{\tt <author>} tags anytime it encounters a change made by the user ID
"donaldp". It writes these changes into the file changelog.xml.

Generate Report

Ant includes a basic XSLT stylesheet that you can use to generate a
HTML report based on the xml output. The following example illustrates
how to generate a HTML report from the XML report.
\begin{verbatim}
        <style in="changelog.xml" 
               out="changelog.html" 
               style="${ant.home}/etc/changelog.xsl">
          <param name="title" expression="Ant ChangeLog"/>
          <param name="module" expression="ant"/>
          <param name="cvsweb" expression="http://cvs.apache.org/viewcvs/"/>
        </style>
\end{verbatim}
Sample Output
\begin{verbatim}
<changelog>
  <entry>
    <date>2002-03-06</date>
    <time>12:00</time>
    <author>Peter Donald</author>
    <file>
      <name>org/apache/myrmidon/build/AntlibDescriptorTask.java</name>
      <revision>1.3</revision>
      <prevrevision>1.2</prevrevision>
    </file>
    <msg><![CDATA[Use URLs directly rather than go via a FIle.
\end{verbatim}
This allows temp[lates to be stored inside jar]]></msg>
\begin{verbatim}
  </entry>
</changelog>
\end{verbatim}

\subsection{CVSPass}

\subsubsection{Description}

Adds entries to a .cvspass file. Adding entries to this file has the
same affect as a cvs login command.

\subsubsection{Parameters}

\begin{tabular}{|l|p{6cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
cvsroot & the CVS repository to add an entry for. & Yes \\ \hline
password & Password to be added to the password file. & Yes \\ \hline
passfile & Password file to add the entry to. & No, default is ~/.cvspass. \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
  <cvspass cvsroot=":pserver:anoncvs@cvs.apache.org:/home/cvspublic"
       password="anoncvs"
  />
\end{verbatim}
Adds an entry into the ~/.cvspass password file.

\subsection{CvsTagDiff}

Description

Generates an XML-formatted report file of the changes between two tags
or dates recorded in a CVS repository.

\subsubsection{Parameters}

\begin{tabular}{|l|p{6cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
startTag & The earliest tag from which diffs are to be included in the report. & exactly one of the two. \\ \hline
startDate & The earliest date from which diffs are to be included in the & report. \\ \hline
endTag & The latest tag from which diffs are to be included in the report. & exactly one of the two. \\ \hline
endDate & The latest date from which diffs are to be included in the & report. \\ \hline
destfile & The file in which to write the diff report. & Yes \\ \hline
rootdir & Root directory for the package, if different from the package name. & No \\ \hline
\end{tabular}

\subsubsection{Parameters inherited from the cvs task}

\begin{tabular}{|l|p{6cm}|p{4cm}|} \hline
Attribute & Description & Required \\ \hline
compression & true, false, or the number 1--9
(corresponding to possible values for CVS -z{\tt \#} argument).
Any other value is treated as false & No. Defaults to no compression. if passed true, level 3 compression is assumed. \\ \hline

cvsRoot & the CVSROOT variable. & No \\ \hline
cvsRsh & the CVS\_RSH variable. & No \\ \hline
package & the package/module to analyze. & Yes \\ \hline
quiet & suppress informational messages. & No, default "false" \\ \hline
port & Port used by CVS to communicate with the server. & No, default port 2401. \\ \hline
passfile & Password file to read passwords from. & No, default file ~/.cvspass. \\ \hline
failonerror & Stop the buildprocess if the command exits with a returncode other than 0. Defaults to false & No \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
  <cvstagdiff cvsRoot=":pserver:anoncvs@cvs.apache.org:/home/cvspublic"
                destfile="tagdiff.xml"
                package="ant"
                startTag="ANT_14"
                endTag="ANT_141"
  />
\end{verbatim}
Generates a tagdiff report for all the changes that have been made in
the ant module between the tags ANT\_14 and ANT\_141. It writes these
changes into the file tagdiff.xml.
\begin{verbatim}
  <cvstagdiff
                destfile="tagdiff.xml"
                package="ant"
                startDate="2002-01-01"
                endDate="2002-31-01"
  />
\end{verbatim}
Generates a tagdiff report for all the changes that have been made in
the ant module in january 2002. In this example cvsRoot has not been
set. The current cvsRoot will be used (assuming the build is started
from a folder stored in cvs. It writes these changes into the file
tagdiff.xml.
\begin{verbatim}
  <cvstagdiff
                destfile="tagdiff.xml"
                package="ant"
                rootdir="apache/ant"
                startDate="2002-01-01"
                endDate="2002-31-01"
  />
\end{verbatim}
Generates a tagdiff report for all the changes that have been made in
the ant module in january 2002, with rootdir indicating that the
actual location of the ant module in cvs is apache/ant rather than
ant. In this example cvsRoot has not been set. The current cvsRoot
will be used (assuming the build is started from a folder stored in
cvs. It writes these changes into the file tagdiff.xml.

\subsubsection{Generate Report}

Ant includes a basic XSLT stylesheet that you can use to generate a
HTML report based on the xml output. The following example illustrates
how to generate a HTML report from the XML report.
\begin{verbatim}
        <style in="tagdiff.xml" 
               out="tagdiff.html" 
               style="${ant.home}/etc/tagdiff.xsl">
          <param name="title" expression="Ant Diff"/>
          <param name="module" expression="ant"/>
          <param name="cvsweb" expression="http://cvs.apache.org/viewcvs/"/>
        </style>
\end{verbatim}
\subsubsection{Sample Output}
\begin{verbatim}
<?xml version="1.0" encoding="UTF-8"?>
<tagdiff startTag="ANT_14" endTag="ANT_141">
  <entry>
    <file>
      <name>src/main/org/apache/tools/ant/DirectoryScanner.java</name>
      <revision>1.15.2.1</revision>
      <prevrevision>1.15</prevrevision>
    </file>
  </entry>
</tagdiff>
\end{verbatim}

\subsection{Delete}

\subsubsection{Description}

Deletes a single file, a specified directory and all its files and
subdirectories, or a set of files specified by one or more FileSets.
When specifying a set of files, empty directories are not removed by
default. To remove empty directories, use the includeEmptyDirs
attribute.

If you use this task to delete temporary files created by editors and
it doesn't seem to work, read up on the default exclusion set in
Directory-based Tasks, and see the defaultexcludes attribute below.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{6cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
\begin{tabular}{l}
file \\ \hline
dir \\ \hline
\end{tabular} &

\begin{tabular}{p{5.5cm}}
The file to delete, specified as either the 
simple filename (if the file exists in the current base 
directory), a relative-path filename, or a full-path filename. \\ \hline

The directory to delete, including all its files and subdirectories.
Note: dir is not used to specify a directory name for file; 
file and dir are independent of each other.
WARNING: Do not set dir to ".", "\$\{basedir\}", 
or the full-pathname equivalent unless you truly intend to 
recursively remove the entire contents of the current base
directory (and the base directory itself, if different from
the current working directory).
\end{tabular} &

At least one of the two, unless a {\tt <fileset>} is specified. \\ \hline

verbose & Show the name of each deleted file ("true"/"false"). Default is "false" when omitted. & No \\ \hline
quiet & If the specified file or directory does not exist, do not display a diagnostic message (unless Ant has been invoked with the ?verbose or ?debug switches) or modify the exit status to reflect an error. When set to "true", if a file or directory cannot be deleted, no error is reported. This setting emulates the -f option to the Unix rm command. Default is "false". Setting this to "true" implies setting failonerror to "false". & No \\ \hline
failonerror & Controls whether an error (such as a failure to delete a file) stops the build or is merely reported to the screen. Only relevant if quiet is "false". Default is "true". & No \\ \hline
includeEmptyDirs & Set to "true" to delete empty directories when using filesets. Default is "false". & No \\ \hline
includes & Deprecated. Use <fileset>. Comma- or space-separated list of patterns of files that must be deleted. All files are relative to the directory specified in dir. & No \\ \hline
includesfile & Deprecated. Use <fileset>. The name of a file. Each line of this file is taken to be an include pattern & No \\ \hline
excludes & Deprecated. Use <fileset>. Comma- or space-separated list of patterns of files that must be excluded from the deletion list. All files are relative to the directory specified in dir. No files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & Deprecated. Use <fileset>. The name of a file. Each line of this file is taken to be an exclude pattern & No \\ \hline
defaultexcludes & Indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
  <delete file="/lib/ant.jar"/>
\end{verbatim}
deletes the file /lib/ant.jar.
\begin{verbatim}
  <delete dir="lib"/>
\end{verbatim}
deletes the lib directory, including all files and subdirectories of lib.
\begin{verbatim}
  <delete>
    <fileset dir="." includes="**/*.bak"/>
  </delete>
\end{verbatim}
deletes all files with the extension .bak from the current directory
and any subdirectories.
\begin{verbatim}
  <delete includeEmptyDirs="true">
    <fileset dir="build"/>
  </delete>
\end{verbatim}
deletes all files and subdirectories of build, including build itself.

\subsection{Deltree}

{\em Deprecated}\hfil\break

This task has been deprecated. Use the Delete task instead.

\subsubsection{Description}

Deletes a directory with all its files and subdirectories.

\subsubsection{Parameters}

\begin{tabular}{|l|p{6cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
dir & the directory to delete. & Yes \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
  <deltree dir="dist"/>
\end{verbatim}
deletes the directory dist, including its files and subdirectories.
\begin{verbatim}
  <deltree dir="${dist}"/>
\end{verbatim}
deletes the directory \$\{dist\}, including its files and subdirectories.

\subsection{Dependset}

A task to manage arbitrary dependencies between files.

\subsubsection{Description}

The dependset task compares a set of source files with a set of target
files. If any of the source files is more recent than any of the
target files, all of the target files are removed.

Source files and target files are specified via nested FileSets and/or
nested FileLists. Arbitrarily many source and target
filesets/filelists may be specified, but at least one filelist/fileset
is required for both sources and targets.

Use a FileSet when you want to use wildcard include or exclude
patterns and don't care about missing files. Use a FileList when you
want to consider the non-existence of a file as if it were out of
date. If there are any non-existing files in any source or target
FileList, all target files will be removed.

DependSet is useful to capture dependencies that are not or cannot be
determined algorithmically. For example, the <style> task only
compares the source XML file and XSLT stylesheet against the target
file to determined whether to restyle the source. Using dependset you
can extend this dependency checking to include a DTD or XSD file as
well as other stylesheets imported by the main stylesheet.

\subsubsection{Parameters}

(none)

\subsubsection{Parameters Specified as Nested Elements}

{\bf srcfileset}\hfil\break

The nested srcfileset element specifies a FileSet. All files included in this fileset will be compared against all files included in all of the targetfileset filesets and targetfilelist filelists. Multiple srcfileset filesets may be specified.

{\bf srcfilelist}\hfil\break

The nested srcfilelist element specifies a FileList. All files included in this filelist will be compared against all files included in all of the targetfileset filesets and targetfilelist filelists. Multiple srcfilelist filelists may be specified.

{\bf targetfileset}\hfil\break

The nested targetfileset element specifies a FileSet. All files included in this fileset will be compared against all files included in all of the srcfileset filesets and sourcefilelist filelists, and if any are older, they are all deleted.

{\bf targetfilelist}\hfil\break

The nested targetfilelist element specifies a FileList. All files
included in this filelist will be compared against all files included
in all of the srcfileset filesets and sourcefilelist filelists, and if
any are older, they are all deleted.

\subsubsection{Examples}
\begin{verbatim}    
    <dependset>
       <srcfilelist
           dir   = "${dtd.dir}"
           files = "paper.dtd,common.dtd"/>
       <srcfilelist
           dir   = "${xsl.dir}"
           files = "common.xsl"/>
       <srcfilelist
           dir   = "${basedir}"
           files = "build.xml"/>
       <targetfileset
           dir      = "${output.dir}"
           includes = "**/*.html"/>
    </dependset>  
\end{verbatim}    
In this example derived HTML files in the \$\{output.dir\} directory will
be removed if any are out-of-date with respect to:

\begin{enumerate}
\item the DTD of their source XML files
\item a common DTD (imported by the main DTD)
\item a subordinate XSLT stylesheet (imported by the main stylesheet), or
\item the buildfile
\end{enumerate}
   
If any of the source files in the above example does not exist, all
target files will also be removed. To ignore missing source files
instead, use filesets instead of filelists for the source files.

\subsection{Dirname}

\subsubsection{Description}

Task to determine the directory path of a specified file.

When this task executes, it will set the specified property to the
value of the specified file up to, but not including, the last path
element. If the specified file is a path that ends in a filename, the
filename will be dropped. If the specified file is just a filename,
the directory will be the current directory.

\subsubsection{Parameters}

\begin{tabular}{|l|p{6cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
file & The path to take the dirname of. & Yes \\ \hline
property & The name of the property to set. & Yes \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}    
  <dirname property="antfile.dir" file="${ant.file}"/>
\end{verbatim}    
will set antfile.dir to the directory path for \$\{ant.file\}.
\begin{verbatim}    
  <dirname property="foo.dirname" file="foo.txt"/>
\end{verbatim}    
will set foo.dirname to the project's basedir.

\subsection{Ear}

\subsubsection{Description}

An extension of the Jar task with special treatment for files that
should end up in an Enterprise Application archive.

(The Ear task is a shortcut for specifying the particular layout of a
EAR file. The same thing can be accomplished by using the prefix and
fullpath attributes of zipfilesets in a Zip or Jar task.)

The extended zipfileset element from the zip task (with attributes
prefix, fullpath, and src) is available in the Ear task.

\subsubsection{Parameters}

\begin{tabular}{|l|p{6cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
destfile & the EAR file to create. & Yes \\ \hline
appxml & The deployment descriptor to use (META-INF/application.xml). & Yes, unless update is set to true \\ \hline
basedir & the directory from which to jar the files. & No \\ \hline
compress & Not only store data but also compress them, defaults to true & No \\ \hline
encoding & The character encoding to use for filenames inside the archive. Defaults to UTF8. It is not recommended to change this value as the created archive will most likely be unreadable for Java otherwise. & No \\ \hline
filesonly & Store only file entries, defaults to false & No \\ \hline
includes & comma- or space-separated list of patterns of files that must be included. All files are included when omitted. & No \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & No \\ \hline
excludes & comma- or space-separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & No \\ \hline
defaultexcludes & indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline
manifest & the manifest file to use. & No \\ \hline
update & indicates whether to update or overwrite the destination file if it already exists. Default is "false". & No \\ \hline
duplicate & behavior when a duplicate file is found. Valid values are "add", "preserve", and "fail". The default value is "add". & No \\ \hline
\end{tabular}

\subsubsection{Nested elements}

{\bf metainf}\hfil\break

The nested metainf element specifies a FileSet. All files included in
this fileset will end up in the META-INF directory of the ear file. If
this fileset includes a file named MANIFEST.MF, the file is ignored
and you will get a warning.

\subsubsection{Example}
\begin{verbatim}
    <ear destfile="${build.dir}/myapp.ear"
             appxml="${src.dir}/metadata/application.xml">
      <fileset dir="${build.dir}" includes="*.jar,*.war"/>
    </ear>
\end{verbatim}

\subsection{Echo}

\subsubsection{Description}

Echoes a message to the current loggers and listeners which means
System.out unless overridden. A level can be specified, which controls
at what logging level the message is filtered at.

The task can also echo to a file, in which case the option to append
rather than overwrite the file is available, and the level option is
ignored

\subsubsection{Parameters}

\begin{tabular}{|l|p{6cm}|p{4cm}|} \hline
Attribute & Description & Required \\ \hline
message & the message to echo. & Yes, unless data is included in a character section within this element. \\ \hline
file & the file to write the message to. & No \\ \hline
append & Append to an existing file? & No - default is false. \\ \hline
level & Control the level at which this message is reported. One of "error", "warning", "info", "verbose", "debug" & No - default is "warning". \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
  <echo message="Hello, world"/>

  
<echo>This is a longer message stretching over
two lines.
</echo>

  
<echo>
This is a longer message stretching over
three lines; the first line is a blank
</echo>
\end{verbatim}

As XML parsers are wont to do, the first newline in the text element
has been included in the text.
\begin{verbatim}
<echo message="Deleting drive C:" level="debug"/>
\end{verbatim}
A message which only appears in -debug mode.
\begin{verbatim}
<echo level="error">
Imminent failure in the antimatter containment facility.
Please withdraw to safe location at least 50km away.  
</echo>
\end{verbatim}
A message which appears even in -quiet mode.
\begin{verbatim}
<echo file="runner.csh" append="false">#\!/bin/tcsh
java-1.3.1 -mx1024m ${project.entrypoint} $$*
\end{verbatim}
Generate a shell script by echoing to a file. Note the use of a double
\$ symbol to stop Ant filtering out the single \$ during variable expansion

\subsection{Exec}

\subsubsection{Description}

Executes a system command. When the os attribute is specified, then
the command is only executed when Ant is run on one of the specified
operating systems.

{\bf Cygwin Users}\hfil\break

In general the {\tt <exec>} task will not understand paths such as /bin/sh
for the executable parameter. This is because the Java VM in which Ant
is running is a Windows executable and is not aware of Cygwin
conventions.

\subsubsection{Parameters}

\begin{tabular}{|l|p{6cm}|p{4cm}|} \hline
Attribute & Description & Required \\ \hline
command & the command to execute with all command line arguments. deprecated, use executable and nested <arg> elements instead. & Exactly one of the two. \\ \hline
executable & the command to execute without any command line & arguments. \\ \hline
dir & the directory in which the command should be executed. & No \\ \hline
os & list of Operating Systems on which the command may be executed. If the current OS's name is contained in this list, the command will be executed. The OS's name is determined by the Java Virtual machine and is set in the "os.name" system property. & No \\ \hline
output & the file to which the output of the command should be redirected. & No \\ \hline
append & whether output should be appended to or overwrite an existing file. Defaults to false. & No \\ \hline
outputproperty & the name of a property in which the output of the command should be stored. & No \\ \hline
resultproperty & the name of a property in which the return code of the command should be stored. Only of interest if failonerror=false & No \\ \hline
timeout & Stop the command if it doesn't finish within the specified time (given in milliseconds). & No \\ \hline
failonerror & Stop the buildprocess if the command exits with a returncode other than 0. Defaults to false & No \\ \hline
failifexecutionfails & Stop the build if we can't start the program. Defaults to true. & No \\ \hline
newenvironment & Do not propagate old environment when new environment variables are specified. & No, default is false \\ \hline
vmlauncher & Run command using the Java VM's execution facilities where available. If set to false the underlying OS's shell, either directly or through the antRun scripts, will be used. Under some operating systems, this gives access to facilities not normally available through the VM including, under Windows, being able to execute scripts, rather than their associated interpreter. If you want to specify the name of the executable as a relative path to the directory given by the dir attribute, it may become necessary to set vmlauncher to false as well. & No, default is true \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
<exec dir="${src}" executable="cmd.exe" os="Windows 2000" output="dir.txt">
  <arg line="/c dir"/>
</exec>
\end{verbatim}

\subsubsection{Parameters specified as nested elements}

{\bf arg}\hfil\break

Command line arguments should be specified as nested <arg>
elements. See Command line arguments.

{\bf env}\hfil\break

It is possible to specify environment variables to pass to the system
command via nested {\tt <env>} elements.

\begin{tabular}{|l|p{6cm}|p{4cm}|} \hline
Attribute & Description & Required \\ \hline
key & The name of the environment variable. & Yes \\ \hline

\begin{tabular}{l}
value \\ \hline
path \\ hline
file \\ \hline
\end{tabular} &

\begin{tabular}{p{5.5cm}}
The literal value for the environment variable. \\ \hline

The value for a PATH like environment variable. You can use ; or : as
separators and Ant will convert it to the platform's local conventions. \\ \hline

The value for the environment variable. Will be replaced by the absolute filename 
of the file by Ant. \\ \hline
\end{tabular} &

Exactly one of these. \\ \hline
\end{tabular}

\subsubsection{Errors and return codes}

By default the return code of a {\tt <exec>} is ignored; when you set
failonerror="true" then any non zero response is treated as an error.
Alternatively, you can set resultproperty to the name of a property
and have it assigned to the result code (barring immutability, of
course).

If the attempt to start the program fails with an OS dependent error
code, then {\tt <exec>} halts the build unless failifexecutionfails is set.
You can use that to run a program if it exists, but otherwise do
nothing.

What do those error codes mean? Well, they are OS dependent. On
Windows boxes you have to look in include\\error.h in your windows
compiler or wine files; error code 2 means 'no such program', which
usually means it is not on the path. Any time you see such an error
from any ant task, it is usually not an ant bug, but some
configuration problem on your machine.

\subsubsection{Examples}
\begin{verbatim}
<exec executable="emacs">
  <env key="DISPLAY" value=":1.0"/>
</exec>
\end{verbatim}
starts emacs on display 1 of the X Window System.
\begin{verbatim}
<exec ... >
  <env key="PATH" path="${java.library.path}:${basedir}/bin"/>
</exec>
\end{verbatim}
adds \$\{basedir\}/bin to the PATH of the system command.

Note: Although it may work for you to specify arguments using a simple
arg-element and separate them by spaces it may fail if you switch to a
newer version of the JDK. JDK < 1.2 will pass these as separate
arguments to the program you are calling, JDK >= 1.2 will pass them as
a single argument and cause most calls to fail.

Note2: If you are using Ant on Windows and a new DOS-Window pops up
for every command which is executed this may be a problem of the JDK
you are using. This problem may occur with all JDK's < 1.2.

Timeouts: If a timeout is specified, when it is reached the sub
process is killed and a message printed to the log. The return value
of the execution will be "-1", which will halt the build if
failonerror=true, but be ignored otherwise.

\subsection{Fail}

Description

Exits the current build (just throwing a BuildException), optionally
printing additional information.

The message of the Exception can be set via the message attribute or
character data nested into the element.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{6cm}|p{4cm}|} \hline
Attribute & Description & Required \\ \hline
message & A message giving further information on why the build exited & No \\ \hline
if & Only fail if a property of the given name exists in the current project & No \\ \hline
unless & Only fail if a property of the given name doesn't exist in the current project & No \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
  <fail/>
\end{verbatim}
will exit the current build with no further information given.
\begin{verbatim}
BUILD FAILED

build.xml:4: No message

  <fail message="Something wrong here."/>
\end{verbatim}
will exit the current build and print something like the following to
wherever your output goes:
\begin{verbatim}
BUILD FAILED

build.xml:4: Something wrong here.

  <fail>Something wrong here.</fail>
\end{verbatim}
will give the same result as above.

\subsection{Filter}

\subsubsection{Description}

Sets a token filter for this project or read multiple token filter
from an input file and sets these as filters. Token filters are used
by all tasks that perform file copying operations through the Project
commodity methods.

Note 1: the token string must not contain the separators chars (@).

Note 2: Either token and value attributes must be provided, or only
the filtersfile attribute.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{6cm}|p{4cm}|} \hline
Attribute & Description & Required \\ \hline
token & the token string without @ & Yes* \\ \hline
value & the string that should be put to replace the token when the file is copied & Yes* \\ \hline
filtersfile & The file from which the filters must be read. This file must be a formatted as a property file. & Yes* \\ \hline
\end{supertabular}
* see notes 1 and 2 above parameters table.

\subsubsection{Examples}
\begin{verbatim}
  <filter token="year" value="2000"/>
  <copy todir="${dest.dir}" filtering="true">
    <fileset dir="${src.dir}"/>
  </copy>
\end{verbatim}
will copy recursively all the files from the src.dir directory into the dest.dir directory replacing all the occurrences of the string @year@ with 2000.
\begin{verbatim}
  <filter filtersfile="deploy_env.properties"/>
\end{verbatim}
will read all property entries from the deploy\_env.properties file
and set these as filters.

\subsection{FixCRLF}

\subsubsection{Description}

Adjusts a text file to local conventions.

The set of files to be adjusted can be refined with the includes,
includesfile, excludes, excludesfile and defaultexcludes attributes.
Patterns provided through the includes or includesfile attributes
specify files to be included. Patterns provided through the exclude or
excludesfile attribute specify files to be excluded. Additionally,
default exclusions can be specified with the defaultexcludes
attribute. See the section on directory based tasks, for details of
file inclusion/exclusion patterns and their usage.

This task forms an implicit FileSet and supports all attributes of
{\tt <fileset>} (dir becomes srcdir) as well as the nested {\tt <include>},
{\tt <exclude>} and {\tt <patternset>} elements.

The output file is only written if it is a new file, or if it differs
from the existing file. This prevents spurious rebuilds based on
unchanged files which have been regenerated by this task.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{8cm}|p{2.5cm}|} \hline
Attribute & Description & Required \\ \hline
srcDir & Where to find the files to be fixed up. & Yes \\ \hline
destDir & Where to place the corrected files. Defaults to srcDir (replacing the original file) & No \\ \hline
includes & comma- or space-separated list of patterns of files that must be included. All files are included when omitted. & No \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & No \\ \hline
excludes & comma- or space-separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & No \\ \hline
defaultexcludes & indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline

eol & Specifies how end-of-line (EOL) characters are to be
handled. The EOL characters are CR, LF and the pair CRLF. Valid values
for this property are:
\begin{itemize}
\item asis: leave EOL characters alone
\item cr: convert all EOLs to a single CR
\item lf: convert all EOLs to a single LF
\item crlf: convert all EOLs to the pair CRLF
\end{itemize}
    
Default is based on the platform on which you are running this
task. For Unix platforms, the default is "lf". For DOS based
systems (including Windows), the default is "crlf". For Mac OS,
the default is "cr".

This is the preferred method for specifying EOL. The "cr" attribute
(see below) is now deprecated.

N.B.: One special case is recognized. 
The three characters CR-CR-LF are regarded as a single EOL. 
Unless this property is specified as "asis", this sequence
will be converted into the specified EOL type. & No \\ \hline

cr & Deprecated. Specifies how CR characters are to be handled at 
end-of-line (EOL). Valid values for this property are:
\begin{itemize}
\item asis: leave EOL characters alone.
\item add: add a CR before any single LF characters. The intent is to convert all EOLs to the pair CRLF.
\item remove: remove all CRs from the file. The intent is to convert all EOLs to a single LF.
\end{itemize}    
Default is based on the platform on which you are running this
task. For Unix platforms, the default is "remove". For DOS based
systems (including Windows), the default is "add".

N.B.: One special case is recognized. The three characters CR-CR-LF 
are regarded as a single EOL. Unless this property is specified as 
"asis", this sequence will be converted into 
the specified EOL type. & No \\ \hline

javafiles & Used only in association with the "tab" 
attribute (see below), this boolean attribute indicates 
whether the fileset is a set of java source files ("yes"/"no"). 
Defaults to "no". See notes in section on "tab". & No \\ \hline

tab & Specifies how tab characters are to be handled. 
Valid values for this property are:
\begin{itemize}
\item add: convert sequences of spaces which span a tab stop to tabs
\item asis: leave tab and space characters alone
\item remove: convert tabs to spaces
\end{itemize}    
Default for this parameter is "asis".

N.B.: When the attribute "javafiles" (see above) is "true", literal
TAB characters occurring within Java string or character constants are
never modified. This functionality also requires the recognition of
Java-style comments.

N.B.: There is an incompatibility between this and the previous
version in the handling of white space at the end of lines. This
version does not remove trailing whitespace on lines. & No \\ \hline

tablength & TAB character interval. Valid values are between 2 and 80 inclusive. The default for this parameter is 8. & No \\ \hline

eof & Specifies how DOS end of file (control-Z) characters are to be handled. Valid values for this property are:
\begin{itemize}
\item add: ensure that there is an EOF character at the end of the file
\item asis: leave EOF characters alone
\item remove: remove any EOF character found at the end
\end{itemize}

Default is based on the platform on which you are 
running this task. For Unix platforms, the default is remove. 
For DOS based systems (including Windows), 
the default is asis. & No \\ \hline

encoding & The encoding of the files & No - defaults to default JVM encoding \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
  <fixcrlf srcdir="${src}"
       eol="lf" 
       eof="remove"
       includes="**/*.sh"
  />
\end{verbatim}
Replaces EOLs with LF characters and removes eof characters from the shell scripts. Tabs and spaces are left as is.
\begin{verbatim}
  <fixcrlf srcdir="${src}"
       eol="crlf"
       includes="**/*.bat"
  />
\end{verbatim}
Replaces all EOLs with cr-lf pairs in the batch files. Tabs and spaces are left as is. EOF characters are left alone if run on DOS systems, and are removed if run on Unix systems.
\begin{verbatim}
  <fixcrlf srcdir="${src}"
       tab="add"
       includes="**/Makefile"
  />
\end{verbatim}
Sets EOLs according to local OS conventions, and converts sequences of spaces and tabs to the minimal set of spaces and tabs which will maintain spacing within the line. Tabs are set at 8 character intervals. EOF characters are left alone if run on DOS systems, and are removed if run on Unix systems. Many versions of make require tabs prior to commands.
\begin{verbatim}
  <fixcrlf srcdir="${src}"
       tab="remove"
       tablength="3"
       eol="lf"
       javafiles="yes"
       includes="**/*.java"
  />
\end{verbatim}
Converts all EOLs in the included java source files to a single LF. Replace all TAB characters except those in string or character constants with spaces, assuming a tab width of 3. If run on a unix system, any CTRL-Z EOF characters at the end of the file are removed. On DOS/Windows, any such EOF characters will be left untouched.
\begin{verbatim}
  <fixcrlf srcdir="${src}"
       tab="remove"
       includes="**/README*"
  />
\end{verbatim}
Sets EOLs according to local OS conventions, and converts all tabs to spaces, assuming a tab width of 8. EOF characters are left alone if run on DOS systems, and are removed if run on Unix systems. You never know what editor a user will use to browse README's.

\subsection{GenKey}

\subsubsection{Description}

Generates a key in keystore. This task needs Java1.2 or later

\subsubsection{Parameters}

\begin{tabular}{|l|p{8cm}|p{2.5cm}|} \hline
Attribute & Description & Required \\ \hline
alias & the alias to add under & Yes. \\ \hline
storepass & password for keystore integrity. Must be at least 6 characters long & Yes. \\ \hline
keystore & keystore location & No \\ \hline
storetype & keystore type & No \\ \hline
keypass & password for private key (if different) & No \\ \hline
sigalg & the algorithm to use in signing & No \\ \hline
keyalg & the method to use when generating name-value pair & No \\ \hline
verbose & (true | false) verbose output when signing & No \\ \hline
dname & The distinguished name for entity Yes if dname element & unspecified \\ \hline
validity & (integer) indicates how many days certificate is valid & No \\ \hline
keysize & (integer) indicates the size of key generated & No \\ \hline
\end{tabular}

Alternatively you can specify the distinguished name by creating a
sub-element named dname and populating it with param elements that
have a name and a value. When using the subelement it is automatically
encoded properly and commas (",") are replaced with "\,".

The following two examples are identical:

\subsubsection{Examples}
\begin{verbatim}
<genkey alias="apache-group" storepass="secret"
     dname="CN=Ant Group, OU=Jakarta Division, O=Apache.org, C=US"/>

<genkey alias="apache-group" storepass="secret" >
  <dname>
    <param name="CN" value="Ant Group"/>
    <param name="OU" value="Jakarta Division"/>
    <param name="O"  value="Apache.Org"/>
    <param name="C"  value="US"/>
  </dname>
</genkey>
\end{verbatim}

\subsection{Get}

Description

Gets a file from a URL. When the verbose option is "on", this task
displays a '.' for every 100 Kb retrieved. Any URL schema supported by
the runtime is valid here, including http:, ftp: and jar:; https: is
only valid if the appropriate support is added to the pre-1.4 Java
runtimes.

This task should be preferred above the CVS task when fetching remote
content. CVS is significantly slower than loading a compressed archive
compared to http/ftp.

The usetimestamp option enables you to control downloads so that the
remote file is only fetched if newer than the local copy. If there is
no local copy, the download always takes place. When a file is
downloaded, the timestamp of the downloaded file is set to the remote
timestamp, if the JVM is Java1.2 or later. NB: This timestamp facility
only works on downloads using the HTTP protocol.

A username and password can be specified, in which case basic
'slightly encoded plain text' authentication is used. This is only a
secure authentication mechanism over an HTTPS link.

If you need to go through a firewall, use <setproxy> to set up the
proxy first.

\subsubsection{Parameters}

\begin{tabular}{|l|p{8cm}|p{2.5cm}|} \hline
Attribute & Description & Required \\ \hline
src & the URL from which to retrieve a file. & Yes \\ \hline
dest & the file where to store the retrieved file. & Yes \\ \hline
verbose & show verbose progress information ("on"/"off"). & No; default "false" \\ \hline
ignoreerrors & Log errors but don't treat as fatal. & No; default "false" \\ \hline
usetimestamp & conditionally download a file based on the timestamp of the local copy. HTTP only & No; default "false" \\ \hline
username & username for 'BASIC' http authentication & if password is set \\ \hline
password & password: & required if username is set \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
  <get src="http://ant.apache.org/" dest="help/index.html"/>
\end{verbatim}
Gets the index page of http://ant.apache.org/, and stores it in the
file help/index.html.
\begin{verbatim}
  <get src="http://jakarta.apache.org/builds/tomcat/nightly/ant.zip" 
    dest="optional.jar" 
    verbose="true"
    usetimestamp="true"/>
\end{verbatim}
Gets the nightly ant build from the tomcat distribution, if the local
copy is missing or out of date. Uses the verbose option for progress
information.
\begin{verbatim}
  <get src="https://insecure-bank.org/statement/user=1214" 
    dest="statement.html" 
    username="1214";
    password="secret"/>
\end{verbatim}
Fetches some file from a server with access control. Because https is
being used the fact that basic auth sends passwords in plaintext is
moot.

\subsection{GUnzip/BUnzip2}

\subsubsection{Description}

Expands a file packed using GZip or BZip2.

If dest is a directory the name of the destination file is the same as
src (with the ".gz" or ".bz2" extension removed if present). If dest
is omitted, the parent dir of src is taken. The file is only expanded
if the source file is newer than the destination file, or when the
destination file does not exist.

\subsubsection{Parameters}

\begin{tabular}{|l|p{8cm}|p{2.5cm}|} \hline
Attribute & Description & Required \\ \hline
src & the file to expand. & Yes \\ \hline
dest & the destination file or directory. & No \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
<gunzip src="test.tar.gz"/>
\end{verbatim}
expands test.tar.gz to test.tar
\begin{verbatim}
<bunzip2 src="test.tar.bz2"/>
\end{verbatim}
expands test.tar.bz2 to test.tar
\begin{verbatim}
<gunzip src="test.tar.gz" dest="test2.tar"/>
\end{verbatim}
expands test.tar.gz to test2.tar
\begin{verbatim}
<gunzip src="test.tar.gz" dest="subdir"/>
\end{verbatim}
expands test.tar.gz to subdir/test.tar (assuming subdir is a directory).

\subsection{GZip/BZip2}

\subsubsection{Description}

Packs a file using the GZip or BZip2 algorithm. The output file is
only generated if it doesn't exist or the source file is newer.

\subsubsection{Parameters}

\begin{tabular}{|l|p{8cm}|p{2.5cm}|} \hline
Attribute & Description & Required \\ \hline
src & the file to gzip/bzip. & Yes \\ \hline
zipfile & the destination file. & Yes \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
<gzip src="test.tar" zipfile="test.tar.gz"/>

<bzip2 src="test.tar" zipfile="test.tar.bz2"/>
\end{verbatim}

\subsection{Input}

\subsubsection{Description}

Allows user interaction during the build process by prompting for
input. To do so, it uses the configured InputHandler.

The prompt can be set via the message attribute or as character data
nested into the element.

Optionally a set of valid input arguments can be defined via the
validargs attribute. Input task will no accept value that don't match
one of the predefined.

Optionally a property can be created from the value entered by the
user. This property can then be used during the following build
run. Input behaves according to property task which means that
existing properties cannot be overriden.

\subsubsection{Parameters}

\begin{tabular}{|l|p{8cm}|p{2.5cm}|} \hline
Attribute & Description & Required \\ \hline
message & the Message which gets displayed to the user during the build run. & No \\ \hline
validargs & comma separated String containing valid input arguments. If set, input task will reject any input not defined here. Validargs are compared case sensitive. If you want 'a' and 'A' to be accepted you will need to define both arguments within validargs. & No \\ \hline
addproperty & the name of a property to be created from input. Behaviour is equal to property task which means that existing properties cannot be overriden. & No \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
  <input/>
\end{verbatim}
Will pause the build run until return key is pressed when using the
default InputHandler, the concrete behavior is defined by the
InputHandler implementation you use.
\begin{verbatim}
  <input>Press Return key to continue...</input>
\end{verbatim}
Will display the message "Press Return key to continue..." and pause
the build run until return key is pressed (again, the concrete
behavior is implementation dependent).
\begin{verbatim}
  <input
    message="Press Return key to continue..."
  />
\end{verbatim}
Will display the message "Press Return key to continue..." and pause the build run until return key is pressed (see above).
\begin{verbatim}
  <input
    message="All data is going to be deleted from DB continue (y/n)?"
    validargs="y,n"
    addproperty="do.delete"
  />
  <condition property="do.abort">
    <equals arg1="n" arg2="${do.delete}"/>
  </condition>
  <fail if="do.abort">Build aborted by user.</fail>
\end{verbatim}
Will display the message "All data is going to be deleted from DB continue (y/n)?" and require 'y' to continue build or 'n' to exit build with following message "Build aborted by user.".
\begin{verbatim}
  <input
    message="Please enter db-username:"
    addproperty="db.user"
  />
\end{verbatim}
Will display the message "Please enter db-username:" and set the property db.user to the value entered by the user.

\subsection{Jar}

\subsubsection{Description}

Jars a set of files.

The basedir attribute is the reference directory from where to jar.

Note that file permissions will not be stored in the resulting jarfile.

It is possible to refine the set of files that are being jarred. This
can be done with the includes, includesfile, excludes, excludesfile
and defaultexcludes attributes. With the includes or includesfile
attribute you specify the files you want to have included by using
patterns. The exclude or excludesfile attribute is used to specify the
files you want to have excluded. This is also done with patterns. And
finally with the defaultexcludes attribute, you can specify whether
you want to use default exclusions or not. See the section on
directory based tasks, on how the inclusion/exclusion of files works,
and how to write patterns.

This task forms an implicit FileSet and supports all attributes of
{\tt <fileset>} (dir becomes basedir) as well as the nested {\tt <include>},
{\tt <exclude>} and {\tt <patternset>} elements.

You can also use nested file sets for more flexibility, and specify
multiple ones to merge together different trees of files into one
JAR. The extended fileset and groupfileset attributes from the zip
task are also available in the jar task. See the Zip task for more
details and examples.

If the manifest is omitted, a simple one will be supplied by Ant.

The update parameter controls what happens if the JAR file already
exists. When set to yes, the JAR file is updated with the files
specified. When set to no (the default) the JAR file is
overwritten. An example use of this is provided in the Zip task
documentation. Please note that ZIP files store file modification
times with a granularity of two seconds. If a file is less than two
seconds newer than the entry in the archive, Ant will not consider it
newer.

(The Jar task is a shortcut for specifying the manifest file of a JAR
file. The same thing can be accomplished by using the fullpath
attribute of a zipfileset in a Zip task. The one difference is that if
the manifest attribute is not specified, the Jar task will include an
empty one for you.)

Manifests are processed by the Jar task according to the Jar file
specification. Note in particular that this may result in manifest
lines greater than 72 bytes being wrapped and continued on the next line.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{8.5cm}|p{2.5cm}|} \hline
Attribute & Description & Required \\ \hline
destfile & the JAR file to create. & Yes \\ \hline
basedir & the directory from which to jar the files. & No \\ \hline
compress & Not only store data but also compress them, defaults to true & No \\ \hline
encoding & The character encoding to use for filenames inside the archive. Defaults to UTF8. It is not recommended to change this value as the created archive will most likely be unreadable for Java otherwise. & No \\ \hline
filesonly & Store only file entries, defaults to false & No \\ \hline
includes & comma- or space-separated list of patterns of files that must be included. All files are included when omitted. & No \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & No \\ \hline
excludes & comma- or space-separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & No \\ \hline
defaultexcludes & indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline
manifest & the manifest file to use. This can be either the location of a manifest, or the name of a jar added through a fileset. If its the name of an added jar, the task expects the manifest to be in the jar at META-INF/MANIFEST.MF & No \\ \hline
update & indicates whether to update or overwrite the destination file if it already exists. Default is "false". & No \\ \hline
whenempty & behavior when no files match. Valid values are "fail", "skip", and "create". Default is "skip". & No \\ \hline
duplicate & behavior when a duplicate file is found. Valid values are "add", "preserve", and "fail". The default value is "add". & No \\ \hline
index & whether to create an index list to speed up classloading. This is a JDK 1.3+ specific feature. Defaults to false. & No \\ \hline
manifestencoding & The encoding used to read the JAR manifest, when a manifest file is specified. & No, defaults to the platform encoding. \\ \hline
\end{supertabular}

\subsubsection{Nested elements}

{\bf metainf}\hfil\break

The nested metainf element specifies a FileSet. All files included in
this fileset will end up in the META-INF directory of the jar file. If
this fileset includes a file named MANIFEST.MF, the file is ignored
and you will get a warning.

{\bf manifest}\hfil\break

The manifest nested element allows the manifest for the Jar file to be
provided inline in the build file rather than in an external file.
This element is identical to the manifest task, but the file and mode
attributes must be omitted.

If both an inline manifest and an external file are both specified,
the manifests are merged.

When using inline manifests, the Jar task will check whether the build
file is more recent that the Jar file when deciding whether to rebuild
the Jar. This will not take into account property file changes which
may affect the resulting Jar.

\subsubsection{Examples}
\begin{verbatim}
  <jar destfile="${dist}/lib/app.jar" basedir="${build}/classes"/>
\end{verbatim}
jars all files in the ${build}/classes directory into a file called app.jar in the ${dist}/lib directory.
\begin{verbatim}
  <jar destfile="${dist}/lib/app.jar"
       basedir="${build}/classes"
       excludes="**/Test.class"
  />
\end{verbatim}
jars all files in the ${build}/classes directory into a file called app.jar in the ${dist}/lib directory. Files with the name Test.class are excluded.
\begin{verbatim}
  <jar destfile="${dist}/lib/app.jar"
       basedir="${build}/classes"
       includes="mypackage/test/**"
       excludes="**/Test.class"
  />
\end{verbatim}
jars all files in the ${build}/classes directory into a file called app.jar in the ${dist}/lib directory. Only files under the directory mypackage/test are used, and files with the name Test.class are excluded.
\begin{verbatim}
  <jar destfile="${dist}/lib/app.jar">
    <fileset dir="${build}/classes"
             excludes="**/Test.class"
    />
    <fileset dir="${src}/resources"/>
  </jar>
\end{verbatim}
jars all files in the ${build}/classes directory and also in the
\$\{src\}/resources directory together into a file called app.jar in the
\$\{dist\}/lib directory. Files with the name Test.class are excluded. If
there are files such as ${build}/classes/mypackage/MyClass.class and
\$\{src\}/resources/mypackage/image.gif, they will appear in the same
directory in the JAR (and thus be considered in the same package by
Java).
\begin{verbatim}
  <jar destfile="test.jar" basedir=".">
    <include name="build"/>
    <manifest>
      <attribute name="Built-By" value="${user.name}"/>
      <section name="common/class1.class">
        <attribute name="Sealed" value="false"/>
      </section>
    </manifest>
  </jar>
\end{verbatim}
This is an example of an inline manifest specification. Note that the
Built-By attribute will take the value of the Ant property
\$\{user.name\}. The manifest produced by the above would look like this:
\begin{verbatim}
Manifest-Version: 1.0
Built-By: conor
Created-By: Apache Ant 1.5alpha

Name: common/class1.class
Sealed: false
\end{verbatim}

\subsection{Java}
\subsubsection{Description}

Executes a Java class within the running (Ant) VM or forks another VM
if specified.

If odd things go wrong when you run this task, set fork="true" to use
a new JVM.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{8.5cm}|p{2.5cm}|} \hline
Attribute & Description & Required \\ \hline
classname & the Java class to execute. & Either jar or classname \\ \hline
jar & the location of the jar file to execute (must have a Main-Class entry in the manifest). Fork must be set to true if this option is selected. & Either jar or classname \\ \hline
args & the arguments for the class that is executed. deprecated, use nested <arg> elements instead. & No \\ \hline
classpath & the classpath to use. & No \\ \hline
classpathref & the classpath to use, given as reference to a PATH defined elsewhere. & No \\ \hline
fork & if enabled triggers the class execution in another VM (disabled by default) & No \\ \hline
jvm & the command used to invoke the Java Virtual Machine, default is 'java'. The command is resolved by java.lang.Runtime.exec(). Ignored if fork is disabled. & No \\ \hline
jvmargs & the arguments to pass to the forked VM (ignored if fork is disabled). deprecated, use nested <jvmarg> elements instead. & No \\ \hline
maxmemory & Max amount of memory to allocate to the forked VM (ignored if fork is disabled) & No \\ \hline
failonerror & Stop the buildprocess if the command exits with a returncode other than 0. Default is "false" & No \\ \hline
dir & The directory to invoke the VM in. (ignored if fork is disabled) & No \\ \hline
output & Name of a file to write the output to. & No \\ \hline
append & whether output should be appended to or overwrite an existing file. Defaults to false. & No \\ \hline
newenvironment & Do not propagate old environment when new environment variables are specified. Default is "false" (ignored if fork is disabled). & No \\ \hline
timeout & Stop the command if it doesn't finish within the specified time (given in milliseconds). It is highly recommended to use this feature only if fork is enabled. & No \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf arg and jvmarg}\hfil\break

Use nested {\tt <arg>} and {\tt <jvmarg>} elements to specify arguments for the
Java class and the forked VM respectively. See Command line arguments.

{\bf sysproperty}\hfil\break

Use nested {\tt <sysproperty>} elements to specify system properties
required by the class. These properties will be made available to the
VM during the execution of the class (either ANT's VM or the forked
VM). The attributes for this element are the same as for environment
variables.

{\bf classpath}\hfil\break

Java's classpath attribute is a PATH like structure and can also be
set via a nested classpath element.

{\bf env}\hfil\break

It is possible to specify environment variables to pass to the forked
VM via nested env elements. See the description in the section about exec

Settings will be ignored if fork is disabled.

\subsubsection{Examples}
\begin{verbatim}  
       <java classname="test.Main">
         <arg value="-h"/> 
         <classpath>
           <pathelement location="dist/test.jar"/>
           <pathelement path="${java.class.path}"/>
         </classpath>
       </java>
\end{verbatim}  
Run a class in this JVM with a new jar on the classpath
\begin{verbatim}  
        <java jar="dist/test.jar" 
           fork="true"
           failonerror="true"
           maxmemory="128m"
           >
         <arg value="-h"/> 
         <classpath>
           <pathelement location="dist/test.jar"/>
           <pathelement path="${java.class.path}"/>
         </classpath>
       </java>
\end{verbatim}  
Run the jar using the manifest supplied entry point, forking (as required), and with a maximum memory of 128MB. Any non zero return code breaks the build.
\begin{verbatim}  
  <java classname="test.Main"/>

  <java classname="test.Main"
        fork="yes" >
    <sysproperty key="DEBUG" value="true"/> 
    <arg value="-h"/> 
    <jvmarg value="-Xrunhprof:cpu=samples,file=log.txt,depth=3"/> 
  </java>
\end{verbatim}  
Note: you can not specify the (highly deprecated) MSJVM, "jview.exe"
as the JVM, as it takes different parameters for other JVMs, That JVM
can be started from {\tt <exec>} if required.

\subsection{Javac}

\subsubsection{Description}

Compiles a Java source tree.

The source and destination directory will be recursively scanned for
Java source files to compile. Only Java files that have no
corresponding .class file or where the class file is older than the
.java file will be compiled.

Note: Ant uses only the names of the source and class files to find
the classes that need a rebuild. It will not scan the source and
therefore will have no knowledge about nested classes, classes that
are named different from the source file, and so on. See the <depend>
task for dependency checking based on other than just
existence/modification times.

When the source files are part of a package, the directory structure
of the source tree should follow the package hierarchy.

It is possible to refine the set of files that are being
compiled. This can be done with the includes, includesfile, excludes,
and excludesfile attributes. With the includes or includesfile
attribute, you specify the files you want to have included. The
exclude or excludesfile attribute is used to specify the files you
want to have excluded. In both cases, the list of files can be
specified by either the filename, relative to the directory(s)
specified in the srcdir attribute or nested <src> element(s), or by
using wildcard patterns. See the section on directory-based tasks, for
information on how the inclusion/exclusion of files works, and how to
write wildcard patterns.

It is possible to use different compilers. This can be specified by
either setting the global build.compiler property, which will affect
all {\tt <javac>} tasks throughout the build, or by setting the compiler
attribute, specific to the current {\tt <javac>} task. Valid values for
either the build.compiler property or the compiler attribute are:

\begin{itemize}
\item classic (the standard compiler of JDK 1.1/1.2) ? javac1.1 and javac1.2 can be used as aliases.
\item modern (the standard compiler of JDK 1.3/1.4) ? javac1.3 and javac1.4 can be used as aliases.
\item jikes (the Jikes compiler).
\item jvc (the Command-Line Compiler from Microsoft's SDK for Java / Visual J++) ? microsoft can be used as an alias.
\item kjc (the kopi compiler).
\item gcj (the gcj compiler from gcc).
\item sj (Symantec java compiler) ? symantec can be used as an alias.
\item extJavac (run either modern or classic in a JVM of its own).
\end{itemize}

The default is javac1.x with x depending on the JDK version you use
while you are running Ant. If you wish to use a different compiler
interface than those supplied, you can write a class that implements
the CompilerAdapter interface (package
org.apache.tools.ant.taskdefs.compilers). Supply the full classname in
the build.compiler property or the compiler attribute.

The fork attribute overrides the build.compiler property or compiler
attribute setting and expects a JDK1.1 or higher to be set in
JAVA\_HOME.

You can also use the compiler attribute to tell Ant which JDK version
it shall assume when it puts together the command line switches - even
if you set fork="true". This is useful if you want to run the compiler
of JDK 1.1 while you current JDK is 1.2+. If you use
compiler="javac1.1" and (for example) depend="true" Ant will use the
command line switch -depend instead of -Xdepend.

This task will drop all entries that point to non-existent
files/directories from the classpath it passes to the compiler.

Windows Note:When the modern compiler is used in unforked mode on
Windows, it locks up the files present in the classpath of the <javac>
task, and does not release them. The side effect of this is that you
will not be able to delete or move those files later on in the
build. The workaround is to fork when invoking the compiler.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{8cm}|p{2.2cm}|} \hline
Attribute & Description & Required \\ \hline
srcdir & Location of the java files. (See the note below.) & Yes, unless nested {\tt <src>} elements are present. \\ \hline
destdir & Location to store the class files. & No \\ \hline
includes & Comma- or space-separated list of files (may be specified using wildcard patterns) that must be included; all .java files are included when omitted. & No \\ \hline
includesfile & The name of a file that contains a list of files to include (may be specified using wildcard patterns). & No \\ \hline
excludes & Comma- or space-separated list of files (may be specified using wildcard patterns) that must be excluded; no files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & The name of a file that contains a list of files to exclude (may be specified using wildcard patterns). & No \\ \hline
classpath & The classpath to use. & No \\ \hline
sourcepath & The sourcepath to use; defaults to the value of the srcdir attribute (or nested <src> elements). To suppress the sourcepath switch, use sourcepath="". & No \\ \hline
bootclasspath & Location of bootstrap class files. & No \\ \hline
classpathref & The classpath to use, given as a reference to a path defined elsewhere. & No \\ \hline
sourcepathref & The sourcepath to use, given as a reference to a path defined elsewhere. & No \\ \hline
bootclasspathref & Location of bootstrap class files, given as a reference to a path defined elsewhere. & No \\ \hline
extdirs & Location of installed extensions. & No \\ \hline
encoding & Encoding of source files. (Note: gcj doesn't support this option yet.) & No \\ \hline
nowarn & Indicates whether the -nowarn switch should be passed to the compiler; defaults to off. & No \\ \hline
debug & Indicates whether source should be compiled with debug information; defaults to off. If set to off, -g:none will be passed on the command line for compilers that support it (for other compilers, no command line argument will be used). If set to true, the value of the debuglevel attribute determines the command line argument. & No \\ \hline
debuglevel & Keyword list to be appended to the -g command-line switch. This will be ignored by all implementations except modern and classic(ver >= 1.2). Legal values are none or a comma-separated list of the following keywords: lines, vars, and source. If debuglevel is not specified, by default, nothing will be appended to -g. If debug is not turned on, this attribute will be ignored. & No \\ \hline
optimize & Indicates whether source should be compiled with optimization; defaults to off. & No \\ \hline
deprecation & Indicates whether source should be compiled with deprecation information; defaults to off. & No \\ \hline
target & Generate class files for specific VM version (e.g., 1.1 or 1.2). Note that the default value depends on the JVM that is running Ant. In particular, if you use JDK 1.4 the generated classes will not be usable for a 1.1 Java VM unless you explicitly set this attribute to the value 1.1 (which is the default value for JDK 1.1 to 1.3). & No \\ \hline
verbose & Asks the compiler for verbose output. & No \\ \hline
depend & Enables dependency-tracking for compilers that support this (jikes and classic). & No \\ \hline
includeAntRuntime & Whether to include the Ant run-time libraries in the classpath; defaults to yes. & No \\ \hline
includeJavaRuntime & Whether to include the default run-time libraries from the executing VM in the classpath; defaults to no. & No \\ \hline
fork & Whether to execute javac using the JDK compiler externally; defaults to no. & No \\ \hline
executable & Complete path to the javac executable to use in case of fork="yes". Defaults to the compiler of the Java version that is currently running Ant. Ignored if fork="no" & No \\ \hline
memoryInitialSize & The initial size of the memory for the underlying VM, if javac is run externally; ignored otherwise. Defaults to the standard VM memory setting. (Examples: 83886080, 81920k, or 80m) & No \\ \hline
memoryMaximumSize & The maximum size of the memory for the underlying VM, if javac is run externally; ignored otherwise. Defaults to the standard VM memory setting. (Examples: 83886080, 81920k, or 80m) & No \\ \hline
failonerror & Indicates whether the build will continue 
even if there are compilation errors; defaults to true. & No \\ \hline

source & Value of the -source command-line switch; will be ignored by all implementations except javac1.4 (or modern when Ant is not running in a 1.3 VM) and jikes.
If you use this attribute together with jikes, 
you must make sure that your version of jikes supports the -source switch.
Legal values are 1.3 and 1.4 -- by default, no -source argument will be
used at all. & No \\ \hline

compiler & The compiler implementation to use. If this attribute is not set, the value of the build.compiler property, if set, will be used. Otherwise, the default compiler for the current VM will be used. (See the above list of valid compilers.) & No \\ \hline
listfiles & Indicates whether the source files to be compiled will be listed; defaults to no. & No \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

This task forms an implicit FileSet and supports all attributes of
{\tt <fileset>} (dir becomes srcdir) as well as the nested {\tt <include>},
{\tt <exclude>} and {\tt <patternset>} elements.  src, classpath, sourcepath,
bootclasspath and extdirs

{\tt <javac>}'s srcdir, classpath, sourcepath, 
bootclasspath, and extdirs attributes are 
path-like structures and can also be set via 
nested {\tt <src>}, {\tt <classpath>}, {\tt <sourcepath>}, 
{\tt <bootclasspath>} and {\tt <extdirs>} elements, respectively.

{\bf compilerarg}\hfil\break

You can specify additional command line arguments for the compiler
with nested {\tt <compilerarg>} elements. These elements are specified like
Command-line Arguments but have an additional attribute that can be
used to enable arguments only if a given compiler implementation will
be used.

\begin{tabular}{|l|p{7cm}|c|}
Attribute & Description & Required \\ \hline
\begin{tabular}{l}
value \\ \hline
line \\ \hline
file \\ \hline
path \\ \hline
\end{tabular} &
See Command-line Arguments. & Exactly one of these. \\ \hline

compiler & Only pass the specified argument if the chosen compiler
implementation matches the value of this attribute. Legal values are
the same as those in the above list of valid compilers.) & No \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}  
  <javac srcdir="${src}"
         destdir="${build}"
         classpath="xyz.jar"
         debug="on"
  />
\end{verbatim}  
compiles all .java files under the ${src} directory, and
stores the .class files in the ${build} directory.
The classpath used includes xyz.jar, and compiling with 
debug information is on.
\begin{verbatim}  
  <javac srcdir="${src}"
         destdir="${build}"
         fork="true"
  />
\end{verbatim}  
compiles all .java files under the ${src} directory, and stores the .class files in the ${build} directory. This will fork off the javac compiler using the default javac executable.
\begin{verbatim}  
  <javac srcdir="${src}"
         destdir="${build}"
         fork="java$$javac.exe"
  />
\end{verbatim}  
compiles all .java files under the ${src} directory, and stores the
.class files in the ${build} directory. This will fork off the javac
compiler, using the executable named java$javac.exe. Note that the $
sign needs to be escaped by a second one.
\begin{verbatim}  
  <javac srcdir="${src}"
         destdir="${build}"
         includes="mypackage/p1/**,mypackage/p2/**"
         excludes="mypackage/p1/testpackage/**"
         classpath="xyz.jar"
         debug="on"
  />
\end{verbatim}  
compiles .java files under the ${src} directory, and stores the .class files in the ${build} directory. The classpath used includes xyz.jar, and debug information is on. Only files under mypackage/p1 and mypackage/p2 are used. All files in and below the mypackage/p1/testpackage directory are excluded from compilation.
\begin{verbatim}  
  <javac srcdir="${src}:${src2}"
         destdir="${build}"
         includes="mypackage/p1/**,mypackage/p2/**"
         excludes="mypackage/p1/testpackage/**"
         classpath="xyz.jar"
         debug="on"
  />
\end{verbatim}  
is the same as the previous example, with the addition of a second source path, defined by the property src2. This can also be represented using nested <src> elements as follows:
\begin{verbatim}  
  <javac destdir="${build}"
         classpath="xyz.jar"
         debug="on">
    <src path="${src}"/>
    <src path="${src2}"/>
    <include name="mypackage/p1/**"/>
    <include name="mypackage/p2/**"/>
    <exclude name="mypackage/p1/testpackage/**"/>
  </javac>
\end{verbatim}  
If you want to run the javac compiler of a different JDK, you should tell Ant, where to find the compiler and which version of JDK you will be using so it can choose the correct command line switches. The following example executes a JDK 1.1 javac in a new process and uses the correct command line switches even when Ant is running in a Java VM of a different version:
\begin{verbatim}
  <javac srcdir="${src}"
         destdir="${build}"
         fork="yes"
         executable="/opt/java/jdk1.1/bin/javac"
         compiler="javac1.1"
  />
\end{verbatim}
Note: If you wish to compile only source files located in certain
packages below a common root, use the include/exclude attributes or
{\tt <include>/<exclude>} nested elements to filter for these packages. Do
not include part of your package structure in the srcdir attribute (or
nested {\tt <src>} elements), or Ant will recompile your source files every
time you run your compile target. See the Ant FAQ for additional
information.

Note: If you are using Ant on Windows and a new DOS window pops up for
every use of an external compiler, this may be a problem of the JDK
you are using. This problem may occur with all JDKs {\tt <} 1.2.

\subsubsection{Jikes Notes}

Jikes supports some extra options, which can be set be defining the
properties shown below prior to invoking the task. The setting for
each property will be in affect for all <javac> tasks throughout the
build. The Ant developers are aware that this is ugly and inflexible ?
expect a better solution in the future. All the options are boolean,
and must be set to true or yes to be interpreted as anything other
than false. By default, build.compiler.warnings is true, while all
others are false.

\begin{tabular}{|p{5cm}|p{5cm}|l|} \hline
Property & Description & Default \\ \hline
build.compiler.emacs & Enable emacs-compatible error messages. & false \\ \hline
build.compiler.fulldepend & Enable full dependency checking; see
the +F switch in the Jikes manual. & false \\ \hline
build.compiler.pedantic & Enable pedantic warnings. & false \\ \hline
build.compiler.warnings
Deprecated. Use {\tt <javac>}'s nowarn attribute instead. &
Don't disable warning messages. & true \\ \hline
\end{tabular}

\subsection{Javadoc/Javadoc2}

\subsubsection{Description}

Generates code documentation using the javadoc tool.

The source directory will be recursively scanned for Java source files
to process but only those matching the inclusion rules, and not
matching the exclusions rules will be passed to the javadoc tool. This
allows wildcards to be used to choose between package names, reducing
verbosity and management costs over time. This task, however, has no
notion of "changed" files, unlike the javac task. This means all
packages will be processed each time this task is run. In general,
however, this task is used much less frequently.

This task works seamlessly between different javadoc versions (1.1,
1.2 and 1.4), with the obvious restriction that the 1.2 attributes
will be ignored if run in a 1.1 VM.

NOTE: since javadoc calls System.exit(), javadoc cannot be run inside
the same VM as ant without breaking functionality. For this reason,
this task always forks the VM. This overhead is not significant since
javadoc is normally a heavy application and will be called
infrequently.

NOTE: the packagelist attribute allows you to specify the list of
packages to document outside of the Ant file. It's a much better
practice to include everything inside the build.xml file. This option
was added in order to make it easier to migrate from regular
makefiles, where you would use this option of javadoc. The packages
listed in packagelist are not checked, so the task performs even if
some packages are missing or broken. Use this option if you wish to
convert from an existing makefile. Once things are running you should
then switch to the regular notation.

DEPRECATION: the javadoc2 task simply points to the javadoc task and
it's there for back compatibility reasons. Since this task will be
removed in future versions, you are strongly encouraged to use javadoc
instead.

In the table below, 1.1 means available if your current Java VM is a
1.1 VM, 1.2 for either 1.2 or 1.3 and 1.4 for a 1.4 Java VM. 1.2+
means any VM of at least version 1.2.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{4cm}|c|p{4cm}|} \hline
Attribute & Description & Availability & Required \\ \hline
\begin{tabular}{l}
sourcepath \\ \hline
sourcepathref \\ hline
sourcefiles \\ \hline
\end{tabular} &

\begin{tabular}{p{3.5cm}}
Specify where to find source files \\ \hline
Specify where to find source files by reference
to a PATH defined elsewhere. \\ \hline
Comma separated list of source files  \\ \hline
\end{tabular} &

\begin{tabular}{c}
all \\ \hline
all \\ \hline
\end{tabular} &

At least one of the three or 
nested {\tt <sourcepath>}, {\tt <fileset>} or {\tt <packageset>} \\ \hline

destdir & Destination directory for output files & all & Yes, unless a 
doclet has been specified. \\ \hline

maxmemory & Max amount of memory to allocate to the javadoc VM & all & No \\ \hline
packagenames & Comma separated list of package files (with terminating wildcard) & all & No \\ \hline
packageList & The name of a file containing the packages to process & 1.2+ & No \\ \hline
classpath & Specify where to find user class files & all & No \\ \hline
Bootclasspath & Override location of class files loaded by the bootstrap class loader & 1.2+ & No \\ \hline
classpathref & Specify where to find user class files by reference to a PATH defined elsewhere. & all & No \\ \hline
bootclasspathref & Override location of class files loaded by the bootstrap class loader by reference to a PATH defined elsewhere. & 1.2+ & No \\ \hline
Extdirs & Override location of installed extensions & 1.2+ & No \\ \hline
Overview & Read overview documentation from HTML file & 1.2+ & No \\ \hline
access & Access mode: one of public, protected, package, or private & all & No (default protected) \\ \hline
Public & Show only public classes and members & all & No \\ \hline
Protected & Show protected/public classes and members (default) & all & No \\ \hline
Package & Show package/protected/public classes and members & all & No \\ \hline
Private & Show all classes and members & all & No \\ \hline
Old & Generate output using JDK 1.1 emulating doclet & 1.2 & No \\ \hline
Verbose & Output messages about what Javadoc is doing & 1.2+ & No \\ \hline
Locale & Locale to be used, e.g. en\_US or en\_US\_WIN & 1.2+ & No \\ \hline
Encoding & Source file encoding name & all & No \\ \hline
Version & Include @version paragraphs & all & No \\ \hline
Use & Create class and package usage pages & 1.2+ & No \\ \hline
Author & Include @author paragraphs & all & No \\ \hline
Splitindex & Split index into one file per letter & 1.2+ & No \\ \hline
Windowtitle & Browser window title for the documentation (text) & 1.2+ & No \\ \hline
Doctitle & Include title for the package index(first) page (html-code) & 1.2+ & No \\ \hline
Header & Include header text for each page (html-code) & 1.2+ & No \\ \hline
Footer & Include footer text for each page (html-code) & 1.2+ & No \\ \hline
bottom & Include bottom text for each page (html-code) & 1.2+ & No \\ \hline
link & Create links to javadoc output at the given URL & 1.2+ & No \\ \hline
linkoffline & Link to docs at <url> using package list at <url2> - separate the URLs by using a space character. & 1.2+ & No \\ \hline
group & Group specified packages together in overview page. The format is as described below. & 1.2+ & No \\ \hline
nodeprecated & Do not include @deprecated information & all & No \\ \hline
nodeprecatedlist & Do not generate deprecated list & 1.2+ & No \\ \hline
notree & Do not generate class hierarchy & all & No \\ \hline
noindex & Do not generate index & all & No \\ \hline
nohelp & Do not generate help link & 1.2+ & No \\ \hline
nonavbar & Do not generate navigation bar & 1.2+ & No \\ \hline
serialwarn & Generate warning about @serial tag & 1.2+ & No \\ \hline
helpfile & Specifies the HTML help file to use & 1.2+ & No \\ \hline
stylesheetfile & Specifies the CSS stylesheet to use & 1.2+ & No \\ \hline
charset & Charset for cross-platform viewing of generated documentation & 1.2+ & No \\ \hline
docencoding & Output file encoding name & all & No \\ \hline
doclet & Specifies the class file that starts the doclet used in generating the documentation. & 1.2+ & No \\ \hline
docletpath & Specifies the path to the doclet class file that is specified with the -doclet option. & 1.2+ & No \\ \hline
docletpathref & Specifies the path to the doclet class file that is specified with the -doclet option by reference to a PATH defined elsewhere. & 1.2+ & No \\ \hline
additionalparam & Lets you add additional parameters to the 
javadoc command line. Useful for doclets.
Parameters containing spaces need to be quoted 
using \&quot;. & all & No \\ \hline
failonerror & Stop the buildprocess if the command exits with a returncode other than 0. & all & No \\ \hline
excludepackagenames & comma separated list of packages you don't want docs for. & all & No \\ \hline
defaultexcludes & indicates whether default excludes should be used (yes | no); default excludes are used when omitted. & all & No \\ \hline
useexternalfile & indicates whether the sourcefile name specified in srcfiles or as nested source elements should be written to a temporary file to make the command line shorter. Also applies to the package names specified via the packagenames attribute or nested package elements. (yes | no). Default is no. & 1.2+ & No \\ \hline
source & Necessary to enable javadoc to handle assertions present in J2SE v 1.4 source code. Set this to "1.4" to documents code that compiles using "javac -source 1.4". & 1.4 & No \\ \hline
\end{supertabular}

\subsubsection{Format of the group attribute}

The arguments are comma-delimited. Each single argument is 2
space-delimited strings, where the first one is the group's title and
the second one a colon delimited list of packages.

If you need to specify more than one group, or a group whose title
contains a comma or a space character, using nested group elements is
highly recommended.

E.g.,
\begin{verbatim}
    group="XSLT_Packages org.apache.xalan.xslt*,
       XPath_Packages org.apache.xalan.xpath*"
\end{verbatim}

\subsubsection{Parameters specified as nested elements}

{\bf packageset}\hfil\break

A DirSet. All matched directories that contain Java source files will
be passed to javadoc as package names. Package names are created from
the directory names by translating the directory separator into
dots. Ant assumes the base directory of the packageset points to the
root of a package hierarchy.

The packagenames, excludepackagenames and defaultexcludes attributes
of the task have no effect on the nested {\tt <packageset>} elements.

{\bf fileset}\hfil\break

A FileSet. All matched files will be passed to javadoc as source
files. Ant will automatically add the include pattern **/*.java to
these filesets.

Nested filesets can be used to document sources that are in the
default package or if you want to exclude certain files from
documentation. If you want to document all source files and don't use
the default package, packagesets should be used instead as this
increases javadocs performance.

The packagenames, excludepackagenames and defaultexcludes attributes
of the task have no effect on the nested {\tt <fileset>} elements.

{\bf package}\hfil\break

Same as one entry in the list given by packagenames.

\subsubsection{Parameters}

\begin{tabular}{|l|l|l|} \hline
Attribute & Description & Required \\ \hline
name & The package name (may be a wildcard) & Yes \\ \hline
\end{tabular}

{\bf excludepackage}\hfil\break

Same as one entry in the list given by excludepackagenames.

{\bf Parameters}\hfil\break

Same as for package.

{\bf source}\hfil\break

Same as one entry in the list given by sourcefiles.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|l|l|} \hline
Attribute & Description & Required \\ \hline
file & The source file to document & Yes \\ \hline
\end{tabular}

{bf doctitle}\hfil\break

Same as the doctitle attribute, but you can nest text inside the element this way.

{\bf header}\hfil\break

Similar to {\tt <doctitle>}.

{\bf footer}\hfil\break

Similar to {\tt <doctitle>}.

{\bf bottom}\hfil\break

Similar to {\tt <doctitle>}.

{\bf link}\hfil\break

Create link to javadoc output at the given URL. This performs the same
role as the link and linkoffline attributes. You can use either syntax
(or both at once), but with the nested elements you can easily specify
multiple occurrences of the arguments.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{5cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
href & The URL for the external documentation you wish to link to & Yes \\ \hline
offline & True if this link is not available online at the time of generating the documentation & No \\ \hline
packagelistLoc & The location to the 
directory containing the package-list file for the external
documentation & Only if the offline attribute is true \\ \hline
\end{tabular}

{\bf group}\hfil\break

Separates packages on the overview page into whatever groups you
specify, one group per table. This performs the same role as the group
attribute. You can use either syntax (or both at once), but with the
nested elements you can easily specify multiple occurrences of the
arguments.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{5cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
title & Title of the group & Yes, unless nested {\tt <title>} given \\ \hline
packages & List of packages to include in that group. 
Multiple packages are separated with ':'. & Yes, unless nested {\tt <package>}s given \\ \hline
\end{tabular}

The title may be specified as a nested {\tt <title>} element with text
contents, and the packages may be listed with nested {\tt <package>}
elements as for the main task.

{\bf doclet}\hfil\break

The doclet nested element is used to specify the doclet that javadoc
will use to process the input source files. A number of the standard
javadoc arguments are actually arguments of the standard doclet. If
these are specified in the javadoc task's attributes, they will be
passed to the doclet specified in the {\tt <doclet>} nested element. Such
attributes should only be specified, therefore, if they can be
interpreted by the doclet in use.

If the doclet requires additional parameters, these can be specified
with {\tt <param>} elements within the {\tt <doclet>} element. These paramaters
are restricted to simple strings. An example usage of the doclet
element is shown below:
\begin{verbatim}
  <javadoc ... >
     <doclet name="theDoclet"
             path="path/to/theDoclet">
        <param name="-foo" value="foovalue"/>
        <param name="-bar" value="barvalue"/>
     </doclet>
  </javadoc>
\end{verbatim}

{\bf tag}\hfil\break

The tag nested element is used to specify custom tags. This option is
only available with Java 1.4.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
name & Name of the tag (e.g. todo) & Yes \\ \hline
description & Description for tag (e.g. To do:) & Yes \\ \hline
enabled & Whether or not the tag is enabled (defaults to true) & No \\ \hline
scope & Scope for the tag - the elements in which it can be used. 
This is a comma separated list of some of the elements: 
overview, packages, types, constructors, methods, fields or the default, all. & No \\ \hline
\end{tabular}

{\bf taglet}\hfil\break

The taglet nested element is used to specify custom taglets. This
option is only available with Java 1.4.

{\bf Parameters}\hfil\break
\begin{tabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
name & The name of the taglet class (e.g. com.sun.tools.doclets.ToDoTaglet) & Yes \\ \hline
path & A path specifying the search path for the taglet 
class (e.g. /home/taglets). The path may also 
be specified by a nested {\tt <path>} element & No \\ \hline
\end{tabular}

{\bf sourcepath, classpath and bootclasspath}\hfil\break

Javadoc's sourcepath, classpath and bootclasspath attributes are PATH
like structure and can also be set via nested sourcepath, classpath
and bootclasspath elements respectively.

{\bf Example}\hfil\break
\begin{verbatim}
  <javadoc packagenames="com.dummy.test.*"
           sourcepath="src"
           excludepackagenames="com.dummy.test.doc-files.*"
           defaultexcludes="yes"
           destdir="docs/api"
           author="true"
           version="true"
           use="true"
           windowtitle="Test API">
    <doctitle><![CDATA[<h1>Test</h1>]]></doctitle>
    <bottom><![CDATA[<i>Copyright &#169; 
               2000 Dummy Corp. All Rights Reserved.</i>]]></bottom>
    <tag name="todo" scope="all" description="To do:" />
    <group title="Group 1 Packages" packages="com.dummy.test.a*"/>
    <group title="Group 2 Packages" 
     packages="com.dummy.test.b*:com.dummy.test.c*"/>
    <link offline="true" 
      href="http://java.sun.com/products/jdk/1.2/docs/api/" 
      packagelistLoc="C:\tmp"/>
    <link href="http://developer.java.sun.com/developer/products/xml/docs/api/"/>
  </javadoc>
\end{verbatim}
is the same as
\begin{verbatim}
  <javadoc 
           destdir="docs/api"
           author="true"
           version="true"
           use="true"
           windowtitle="Test API">

    <packageset dir="src" defaultexcludes="yes">
      <include name="com/dummy/test/**" />
      <exclude name="com/dummy/test/doc-files/**"/>
    </packageset>

    <doctitle><![CDATA[<h1>Test</h1>]]></doctitle>
    <bottom><![CDATA[<i>Copyright &#169; 
               2000 Dummy Corp. All Rights Reserved.</i>]]></bottom>
    <tag name="todo" scope="all" description="To do:" />
    <group title="Group 1 Packages" packages="com.dummy.test.a*"/>
    <group title="Group 2 Packages" 
     packages="com.dummy.test.b*:com.dummy.test.c*"/>
    <link offline="true" 
     href="http://java.sun.com/products/jdk/1.2/docs/api/"
     packagelistLoc="C:\tmp"/>
    <link href="http://developer.java.sun.com/developer/products/xml/docs/api/"/>
  </javadoc>
\end{verbatim}
or
\begin{verbatim}
  <javadoc 
           destdir="docs/api"
           author="true"
           version="true"
           use="true"
           windowtitle="Test API">

    <fileset dir="src" defaultexcludes="yes">
      <include name="com/dummy/test/**" />
      <exclude name="com/dummy/test/doc-files/**"/>
    </fileset>

    <doctitle><![CDATA[<h1>Test</h1>]]></doctitle>
    <bottom><![CDATA[<i>Copyright &#169; 
               2000 Dummy Corp. All Rights Reserved.</i>]]></bottom>
    <tag name="todo" scope="all" description="To do:" />
    <group title="Group 1 Packages" packages="com.dummy.test.a*"/>
    <group title="Group 2 Packages" packages="com.dummy.test.b*:com.dummy.test.c*"/>
    <link offline="true" 
     href="http://java.sun.com/products/jdk/1.2/docs/api/" packagelistLoc="C:\tmp"/>
    <link href="http://developer.java.sun.com/developer/products/xml/docs/api/"/>
  </javadoc>
\end{verbatim}

\subsection{LoadFile}

\subsubsection{Description}

Load a text file into a single property. Unless an encoding is
specified, the encoding of the current locale is used.

\subsubsection{Parameters}

\begin{tabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
srcFile & source file & Yes \\ \hline
property & property to save to & Yes \\ \hline
encoding & encoding to use when loading the file & No \\ \hline
failonerror & Whether to halt the build on failure & No, default "true" \\ \hline
\end{tabular}

The LoadFile task supports nested FilterChains.

\subsubsection{Examples}
\begin{verbatim}
    <loadfile property="message"
      srcFile="message.txt"/>
\end{verbatim}
Load file message.txt into property "message"; an <echo> can print this.
\begin{verbatim}
    <loadfile property="encoded-file"
      srcFile="loadfile.xml"
      encoding="ISO-8859-1"/>
\end{verbatim}
Load a file using the latin-1 encoding
\begin{verbatim}
    <loadfile
      property="optional.value"
      srcFile="optional.txt"
      failonerror="false"/>
\end{verbatim}
Load a file, don't fail if it is missing (a message is printed, though)
\begin{verbatim}
    <loadfile
      property="mail.recipients"
      srcFile="recipientlist.txt">
      <filterchain>
        <striplinebreaks/>
      </filterchain>
    </loadfile>
\end{verbatim}
Load a property which can be used as a parameter for another task (in this case mail), merging lines to ensure this happens.
\begin{verbatim}
    <loadfile
      property="system.configuration.xml"
      srcFile="configuration.xml">
        <expandproperties/>
    </loadfile>
\end{verbatim}
Load an XML file into a property, expanding all properties declared in
the file in the process.

\subsection{LoadProperties}

\subsubsection{Description}

Load a file's contents as Ant properties. This is equivalent to
{\tt <property file="..."/>} except that it supports nested {\tt <filterchain>}
elements and it cannot be specified outside a target.

If you want to simulate property's prefix attribute, please use prefixlines filter.

\subsubsection{Parameters}

\begin{tabular}{|l|p{6cm}|c|} \hline
Attribute & Description & Required \\ \hline
srcFile & source file & Yes \\ \hline
\end{tabular}

The LoadProperties task supports nested FilterChains.

\subsubsection{Examples}
\begin{verbatim}
    <loadproperties srcFile="file.properties"/>
\end{verbatim}
Load contents of file.properties as Ant properties.
\begin{verbatim}
    <loadproperties srcFile="file.properties">
      <filterchain>
        <linecontains>
          <contains value="import."/>
        </linecontains>
      </filterchain>
    </loadproperties>
\end{verbatim}    
Read the lines that contain the string "import." from the file
"file.properties" and load them as Ant properties.

\subsection{Mail}

\subsubsection{Description}

A task to send SMTP email. This task can send mail using either plain
text, UU encoding, or MIME format mail, depending on what is
available. Attachments may be sent using nested fileset elements.

Note: This task may depend on external libraries that are not included
in the Ant distribution. See Library Dependencies for more
information.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{6cm}|p{4cm}|} \hline
Attribute & Description & Required \\ \hline
from & Email address of sender. & Either a from attribute, or a {\tt <from>} element. \\ \hline

\begin{tabular}{l} \hline
tolist \\ \hline
cclist \\ \hline
bcclist \\ \hline
\end{tabular} &

\begin{tabular}{p{5.5cm}} \hline
Comma-separated list of recipients. 
Comma-separated list of recipients to carbon copy
Comma-separated list of recipients to carbon copy
\end{tabular} &
At least one of these, or the equivalent elements. \\ \hline

\begin{tabular}{l} \hline
message \\ \hline
messagefile \\ \hline
\end{tabular} &
\begin{tabular}{p{5.5cm}} \hline
Message to send in the body of the email.  \\ \hline
File to send as the body of the email. Property values in the file will be expanded. \\ \hline
\end{tabular} &
One of these or a {\tt <message>} element. \\ \hline

messagemimetype & The content type of the message. The default is text/plain. & No \\ \hline
files & Files to send as attachments to the email. Separate multiple file names using a comma or space. You can also use <fileset> elements to specify files. & No \\ \hline
failonerror & flag to indicate whether to halt the build on any error. The default value is true. & No. \\ \hline
includefilenames & Include filename(s) before file contents. Valid only when the plain encoding is used. The default value is false. & No \\ \hline
mailhost & Host name of the SMTP server. The default value is localhost. & No \\ \hline
mailport & TCP port of the SMTP server. The default value is 25. & No \\ \hline
encoding & Specifies the encoding to use for the content of the email. Values are mime, uu, plain, or auto. The default value is auto. & No \\ \hline
subject & Email subject line. & No \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}
\begin{verbatim}
to / cc / bcc / from
\end{verbatim}
Adds an email address element. It takes the following attributes:

\begin{supertabular}{|l|p{6cm}|p{4cm}|} \hline
Attribute & Description & Required \\ \hline
name & The display name for the address. & No \\ \hline
address & The email address. & Yes \\ \hline
\end{supertabular}

{\bf message}\hfil\break

Specifies the message to include in the email body. It takes the
following attributes:

\begin{supertabular}{|l|p{6cm}|p{4cm}|} \hline
Attribute & Description & Required \\ \hline
src & The file to use as the message. & No \\ \hline
mimetype & The content type to use for the message. & No \\ \hline
\end{supertabular}

If the src attribute is not specified, then text can be added inside
the {\tt <message>} element. Property expansion will occur in the message,
whether it is specified as an external file or as text within the
{\tt <message>} element.

\subsubsection{Examples}
\begin{verbatim}  
<mail from="me"
      tolist="you"
      subject="Results of nightly build"
      files="build.log"/>
\end{verbatim}  
Sends an email from me to you with a subject of Results of nightly
build and includes the contents of the file build.log in the body of
the message.
\begin{verbatim}  
<mail mailhost="smtp.myisp.com" mailport="1025" subject="Test build">
  <from address="me@myisp.com"/>
  <to address="all@xyz.com"/>
  <message>The ${buildname} nightly build has completed</message>
  <fileset dir="dist">
    <includes name="**/*.zip"/>
  </fileset>
</mail>
\end{verbatim}  
Sends an eMail from me@myisp.com to all@xyz.com with a subject of Test
Build and attaches any zip files from the dist directory.  The task
will attempt to use JavaMail and fall back to UU encoding or no
encoding in that order depending on what support classes are
available. \$\{buildname\} will be replaced with the buildname property's
value.

\subsection{Manifest}

\subsubsection{Description}

Creates a manifest file.

This task can be used to write a Manifest file, optionally replacing
or updating an existing file.

Manifests are processed according to the Jar file specification..
Specifically, a manifest element consists of a set of attributes and
sections. These sections in turn may contain attributes. Note in
particular that this may result in manifest lines greater than 72
bytes being wrapped and continued on the next line.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{6cm}|p{4cm}|} \hline
Attribute & Description & Required \\ \hline
file & the manifest-file to create/update. & Yes \\ \hline
mode & One of "update" or "replace", default is "replace". & No \\ \hline
encoding & The encoding used to read the existing manifest when updating. & No, defaults to UTF-8 encoding. \\ \hline
\end{supertabular}

\subsubsection{Nested elements}

{\bf attribute}\hfil\break

One attribute for the manifest file. Those attributes that are not
nested into a section will be added to the "Main" section.

\begin{supertabular}{|l|p{6cm}|p{4cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
name & the name of the attribute. & Yes \\ \hline
value & the value of the attribute. & Yes \\ \hline
\end{supertabular}

{\bf section}\hfil\break

A manifest section - you can nest attribute elements into sections.

\begin{supertabular}{|l|p{6cm}|p{4cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
name & the name of the section. & No, if omitted it will be assumed to be the main section. \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
  <manifest file="MANIFEST.MF">
    <attribute name="Built-By" value="${user.name}"/>
    <section name="common">
      <attribute name="Specification-Title" value="Example"/>
      <attribute name="Specification-Version" value="${version}"/>
      <attribute name="Specification-Vendor" value="Example Organization"/>
      <attribute name="Implementation-Title" value="common"/>
      <attribute name="Implementation-Version" value="${version} ${TODAY}"/> 
      <attribute name="Implementation-Vendor" value="Example Corp."/>
    </section>
    <section name="common/class1.class">
      <attribute name="Sealed" value="false"/>
    </section>
  </manifest>
\end{verbatim}  
Creates or replaces the file MANIFEST.MF. Note that the Built-By
  attribute will take the value of the Ant property \$\{user.name\}. The
  same is true for the \$\{version\} and \$\{TODAY\} properties. This
  example produces a MANIFEST.MF that contains package version
  identification for the package common.

The manifest produced by the above would look like this:
\begin{verbatim}
Manifest-Version: 1.0
Built-By: bodewig
Created-By: Apache Ant 1.5alpha

Name: common
Specification-Title: Example
Specification-Vendor: Example Organization
Implementation-Vendor: Example Corp.
Specification-Version: 1.1
Implementation-Version: 1.1 February 19 2002
Implementation-Title: common

Name: common/class1.class
Sealed: false
\end{verbatim}

\subsection{Mkdir}

\subsubsection{Description}

Creates a directory. Also non-existent parent directories are created,
when necessary.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{6cm}|p{4cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
dir & the directory to create. & Yes \\ \hline
\end{supertabular}

Examples
\begin{verbatim}
<mkdir dir="${dist}"/>
\end{verbatim}
creates a directory \$\{dist\}.
\begin{verbatim}
<mkdir dir="${dist}/lib"/>
\end{verbatim}
creates a directory \$\{dist\}/lib.

\subsection{Move}

\subsubsection{Description}

Moves a file to a new file or directory, or sets of files to a new
directory. By default, the destination file is overwritten if it
already exists. When overwrite is turned off, then files are only
moved if the source file is newer than the destination file, or when
the destination file does not exist.

FileSets are used to select sets of files to move to the todir directory.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{6cm}|p{4cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
file & the file to move & One of file or at least one nested fileset element \\ \hline

preservelastmodified & Give the moved files the same last modified time
as the original source files. (Note: Ignored on Java 1.1) & No; defaults to false. \\ \hline

\begin{tabular}{l} \hline
tofile \\ \hline
todir \\ \hline
\end{tabular} &
\begin{tabular}{p{5.5cm}} \hline
the file to move to  \\ \hline
todir the directory to move to \\ \hline
\end{tabular} &
With the file attribute, either tofile or
can be used. With nested filesets, if the fileset size is
greater than 1 or if the only entry in the fileset is a directory or
if the file attribute is already specified, only todir is allowed \\ \hline

overwrite & overwrite existing files even if the destination files are newer (default is "true") & No \\ \hline
filtering & indicates whether token filtering should take place during the move. See the filter task for a description of how filters work. & No \\ \hline
flatten & ignore directory structure of source directory, copy all files into a single directory, specified by the todir attribute (default is "false").Note that you can achieve the same effect by using a flatten mapper & No \\ \hline
includeEmptyDirs & Copy empty directories included with the nested FileSet(s). Defaults to "yes". & No \\ \hline
failonerror & Log a warning message, but do not stop the build, when the file to move does not exist. Only meaningful when moving a single file. & No; defaults to true. \\ \hline
verbose & Log the files that are being moved. & No; defaults to false. \\ \hline
encoding & The encoding to assume when filter-moving the files. since Ant 1.5. & No - defaults to default JVM encoding \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf mapper}\hfil\break

You can define file name transformations by using a nested mapper
element. The default mapper used by {\tt <copy>} is the identity.

{\bf filterchain}\hfil\break

The Move task supports nested FilterChains.

If {\tt <filterset>} and {\tt <filterchain>} elements are used inside the same
{\tt <move>} task, all {\tt <filterchain>}
elements are processed first followed
by {\tt <filterset>} elements.

\subsubsection{Examples}

Move a single file (rename a file)
\begin{verbatim}
  <move file="file.orig" tofile="file.moved"/>
\end{verbatim}
Move a single file to a directory
\begin{verbatim}
  <move file="file.orig" todir="dir/to/move/to"/>
\end{verbatim}
Move a directory to a new directory
\begin{verbatim}
  <move todir="new/dir/to/move/to">
    <fileset dir="src/dir"/>
  </move>
\end{verbatim}
Move a set of files to a new directory
\begin{verbatim}
  <move todir="some/new/dir">
    <fileset dir="my/src/dir">
      <include name="**/*.jar"/>
      <exclude name="**/ant.jar"/>
    </fileset>
  </move>
\end{verbatim}
Append ".bak" to the names of all files in a directory.
\begin{verbatim}
  <move todir="my/src/dir">
    <fileset dir="my/src/dir">
      <exclude name="**/*.bak"/>
    </fileset>
    <mapper type="glob" from="*" to="*.bak"/>
  </move>
\end{verbatim}

\subsection{Parallel}

\subsubsection{Description}

Parallel is a container task - it can contain other Ant tasks. Each
nested task within the parallel task will be executed in its own
thread.

Parallel tasks have a number of uses in an Ant build file including:

\begin{itemize}
\item Taking advantage of available processing resources to reduce build time
\item Testing servers, where the server can be run in one thread and the test harness is run in another thread.
\end{itemize}

Care must be taken when using multithreading to ensure the tasks
within the threads do not interact. For example, two javac compile
tasks which write classes into the same destination directory may
interact where one tries to read a class for dependency information
while the other task is writing the class file. Be sure to avoid these
types of interactions within a {\tt <parallel>} task

The parallel task has no attributes and does not support any nested
elements apart from Ant tasks. Any valid Ant task may be embedded
within a parallel task, including other parallel tasks.

Note that while the tasks within the parallel task are being run, the
main thread will be blocked waiting for all the child threads to
complete.

If any of the tasks within the {\tt <parallel>} task fails, the remaining
tasks in other threads will continue to run until all threads have
completed. In this situation, the parallel task will also fail.

The parallel task may be combined with the sequential task to define
sequences of tasks to be executed on each thread within the parallel
block

\subsubsection{Examples}
\begin{verbatim}
<parallel>
  <wlrun ... >
  <sequential>
    <sleep seconds="30"/>
    <junit ... >
    <wlstop/>
  </sequential>
</parallel>
\end{verbatim}
This example represents a typical pattern for testing a server
application. In one thread the server is started (the wlrun task). The
other thread consists of a three tasks which are performed in
sequence. The sleep task is used to give the server time to come
up. Another task which is capable of validating that the server is
available could be used in place of the sleep task. The test harness
is then run. Once the tests are complete, the server is stopped (using
wlstop in this example), allowing both threads to complete. The
parallel task will also complete at this time and the build will then
continue.
\begin{verbatim}
<parallel>
  <javac ...> <!-- compiler servlet code -->
  <wljspc ...> <!-- precompile JSPs -->
</parallel>
\end{verbatim}
This example shows two independent tasks being run to achieve better
resource utilization during the build. In this instance, some servlets
are being compiled in one thead and a set of JSPs is being precompiled
in another. As noted above, you need to be careful that the two tasks
are independent, both in terms of their dependencies and in terms of
their potential interactions in Ant's external environment.

\subsection{Patch}

\subsubsection{Description}

Applies a diff file to originals. ; requires "patch" to be on the
execution path.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{6cm}|p{4cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
patchfile & the file that includes the diff output & Yes \\ \hline
originalfile & the file to patch & No, tries to guess it from the diff file \\ \hline
backups & Keep backups of the unpatched files & No \\ \hline
quiet & Work silently unless an error occurs & No \\ \hline
reverse & Assume patch was created with old and new files swapped. & No \\ \hline
ignorewhitespace & Ignore whitespace differences. & No \\ \hline
strip & Strip the smallest prefix containing num leading slashes from filenames. & No \\ \hline
dir & The directory in which to run the patch command. & No, default is the project's basedir. \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
  <patch patchfile="module.1.0-1.1.patch"/>
\end{verbatim}
applies the diff included in module.1.0-1.1.patch to the files in base
directory guessing the filename(s) from the diff output.
\begin{verbatim}
  <patch patchfile="module.1.0-1.1.patch" strip="1"/>
\end{verbatim}
like above but one leading directory part will be removed. i.e. if the
diff output looked like
\begin{verbatim}
--- a/mod1.0/A  Mon Jun  5 17:28:41 2000
+++ a/mod1.1/A  Mon Jun  5 17:28:49 200
\end{verbatim}
the leading a/ will be stripped.

\subsection{PathConvert}

\subsubsection{Description}

Converts a nested {\tt <path>} or reference to a Path, FileSet, DirSet, or
FileList into a path form for a particular platform, and stores the
result in a given property. It can also be used when you need to
convert a Path, FileSet, or DirSet into a list, separated by a given
character, such as a comma or space, or, conversely, to convert a list
of files in a FileList into a path.

Nested {\tt <map>} elements can be specified to map Windows drive letters to
Unix paths, and vice-versa.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{6cm}|p{4cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
targetos & The target architecture. Must be one of 'unix', 'windows', 'netware' or 'os/2'. This is a shorthand mechanism for specifying 
both pathsep and dirsep according to the specified target architecture. & Yes, unless pathsep and/or dirsep are specified. \\ \hline
dirsep & The character(s) to use as the directory separator in the generated paths. & No, defaults to current JVM File.separator \\ \hline
pathsep & The character(s) to use as the path-element separator in the generated paths. & No, defaults to current JVM File.pathSeparator \\ \hline
property & The name of the property in which to place the converted path. & Yes \\ \hline
refid & What to convert, given as a reference to a {\tt <path>}, {\tt <fileset>}, {\tt <dirset>}, or {\tt <filelist>} defined elsewhere & No; if omitted, a nested {\tt <path>} element must be supplied. \\ \hline
setonempty & Should the property be set, even if the result is the empty string? & No; default is "true". \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf map}\hfil\break

Specifies the mapping of path prefixes between Unix and Windows.

\begin{supertabular}{|l|p{6cm}|p{4cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
from & The prefix to match. Note that this value is case-insensitive
when the build is running on a Windows platform and case-sensitive 
when running on a Unix platform. & Yes \\ \hline
to & The replacement text to use when from is matched. & Yes \\ \hline
\end{supertabular}

Each map element specifies a single replacement map to be applied to
the elements of the path being processed. If no map entries are
specified, then no path prefix mapping is performed.

Note: The map elements are applied in the order specified, and only
the first matching map element is applied. So, the ordering of your
map elements can be important, if any from values are prefixes of
other from values.

{\bf path}\hfil\break

If the refid attribute is not specified, then a nested <path> element
must be supplied. See Path-like Structures for details.

\subsubsection{Examples}

In the examples below, assume that the \$\{wl.home\} property has the
value d:${\backslash}{\backslash}$weblogic, and \$\{wl.home.unix\} has the value /weblogic.

{\bf Example 1}\hfil\break
\begin{verbatim}
    <path id="wl.path">
      <pathelement location="${wl.home}/lib/weblogicaux.jar"/>
      <pathelement location="${wl.home}/classes"/>
      <pathelement location="${wl.home}/mssqlserver4/classes"/>
      <pathelement location="c:\winnt\System32"/>
    </path>
    
    <pathconvert targetos="unix" property="wl.path.unix" refid="wl.path">
      <map from="${wl.home}" to="${wl.home.unix}"/>
      <map from="c:" to=""/>
    </pathconvert>
\end{verbatim}
will generate the path shown below and store it in the property named
wl.path.unix.

/weblogic/lib/weblogicaux.jar:/weblogic/classes:/weblogic/mssqlserver4/classes:/WINNT/SYSTEM32

{\bf Example 2}\hfil\break
Given a FileList defined as:
\begin{verbatim}
  <filelist id="custom_tasks.jars"
        dir="${env.HOME}/ant/lib"
        files="njavac.jar,xproperty.jar"/>
\end{verbatim}
then:
\begin{verbatim}
    <pathconvert targetos="unix" 
     property="custom_tasks.jars" refid="custom_tasks.jars">
      <map from="${env.HOME}" to="/usr/local"/>
    </pathconvert>
\end{verbatim}
will convert the list of files to the following Unix path:

/usr/local/ant/lib/njavac.jar:/usr/local/ant/lib/xproperty.jar

{\bf Example 3}\hfil\break
\begin{verbatim}
    <fileset dir="${src.dir}" id="src.files">
      <include name="**/*.java"/>
    </fileset>
  
    <pathconvert pathsep="," property="javafiles" refid="src.files"/>
\end{verbatim}
This example takes the set of files determined by the fileset (all
files ending in .java), joins them together separated by commas,
and places the resulting list into the property javafiles. The
directory separator is not specified, so it defaults to the
appropriate character for the current platform. Such a list could
then be used in another task, like javadoc, that requires a comma
separated list of files.

\subsection{Property}

\subsubsection{Description}

Sets a property (by name and value), or set of properties (from file
or resource) in the project. Properties are case sensitive.

Properties are immutable: whoever sets a property first freezes it for
the rest of the build; they are most definately not variable.

There are five ways to set properties:
\begin{enumerate}
\item By supplying both the name and value attribute.
\item By supplying both the name and refid attribute.
\item By setting the file attribute with the filename of the property file to load. This property file has the format as defined by the file used in the class java.util.Properties.
\item By setting the resource attribute with the resource name of the property file to load. This property file has the format as defined by the file used in the class java.util.Properties.
\item By setting the environment attribute with a prefix to use. Properties will be defined for every environment variable by prefixing the supplied name and a period to the name of the variable.
\end{enumerate}

Although combinations of these ways are possible, only one should be
used at a time. Problems might occur with the order in which
properties are set, for instance.

The value part of the properties being set, might contain references
to other properties. These references are resolved at the time these
properties are set. This also holds for properties loaded from a
property file.

A list of predefined properties can be found here.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
name & the name of the property to set. & No \\ \hline
\begin{tabular}{l}
value \\ \hline
location \\ \hline
refid \\ \hline
\end{tabular} &
\begin{tabular}{p{6.5cm}}
the value of the property.  \\ \hline
Sets the property to the absolute filename of the given file. 
If the value of this attribute is an absolute path, 
it is left unchanged (with / and \\ characters converted to 
the current platforms conventions). Otherwise it is taken as
a path relative to the project's basedir and expanded. \\ \hline
Reference to an object defined elsewhere. 
Only yields reasonable results for references to PATH like 
structures or properties. \\ \hline
\end{tabular} &
One of these, when using the name attribute \\ \hline

\begin{tabular}{l}
resource \\ \hline
file \\ \hline
environment \\ \hline
\end{tabular} &
\begin{tabular}{p{6.5cm}}
the resource name of the property file.  \\ \hline
the filename of the property file. \\ \hline
the prefix to use when retrieving environment variables. 
Thus if you specify environment="myenv" you will be able
to access OS-specific environment variables via property 
names "myenv.PATH" or "myenv.TERM". Note that if you supply
a property name with a final "." it will not be doubled. 
i.e. environment="myenv." will still allow access of
environment variables through "myenv.PATH" and "myenv.TERM". 
This functionality is currently only implemented on select platforms. 
Feel free to send patches to increase the number of 
platforms this functionality is supported on ;). 

Note also that properties are case sensitive, even if the environment
variables on your operating system are not, e.g. it will be
${env.Path} not ${env.PATH} on Windows 2000.  \\ \hline
\end{tabular} &
One of these, when not using the name attribute \\ \hline

classpath & the classpath to use when looking up a resource. & No \\ \hline
classpathref & the classpath to use when looking up a resource, given as reference to a <path> defined elsewhere.. & No \\ \hline
prefix & Prefix to apply to properties loaded using file or resource. A "." is appended to the prefix if not specified. & No \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf classpath}\hfil\break

Property's classpath attribute is a PATH like structure and can also
be set via a nested classpath element.

Examples
\begin{verbatim}
  <property name="foo.dist" value="dist"/>
\end{verbatim}
sets the property foo.dist to the value "dist".
\begin{verbatim}
  <property file="foo.properties"/>
\end{verbatim}
reads a set of properties from a file called "foo.properties".
\begin{verbatim}
  <property resource="foo.properties"/>
\end{verbatim}
reads a set of properties from a resource called "foo.properties".

Note that you can reference a global properties file for all of your Ant builds using the following:
\begin{verbatim}
  <property file="${user.home}/.ant-global.properties"/>
\end{verbatim}
since the "user.home" property is defined by the Java virtual machine to be your home directory. This technique is more appropriate for Unix than Windows since the notion of a home directory doesn't exist on Windows. On the JVM that I tested, the home directory on Windows is "C:\". Different JVM implementations may use other values for the home directory on Windows.
\begin{verbatim}
  <property environment="env"/>
  <echo message="Number of Processors = ${env.NUMBER_OF_PROCESSORS}"/>
  <echo message="ANT_HOME is set to = ${env.ANT_HOME}"/>
\end{verbatim}
reads the system environment variables and stores them in properties,
prefixed with "env". Note that this only works on select operating
systems. Two of the values are shown being echoed.

\subsection{Record}

\subsubsection{Description}

A recorder is a listener to the current build process that records the output to a file.

Several recorders can exist at the same time. Each recorder is
associated with a file. The filename is used as a unique identifier
for the recorders. The first call to the recorder task with an unused
filename will create a recorder (using the parameters provided) and
add it to the listeners of the build. All subsequent calls to the
recorder task using this filename will modify that recorders state
(recording or not) or other properties (like logging level).

Some technical issues: the file's print stream is flushed for
"finished" events (buildFinished, targetFinished and taskFinished),
and is closed on a buildFinished event.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
name & The name of the file this logger is associated with. & yes \\ \hline
action & This tells the logger what to do: should it start recording or stop? The first time that the recorder task is called for this logfile, and if this attribute is not provided, then the default for this attribute is "start". If this attribute is not provided on subsequent calls, then the state remains as previous. [Values = {start|stop}, Default = no state change] & no \\ \hline
append & Should the recorder append to a file, or create a new one? This is only applicable the first time this task is called for this file. [Values = {yes|no}, Default=yes] & no \\ \hline
emacsmode & Removes [task] banners like Ant's -emacs command line switch if set to true. & no, default is false \\ \hline
loglevel & At what logging level should this recorder instance record to? This is not a once only parameter (like append is) -- you can increase or decrease the logging level as the build process continues. [Values= {error|warn|info|verbose|debug}, Default = no change] & no \\ \hline
\end{supertabular}

\subsubsection{Examples}

The following build.xml snippet is an example of how to use the
recorder to record just the {\tt <javac>} task:
\begin{verbatim}
    ...
    <compile >
        <record name="log.txt" action="start"/>
        <javac ...
        <record name="log.txt" action="stop"/>
    <compile/>
    ...
\end{verbatim}
The following two calls to <record> set up two recorders: one to file "records-simple.log" at logging level info (the default) and one to file "ISO.log" using logging level of verbose.
\begin{verbatim}
    ...
    <record name="records-simple.log"/>
    <record name="ISO.log" loglevel="verbose"/>
    ...
\end{verbatim}

\subsubsection{Notes}

There is some functionality that I would like to be able to add in the
future. They include things like the following:

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
listener & A classname of a build listener to use from this point on instead of the default listener. & no \\ \hline
includetarget & A comma-separated list of targets to automatically record. If this value is "all", then all targets are recorded. [Default = all] & no \\ \hline
excludetarget & A comma-separated list of targets to automatically record. If this value is "all", then all targets are recorded. [Default = all] & no \\ \hline

\begin{tabular}{l}
includetask \\ \hline
excludetask \\ \hline
\end{tabular} &
\begin{tabular}{p{6.5cm}} \hline
A comma-separated list of task to automatically record or not. This
could be difficult as it could conflict with the
includetarget/excludetarget. (e.g.: includetarget="compile"
excludetask="javac", what should happen?)
\end{tabular} &
no \\ \hline

action & add greater flexibility to the action attribute. Things like close to close the print stream. & no \\ \hline
\end{supertabular}

\subsection{Rename}

{\em Deprecated}\hfil\break

This task has been deprecated. Use the Move task instead.

\subsubsection{Description}

Renames a given file.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
src & file to rename. & Yes \\ \hline
dest & new name of the file. & Yes \\ \hline
replace & Enable replacing of existing file (default: on). & No \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
  <rename src="foo.jar" dest="${name}-${version}.jar"/>
\end{verbatim}
Renames the file foo.jar to ${name}-${version}.jar (assuming name and
version being predefined properties). If a file named
${name}-${version}.jar already exists, it will be removed prior to
renaming foo.jar.

\subsection{Replace}

\subsubsection{Description}

Replace is a directory based task for replacing the occurrence of a
given string with another string in selected file.

If you want to replace a text that crosses line boundaries, you must
use a nested {\tt <replacetoken>} element.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
\begin{tabular}{l} \hline
file \\ \hline
dir \\ \hline
\end{tabular} &
\begin{tabular}{p{6.5cm}} \hline
file for which the token should be replaced.  \\ \hline
The base directory to use when replacing a token in multiple files. \\ \hline
\end{tabular} &
Exactly one of the two. \\ \hline

encoding & The encoding of the files upon which replace operates. & No - defaults to default JVM encoding \\ \hline

token & the token which must be replaced. & Yes, unless a nested
replacetoken element or the replacefilterfile attribute is used. \\ \hline

value & the new value for the token. When omitted, an empty string ("") is used. & No \\ \hline

summary & Indicates whether a summary of the replace operation should
be produced, detailing how many token occurrences and files were
processed & No, by default no summary is produced \\ \hline

propertyFile & valid property file from which properties specified using
nested {\tt <replacefilter>} elements are drawn. & Yes only if property
attribute of {\tt <replacefilter>} is used. \\ \hline

replacefilterfile & valid property file. Each property will be treated as a replacefilter where token is the name of the property and value is the properties value. & No. \\ \hline
includes & comma- or space-separated list of patterns of files that must be included. All files are included when omitted. & No \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & No \\ \hline
excludes & comma- or space-separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & No \\ \hline
defaultexcludes & indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
  <replace file="${src}/index.html" token="@@@" value="wombat"/>
\end{verbatim}
replaces occurrences of the string "@@@" with the string "wombat", in
the file \$\{src\}/index.html.

\subsubsection{Parameters specified as nested elements}

This task forms an implicit FileSet and supports all attributes of
{\tt <fileset>} as well as the nested {\tt <include>}, 
{\tt <exclude>} and {\tt <patternset>} elements.

If either the text you want to replace or the replacement text cross
line boundaries, you can use nested elements to specify them.

\subsubsection{Examples}
\begin{verbatim}
<replace dir="${src}" value="wombat">
  <include name="**/*.html"/>
  <replacetoken><![CDATA[multi line
token]]></replacetoken>
</replace>
\end{verbatim}
replaces occurrences of the string "multi line\\ntoken" with the string
"wombat", in all HTML files in the directory \$\{src\}.Where \\n is the
platform specific line separator.
\begin{verbatim}
<replace file="${src}/index.html">
  <replacetoken><![CDATA[two line
token]]></replacetoken>
  <replacevalue><![CDATA[two line
token]]></replacevalue>
</replace>
\end{verbatim}

{\bf replacefilter}\hfil\break

In addition to allowing for multiple replacements, optional nested
{\tt <replacefilter>} elements allow replacement values to be extracted from
a property file. The name of this file is specified using the
{\tt <replace>} attribute propertyFile.

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
token & The string to search for. & Yes \\ \hline
\begin{tabular}{l}
value \\ \hline
property \\ \hline
\end{tabular} &
\begin{tabular}{p{6.5cm}}
The replacement string.  \\ \hline
Name of the property whose value is to serve as the replacement value. \\ \hline
\end{tabular} &
Either may be specified, but not both. Both can be omitted, if desired. \\ \hline
\end{supertabular}

If neither value nor property is used, the value provided using the
{\tt <replace>} attribute value and/or the 
{\tt <replacevalue>} element is used.
If no value was specified using either of these options, the token is
replaced with an empty string.

\subsubsection{Examples}
\begin{verbatim}
<replace 
    file="configure.sh"
    value="defaultvalue"
    propertyFile="source/name.properties">
  <replacefilter 
    token="@token1@"/>
  <replacefilter 
    token="@token2@" 
    value="value2"/>
  <replacefilter 
    token="@token3@" 
    property="property.key"/>
</replace>
\end{verbatim}
In file configure.sh, replace all instances of "@token1@" with
"defaultvalue", all instances of "@token2@" with "value2", and all
instances of "@token3@" with the value of the property "property.key",
as it appears in property file src/name.properties.

Note: It is possible to use either the {\tt token/<replacetoken>} and
{\tt value/<replacevalue>} attributes/elements, the nested replacefilter
elements, or both in the same operation.

\subsection{Rmic}

\subsubsection{Description}

Runs the rmic compiler for a certain class.

Rmic can be run on a single class (as specified with the classname
attribute) or a number of classes at once (all classes below base that
are neither \_Stub nor \_Skel classes). If you want to rmic a single
class and this class is a class nested into another class, you have to
specify the classname in the form Outer\$\$Inner instead of Outer.Inner.

It is possible to refine the set of files that are being rmiced. This
can be done with the includes, includesfile, excludes, excludesfile
and defaultexcludes attributes. With the includes or includesfile
attribute you specify the files you want to have included by using
patterns. The exclude or excludesfile attribute is used to specify the
files you want to have excluded. This is also done with patterns. And
finally with the defaultexcludes attribute, you can specify whether
you want to use default exclusions or not. See the section on
directory based tasks, on how the inclusion/exclusion of files works,
and how to write patterns.

This task forms an implicit FileSet and supports all attributes of
{\tt <fileset>} (dir becomes base) as well as the nested
{\tt  <include>}, {\tt <exclude>} and {\tt <patternset>} elements.

It is possible to use different compilers. This can be selected with
the "build.rmic" property or the compiler attribute. There are three
choices:
\begin{enumerate}
\item sun (the standard compiler of the JDK)
\item kaffe (the standard compiler of Kaffe)
\item weblogic
\end{enumerate}    
The miniRMI project contains a compiler implementation for this
task as well, please consult miniRMI's documentation to learn how
to use it.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
base & the location to store the compiled files. & Yes \\ \hline
classname & the class for which to run rmic. & No \\ \hline
filtering & indicates whether token filtering should take place & No \\ \hline
sourcebase & Pass the "-keepgenerated" flag to rmic and move the generated source file to the given sourcebase directory. & No \\ \hline
stubversion & Specify the JDK version for the generated stub code. Specify "1.1" to pass the "-v1.1" option to rmic. & No \\ \hline
classpath & The classpath to use during compilation & No \\ \hline
classpathref & The classpath to use during compilation, given as reference to a PATH defined elsewhere & No \\ \hline
includes & comma- or space-separated list of patterns of files that must be included. All files are included when omitted. & No \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & No \\ \hline
excludes & comma- or space-separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & No \\ \hline
defaultexcludes & indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline
verify & check that classes implement Remote before handing them to rmic (default is false) & No \\ \hline
iiop & indicates that portable (RMI/IIOP) stubs should be generated & No \\ \hline
iiopopts & additional arguments for IIOP class generation & No \\ \hline
idl & indicates that IDL output files should be generated & No \\ \hline
idlopts & additional arguments for IDL file generation & No \\ \hline
debug & generate debug info (passes -g to rmic). Defaults to false. & No \\ \hline
includeAntRuntime & whether to include the Ant run-time libraries; defaults to yes. & No \\ \hline
includeJavaRuntime & whether to include the default run-time libraries from the executing VM; defaults to no. & No \\ \hline
extdirs & location of installed extensions. & No \\ \hline
compiler & The compiler implementation to use. If this attribute is not set, the value of the build.rmic property, if set, will be used. Otherwise, the default compiler for the current VM will be used. (See the above list of valid compilers.) & No \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf classpath and extdirs}\hfil\break

Rmic's classpath and extdirs attributes are PATH like structure and
can also be set via a nested classpath and extdirs elements.

{\bf compilerarg}\hfil\break

You can specify additional command line arguments for the compiler
with nested {\tt <compilerarg>} elements. These elements are specified like
Command-line Arguments but have an additional attribute that can be
used to enable arguments only if a given compiler implementation will
be used.

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
\begin{tabular}{l} \hline
value \\ \hline
line \\ \hline
file \\ \hline
path \\ \hline
\end{tabular} &
\begin{tabular}{p{6.5cm}} \hline
See Command-line Arguments. 
\end{tabular} &
Exactly one of these. \\ \hline

compiler & Only pass the specified argument if the chosen compiler
implementation matches the value of this attribute. Legal values are
the same as those in the above list of valid compilers.) & No \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
  <rmic classname="com.xyz.FooBar" base="${build}/classes"/>
\end{verbatim}
runs the rmic compiler for the class com.xyz.FooBar. The compiled
files will be stored in the directory \$\{build\}/classes.
\begin{verbatim}
  <rmic base="${build}/classes" includes="**/Remote*.class"/>
\end{verbatim}  
runs the rmic compiler for all classes with .class files below
\$\{build\}/classes whose classname starts with Remote. The compiled
files will be stored in the directory \$\{build\}/classes.

\subsection{Sequential}

\subsubsection{Description}

Sequential is a container task - it can contain other Ant tasks. The
nested tasks are simply executed in sequence. Sequential's primary use
is to support the sequential execution of a subset of tasks within the
parallel task

The sequential task has no attributes and does not support any nested
elements apart from Ant tasks. Any valid Ant task may be embedded
within the sequential task.

\subsubsection{Example}
\begin{verbatim}
<parallel>
  <wlrun ... >
  <sequential>
    <sleep seconds="30"/>
    <junit ... >
    <wlstop/>
  </sequential>
</parallel>
\end{verbatim}  
This example shows how the sequential task is used to execute three
tasks in sequence, while another task is being executed in a separate thread.

\subsection{SignJar}

\subsubsection{Description}

Signs jar or zip files with the javasign command line tool. The tool detailed dependency checking: files are only signed if they are not signed. The signjar attribute can point to the file to generate; if this file exists then its modification date is used as a cue as to whether to resign any JAR file.
Note: Requires Java 1.2 or later.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
jar & the jar file to sign & Yes, unless nested filesets have been used. \\ \hline
alias & the alias to sign under & Yes. \\ \hline
storepass & password for keystore integrity. & Yes. \\ \hline
keystore & keystore location & No \\ \hline
storetype & keystore type & No \\ \hline
keypass & password for private key (if different) & No \\ \hline
sigfile & name of .SF/.DSA file & No \\ \hline
signedjar & name of signed JAR file & No \\ \hline
verbose & (true | false) verbose output when signing & No; default false \\ \hline
internalsf & (true | false) include the .SF file inside the signature block & No; default false \\ \hline
sectionsonly & (true | false) don't compute hash of entire manifest & No; default false \\ \hline
lazy & flag to control whether the presence of a signature file means a JAR is signed & No; default false \\ \hline
maxmemory & Specifies the maximum memory the jarsigner VM will use. Specified in the style of standard java memory specs (e.g. 128m = 128 MBytes) & No \\ \hline
\end{supertabular}

\subsubsection{Parameters as nested elements}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
fileset & fileset of JAR files to sign. Will be ignored if the jar
attribute of the task has been set. & No \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
<signjar jar="${dist}/lib/ant.jar" alias="apache-group" storepass="secret"/>
\end{verbatim}
signs the ant.jar with alias "apache-group" accessing the keystore and private key via "secret" password.

\subsection{Sleep}

\subsubsection{Description}

A task for sleeping a short period of time, useful when a build or
deployment process requires an interval between tasks.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
hours & hours to to add to the sleep time & No \\ \hline
minutes & minutes to add to the sleep time & No \\ \hline
seconds & seconds to add to the sleep time & No \\ \hline
milliseconds & milliseconds to add to the sleep time & No \\ \hline
failonerror & flag controlling whether to break the build on an error. & No \\ \hline
\end{supertabular}

The sleep time is the sum of specified values, hours, minutes seconds
and milliseconds. A negative value can be supplied to any of them
provided the total sleep time is positive

Note that sleep times are always hints to be interpred by the OS how
it feels - small times may either be ignored or rounded up to a
minimum timeslice. Note also that the system clocks often have a
fairly low granularity too, which complicates measuring how long a
sleep actually took.

\subsubsection{Examples}
\begin{verbatim}
   <sleep milliseconds="10"/>
\end{verbatim}
Sleep for about 10 mS.
\begin{verbatim}
   <sleep seconds="2"/>
\end{verbatim}
Sleep for about 2 seconds.
\begin{verbatim}
   <sleep hours="1" minutes="-59" seconds="-58"/>
\end{verbatim}
Sleep for one hour less 59:58, or two seconds again
\begin{verbatim}
   <sleep/>
\end{verbatim}
Sleep for no time at all. This may yield the CPU time to another
thread or process.

\subsection{Sql}

\subsubsection{Description}

Executes a series of SQL statements via JDBC to a database. Statements
can either be read in from a text file using the src attribute or from
between the enclosing SQL tags.

Multiple statements can be provided, separated by semicolons (or the
defined delimiter). Individual lines within the statements can be
commented using either --, // or REM at the start of the line.

The autocommit attribute specifies whether auto-commit should be
turned on or off whilst executing the statements. If auto-commit is
turned on each statement will be executed and committed. If it is
turned off the statements will all be executed as one transaction.

The onerror attribute specifies how to proceed when an error occurs
during the execution of one of the statements. The possible values
are: continue execution, only show the error; stop execution and
commit transaction; and abort execution and transaction and fail task.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
driver & Class name of the jdbc driver & Yes \\ \hline
url & Database connection url & Yes \\ \hline
userid & Database user name & Yes \\ \hline
password & Database password & Yes \\ \hline
src & File containing SQL statements & Yes, unless statements enclosed within tags \\ \hline
encoding & The encoding of the files containing SQL statements & No - defaults to default JVM encoding \\ \hline
delimiter & String that separates SQL statements & No, default ";" \\ \hline
autocommit & Auto commit flag for database connection (default false) & No, default "false" \\ \hline
print & Print result sets from the statements (default false) & No, default "false" \\ \hline
showheaders & Print headers for result sets from the statements (default true) & No, default "true" \\ \hline
output & Output file for result sets (defaults to System.out) & No (print to System.out by default) \\ \hline
append & whether output should be appended to or overwrite an existing file. Defaults to false. & No \\ \hline
classpath & Classpath used to load driver & No (use system classpath) \\ \hline
classpathref & The classpath to use, given as a reference to a path defined elsewhere. & No (use system classpath) \\ \hline
onerror & Action to perform when statement fails: continue, stop, abort & No, default "abort" \\ \hline
rdbms & Execute task only if this rdbms & No (no restriction) \\ \hline
version & Execute task only if rdbms version match & No (no restriction) \\ \hline
caching & Should the task cache loaders and the driver? & No (default=true) \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf transaction}\hfil\break

Use nested {\tt <transaction>} elements to specify multiple blocks of
commands to the executed executed in the same connection but different
transactions. This is particularly useful when there are multiple
files to execute on the same schema.

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
src & File containing SQL statements & Yes, unless statements enclosed within tags \\ \hline
\end{supertabular}

{\bf fileset}\hfil\break

You can specify multiple source files via nested fileset
elements. Each file of the fileset will be run in a transaction of its
own, the order by which the files of a single fileset will be executed
is not defined.

{\bf classpath}\hfil\break

Sql's classpath attribute is a PATH like structure and can also be set
via a nested classpath element. It is used to load the JDBC classes.

{\bf Examples}\hfil\break
\begin{verbatim}
<sql
    driver="org.database.jdbcDriver"
    url="jdbc:database-url"
    userid="sa"
    password="pass"
    src="data.sql"
/>
\end{verbatim}
Connects to the database given in url as the sa user using the
org.database.jdbcDriver and executes the SQL statements contained
within the file data.sql
\begin{verbatim}
<sql
    driver="org.database.jdbcDriver"
    url="jdbc:database-url"
    userid="sa"
    password="pass"
    >
insert
into table some_table
values(1,2,3,4);

truncate table some_other_table;
</sql>
\end{verbatim}
Connects to the database given in url as the sa user using the
org.database.jdbcDriver and executes the two SQL statements inserting
data into some\_table and truncating some\_other\_table

Note that you may want to enclose your statements in {\tt <![CDATA[ ... ]]>}
sections so you don't need to escape {\tt <}, {\tt >} \& or other special
characters. For example:
\begin{verbatim}
<sql
    driver="org.database.jdbcDriver"
    url="jdbc:database-url"
    userid="sa"
    password="pass"
    ><![CDATA[
\end{verbatim}
update some\_table set column1 = column1 + 1 where column2 {\tt <} 42;
\begin{verbatim}
]]></sql>
\end{verbatim}
The following connects to the database given in url as the sa user
using the org.database.jdbcDriver and executes the SQL statements
contained within the files data1.sql, data2.sql and data3.sql and then
executes the truncate operation on some\_other\_table.
\begin{verbatim}
<sql
    driver="org.database.jdbcDriver"
    url="jdbc:database-url"
    userid="sa"
    password="pass" >
  <transaction  src="data1.sql"/>
  <transaction  src="data2.sql"/>
  <transaction  src="data3.sql"/>
  <transaction>
    truncate table some_other_table;
  </transaction>
</sql>
\end{verbatim}
The following example does the same as (and may execute additional SQL
files if there are more files matching the pattern data*.sql) but
doesn't guarantee that data1.sql will be run before data2.sql.
\begin{verbatim}
<sql
    driver="org.database.jdbcDriver"
    url="jdbc:database-url"
    userid="sa"
    password="pass">
  <fileset dir=".">
    <include name="data*.sql"/>
  </fileset>
  <transaction>
    truncate table some_other_table;
  </transaction>
</sql>
\end{verbatim}
The following connects to the database given in url as the sa user
using the org.database.jdbcDriver and executes the SQL statements
contained within the file data.sql, with output piped to
outputfile.txt, searching /some/jdbc.jar as well as the system
classpath for the driver class.
\begin{verbatim}
<sql
    driver="org.database.jdbcDriver"
    url="jdbc:database-url"
    userid="sa"
    password="pass"
    src="data.sql"
    print="yes"
    output="outputfile.txt"
    >
<classpath>
        <pathelement location="/some/jdbc.jar"/>
</classpath>
</sql>
\end{verbatim}
The following will only execute if the RDBMS is "oracle" and the
version starts with "8.1."
\begin{verbatim}
<sql
    driver="org.database.jdbcDriver"
    url="jdbc:database-url"
    userid="sa"
    password="pass"
    src="data.sql"
    rdbms="oracle"
    version="8.1."
    >
insert
into table some_table
values(1,2,3,4);

truncate table some_other_table;
</sql>
\end{verbatim}

\subsection{Xslt/Style}

\subsubsection{Description}

Process a set of documents via XSLT.

This is useful for building views of XML based documentation, or for
generating code.

Note: This task depends on external libraries not included in the Ant
distribution. See Library Dependencies for more information.

It is possible to refine the set of files that are being processed.
This can be done with the includes, includesfile, excludes,
excludesfile and defaultexcludes attributes. With the includes or
includesfile attribute you specify the files you want to have included
by using patterns. The exclude or excludesfile attribute is used to
specify the files you want to have excluded. This is also done with
patterns. And finally with the defaultexcludes attribute, you can
specify whether you want to use default exclusions or not. See the
section on directory based tasks, on how the inclusion/exclusion of
files works, and how to write patterns.

This task forms an implicit FileSet and supports all attributes of
{\tt <fileset>} (dir becomes basedir) as well as the nested
{\tt <include>},
{\tt <exclude>} and {\tt <patternset>} elements.

This task supports the use of a nested {\tt <param>} element which is used
to pass values to an <xsl:param> declaration.

This task supports the use of a nested xmlcatalog element which is
used to perform Entity and URI resolution

{\tt <style>} and {\tt <xslt>} refer to the same Ant 
task and can be used interchangeably.

If you want to use Xalan-J 1 or XSL:P, you also need Ant's optional.jar

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
basedir & where to find the source XML file, default is the project's basedir. & No \\ \hline
destdir & directory in which to store the results. & Yes, unless in and out have been specified. \\ \hline
extension & desired file extension to be used for the targets. If not specified, the default is ".html". & No \\ \hline
style & name of the stylesheet to use - given either relative to the project's basedir or as an absolute path DEPRECATED - can be specified as a path relative to the basedir attribute of this task as well. & Yes \\ \hline
classpath & the classpath to use when looking up the XSLT processor. & No \\ \hline
classpathref & the classpath to use, given as reference to a path defined elsewhere. & No \\ \hline
force & Recreate target files, even if they are newer than their corresponding source files or the stylesheet. & No; default is false \\ \hline
processor & name of the XSLT processor to use. Permissible values are "trax" for a TraX compliant processor (ie JAXP interface implementation such as Xalan 2 or Saxon), "xslp" for the XSL:P processor, "xalan" for the Apache XML Xalan (version 1) processor the name of an arbitrary XSLTLiaison class. Defaults to trax, followed by xalan and then xslp (in that order). The first one found in your class path is the one that is used. DEPRECATED - XSL:P and xalan are deprecated and no more supported.. & No \\ \hline
includes & comma- or space-separated list of patterns of files that must be included. All files are included when omitted. & No \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & No \\ \hline
excludes & comma- or space-separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & No \\ \hline
defaultexcludes & indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline
in & specifies a single XML document to be styled. Should be used with the out attribute. & No \\ \hline
out & specifies the output name for the styled result from the in attribute. & No \\ \hline
scanincludeddirectories & If any directories are matched by the includes/excludes patterns, try to transform all files in these directories. Default is true & No \\ \hline
reloadstylesheet & Control whether the stylesheet transformer is created anew for every transform opertaion. If you set this to true, performance may suffer, but you may work around a bug in certain Xalan-J versions. Default is false. Since Ant 1.5.2. & No \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf classpath}\hfil\break

The classpath to load the processor from can be specified via a nested
<classpath>, as well - that is, a path-like structure.

{\bf xmlcatalog}\hfil\break

The xmlcatalog element is used to perform Entity and URI resolution.

{\bf param}\hfil\break

Param is used to pass a parameter to the XSL stylesheet.

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
name & Name of the XSL parameter & Yes \\ \hline
expression & XSL expression to be placed into the param. To pass a text value into the style sheet it needs to be escaped using single quotes. & Yes \\ \hline
\end{supertabular}

{\bf outputproperty ('trax' processors only)}\hfil\break

Used to specify how you wish the result tree to be output as specified
in the XSLT specifications.

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
name & Name of the property & Yes \\ \hline
value & value of the property. & Yes \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
<style basedir="doc" destdir="build/doc"
       extension=".html" style="style/apache.xsl"/>
\end{verbatim}
Using an xmlcatalog
\begin{verbatim}
<xslt basedir="doc" destdir="build/doc"
      extension=".html" style="style/apache.xsl">
  <xmlcatalog refid="mycatalog"/>
</xslt>

<xslt basedir="doc" destdir="build/doc"
   extension=".html" style="style/apache.xsl">
   <xmlcatalog>
       <dtd
         publicId="-//ArielPartners//DTD XML Article V1.0//EN"
         location="com/arielpartners/knowledgebase/dtd/article.dtd"/>
   </xmlcatalog>
</xslt>
\end{verbatim}
Using XSL parameters
\begin{verbatim}
<xslt basedir="doc" destdir="build/doc"
      extension=".html" style="style/apache.xsl">
  <param name="date" expression="07-01-2000"/>
</xslt>
\end{verbatim}
Then if you declare a global parameter "date" with the top-level
element <xsl:param name="date"/>, the variable \$date will subsequently
have the value 07-01-2000.

Using output properties
\begin{verbatim}
<xslt in="doc.xml" out="build/doc/output.xml"
      style="style/apache.xsl">
  <outputproperty name="method" value="xml";/>
  <outputproperty name="standalone" value="yes"/>
  <outputproperty name="encoding" value="iso8859_1"/>
  <outputproperty name="indent" value="yes"/>
</xslt>
\end{verbatim}

\subsection{Tar}

\subsubsection{Description}

Creates a tar archive.

The basedir attribute is the reference directory from where to tar.

This task is a directory based task and, as such, forms an implicit
Fileset. This defines which files, relative to the basedir, will be
included in the archive. The tar task supports all the attributes of
Fileset to refine the set of files to be included in the implicit
fileset.

In addition to the implicit fileset, the tar task supports nested
filesets. These filesets are extended to allow control over the access
mode, username and groupname to be applied to the tar entries. This is
useful, for example, when preparing archives for Unix systems where
some files need to have execute permission.

Early versions of tar did not support path lengths greater than 100
characters. Modern versions of tar do so, but in incompatible ways.
The behaviour of the tar task when it encounters such paths is
controlled by the longfile attribute. If the longfile attribute is set
to fail, any long paths will cause the tar task to fail. If the
longfile attribute is set to truncate, any long paths will be
truncated to the 100 character maximum length prior to adding to the
archive. If the value of the longfile attribute is set to omit then
files containing long paths will be omitted from the archive. Either
option ensures that the archive can be untarred by any compliant
version of tar. If the loss of path or file information is not
acceptable, and it rarely is, longfile may be set to the value gnu.
The tar task will then produce a GNU tar file which can have arbitrary
length paths. Note however, that the resulting archive will only be
able to be untarred with GNU tar. The default for the longfile
attribute is warn which behaves just like the gnu option except that
it produces a warning for each file path encountered that does not
match the limit.

This task can perform compression by setting the compression attribute
to "gzip" or "bzip2".

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
destfile & the tar-file to create. & Yes \\ \hline
basedir & the directory from which to tar the files. & No \\ \hline
longfile & Determines how long files (>100 chars) are to be handled. Allowable values are "truncate", "fail", "warn", "omit" and "gnu". Default is "warn". & No \\ \hline
includes & comma- or space-separated list of patterns of files that must be included. All files are included when omitted. & No \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & No \\ \hline
excludes & comma- or space-separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & No \\ \hline
defaultexcludes & indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline
compression & compression method. Allowable values are "none", "gzip" and "bzip2". Default is "none". & No \\ \hline
\end{supertabular}

\subsubsection{Nested Elements}

The tar task supports nested tarfileset elements. These are extended
Filesets which, in addition to the standard fileset elements, support
three additional attributes

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
mode & A 3 digit octal string, specify the user, group and other modes in the standard Unix fashion & No \\ \hline
username & The username for the tar entry. This is not the same as the UID, which is not currently set by the tar task. & No \\ \hline
group & The groupname for the tar entry. This is not the same as the GID, which is not currently set by the tar task. & No \\ \hline
prefix & If the prefix attribute is set, all files in the fileset are prefixed with that path in the archive. & No \\ \hline
fullpath & If the fullpath attribute is set, the file in the fileset is written with that path in the archive. The prefix attribute, if specified, is ignored. It is an error to have more than one file specified in such a fileset. & No \\ \hline
preserveLeadingSlashes & Indicates whether leading `/'s should be preserved in the file names. Default is false. & No \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
  <tar tarfile="${dist}/manual.tar" basedir="htdocs/manual"/>
  <gzip zipfile="${dist}/manual.tar.gz" src="${dist}/manual.tar"/>
\end{verbatim}
tars all files in the htdocs/manual directory into a file called manual.tar
in the \$\{dist\} directory, then applies the gzip task to compress it.
\begin{verbatim}
  <tar destfile="${dist}/manual.tar"
       basedir="htdocs/manual"
       excludes="mydocs/**, **/todo.html"
  />
\end{verbatim}
tars all files in the htdocs/manual directory into a file called
manual.tar in the \$\{dist\} directory. Files in the directory mydocs, or
files with the name todo.html are excluded.
\begin{verbatim}
<tar destfile="${basedir}/docs.tar">
  <tarfileset dir="${dir.src}/docs"
              fullpath="/usr/doc/ant/README"
              preserveLeadingSlashes="true">
    <include name="readme.txt"/>
  </tarfileset>
  <tarfileset dir="${dir.src}/docs"
              prefix="/usr/doc/ant"
              preserveLeadingSlashes="true">
    <include name="*.html"/>
  </tarfileset>
</tar>
\end{verbatim}
Writes the file docs/readme.txt as /usr/doc/ant/README into the
archive. All *.html files in the docs directory are prefixed by
/usr/doc/ant, so for example docs/index.html is written as
/usr/doc/ant/index.html to the archive.
\begin{verbatim}
<tar longfile="gnu"
     destfile="${dist.base}/${dist.name}-src.tar" >
  <tarfileset dir="${dist.name}/.." mode="755" username="ant" group="ant">
    <include name="${dist.name}/bootstrap.sh"/>
    <include name="${dist.name}/build.sh"/>
  </tarfileset>
  <tarfileset dir="${dist.name}/.." username="ant" group="ant">
    <include name="${dist.name}/**"/>
    <exclude name="${dist.name}/bootstrap.sh"/>
    <exclude name="${dist.name}/build.sh"/>
  </tarfileset>
</tar> 
\end{verbatim}
This example shows building a tar which uses the GNU extensions for
long paths and where some files need to be marked as executable (mode~755)
and the rest are use the default mode (read-write by owner). The
first fileset selects just the executable files. The second fileset
must exclude the executable files and include all others.

Note: The tar task does not ensure that a file is only selected by one
fileset. If the same file is selected by more than one fileset, it
will be included in the tar file twice, with the same path.

Note: The patterns in the include and exclude elements are considered
to be relative to the corresponding dir attribute as with all other
filesets. In the example above, \$\{dist.name\} is not an absolute path,
but a simple name of a directory, so \$\{dist.name\} is a valid path
relative to \$\{dist.name\}/...

\subsection{Taskdef}

\subsubsection{Description}

Adds a task definition to the current project, such that this new task
can be used in the current project. Two attributes are needed, the
name that identifies this task uniquely, and the full name of the
class (including the packages) that implements this task.

You can also define a group of tasks at once using the file or
resource attributes. These attributes point to files in the format of
Java property files. Each line defines a single task in the format:
\begin{verbatim}
taskname=fully.qualified.java.classname
\end{verbatim}
Taskdef should be used to add your own tasks to the system. See also
"Writing your own task".

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
name & the name of the task & Yes, unless file or resource have been specified. \\ \hline
classname & the full class name implementing the task & Yes, unless file or resource have been specified. \\ \hline
file & Name of the property file to load taskname/classname pairs from. & No \\ \hline
resource & Name of the property resource to load taskname/classname pairs from. & No \\ \hline
classpath & the classpath to use when looking up classname or resource. & No \\ \hline
classpathref & Reference to a classpath to use when looking up classname or resource. & No \\ \hline
loaderRef & the name of the loader that is used to load the class, constructed from the specified classpath. Use this to allow multiple tasks/types to be loaded with the same loader, so they can call each other. ( introduced in ant1.5 ) & No \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf classpath}\hfil\break

Taskdef's classpath attribute is a PATH like structure and can also be
set via a nested classpath element.

\subsubsection{Examples}
\begin{verbatim}
  <taskdef name="myjavadoc" classname="com.mydomain.JavadocTask"/>
\end{verbatim}
makes a task called myjavadoc available to Ant. The class
com.mydomain.JavadocTask implements the task.

\subsection{Tempfile}

\subsubsection{Description}

This task sets a property to the name of a temporary file. Unlike the
Java1.2 method to create a temporary file, this task does work with
Java1.1. It does not actually create the temporary file, but it does
guarantee that the file did not exist when the task was executed.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
destdir & The directory the temporary file should be located in. If not set, the current directory is used. & No \\ \hline
prefix & A prefix for the temporary file name. & No \\ \hline
property & The name of the property to set with the value of the temporary file name. & Yes \\ \hline
suffix & A suffix for the temporary file name. & No \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
  <tempfile property="temp.file"/>
\end{verbatim}
will set temp.file to the name of a new temporary file.
\begin{verbatim}
  <tempfile property="temp.file" suffix=".xml"/>
\end{verbatim}
will set temp.file to the name of a new temporary file with a suffix of .xml.
\begin{verbatim}
  <tempfile property="temp.file" destdir="build"/>
\end{verbatim}
will set temp.file to the name of a new temporary file located in the build sub-directory. 

\subsection{Touch}

\subsubsection{Description}

Changes the modification time of a file and possibly creates it at the
same time. In addition to working with a single file, this Task can
also work a Fileset (which also includes directories).

For JDK 1.1 only the creation of new files with a modification time of
now works, all other cases will emit a warning.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
file & the name of the file & unless a nested fileset element has been specified. \\ \hline
millis & specifies the new modification time of the file in milliseconds since midnight Jan 1 1970 & No \\ \hline
datetime & specifies the new modification time of the file in the format
MM/DD/YYYY HH:MM AM\_or\_PM. & No \\ \hline
\end{supertabular}

If both millis and datetime are omitted the current time is assumed.

\subsubsection{Examples}
\begin{verbatim}
  <touch file="myfile"/>
\end{verbatim}
creates myfile if it doesn't exist and changes the modification time to the current time.
\begin{verbatim}
  <touch file="myfile" datetime="06/28/2000 2:02 pm"/>
\end{verbatim}
creates myfile if it doesn't exist and changes the modification time to Jun, 28 2000 2:02 pm (14:02 for those used to 24 hour times).
\begin{verbatim}
  <touch datetime="09/10/1974 4:30 pm">
    <fileset dir="src_dir"/>
  </touch>
\end{verbatim}
changes the modification time to Oct, 09 1974 4:30 pm of all files and
directories found in src\_dir.

\subsection{TStamp}

\subsubsection{Description}

Sets the DSTAMP, TSTAMP, and TODAY properties in the current project.
By default, the DSTAMP property is in the format "yyyyMMdd", TSTAMP is
in the format "hhmm", and TODAY is in the format "MMMM dd yyyy". Use
the nested <format> element to specify a different format.

These properties can be used in the build-file, for instance, to
create time-stamped filenames, or used to replace placeholder tags
inside documents to indicate, for example, the release date. The best
place for this task is probably in an initialization target.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
prefix & Prefix used for all properties set. The default is no prefix. & No \\ \hline
\end{supertabular}

\subsubsection{Nested Elements}

The Tstamp task supports a <format> nested element that allows a
property to be set to the current date and time in a given format. The
date/time patterns are as defined in the Java SimpleDateFormat class.
The format element also allows offsets to be applied to the time to
generate different time values.

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
property & The property to receive the date/time string in the given pattern. & Yes \\ \hline
pattern & The date/time pattern to be used. The values are as defined by the Java SimpleDateFormat class. & Yes \\ \hline
timezone & The timezone to use for displaying time. The values are as defined by the Java TimeZone class. & No \\ \hline
offset & The numeric offset to the current time & No \\ \hline
unit & The unit of the offset to be applied to the current time. Valid Values are
\begin{itemize}
\item millisecond
\item second
\item minute
\item hour
\item day
\item week
\item month
\item year
\end{itemize}
& No \\ \hline

locale & The locale used to create date/time string. The general form is
"language, country, variant" but either variant or variant and country
may be omitted. For more information please refer to documentation for
the Locale class. & No \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
  <tstamp/>
\end{verbatim}
sets the standard DSTAMP, TSTAMP, and TODAY properties according to
the default formats.
\begin{verbatim}
  <tstamp>
    <format property="TODAY_UK" pattern="d-MMMM-yyyy" locale="en"/>
  </tstamp>
\end{verbatim}
sets the standard properties as well as the property 
{\tt TODAY\_UK} with the date/time pattern "d-MMMM-yyyy" using
English locale (eg. 21-May-2001).
\begin{verbatim}
  <tstamp>
      <format property="touch.time" pattern="MM/dd/yyyy hh:mm aa"
              offset="-5" unit="hour"/>
  </tstamp>
\end{verbatim}
Creates a timestamp, in the property touch.time, 5 hours before the current time. The format in this example is suitable for use with the <touch> task. The standard properties are set also.
\begin{verbatim}
  <tstamp prefix="start"/>
\end{verbatim}
Sets three properties with the standard formats, 
prefixed with "start.": start.DSTAMP, start.TSTAMP, and start.TODAY.

\subsection{Typedef}

\subsubsection{Description}

Adds a data type definition to the current project, such that this new
type can be used in the current project. Two attributes are needed,
the name that identifies this data type uniquely, and the full name of
the class (including the packages) that implements this type.

You can also define a group of data types at once using the file or
resource attributes. These attributes point to files in the format of
Java property files. Each line defines a single data type in the
format:
\begin{verbatim}
typename=fully.qualified.java.classname
\end{verbatim}
Typedef should be used to add your own types to the system. Data types
are things like paths or filesets that can be defined at the project
level and referenced via their ID attribute.

Custom data types usually need custom tasks to put them to good use.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
name & the name of the data type & Yes, unless file or resource have been specified. \\ \hline
classname & the full class name implementing the data type & Yes, unless file or resource have been specified. \\ \hline
file & Name of the property file to load typename/classname pairs from. & No \\ \hline
resource & Name of the property resource to load typename/classname pairs from. & No \\ \hline
classpath & the classpath to use when looking up classname. & No \\ \hline
loaderRef & the name of the loader that is used to load the class, constructed from the specified classpath. Use this to allow multiple tasks/types to be loaded with the same loader, so they can call each other. ( introduced in ant1.5 ) & No \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf classpath}\hfil\break

Typedef's classpath attribute is a PATH like structure and can also be
set via a nested classpath element.

\subsubsection{Examples}
\begin{verbatim}
  <typedef name="urlset" classname="com.mydomain.URLSet"/>
\end{verbatim}
makes a data type called urlset available to Ant. The class
com.mydomain.URLSet implements this type.

\subsection{Unjar/Untar/Unwar/Unzip}

\subsubsection{Description}

Unzips a zip-, war-, tar- or jarfile.

For JDK 1.1 "last modified time" field is set to current time instead
of being carried from the archive file.

PatternSets are used to select files to extract from the archive. If
no patternset is used, all files are extracted.

FileSets may be used used to select archived files to perform unarchival upon.

File permissions will not be restored on extracted files.

The untar task recognizes the long pathname entries used by GNU tar.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
src & archive file to expand. & Yes, if filesets are not used. \\ \hline
dest & directory where to store the expanded files. & Yes \\ \hline
overwrite & Overwrite files, even if they are newer than the corresponding entries in the archive (true or false, default is true). & No \\ \hline
compression & compression method for untar. Allowable values are "none", "gzip" and "bzip2". Default is "none". & No \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
<unzip src="${tomcat_src}/tools-src.zip" dest="${tools.home}"/>

<gunzip src="tools.tar.gz"/>
<untar src="tools.tar" dest="${tools.home}"/>

<unzip src="${tomcat_src}/tools-src.zip"
       dest="${tools.home}">
    <patternset>
        <include name="**/*.java"/>
        <exclude name="**/Test*.java"/>
    </patternset>
</unzip>

<unzip dest="${tools.home}">
    <patternset>
        <include name="**/*.java"/>
        <exclude name="**/Test*.java"/>
    </patternset>
    <fileset dir=".">
        <include name="**/*.zip"/>
        <exclude name="**/tmp*.zip"/>
    </fileset>
</unzip>
\end{verbatim}

\subsection{Untar}

\subsubsection{Description}

Unzips a zip-, war-, tar- or jarfile.

For JDK 1.1 "last modified time" field is set to current time instead
of being carried from the archive file.

PatternSets are used to select files to extract from the archive. If
no patternset is used, all files are extracted.

FileSets may be used used to select archived files to perform unarchival upon.

File permissions will not be restored on extracted files.

The untar task recognizes the long pathname entries used by GNU tar.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
src & archive file to expand. & Yes, if filesets are not used. \\ \hline
dest & directory where to store the expanded files. & Yes \\ \hline
overwrite & Overwrite files, even if they are newer than the corresponding entries in the archive (true or false, default is true). & No \\ \hline
compression & compression method for untar. Allowable values are "none", "gzip" and "bzip2". Default is "none". & No \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
<unzip src="${tomcat_src}/tools-src.zip" dest="${tools.home}"/>

<gunzip src="tools.tar.gz"/>
<untar src="tools.tar" dest="${tools.home}"/>

<unzip src="${tomcat_src}/tools-src.zip"
       dest="${tools.home}">
    <patternset>
        <include name="**/*.java"/>
        <exclude name="**/Test*.java"/>
    </patternset>
</unzip>

<unzip dest="${tools.home}">
    <patternset>
        <include name="**/*.java"/>
        <exclude name="**/Test*.java"/>
    </patternset>
    <fileset dir=".">
        <include name="**/*.zip"/>
        <exclude name="**/tmp*.zip"/>
    </fileset>
</unzip>
\end{verbatim}

\subsection{Unwar}

\subsubsection{Description}

Unzips a zip-, war-, tar- or jarfile.

For JDK 1.1 "last modified time" field is set to current time instead
of being carried from the archive file.

PatternSets are used to select files to extract from the archive. If
no patternset is used, all files are extracted.

FileSets may be used used to select archived files to perform unarchival upon.

File permissions will not be restored on extracted files.

The untar task recognizes the long pathname entries used by GNU tar.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
src & archive file to expand. & Yes, if filesets are not used. \\ \hline
dest & directory where to store the expanded files. & Yes \\ \hline
overwrite & Overwrite files, even if they are newer than the corresponding entries in the archive (true or false, default is true). & No \\ \hline
compression & compression method for untar. Allowable values are "none", "gzip" and "bzip2". Default is "none". & No \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
<unzip src="${tomcat_src}/tools-src.zip" dest="${tools.home}"/>

<gunzip src="tools.tar.gz"/>
<untar src="tools.tar" dest="${tools.home}"/>

<unzip src="${tomcat_src}/tools-src.zip"
       dest="${tools.home}">
    <patternset>
        <include name="**/*.java"/>
        <exclude name="**/Test*.java"/>
    </patternset>
</unzip>

<unzip dest="${tools.home}">
    <patternset>
        <include name="**/*.java"/>
        <exclude name="**/Test*.java"/>
    </patternset>
    <fileset dir=".">
        <include name="**/*.zip"/>
        <exclude name="**/tmp*.zip"/>
    </fileset>
</unzip>
\end{verbatim}

\subsection{Unzip}

Unzips a zip-, war-, tar- or jarfile.

For JDK 1.1 "last modified time" field is set to current time instead of being carried from the archive file.

PatternSets are used to select files to extract from the archive. If no patternset is used, all files are extracted.

FileSets may be used used to select archived files to perform unarchival upon.

File permissions will not be restored on extracted files.

The untar task recognizes the long pathname entries used by GNU tar.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
src & archive file to expand. & Yes, if filesets are not used. \\ \hline
dest & directory where to store the expanded files. & Yes \\ \hline
overwrite & Overwrite files, even if they are newer than the corresponding entries in the archive (true or false, default is true). & No \\ \hline
compression & compression method for untar. Allowable values are "none", "gzip" and "bzip2". Default is "none". & No \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
<unzip src="${tomcat_src}/tools-src.zip" dest="${tools.home}"/>

<gunzip src="tools.tar.gz"/>
<untar src="tools.tar" dest="${tools.home}"/>

<unzip src="${tomcat_src}/tools-src.zip"
       dest="${tools.home}">
    <patternset>
        <include name="**/*.java"/>
        <exclude name="**/Test*.java"/>
    </patternset>
</unzip>

<unzip dest="${tools.home}">
    <patternset>
        <include name="**/*.java"/>
        <exclude name="**/Test*.java"/>
    </patternset>
    <fileset dir=".">
        <include name="**/*.zip"/>
        <exclude name="**/tmp*.zip"/>
    </fileset>
</unzip>
\end{verbatim}

\subsection{Uptodate}

\subsubsection{Description}

Sets a property if a target file or set of target files is more
up-to-date than a source file or set of source files. A single source
file is specified using the srcfile attribute. A set of source files
is specified using the nested <srcfiles> elements. These are FileSets,
whereas multiple target files are specified using a nested <mapper>
element.

By default, the value of the property is set to true if the timestamp
of the target file(s) is more recent than the timestamp of the
corresponding source file(s). You can set the value to something other
than the default by specifying the value attribute.

If a <srcfiles> element is used, without also specifying a <mapper>
element, the default behavior is to use a merge mapper, with the to
attribute set to the value of the targetfile attribute.

Normally, this task is used to set properties that are useful to avoid
target execution depending on the relative age of the specified files.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
property & The name of the property to set. & Yes \\ \hline
value & The value to set the property to. & No; defaults to true. \\ \hline
srcfile & The file to check against the target file(s). & Yes, unless a nested <srcfiles> element is present. \\ \hline
targetfile & The file for which we want to determine the status. & Yes, unless a nested <mapper> element is present. \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf srcfiles}\hfil\break

The nested {\tt <srcfiles>} element allows you to specify a set of files to
check against the target file(s).

Note: You can specify either the srcfile attribute or nested
{\tt <srcfiles>} elements, but not both.

{\bf mapper}\hfil\break

The nested {\tt <mapper>} element allows you to specify a set of target
files to check for being up-to-date with respect to a set of source files.

\subsubsection{Examples}
\begin{verbatim}
  <uptodate property="xmlBuild.notRequired"
   targetfile="${deploy}\xmlClasses.jar" >
    <srcfiles dir= "${src}/xml" includes="**/*.dtd"/>
  </uptodate>
\end{verbatim}
sets the property xmlBuild.notRequired to true if the
\$\{deploy\}/xmlClasses.jar file is more up-to-date than any of the DTD
files in the \$\{src\}/xml directory.

This can be written as:
\begin{verbatim}
  <uptodate property="xmlBuild.notRequired">
    <srcfiles dir= "${src}/xml" includes="**/*.dtd"/>
    <mapper type="merge" to="${deploy}\xmlClasses.jar"/>
  </uptodate>
\end{verbatim}
as well. The xmlBuild.notRequired property can then be used in a
{\tt <target>} tag's unless attribute to conditionally run that target. For
example, running the following target:
\begin{verbatim}
<target name="xmlBuild" depends="chkXmlBuild" unless="xmlBuild.notRequired">
  ...
</target>
\end{verbatim}
will first run the chkXmlBuild target, which contains the <uptodate>
task that determines whether xmlBuild.notRequired gets set. The
property named in the unless attribute is then checked for being
set/not set. If it did get set (ie., the jar file is up-to-date), then
the xmlBuild target won't be run.

The following example shows a single source file being checked against a single target file:
\begin{verbatim}
  <uptodate property="isUpToDate"
            srcfile="/usr/local/bin/testit"
            targetfile="${build}/.flagfile"/>
\end{verbatim}
sets the property isUpToDate to true if /usr/local/bin/testit is newer
than \$\{build\}/.flagfile.

\subsection{Waitfor}

\subsubsection{Description}

Blocks execution until a set of specified conditions become true. This
is intended to be used with the parallel task to synchronize a set of
processes.

The conditions to wait for are defined in nested elements, if multiple
conditions are specified, then the task will wait until all conditions
are true..

If both maxwait and maxwaitunit are not specified, the maxwait is 3
minutes (180000 milliseconds).

If the timeoutproperty attribute has been set, a property of that name
will be created if the condition didn't come true within the specified
time.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
maxwait & The maximum amount of time to wait for all the required conditions to become true before failing the task. Defaults to 180000 maxwaitunits. & No \\ \hline
maxwaitunit & The unit of time that must be used to interpret the value of the maxwait attribute. Defaults to millisecond. Valid Values are
\begin{itemize}
\item millisecond
\item second
\item minute
\item hour
\item day
\item week
\end{itemize}
& No \\ \hline

checkevery & The amount of time to wait between each test of the conditions. Defaults to 500 checkeveryunits. & No \\ \hline
checkeveryunit & The unit of time that must be used to interpret the value of the checkevery attribute. Defaults to millisecond. Valid Values are
\begin{itemize}
\item second
\item minute
\item hour
\item day
\item week
\end{itemize}
& No \\ \hline

timeoutproperty & the name of the property to set if maxwait has been exceeded. & No \\ \hline
\end{supertabular}

\subsubsection{Nested Elements}

The available conditions that satisfy the {\tt <waitfor>} task are the same
as those for the {\tt <condition>} task. See here for the full list.

\subsubsection{Examples}
\begin{verbatim}
<waitfor maxwait="30" maxwaitunit="second">
    <available file="errors.log"/>
</waitfor>
\end{verbatim}
waits up to 30 seconds for a file called errors.log to appear.
\begin{verbatim}
<waitfor maxwait="3" maxwaitunit="minute" checkevery="500">
    <http url="http://localhost/myapp/index.html"/>
</waitfor>
\end{verbatim}
waits up to 3 minutes (and checks every 500 milliseconds) for a web
server on localhost to serve up the specified URL.
\begin{verbatim}
<waitfor maxwait="10" maxwait="second">
    <and>
        <socket server="dbserver" port="1521"/>
        <http url="http://webserver/mypage.html"/>
    </and>
</waitfor>
\end{verbatim}
waits up to 10 seconds for a server on the dbserver machine to begin
listening on port 1521 and for the http://webserver/mypage.html web
page to become available.

\subsection{War}
\subsubsection{Description}

An extension of the Jar task with special treatment for files that
should end up in the WEB-INF/lib, WEB-INF/classes or WEB-INF
directories of the Web Application Archive.

(The War task is a shortcut for specifying the particular layout of a
WAR file. The same thing can be accomplished by using the prefix and
fullpath attributes of zipfilesets in a Zip or Jar task.)

The extended zipfileset element from the zip task (with attributes
prefix, fullpath, and src) is available in the War task.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
destfile & the WAR file to create. & Yes \\ \hline
warfile & Deprecated name of the file to create -use destfile instead. & No \\ \hline
webxml & The deployment descriptor to use (WEB-INF/web.xml). & Yes, unless update is set to true \\ \hline
basedir & the directory from which to jar the files. & No \\ \hline
compress & Not only store data but also compress them, defaults to true & No \\ \hline
encoding & The character encoding to use for filenames inside the archive. Defaults to UTF8. It is not recommended to change this value as the created archive will most likely be unreadable for Java otherwise. & No \\ \hline
filesonly & Store only file entries, defaults to false & No \\ \hline
includes & comma- or space-separated list of patterns of files that must be included. All files are included when omitted. & No \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & No \\ \hline
excludes & comma- or space-separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & No \\ \hline
defaultexcludes & indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline
manifest & the manifest file to use. & No \\ \hline
update & indicates whether to update or overwrite the destination file if it already exists. Default is "false". & No \\ \hline
duplicate & behavior when a duplicate file is found. Valid values are "add", "preserve", and "fail". The default value is "add". & No \\ \hline
\end{supertabular}

\subsubsection{Nested elements}

{\bf lib}\hfil\break

The nested lib element specifies a FileSet. All files included in this
fileset will end up in the WEB-INF/lib directory of the war file.

{\bf classes}\hfil\break

The nested classes element specifies a FileSet. All files included in
this fileset will end up in the WEB-INF/classes directory of the war file.

{\bf webinf}\hfil\break

The nested webinf element specifies a FileSet. All files included in
this fileset will end up in the WEB-INF directory of the war file. If
this fileset includes a file named web.xml, the file is ignored and
you will get a warning.

{\bf metainf}\hfil\break

The nested metainf element specifies a FileSet. All files included in
this fileset will end up in the META-INF directory of the war file. If
this fileset includes a file named MANIFEST.MF, the file is ignored
and you will get a warning.

\subsubsection{Examples}

Assume the following structure in the project's base directory:
\begin{verbatim}
thirdparty/libs/jdbc1.jar
thirdparty/libs/jdbc2.jar
build/main/com/myco/myapp/Servlet.class
src/metadata/myapp.xml
src/html/myapp/index.html
src/jsp/myapp/front.jsp
src/graphics/images/gifs/small/logo.gif
src/graphics/images/gifs/large/logo.gif
\end{verbatim}
then the war file myapp.war created with
\begin{verbatim}
<war destfile="myapp.war" webxml="src/metadata/myapp.xml">
  <fileset dir="src/html/myapp"/>
  <fileset dir="src/jsp/myapp"/>
  <lib dir="thirdparty/libs">
    <exclude name="jdbc1.jar"/>
  </lib>
  <classes dir="build/main"/>
  <zipfileset dir="src/graphics/images/gifs" 
              prefix="images"/>
</war>
\end{verbatim}
will consist of
\begin{verbatim}
WEB-INF/web.xml
WEB-INF/lib/jdbc2.jar
WEB-INF/classes/com/myco/myapp/Servlet.class
META-INF/MANIFEST.MF
index.html
front.jsp
images/small/logo.gif
images/large/logo.gif
\end{verbatim}
using Ant's default manifest file. The content of WEB-INF/web.xml is
identical to src/metadata/myapp.xml.

\subsection{XmlProperty}

\subsubsection{Description}

Loads property values from a valid xml file.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
file & The XML file to parse. & Yes \\ \hline
prefix & The prefix to prepend to each property & No \\ \hline
keepRoot & If false, it doesn't include the xml root tag as a first value in the property name. & No, default is true. \\ \hline
validate & If true, it enables validation. & No, default is false. \\ \hline
collapseAttributes & If true, it treats attributes as nested elements. & No, default is false. \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
   <xmlproperty file="somefile.xml" />
\end{verbatim}
Load contents of somefile.xml as Ant properties, generating the
property names from the file's element and attribute names.
\begin{verbatim} 
   <root-tag myattr="true">
    <inner-tag someattr="val">Text</inner-tag>
    <a2><a3><a4>false</a4></a3></a2>
   </root-tag>
\end{verbatim}
This is an example xml file.
\begin{verbatim} 
   root-tag(myattr)=true
   root-tag.inner-tag=Text
   root-tag.inner-tag(someattr)=val
   root-tag.a2.a3.a4=false
\end{verbatim}
These are the properties loaded by this task from the previous example file.
\begin{verbatim} 
   <xmlproperty file="somefile.xml" collapseAttributes="true"/>
\end{verbatim}
Load contents of somefile.xml as Ant properties collapsing attributes as nodes.
\begin{verbatim} 
   root-tag.myattr=true
   root-tag.inner-tag=Text
   root-tag.inner-tag.someatt=val
   root-tag.a2.a3.a4=false
\end{verbatim}
These are the properties loaded by this task from the previous example
file, with attribute collapsing true.

\subsection{Xslt}

\subsubsection{Description}

Process a set of documents via XSLT.

This is useful for building views of XML based documentation, or for
generating code.

Note: This task depends on external libraries not included in the Ant
distribution. See Library Dependencies for more information.

It is possible to refine the set of files that are being
processed. This can be done with the includes, includesfile, excludes,
excludesfile and defaultexcludes attributes. With the includes or
includesfile attribute you specify the files you want to have included
by using patterns. The exclude or excludesfile attribute is used to
specify the files you want to have excluded. This is also done with
patterns. And finally with the defaultexcludes attribute, you can
specify whether you want to use default exclusions or not. See the
section on directory based tasks, on how the inclusion/exclusion of
files works, and how to write patterns.

This task forms an implicit FileSet and supports all attributes of
{\tt <fileset>} (dir becomes basedir) as well as the nested {\tt <include>},
{\tt <exclude>} and {\tt <patternset>} elements.

This task supports the use of a nested {\tt <param>} element which is used
to pass values to an {\tt <xsl:param>} declaration.

This task supports the use of a nested xmlcatalog element which is
used to perform Entity and URI resolution

{\tt <style>} and {\tt <xslt>} refer to the same 
Ant task and can be used interchangeably.

If you want to use Xalan-J 1 or XSL:P, you also need Ant's optional.jar

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
basedir & where to find the source XML file, default is the project's basedir. & No \\ \hline
destdir & directory in which to store the results. & Yes, unless in and out have been specified. \\ \hline
extension & desired file extension to be used for the targets. If not specified, the default is ".html". & No \\ \hline
style & name of the stylesheet to use - given either relative to the project's basedir or as an absolute path DEPRECATED - can be specified as a path relative to the basedir attribute of this task as well. & Yes \\ \hline
classpath & the classpath to use when looking up the XSLT processor. & No \\ \hline
classpathref & the classpath to use, given as reference to a path defined elsewhere. & No \\ \hline
force & Recreate target files, even if they are newer than their corresponding source files or the stylesheet. & No; default is false \\ \hline
processor & name of the XSLT processor to use. Permissible values are "trax" for a TraX compliant processor (ie JAXP interface implementation such as Xalan 2 or Saxon), "xslp" for the XSL:P processor, "xalan" for the Apache XML Xalan (version 1) processor the name of an arbitrary XSLTLiaison class. Defaults to trax, followed by xalan and then xslp (in that order). The first one found in your class path is the one that is used. DEPRECATED - XSL:P and xalan are deprecated and no more supported.. & No \\ \hline
includes & comma- or space-separated list of patterns of files that must be included. All files are included when omitted. & No \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & No \\ \hline
excludes & comma- or space-separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & No \\ \hline
defaultexcludes & indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline
in & specifies a single XML document to be styled. Should be used with the out attribute. & No \\ \hline
out & specifies the output name for the styled result from the in attribute. & No \\ \hline
scanincludeddirectories & If any directories are matched by the includes/excludes patterns, try to transform all files in these directories. Default is true & No \\ \hline
reloadstylesheet & Control whether the stylesheet transformer is created anew for every transform opertaion. If you set this to true, performance may suffer, but you may work around a bug in certain Xalan-J versions. Default is false. Since Ant 1.5.2. & No \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf classpath}\hfil\break

The classpath to load the processor from can be specified via a nested <classpath>, as well - that is, a path-like structure.

{\bf xmlcatalog}\hfil\break

The xmlcatalog element is used to perform Entity and URI resolution.

{\bf param}\hfil\break

Param is used to pass a parameter to the XSL stylesheet.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
name & Name of the XSL parameter & Yes \\ \hline
expression & XSL expression to be placed into the param. To pass a text value into the style sheet it needs to be escaped using single quotes. & Yes \\ \hline
\end{supertabular}

{\bf outputproperty ('trax' processors only)}\hfil\break

Used to specify how you wish the result tree to be output as specified
in the XSLT specifications.

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
name & Name of the property & Yes \\ \hline
value & value of the property. & Yes \\ \hline
\end{supertabular}

\subsubsection{Examples}
\begin{verbatim}
<style basedir="doc" destdir="build/doc"
       extension=".html" style="style/apache.xsl"/>
\end{verbatim}
Using an xmlcatalog
\begin{verbatim}
<xslt basedir="doc" destdir="build/doc"
      extension=".html" style="style/apache.xsl">
  <xmlcatalog refid="mycatalog"/>
</xslt>

<xslt basedir="doc" destdir="build/doc"
   extension=".html" style="style/apache.xsl">
   <xmlcatalog>
       <dtd
         publicId="-//ArielPartners//DTD XML Article V1.0//EN"
         location="com/arielpartners/knowledgebase/dtd/article.dtd"/>
   </xmlcatalog>
</xslt>
\end{verbatim}
Using XSL parameters
\begin{verbatim}
<xslt basedir="doc" destdir="build/doc"
      extension=".html" style="style/apache.xsl">
  <param name="date" expression="07-01-2000"/>
</xslt>
\end{verbatim}
Then if you declare a global parameter "date" with the top-level
element <xsl:param name="date"/>, the variable \$date will subsequently
have the value 07-01-2000.
Using output properties
\begin{verbatim}
<xslt in="doc.xml" out="build/doc/output.xml"
      style="style/apache.xsl">
  <outputproperty name="method" value="xml";/>
  <outputproperty name="standalone" value="yes"/>
  <outputproperty name="encoding" value="iso8859_1"/>
  <outputproperty name="indent" value="yes"/>
</xslt>
\end{verbatim}

\subsection{Zip}

\subsubsection{Description}

Creates a zipfile.

The basedir attribute is the reference directory from where to zip.

Note that file permissions will not be stored in the resulting zipfile.

It is possible to refine the set of files that are being zipped. This
can be done with the includes, includesfile, excludes, excludesfile
and defaultexcludes attributes. With the includes or includesfile
attribute you specify the files you want to have included by using
patterns. The exclude or excludesfile attribute is used to specify the
files you want to have excluded. This is also done with patterns. And
finally with the defaultexcludes attribute, you can specify whether
you want to use default exclusions or not. See the section on
directory based tasks, on how the inclusion/exclusion of files works,
and how to write patterns.

This task forms an implicit FileSet and supports all attributes of
{\tt <fileset>} (dir becomes basedir) as well as the nested {\tt <include>},
{\tt <exclude>} and {\tt <patternset>} elements.

Or, you may place within it nested file sets, or references to file
sets. In this case basedir is optional; the implicit file set is only
used if basedir is set. You may use any mixture of the implicit file
set (with basedir set, and optional attributes like includes and
optional subelements like {\tt <include>}); explicit nested {\tt <fileset>}
elements so long as at least one fileset total is specified. The ZIP
file will only reflect the relative paths of files within each
fileset. The Zip task and its derivatives know a special form of a
fileset named zipfileset that has additional attributes (described
below).

The Zip task also supports the merging of multiple zip files into the
zip file. This is possible through either the src attribute of any
nested filesets or by using the special nested fileset
zipgroupfileset.

The update parameter controls what happens if the ZIP file already
exists. When set to yes, the ZIP file is updated with the files
specified. (New files are added; old files are replaced with the new
versions.) When set to no (the default) the ZIP file is
overwritten. Please note that ZIP files store file modification times
with a granularity of two seconds. If a file is less than two seconds
newer than the entry in the archive, Ant will not consider it newer.

The whenempty parameter controls what happens when no files match. If
skip (the default), the ZIP is not created and a warning is issued. If
fail, the ZIP is not created and the build is halted with an error. If
create, an empty ZIP file (explicitly zero entries) is created, which
should be recognized as such by compliant ZIP manipulation tools.

This task will now use the platform's default character encoding for
filenames - this is consistent with the command line ZIP tools, but
causes problems if you try to open them from within Java and your
filenames contain non US-ASCII characters. Use the encoding attribute
and set it to UTF8 to create zip files that can safely be read by
Java.

Starting with Ant 1.5.2, {\tt <zip>} can store Unix permissions inside the
archive (see description of the filemode and dirmode attributes for
{\tt <zipfileset>}). Unfortunately there is no portable way to store these
permissions. Ant uses the algorithm used by Info-Zip's implementation
of the zip and unzip commands - these are the default versions of zip
and unzip for many Unix and Unix-like systems.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{9cm}|c|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
destfile & the zip-file to create. & Yes \\ \hline
zipfile & the deprecated old name of destfile. & Yes \\ \hline
basedir & the directory from which to zip the files. & No \\ \hline
compress & Not only store data but also compress them, defaults to true & No \\ \hline
encoding & The character encoding to use for filenames inside the zip file. For a list of possible values see http://java.sun.com/products/jdk/1.2/docs/guide\hfil\break
/internat/encoding.doc.html. Defaults to the platform's default character encoding. & No \\ \hline
filesonly & Store only file entries, defaults to false & No \\ \hline
includes & comma- or space-separated list of patterns of files that must be included. All files are included when omitted. & No \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & No \\ \hline
excludes & comma- or space-separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & No \\ \hline
defaultexcludes & indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline
update & indicates whether to update or overwrite the destination file if it already exists. Default is "false". & No \\ \hline
whenempty & behavior when no files match. Valid values are "fail", "skip", and "create". Default is "skip". & No \\ \hline
duplicate & behavior when a duplicate file is found. Valid values are "add", "preserve", and "fail". The default value is "add". & No \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf fileset}

The zip task supports any number of nested {\tt <fileset>} elements to
specify the files to be included in the archive.

{\bf zipfileset}\hfil\break

A {\tt <zipfileset>} is a special form of a {\tt <fileset>} that adds some extra
functionality. It supports all attributes of {\tt <fileset>} in addition to
those listed below.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
prefix & all files in the fileset are prefixed with that path in the archive. & No \\ \hline
fullpath & the file described by the fileset is placed at that exact location in the archive. & No \\ \hline
src & may be used in place of the dir attribute to specify a zip file whose contents will be extracted and included in the archive. & No \\ \hline
filemode & A 3 digit octal string, specify the user, group and other modes in the standard Unix fashion. Only applies to plain files. Default is 644. since Ant 1.5.2. & No \\ \hline
dirmode & A 3 digit octal string, specify the user, group and other modes in the standard Unix fashion. Only applies to directories. Default is 755. since Ant 1.5.2. & No \\ \hline
\end{supertabular}

The fullpath attribute can only be set for filesets that represent a
single file. The prefix and fullpath attributes cannot both be set on
the same fileset.

When using the src attribute, include and exclude patterns may be used
to specify a subset of the zip file for inclusion in the archive as
with the dir attribute.

{\bf zipgroupfileset}\hfil\break

A {\tt <zipgroupfileset>} allows for multiple zip files to be merged into
the archive. Each file found in this fileset is added to the archive
the same way that zipfileset src files are added.

\subsubsection{Examples}
\begin{verbatim}
  <zip destfile="${dist}/manual.zip"
       basedir="htdocs/manual"
  />
\end{verbatim}  
zips all files in the htdocs/manual directory into a file called
manual.zip in the \$\{dist\} directory.
\begin{verbatim}
  <zip destfile="${dist}/manual.zip"
       basedir="htdocs/manual"
       update="true"
  />
\end{verbatim}  
zips all files in the htdocs/manual directory into a file called
manual.zip in the \$\{dist\} directory. If manual.zip doesn't exist, it
is created; otherwise it is updated with the new/changed files.
\begin{verbatim}
  <zip destfile="${dist}/manual.zip"
       basedir="htdocs/manual"
       excludes="mydocs/**, **/todo.html"
  />
\end{verbatim}  
zips all files in the htdocs/manual directory. Files in the directory
mydocs, or files with the name todo.html are excluded.
\begin{verbatim}
  <zip destfile="${dist}/manual.zip"
       basedir="htdocs/manual"
       includes="api/**/*.html"
       excludes="**/todo.html"
  />
\end{verbatim}  
zips all files in the htdocs/manual directory. Only html files under the directory api are zipped, and files with the name todo.html are excluded.
\begin{verbatim}
  <zip destfile="${dist}/manual.zip">
    <fileset dir="htdocs/manual"/>
    <fileset dir="." includes="ChangeLog.txt"/>
  </zip>
\end{verbatim}    
zips all files in the htdocs/manual directory, and also adds the
file ChangeLog.txt in the current directory. ChangeLog.txt will be
added to the top of the ZIP file, just as if it had been located at
htdocs/manual/ChangeLog.txt.
\begin{verbatim}
  <zip destfile="${dist}/manual.zip">
    <zipfileset dir="htdocs/manual" prefix="docs/user-guide"/>
    <zipfileset dir="." includes="ChangeLog27.txt" fullpath="docs/ChangeLog.txt"/>
    <zipfileset src="examples.zip" includes="**/*.html" prefix="docs/examples"/>
  </zip>
\end{verbatim}  

zips all files in the htdocs/manual directory into the docs/user-guide
directory in the archive, adds the file ChangeLog27.txt in the current
directory as docs/ChangeLog.txt, and includes all the html files in
examples.zip under docs/examples. The archive might end up containing
the files:
\begin{verbatim}
    docs/user-guide/html/index.html
    docs/ChangeLog.txt
    docs/examples/index.html
\end{verbatim}  
The code
\begin{verbatim}
  <zip destfile="${dist}/manual.zip">
    <zipfileset dir="htdocs/manual" prefix="docs/user-guide"/>
    <zipgroupfileset dir="." includes="examples*.zip"/>
  </zip>
\end{verbatim}  
zips all files in the htdocs/manual directory into the
docs/user-guide directory in the archive and includes all the files
in any file that maches examples*.zip, such as all files within
 examples1.zip or examples\_for\_brian.zip.

\section{Optional Tasks}

\subsection{NET Tasks}

\subsubsection{{\tt <CSC>}}

This task compiles CSharp source into executables or modules. This
task compiles CSharp source into executables or modules. The task will
only work on win2K/XP or other platforms with csc.exe or an
equivalent. CSC must be on the execute path.

All parameters are optional: {\tt <csc/>} should suffice to produce a debug
build of all *.cs files. References to external files do require
explicit enumeration, so are one of the first attributes to consider
adding.

The task is a directory based task, so attributes like
includes="**/*.cs" and excludes="broken.cs" can be used to control the
files pulled in. By default, all *.cs files from the project folder
down are included in the command. When this happens the destFile -if
not specified- is taken as the first file in the list, which may be
somewhat hard to control. Specifying the output file with 'destfile'
seems prudent.

Also, dependency checking only works if destfile is set.

\begin{supertabular}{|l|p{5.0cm}|p{5cm}|} \hline
Attribute & Description & Example Values \\ \hline
additionalModules & Semicolon separated list of modules to refer to & \\ \hline
defaultexcludes & indicates whether default excludes should be used or not & "true"(default) or "false" \\ \hline
definitions & defined constants & "RELEASE;BETA1" \\ \hline
debug & include debug information & "true"(default) \\ \hline
destFile & name of exe/library to create & "example.exe" \\ \hline
docFile & name of file for documentation & "doc.xml" \\ \hline
excludes & comma- or space-separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & \\ \hline
extraOptions & Any extra options which aren't explicitly supported by the CSharp task & "/warnaserror+ /baseaddress:0x12840000" \\ \hline
failOnError & Should a failed compile halt the build? & "true"(default) or "false" \\ \hline
fileAlign & set the file alignment. Valid values are 0,512, 1024, 2048, 4096, 8192, and 16384 0 means 'leave to the compiler' & 512 \\ \hline
fullpaths & print the full path of files on on errors & \\ \hline
includes & comma- or space-separated list of patterns of files that must be included. All files are included when omitted. & \\ \hline
includeDefaultReferences & Flag which when true automatically includes the common assemblies in dotnet, and tells the compiler to link in mscore.dll & "true"(default) or "false" \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & \\ \hline
incremental & Incremental build flag. Avoid till it works & "true" or "false"(default) \\ \hline
mainClass & name of main class for executables & "com.example.project.entrypoint" \\ \hline
noConfig & a flag which tells the compiler not to read in the compiler settings files 'csc.rsp' in its bin directory and then the local directory & "true" or "false"(default) \\ \hline
optimize & optimisation flag & "true" or "false"(default) \\ \hline
references & Semicolon separated list of dlls to refer to & "mylib.dll;nunit.dll" \\ \hline
referenceFiles & Ant Path descriptioon of references to include. Wildcards should work. & \\ \hline
srcDir & source directory (default = project directory) & "." \\ \hline
targetType & Type of target & "exe", "module", "winexe" or "library" \\ \hline
unsafe & enable the unsafe keyword & "true" or "false"(default) \\ \hline
utf8output & require all compiler output to be in utf-8 format & "true" or "false"(default) \\ \hline
warnLevel & level of warning currently between 1 and 4 with 4 being the strictest. & "1"-"4" \\ \hline
win32Icon & filename of icon to include & "res/myicon.ico" \\ \hline
win32res & filename of a win32 resource (.RES)file to include This is not a .NET resource, but it what windows is used to. & "res/myapp.res" \\ \hline
\end{supertabular}

Example
\begin{verbatim}
<csc
        optimize="true"
        debug="false"
        docFile="documentation.xml"
        warnLevel="4"
        unsafe="false"
        targetType="exe"
        incremental="false"
        definitions="RELEASE"
        excludes="src/unicode_class.cs"
        mainClass = "MainApp"
        destFile="NetApp.exe"
        />   
\end{verbatim}

\subsubsection{{\tt <ilasm>}}

Task to assemble .net 'Intermediate Language' files. The task will
only work on windows until other platforms support csc.exe or an
equivalent. ilasm.exe must be on the execute path too.

All parameters are optional: {\tt <il/>} should suffice to produce a debug
build of all *.il files. The option set is roughly compatible with the
CSharp class; even though the command line options are only vaguely
equivalent. [The low level commands take things like /OUT=file, csc
wants /out:file ... /verbose is used some places; /quiet here in
ildasm... etc.] It would be nice if someone made all the command line
tools consistent (and not as brittle as the java cmdline tools)

The task is a directory based task, so attributes like includes="*.il"
and excludes="broken.il" can be used to control the files pulled
in. Each file is built on its own, producing an appropriately named
output file unless manually specified with outfile

\begin{supertabular}{|l|p{5cm}|p{3cm}|} \hline
Attribute & Description & Example \\ \hline
defaultexcludes & indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & \\ \hline
debug & include debug information & true (default) \\ \hline
excludes & comma separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & \\ \hline
extraOptions & Any extra options which aren't explicitly supported by the ilasm task, primarily because they arent really documented: use ilasm /? to see them & \\ \hline
failOnError & Should a failed compile halt the build? & "true"(default) \\ \hline
fullpaths & Should error text provide the full path to files & "true"(default) \\ \hline
includes & comma separated list of patterns of files that must be included. All files are included when omitted. & \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & \\ \hline
keyfile & the name of a file containing a private key, with which the assembly output is checksumed and then MD5 signed to have a strong name & \\ \hline
listing & Produce a listing (off by default). Listings go to the current output stream & "on", "off" (default) \\ \hline
outputFile & filename of output & "example.exe" \\ \hline
resourceFile & name of resource file to include & "resources.res" \\ \hline
srcDir & source directory (default = project directory) & \\ \hline
targetType & Type of target. library means DLL is output. & "exe"(default), "library" \\ \hline
verbose & output progress messages & "on", "off" (default) \\ \hline
\end{supertabular}

Example
\begin{verbatim}
<ilasm
        outputFile="app.exe"
        verbose="on"
        listing="on"
        owner="secret"
        />
\end{verbatim}
\subsubsection{{\tt <WsdlToDotnet>}}

Why add a wrapper to the MS WSDL tool? So that you can verify that
your web services, be they written with Axis or anyone else's SOAP
toolkit, work with .NET clients.

This task is dependency aware when using a file as a source and
destination; so if you {\tt <get>} the file (with usetimestamp="true") then
you only rebuild stuff when the WSDL file is changed. Of course, if
the server generates a new timestamp every time you ask for the WSDL,
this is not enough...use the {\tt <filesmatch> <condition>} to to byte for
byte comparison against a cached WSDL file then make the target
conditional on that test failing.

\begin{supertabular}{|l|p{5cm}|p{4.5cm}|} \hline
Attribute & Description & Example \\ \hline
destFile & name of file to generate. Required & ApacheNet.cs \\ \hline
srcFile & name of WSDL file to use. Required if url is not set & service.wsdl \\ \hline
url & url to retrive WSDL from. required if srcFile is unset & http://localhost/service?wsdl \\ \hline
server & generate server stubs, not client proxy code. optional; default false & "false"(default) \\ \hline
namespace & namespace to place the source in. optional; default "" & Apache.Net \\ \hline
language & language; one of "CS", "JS", or "VB" optional; & "CS" (default) \\ \hline
failOnError & Should failure halt the build? & "true"(default) \\ \hline
extraOptions & Any extra options which aren't explicitly supported by the task, like all the proxy server config stuff & \\ \hline
\end{supertabular}

\subsubsection{Change Log}
\begin{verbatim}
Version 0.5
This revision goes along with NET 1.0 (SP1)

   1. CSC: added filealign
   2. CSC: added reference to office.dll
   3. CSC: dependency checking! only if destFile is set!
   4. WsdlToDotnet written 

Version 0.4
This is the beta-2 revision of the tasks.

   1. ILASM: pulled the owner attribute, added keyfile for giving 
      binaries a strong name (MD5 hash of the checksum)
   2. CSC: added win32res , noConfig, utf8output, fullpaths
   3. CSC:

Version 0.3

The changes here reflect Beta-1 of the dotnet SDK and experience of
use in more complex projects. This build does not work with the older
SDK, primarily because the automatic reference feature references
libraries only found in the new SDK version.

External changes

    * Recursive inclusion of .cs and .il files
    * Documentation enhanced, includes examples and details of all parameters
    * The csc task automatically includes the common dotnet assemblies, 
      so there is no need to remember to refer to 'System.dll',
      'System.Web.Services', etc. This feature can be disabled by 
      setting the 'includeDefaultReferences' flag to false.
    * References can also be referred to using the ReferenceFiles
      parameter, which is an ant path specification. The old 'references'
      string is still retained.
    * An 'extraoptions' attribute enables the build file to include any
      CSC options which are not explicitly supported in the CSC task.

Internal changes

    * Some minor refactoring (move common code a method)
    * Application of Jedits JavaStyle task resulted in a major reshaping of the codebase and the insertion of a blank line every second line. Significant effort was required to revert some (but not all) changes.
    * Removed throws clause from methods which can't throw exceptions

The test harness has been expanded to include unicode source file (the
build works but the rest of the system has 'issues' with high unicode
package and method names)

Version 0.2
First public edition, added to the ant cvs tree. 
Tested on the PDC build of the dotnet SDK only, and still immature. 
The command execution code was refactored out into a 'NetCommand' 
class for re-use. The Ilasm task was added at this time.
Version 0.1
Initial proof of concept; very rudimentary support for CSC only.
\end{verbatim}

\subsection{ANTLR}

\subsubsection{Description}

Invokes the ANTLR Translator generator on a grammar file.

To use the ANTLR task, set the target attribute to the name of the
grammar file to process. Optionally, you can also set the
outputdirectory to write the generated file to a specific
directory. Otherwise ANTLR writes the generated files to the directory
containing the grammar file.

This task only invokes ANTLR if the grammar file is newer than the
generated files.

Antlr 2.7.1 Note: To successfully run ANTLR, your best option is
probably to build the whole jar with the provided script mkalljar and
drop the resulting jar (about 300KB) into \$\{ant.home\}/lib. Dropping
the default jar (70KB) is probably not enough for most needs and your
only option will be to add ANTLR home directory to your classpath as
described in ANTLR install.html document.

Antlr 2.7.2 Note: Instead of the above, you will need antlrall.jar
that can be created by the antlr-all.jar target of the Makefile
provided with the download.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{6cm}|p{2cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
target & The grammar file to process. & Yes \\ \hline
outputdirectory & The directory to write the generated files to. If not set, the files are written to the directory containing the grammar file. & No \\ \hline
glib & An optional super grammar file that the target grammar overrides. This feature is only needed for advanced vocabularies. & No \\ \hline
debug & When set to "yes", this flag adds code to the generated parser that will launch the ParseView debugger upon invocation. The default is "& no". \\ \hline
Note &: ParseView is a separate component that needs to be installed or your grammar will have compilation errors. & No \\ \hline
html & Emit an html version of the grammar with hyperlinked actions. & No \\ \hline
diagnostic & Generates a text file with debugging infomation based on the target grammar. & No \\ \hline
trace & Forces all rules to call traceIn/traceOut if set to "yes". The default is "no". & No \\ \hline
traceParser & Only forces parser rules to call traceIn/traceOut if set to "yes". The default is "no". & No \\ \hline
traceLexer & Only forces lexer rules to call traceIn/traceOut if set to "yes". The default is "no". & No \\ \hline
traceTreeWalker & Only forces tree walker rules to call traceIn/traceOut if set to "yes". The default is "no". & No \\ \hline
dir & The directory to invoke the VM in. & No \\ \hline
\end{supertabular}

\subsubsection{Nested Elements}

ANTLR supports a nested {\tt <classpath>} element, that represents a PATH
like structure. It is given as a convenience if you have to specify
the original ANTLR directory. In most cases, dropping the appropriate
ANTLR jar in the normal Ant lib repository will be enough.

{\bf jvmarg}\hfil\break

Additional parameters may be passed to the new VM via nested {\tt <jvmarg>}
attributes, for example:
\begin{verbatim}
<antlr target="...">
  <jvmarg value="-Djava.compiler=NONE"/>
  ...
</antlr>
\end{verbatim}
would run ANTLR in a VM without JIT.

{\tt <jvmarg>} allows all attributes described in Command line arguments.

\subsubsection{Example}
\begin{verbatim}
<antlr
    target="etc/java.g"
    outputdirectory="build/src"
/>
\end{verbatim}
This invokes ANTLR on grammar file etc/java.g, writing the generated
files to build/src.

\subsection{Cab}

\subsubsection{Description}

The cab task creates Microsoft cab archive files. It is invoked
similar to the jar or zip tasks. This task will work on Windows using
the external cabarc tool (provided by Microsoft) which must be located
in your executable path.

To use this task on other platforms you need to download and compile
libcabinet from
http://trill.cis.fordham.edu/~barbacha/cabinet\_library/.

See the section on directory based tasks, on how the
inclusion/exclusion of files works, and how to write patterns.

This task forms an implicit FileSet and supports all attributes of
{\tt <fileset>} (dir becomes basedir) as well as the nested {\tt <include>},
{\tt <exclude>} and {\tt <patternset>} elements.

\subsubsection{Parameters}

\begin{supertabular}{|l|p{6cm}|p{2cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
cabfile & the name of the cab file to create. & Yes \\ \hline
basedir & the directory to start archiving files from. & Yes \\ \hline
verbose & set to "yes" if you want to see the output from the cabarc tool. defaults to "no". & No \\ \hline
compress & set to "no" to store files without compressing. defaults to "yes". & No \\ \hline
options & use to set additional command-line options for the cabarc tool. should not normally be necessary. & No \\ \hline
includes & comma- or space-separated list of patterns of files that must be included. All files are included when omitted. & No \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & No \\ \hline
excludes & comma- or space-separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & No \\ \hline
defaultexcludes & indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline
\end{supertabular}

\subsubsection{Parameters specified as nested elements}

{\bf fileset}\hfil\break

The cab task supports any number of nested {\tt <fileset>} elements to
specify the files to be included in the archive.

\subsubsection{Examples}
\begin{verbatim}
<cab cabfile="${dist}/manual.cab"
     basedir="htdocs/manual" 
  />
\end{verbatim}
cabs all files in the htdocs/manual directory into a file called
manual.cab in the \$\{dist\} directory.
\begin{verbatim}
<cab cabfile="${dist}/manual.cab"
     basedir="htdocs/manual"
     excludes="mydocs/**, **/todo.html"
  />
\end{verbatim}
cabs all files in the htdocs/manual directory into a file called
manual.cab in the \$\{dist\} directory. Files in the directory mydocs, or
files with the name todo.html are excluded.
\begin{verbatim}
<cab cabfile="${dist}/manual.cab"
     basedir="htdocs/manual"
     includes="api/**/*.html"
     excludes="**/todo.html"
     verbose="yes"
  />
\end{verbatim}
Cab all files in the htdocs/manual directory into a file called
manual.cab in the \$\{dist\} directory. Only html files under the
directory api are archived, and files with the name todo.html are
excluded. Output from the cabarc tool is displayed in the build output.

\subsection{Clearcase Tasks}
\subsubsection{CCCheckin}

{\bf Description}\hfil\break

Task to perform a Checkin command to ClearCase.

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{6cm}|p{2cm}|} \hline
\tablehead{Attribute & Values & Required \\ \hline}
viewpath & Path to the ClearCase view file or directory that the command will operate on & No \\ \hline
comment & Specify a comment. Only one of comment or commentfile may be used. & No \\ \hline
commentfile & Specify a file containing a comment. Only one of comment or commentfile may be used. & No \\ \hline
nowarn & Suppress warning messages & No \\ \hline
preservetime & Preserve the modification time & No \\ \hline
keepcopy & Keeps a copy of the file with a .keep extension & No \\ \hline
identical & Allows the file to be checked in even if it is identical to the original & No \\ \hline
\end{supertabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<cccheckin viewpath="c:/views/viewdir/afile"
        commentfile="acomment.txt"
        nowarn="true"
        identical="true"/>
\end{verbatim}
Does a ClearCase checkin on the file c:/views/viewdir/afile. Comment
text from the file acomment.txt is added to ClearCase as a
comment. All warning messages are suppressed. The file is checked in
even if it is identical to the original.

\subsubsection{CCCheckout}

{\bf Description}\hfil\break

Task to perform a Checkout command to ClearCase.

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{6cm}|p{2cm}|} \hline
\tablehead{Attribute & Values & Required \\ \hline}
viewpath & Path to the ClearCase view file or directory that the command will operate on & No \\ \hline
reserved & Specifies whether to check out the file as reserved or not & Yes \\ \hline
out & Creates a writable file under a different filename & No \\ \hline
nodata & Checks out the file but does not create an editable file containing its data & No \\ \hline
branch & Specify a branch to check out the file to & No \\ \hline
version & Allows checkout of a version other than main latest & No \\ \hline
nowarn & Suppress warning messages & No \\ \hline
comment & Specify a comment. Only one of comment or commentfile may be used. & No \\ \hline
commentfile & Specify a file containing a comment. Only one of comment or commentfile may be used. & No \\ \hline
\end{supertabular}

Examples
\begin{verbatim}
<cccheckout viewpath="c:/views/viewdir/afile"
        reserved="true" 
        branch="abranch"
        nowarn="true"
        comment="Some comment text"/>
\end{verbatim}
Does a ClearCase checkout on the file c:/views/viewdir/afile. It is
checked out as reserved on branch called abranch. All warning messages
are suppressed. A Some comment text is added to ClearCase as a
comment.

\subsubsection{CCUnCheckout}

{\bf Description}\hfil\break

Task to perform a UnCheckout command to ClearCase.

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{6cm}|p{2cm}|} \hline
\tablehead{Attribute & Values & Required \\ \hline}
viewpath & Path to the ClearCase view file or directory that the command will operate on & No \\ \hline
keepcopy & Specifies whether to keep a copy of the file with a .keep extension or not & No \\ \hline
\end{supertabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<ccuncheckout viewpath="c:/views/viewdir/afile"
        keepcopy="true"/>
\end{verbatim}
Does a ClearCase uncheckout on the file c:/views/viewdir/afile. A copy
of the file called c:/views/viewdir/afile.keep is kept.

\subsubsection{CCUpdate}

{\bf Description}\hfil\break

Task to perform an Update command to ClearCase.

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{6cm}|p{2cm}|} \hline
\tablehead{Attribute & Values & Required \\ \hline}
viewpath & Path to the ClearCase view file or directory that the command will operate on & No \\ \hline
graphical & Displays a graphical dialog during the update & No \\ \hline
log & Specifies a log file for ClearCase to write to & No \\ \hline
overwrite & Specifies whether to overwrite hijacked files or not & No \\ \hline
rename & Specifies that hijacked files should be renamed with a .keep extension & No \\ \hline
currenttime & Specifies that modification time should be written as the current time. Either currenttime or preservetime can be specified. & No \\ \hline
preservetime & Specifies that modification time should preserved from the VOB time. Either currenttime or preservetime can be specified. & No \\ \hline
\end{supertabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<ccupdate viewpath="c:/views/viewdir"
        graphical="false" 
        log="log.log"
        overwrite="true"
        currenttime="true"
        rename="false"/>
\end{verbatim}
Does a ClearCase update on the directory c:/views/viewdir. A graphical
dialog will be displayed. The output will be logged to log.log and it
will overwrite any hijacked files. The modified time will be set to
the current time.

\subsection{Continuus/Synergy Tasks}

These ant tasks are wrappers around Continuus Source Manager. They
have been tested with version 5.1 on Windows 2000, but should work on
other platforms with ccm installed.

\subsubsection{CCMCheckin}

{\bf Description}\hfil\break

Task to checkin a file

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{6cm}|p{2cm}|} \hline
\tablehead{Attribute & Values & Required \\ \hline}
file & Path to the file that the command will operate on & Yes \\ \hline
comment & Specify a comment. Default is "Checkin" plus the date & No \\ \hline
task & Specify the task number used to check in the file (may use 'default') & No \\ \hline
ccmdir & path to the ccm executable file, required if it is not on the PATH & No \\ \hline
\end{supertabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<ccmcheckin file="c:/wa/com/foo/MyFile.java"
        comment="mycomment"/>
\end{verbatim}
Checks in the file c:/wa/com/foo/MyFile.java. Comment attribute
mycomment is added as a task comment. The task used is the one set as
the default.

\subsubsection{CCMCheckout}

{\bf Description}\hfil\break

Task to perform a Checkout command to Continuus

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{6cm}|p{2cm}|} \hline
\tablehead{Attribute & Values & Required \\ \hline}
file & Path to the file that the command will operate on & Yes \\ \hline
comment & Specify a comment. & No \\ \hline
task & Specify the task number used to checkin the file (may use 'default') & No \\ \hline
ccmdir & path to the ccm executable file, required if it is not on the PATH & No \\ \hline
\end{supertabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<ccmcheckout file="c:/wa/com/foo/MyFile.java"
        comment="mycomment"/>
\end{verbatim}
Check out the file c:/wa/com/foo/MyFile.java. Comment attribute
mycomment is added as a task comment The used task is the one set as
the default.

\subsubsection{CCMCheckinTask}

{\bf Description}\hfil\break

Task to perform a check in default task command to Continuus

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{6cm}|p{2cm}|} \hline
\tablehead{Attribute & Values & Required \\ \hline}
comment & Specify a comment. & No \\ \hline
task & Specify the task number used to check in the file (may use 'default') & No \\ \hline
ccmdir & path to the ccm executable file, required if it is not on the PATH & No \\ \hline
\end{supertabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<ccmcheckintask comment="blahblah/>
\end{verbatim}
Does a Checkin default task on all the checked out files in the
current task.

\subsubsection{CCMReconfigure}

{\bf Description}\hfil\break

Task to perform an reconfigure command to Continuus.

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{6cm}|p{2cm}|} \hline
\tablehead{Attribute & Values & Required \\ \hline}
recurse & recurse on subproject (default false) & No \\ \hline
verbose & do a verbose reconfigure operation (default false) & No \\ \hline
ccmproject & Specifies the ccm project on which the operation is applied. & Yes \\ \hline
ccmdir & path to the ccm executable file, required if it is not on the PATH & No \\ \hline
\end{supertabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<ccmreconfigure ccmproject="ANTCCM_TEST#BMO_1" 
         verbose="true" />
\end{verbatim}
Does a Continuus reconfigure on the project {\tt ANTCCM\_TEST\#BMO\_1}.

\subsubsection{CCMCreateTask}

{\bf Description}\hfil\break

Create a Continuus task.

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{6cm}|p{2cm}|} \hline
\tablehead{Attribute & Values & Required \\ \hline}
comment & Specify a comment. & No \\ \hline
platform & Specify the target platform & No \\ \hline
ccmdir & path to the ccm executable file, required if it is not on the PATH & No \\ \hline
resolver & Specify the resolver & No \\ \hline
release & Specify the CCM release & No \\ \hline
subsystem & Specify the subsystem & No \\ \hline
task & Specify the task number used to checkin the file (may use 'default') & No \\ \hline
\end{supertabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<ccmcreatetask resolver="${user.name}" 
            release="ANTCCM_TEST" comment="blahblah" />
\end{verbatim}
Creates a task for the release ANTCCM\_TEST with the current user as
the resolver for this task.

\subsection{Depend}

A task to manage Java class file dependencies.

\subsubsection{Description}

The depend task works by determining which classes are out of date
with respect to their source and then removing the class files of any
other classes which depend on the out-of-date classes.

To determine the class dependencies, the depend task analyses the
class files of all class files passed to it. Depend does not parse
your source code in any way but relies upon the class references
encoded into the class files by the compiler. This is generally faster
than parsing the Java source.

To learn more about how this information is obtained from the class
files, please refer to the Java Virtual Machine Specification

Since a class' dependencies only change when the class itself changes,
the depend task is able to cache dependency information. Only those
class files which have changed will have their dependency information
re-analysed. Note that if you change a class' dependencies by changing
the source, it will be recompiled anyway. You can examine the
dependency files created to understand the dependencies of your
classes. Please do not rely, however, on the format of the
information, as it may change in a later release.

Once depend discovers all of the class dependencies, it "inverts" this
relation to determine, for each class, which other classes are
dependent upon it. This "affects" list is used to discover which
classes are invalidated by the out of date class. The class files of
the invalidated classes are removed, triggering the compilation of the
affected classes.

The depend task supports an attribute, "closure" which controls
whether depend will only consider direct class-class relationships or
whether it will also consider transitive, indirect relationships. For
example, say there are three classes, A, which depends on B, which
in-turn depend on C. Now say that class C is out of date. Without
closure, only class B would be removed by depend. With closure set,
class A would also be removed. Normally direct relationships are
sufficient - it is unusual for a class to depend on another without
having a direct relationship. With closure set, you will notice that
depend typically removes far more class files.

The classpath attribute for {\tt <depend>} is optional. If it is present,
depend will check class dependencies against classes and jars on this
classpath. Any classes which depend on an element from this classpath
and which are older than that element will be deleted. A typical
example where you would use this facility would be where you are
building a utility jar and want to make sure classes which are out of
date with respect to this jar are rebuilt. You should not include jars
in this classpath which you do not expect to change, such as the JDK
runtime jar or third party jars, since doing so will just slow down
the dependency check. This means that if you do use a classpath for
the depend task it may be different from the classpath necessary to
actually compile your code.

\subsubsection{Performance}

The performance of the depend task is dependent on a number of factors
such as class relationship complexity and how many class files are out
of date. The decision about whether it is cheaper to just recompile
all classes or to use the depend task will depend on the size of your
project and how interrelated your classes are.

\subsubsection{Limitations}

There are some source dependencies which depend will not detect.
\begin{itemize}
\item If the Java compiler optimizes away a class relationship, there can be a source dependency without a class dependency.
\item Non public classes cause two problems. Firstly depend cannot relate the class file to a source file. In the future this may be addressed using the source file attribute in the classfile. Secondly, neither depend nor the compiler tasks can detect when a non public class is missing. Inner classes are handled by the depend task.
\end{itemize}
The most obvious example of these limitations is that the task can't
tell which classes to recompile when a constant primitive data type
exported by other classes is changed. For example, a change in the
definition of something like
\begin{verbatim}
public final class Constants {
  public final static boolean DEBUG=false;
}
\end{verbatim}
will not be picked up by other classes.

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{6cm}|p{2cm}|} \hline
\tablehead{Attribute & Values & Required \\ \hline}
srcDir & This is the directory where the source exists. depend will examine this to determine which classes are out of date. If you use multiple source directories you can pass this attribute a path of source directories. & Yes \\ \hline
destDir & This is the root directory of the class files which will be analysed. If this is not present, the srcdir is used. & No \\ \hline
cache & This is a directory in which depend can store and retrieve dependency information. If this is not present, depend will not use a cache & No \\ \hline
closure & This attribute controls whether depend only removes classes which directly depend on out of date classes. If this is set to true, depend will traverse the class dependency graph deleting all affected classes. Defaults to false & No \\ \hline
dump & If true the dependency information will be written to the debug level log & No \\ \hline
classpath & The classpath containg jars and classes for which {\tt <depend>} should also check dependencies & No \\ \hline
\end{supertabular}

{\bf Parameters specified as nested elements}\hfil\break

The depend task's classpath attribute is a PATH-like structure and can
also be set via a nested {\tt <classpath>} element.

Additionally, this task forms an implicit FileSet and supports all
attributes of {\tt <fileset>} (dir becomes srcdir), as well as the nested
{\tt <include>}, {\tt <exclude>}, and {\tt <patternset>} elements.

Examples
\begin{verbatim}
<depend srcdir="${java.dir}"
        destdir="${build.classes}"
        cache="depcache"
        closure="yes"/>
\end{verbatim}
removes any classes in the \$\{build.classes\} directory that depend on
out-of-date classes. Classes are considered out-of-date with respect
to the source in the \$\{java.dir\} directory, using the same mechanism
as the {\tt <javac>} task. In this example, the {\tt <depend>} task caches its
dependency information in the depcache directory.
\begin{verbatim}
<depend srcdir="${java.dir}" destdir="${build.classes}"
        cache="depcache" closure="yes">
  <include name="**/*.java"/>
  <excludesfile name="${java.dir}/build_excludes"/>
</depend>
\end{verbatim}
does the same as the previous example, but explicitly includes all
.java files, except those that match the list given in
\$\{java.dir\}/build\_excludes.

\subsection{EJB Tasks}

by
\begin{verbatim}
    * Paul Austin (p_d_austin@yahoo.com)
    * Holger Engels (hengels@innovidata.com)
    * Tim Fennell (tfenne@rcn.com)
    * Martin Gee (martin.gee@icsynergy.com)
    * Conor MacNeill
    * Cyrille Morvan (cmorvan@ingenosya.com)
    * Greg Nelson (gn@sun.com)

Version @VERSION@
$Id: ejb.html,v 1.23.2.17 2003/03/19 13:43:32 conor Exp $
\end{verbatim}

Ant provides a number of optional tasks for developing Enterprise Java
Beans (EJBs). In general these tasks are specific to the particular
vendor's EJB Server.

At present the tasks support:
\begin{itemize}
\item Borland Application Server 4.5
\item iPlanet Application Server 6.0
\item JBoss 2.1 and above EJB servers
\item Weblogic 4.5.1 through to 7.0 EJB servers
\item JOnAS 2.4.x and 2.5 Open Source EJB server
\item IBM WebSphere 4.0
\end{itemize}
Over time we expect further optional tasks to support additional EJB Servers.

\subsubsection{EJB Tasks}

\begin{tabular}{|l|l|} \hline
Task & Application Servers \\ \hline
blgenclient & Borland Application Server 4.5 \\ \hline
ddcreator & Weblogic 4.5.1 \\ \hline
ejbc & Weblogic 4.5.1 \\ \hline
iplanet-ejbc & iPlanet Application Server 6.0 \\ \hline

\begin{tabular}{|l|p{5cm}|} \hline
ejbjar &
    \begin{tabular}{p{4.5cm}} \hline
        Nested Elements \\ \hline
        \begin{tabular}{|l|l|}
            borland & Borland Application Server 4.5 \\ \hline
            iPlanet & iPlanet Application Server 6.0 \\ \hline
            jboss & JBoss \\ \hline
            jonas & JOnAS 2.4.x and 2.5 \\ \hline
            weblogic & Weblogic 5.1 to 7.0 \\ \hline
            websphere & IBM WebSphere 4.0 \\ \hline
        \end{tabular} \\
    \end{tabular} 
\end{tabular}
    \\ \hline
wlrun & Weblogic 4.5.1 to 7.0 \\ \hline
wlstop & Weblogic 4.5.1 to 7.0 \\ \hline
\end{tabular}

{\bf ddcreator}\hfil\break

Description:

ddcreator will compile a set of Weblogic text-based deployment
descriptors into a serialized EJB deployment descriptor. The selection
of which of the text-based descriptors are to be compiled is based on
the standard Ant include and exclude selection mechanisms.

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{6cm}|p{2cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
descriptors & This is the base directory from which descriptors are selected. & Yes \\ \hline
dest & The directory where the serialized deployment descriptors will be written & Yes \\ \hline
classpath & This is the classpath to use to run the underlying weblogic ddcreator tool. This must include the weblogic.ejb.utils.DDCreator class & No \\ \hline
\end{supertabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<ddcreator descriptors="${dd.dir}"
           dest="${gen.classes}"
           classpath="${descriptorbuild.classpath}">
  <include name="*.txt"/>
</ddcreator>
\end{verbatim}

\subsubsection{ejbc}

{\bf Description:}\hfil\break

The ejbc task will run Weblogic's ejbc tool. This tool will take a
serialized deployment descriptor, examine the various EJB interfaces
and bean classes and then generate the required support classes
necessary to deploy the bean in a Weblogic EJB container. This will
include the RMI stubs and skeletons as well as the classes which
implement the bean's home and remote interfaces.

The ant task which runs this tool is able to compile several beans in
a single operation. The beans to be compiled are selected by including
their serialized deployment descriptors. The standard ant include and
exclude constructs can be used to select the deployment descriptors to
be included.

Each descriptor is examined to determine whether the generated classes
are out of date and need to be regenerated. The deployment descriptor
is de-serialized to discover the home, remote and implementation
classes. The corresponding source files are determined and checked to
see their modification times. These times and the modification time of
the serialized descriptor itself are compared with the modification
time of the generated classes. If the generated classes are not
present or are out of date, the ejbc tool is run to generate new
versions.

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{6cm}|p{2cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
descriptors & This is the base directory from which the serialized deployment descriptors are selected. & Yes \\ \hline
dest & The base directory where the generated classes, RIM stubs and RMI skeletons are written & Yes \\ \hline
manifest & The name of a manifest file to be written. This manifest will contain an entry for each EJB processed & Yes \\ \hline
src & The base directory of the source tree containing the source files of the home interface, remote interface and bean implementation classes. & Yes \\ \hline
classpath & This classpath must include both the weblogic.ejbc class and the class files of the bean, home interface, remote interface, etc of the bean being processed. & No \\ \hline
keepgenerated & Controls whether ejbc will keep the intermediate Java files used to build the class files. This can be useful when debugging. & No, defaults to false. \\ \hline
\end{supertabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<ejbc descriptors="${gen.classes}"
           src="${src.dir}"
           dest="${gen.classes}"
           manifest="${build.manifest}"
           classpath="${descriptorbuild.classpath}">
  <include name="*.ser"/>
</ejbc>
\end{verbatim}

\subsubsection{iplanet-ejbc}

{\bf Description:}\hfil\break

Task to compile EJB stubs and skeletons for the iPlanet Application
Server 6.0. Given a standard EJB 1.1 XML descriptor as well as an
iAS-specific EJB descriptor, this task will generate the stubs and
skeletons required to deploy the EJB to iAS. Since the XML descriptors
can include multiple EJBs, this is a convenient way of specifying many
EJBs in a single Ant task.

For each EJB specified, the task will locate the three classes that
comprise the EJB in the destination directory. If these class files
cannot be located in the destination directory, the task will
fail. The task will also attempt to locate the EJB stubs and skeletons
in this directory. If found, the timestamps on the stubs and skeletons
will be checked to ensure they are up to date. Only if these files
cannot be found or if they are out of date will the iAS ejbc utility
be called to generate new stubs and skeletons.

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{6cm}|p{2cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
ejbdescriptor & Standard EJB 1.1 XML descriptor (typically titled "ejb-jar.xml"). & Yes \\ \hline
iasdescriptor & iAS-specific EJB XML descriptor (typically titled "ias-ejb-jar.xml"). & Yes \\ \hline
dest & The is the base directory where the RMI stubs and skeletons are written. In addition, the class files for each bean (home interface, remote interface, and EJB implementation) must be found in this directory. & Yes \\ \hline
classpath & The classpath used when generating EJB stubs and skeletons. If omitted, the classpath specified when Ant was started will be used. Nested "classpath" elements may also be used. & No \\ \hline
keepgenerated & Indicates whether or not the Java source files which are generated by ejbc will be saved or automatically deleted. If "yes", the source files will be retained. If omitted, it defaults to "no". & No \\ \hline
debug & Indicates whether or not the ejbc utility should log additional debugging statements to the standard output. If "yes", the additional debugging statements will be generated. If omitted, it defaults to "no". & No \\ \hline
iashome & May be used to specify the "home" directory for this iAS installation. This is used to find the ejbc utility if it isn't included in the user's system path. If specified, it should refer to the "[install-location]/iplanet/ias6/ias" directory. If omitted, the ejbc utility must be on the user's system path. & No \\ \hline
\end{supertabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<iplanet-ejbc ejbdescriptor="ejb-jar.xml"
              iasdescriptor="ias-ejb-jar.xml"
              dest="${build.classesdir}"
              classpath="${ias.ejbc.cpath}"/>

<iplanet-ejbc ejbdescriptor="ejb-jar.xml"
              iasdescriptor="ias-ejb-jar.xml"
              dest="${build.classesdir}"
              keepgenerated="yes"
              debug="yes"
              iashome="${ias.home}">
              <classpath>
                  <pathelement path="."/>
                  <pathelement path="${build.classpath}"/>
              </classpath>
</iplanet-ejbc>
\end{verbatim}

\subsubsection{wlrun}

{\bf Description:}\hfil\break

The wlrun task is used to start a weblogic server. The task runs a
weblogic instance in a separate Java Virtual Machine. A number of
parameters are used to control the operation of the weblogic
instance. Note that the task, and hence ant, will not complete until
the weblogic instance is stopped.

{\bf Parameters}\hfil\break

\begin{supertabular}{|l|p{6cm}|p{2.5cm}|p{2.5cm}|} \hline
\tablehead{Attribute & Description & Required for 4.5.1 and 5.1 & Required for 6.0 \\ \hline}
BEA Home & The location of the BEA Home where the server's config is defined. If this attribute is present, wlrun assumes that the server will be running under Weblogic 6.0 & N/A & Yes \\ \hline
home & The location of the weblogic home that is to be used. This is the location where weblogic is installed. & Yes & Yes. Note this is the absolute location, not relative to BEA home. \\ \hline
Domain & The domain to which the server belongs. & N/A & Yes \\ \hline
classpath & The classpath to be used with the Java Virtual Machine that runs the Weblogic Server. Prior to Weblogic 6.0, this is typically set to the Weblogic boot classpath. Under Weblogic 6.0 this should include all the weblogic jars & Yes & Yes \\ \hline
wlclasspath & The weblogic classpath used by the Weblogic Server. & No & N/A \\ \hline
properties & The name of the server's properties file within the weblogic home directory used to control the weblogic instance. & Yes & N/A \\ \hline
name & The name of the weblogic server within the weblogic home which is to be run. This defaults to "myserver" & No & No \\ \hline
policy & The name of the security policy file within the weblogic home directory that is to be used. If not specified, the default policy file weblogic.policy is used. & No & No \\ \hline
username & The management username used to manage the server & N/A & No \\ \hline
password & The server's management password & N/A & Yes \\ \hline
pkPassword & The private key password so the server can decrypt the SSL private key file & N/A & No \\ \hline
jvmargs  & Additional argument string passed to the Java Virtual Machine used to run the Weblogic instance. & No & No \\ \hline
weblogicMainClass & name of the main class for weblogic & No & No \\ \hline
\end{supertabular}

{\bf Nested Elements}\hfil\break

The wlrun task supports nested {\tt <classpath>} and {\tt <wlclasspath>}
elements to set the respective classpaths.

{\bf Examples}\hfil\break

This example shows the use of wlrun to run a server under Weblogic 5.1
\begin{verbatim}
    <wlrun taskname="myserver"
           classpath="${weblogic.boot.classpath}"
           wlclasspath="${weblogic.classes}:${code.jars}"
           name="myserver"
           home="${weblogic.home}"
           properties="myserver/myserver.properties"/>
\end{verbatim}
This example shows wlrun being used to run the petstore server under
Weblogic 6.0
\begin{verbatim}
    <wlrun taskname="petstore"
           classpath="${weblogic.classes}"
           name="petstoreServer"
           domain="petstore"
           home="${weblogic.home}"
           password="petstorePassword"
           beahome="${bea.home}"/>
\end{verbatim}

\subsubsection{wlstop}

{\bf Description:}\hfil\break

The wlstop task is used to stop a weblogic instance which is currently
running. To shut down an instance you must supply both a username and
a password. These will be stored in the clear in the build script used
to stop the instance. For security reasons, this task is therefore
only appropriate in a development environment.

This task works for most version of Weblogic, including 6.0. You need
to specify the BEA Home to have this task work correctly under 6.0

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|c|} \hline
Attribute & Description & Required \\ \hline
BEAHome & This attribute selects Weblogic 6.0 shutdown. & No \\ \hline
classpath & The classpath to be used with the Java Virtual Machine that runs the Weblogic Shutdown command. & Yes \\ \hline
user & The username of the account which will be used to shutdown the server & Yes \\ \hline
password & The password for the account specified in the user parameter. & Yes \\ \hline
url & The URL which describes the port to which the server is listening for T3 connections. For example, t3://localhost:7001 & Yes \\ \hline
delay & The delay in seconds after which the server will stop. This defaults to an immediate shutdown. & No \\ \hline
\end{tabular}

{\bf Nested Element}\hfil\break

The classpath of the wlstop task can be set by a {\tt <classpath>}
nested element.

{\bf Examples}\hfil\break

This example show the shutdown for a Weblogic 6.0 server
\begin{verbatim}
    <wlstop classpath="${weblogic.classes}"
            user="system"
            url="t3://localhost:7001"
            password="foobar"
            beahome="${bea.home}"/>
\end{verbatim}

\subsubsection{ejbjar}

{\bf Description:}\hfil\break

This task is designed to support building of EJB jar files (EJB 1.1 \&
2.0). Support is currently provided for 'vanilla' EJB jar files -
i.e. those containing only the user generated class files and the
standard deployment descriptor. Nested elements provide support for
vendor specific deployment tools. These currently include:
\begin{itemize}
\item Borland Application Server 4.5
\item iPlanet Application Server 6.0
\item JBoss 2.1 and above
\item Weblogic 5.1/6.0 session/entity beans using the weblogic.ejbc tool
\item IBM WebSphere 4.0
\item TOPLink for WebLogic 2.5.1-enabled entity beans
\item JOnAS 2.4.x and 2.5 Open Source EJB server
\end{itemize}
The task works as a directory scanning task, and performs an action
for each deployment descriptor found. As such the includes and
excludes should be set to ensure that all desired EJB descriptors are
found, but no application server descriptors are found. For each
descriptor found, ejbjar will parse the deployment descriptor to
determine the necessary class files which implement the bean. These
files are assembled along with the deployment descriptors into a well
formed EJB jar file. Any support files which need to be included in
the generated jar can be added with the {\tt <support>} nested element. For
each class included in the jar, ejbjar will scan for any super classes
or super interfaces. These will be added to the generated jar.

If no nested vendor-specific deployment elements are present, the task
will simply generate a generic EJB jar. Such jars are typically used
as the input to vendor-specific deployment tools. For each nested
deployment element, a vendor specific deployment tool is run to
generate a jar file ready for deployment in that vendor's EJB
container.

The jar files are only built if they are out of date. Each deployment
tool element will examine its target jar file and determine if it is
out of date with respect to the class files and deployment descriptors
that make up the bean. If any of these files are newer than the jar
file the jar will be rebuilt otherwise a message is logged that the
jar file is up to date.

The task uses the jakarta-BCEL framework to extract all dependent
classes. This means that, in addition to the classes that are
mentioned in the deployment descriptor, any classes that these depend
on are also automatically included in the jar file.

{\bf Naming Convention}\hfil\break

Ejbjar handles the processing of multiple beans, and it uses a set of
naming conventions to determine the name of the generated EJB
jars. The naming convention that is used is controlled by the "naming"
attribute. It supports the following values
\begin{itemize}
\item descriptor\hfil\break

 This is the default naming scheme. The name of the generated bean is
 derived from the name of the deployment descriptor. For an Account
 bean, for example, the deployment descriptor would be named
 Account-ejb-jar.xml. Vendor specific descriptors are located using
 the same naming convention. The weblogic bean, for example, would be
 named Account-weblogic-ejb-jar.xml. Under this arrangement, the
 deployment descriptors can be separated from the code implementing
 the beans, which can be useful when the same bean code is deployed in
 separate beans.

 This scheme is useful when you are using one bean per EJB jar and
 where you may be deploying the same bean classes in different beans,
 with different deployment characteristics.

\item ejb-name\hfil\break

      This naming scheme uses the {\tt <ejb-name>} element from the
      deployment descriptor to determine the bean name. In this
      situation, the descriptors normally use the generic descriptor
      names, such as ejb-jar.xml along with any associated vendor
      specific descriptor names. For example, If the value of the
      {\tt <ejb-name>} were to be given in the deployment descriptor as
      follows:

\begin{verbatim}
<ejb-jar>
    <enterprise-beans>
        <entity>
            <ejb-name>Sample</ejb-name>
            <home>org.apache.ant.ejbsample.SampleHome</home>
\end{verbatim}
      then the name of the generated bean would be Sample.jar

 This scheme is useful where you want to use the standard deployment
 descriptor names, which may be more compatible with other EJB
 tools. This scheme must have one bean per jar.

 \item directory\hfil\break

 In this mode, the name of the generated bean jar is derived from the
 directory containing the deployment descriptors. Again the deployment
 descriptors typically use the standard filenames. For example, if the
 path to the deployment descriptor is
 /home/user/dev/appserver/dd/sample, then the generated bean will be
 named sample.jar

 This scheme is also useful when you want to use standard style
 descriptor names. It is often most useful when the descriptors are
 located in the same directory as the bean source code, although that
 is not mandatory. This scheme can handle multiple beans per jar.
 
\item basejarname\hfil\break

 The final scheme supported by the {\tt <ejbjar>} task is used when
 you want to specify the generated bean jar name directly. In this
 case the name of the generated jar is specified by the "basejarname"
 attribute. Since all generated beans will have the same name, this
 task should be only used when each descriptor is in its own
 directory.

This scheme is most appropriate when you are using multiple beans per
jar and only process a single deployment descriptor. You typically
want to specify the name of the jar and not derive it from the beans
in the jar.
\end{itemize}

{\bf Dependencies}\hfil\break

In addition to the bean classes, ejbjar is able to ad additional
classes to the generated ejbjar. These classes are typically the
support classes which are used by the bean's classes or as parameters
to the bean's methods.

In versions of Ant prior to 1.5, ejbjar used reflection and attempted
to add the super classes and super interfaces of the bean classes. For
this technique to work the bean classes had to be loaded into Ant's
JVM. This was not always possible due to class dependencies.

The ejbjar task in Ant releases 1.5 and later uses the jakarta-BCEL
library to analyze the bean's class files directly, rather than
loading them into the JVM. This also allows ejbjar to add all of the
required support classes for a bean and not just super classes.

In Ant 1.5, a new attribute, dependency has been introduced to allow
the buildfile to control what additional classes are added to the
generated jar. It takes three possible values
\begin{itemize}
\item none - only the bean classes and interfaces described in the bean's descriptor are added to the jar.
\item super - this is the default value and replicates the original ejbjar behaviour where super classes and super interfaces are added to the jar
\item full - In this mode all classes used by the bean's classes and interfaces are added to the jar
\end{itemize}
The super and full values require the jakarta-BCEL library to be
available. If it is not, ejbjar will drop back to the behaviour
corresponding to the value none.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{6cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
descriptordir & The base directory under which to scan for EJB deployment descriptors. If this attribute is not specified, then the deployment descriptors must be located in the directory specified by the 'srcdir' attribute. & No \\ \hline
srcdir & The base directory containing the .class files that make up the bean. Included are the home- remote- pk- and implementation- classes and all classes, that these depend on. Note that this can be the same as the descriptordir if all files are in the same directory tree. & Yes \\ \hline
destdir & The base directory into which generated jar files are deposited. Jar files are deposited in directories corresponding to their location within the descriptordir namespace. Note that this attribute is only used if the task is generating generic jars (i.e. no vendor-specific deployment elements have been specified). & Yes \\ \hline
naming & Controls the naming convention used to name generated EJB jars. Please refer to the description above. & No \\ \hline
basejarname & The base name that is used for the generated jar files. If this attribute is specified, the generic jar file name will use this value as the prefix (followed by the value specified in the 'genericjarsuffix' attribute) and the resultant ejb jar file (followed by any suffix specified in the nested element). & No \\ \hline
basenameterminator & String value used to substring out a string from the name of each deployment descriptor found, which is then used to locate related deployment descriptors (e.g. the WebLogic descriptors). For example, a basename of '.' and a deployment descriptor called 'FooBean.ejb-jar.xml' would result in a basename of 'FooBean' which would then be used to find FooBean.weblogic-ejb-jar.xml and FooBean.weblogic-cmp-rdbms-jar.xml, as well as to create the filenames of the jar files as FooBean-generic.jar and FooBean-wl.jar. This attribute is not used if the 'basejarname' attribute is specified. No, defaults to '-& '. \\ \hline
genericjarsuffix & String value appended to the basename of the deployment descriptor to create the filename of the generic EJB jar file. No, defaults to '-generic.& jar'. \\ \hline
classpath & This classpath is used when resolving classes which are to be added to the jar. Typically nested deployment tool elements will also support a classpath which will be combined with this classpath when resolving classes & No. \\ \hline
flatdestdir & Set this attribute to true if you want all generated jars to be placed in the root of the destdir, rather than according to the location of the deployment descriptor within the descriptor dir hierarchy. & No. \\ \hline
dependency & This attribute controls which additional classes and interfaces are added to the jar. Please refer to the description above & No. \\ \hline
\end{tabular}

{\bf Nested Elements}\hfil\break

In addition to the vendor specific nested elements, the ejbjar task
provides three nested elements.

{\bf Classpath}\hfil\break

The {\tt <classpath>} nested element allows the classpath to be
set. It is useful when setting the classpath from a reference path. In
all other respects the behaviour is the same as the classpath
attribute.

{\bf dtd}\hfil\break

The {\tt <dtd>} element is used to specify the local location of DTDs
to be used when parsing the EJB deployment descriptor. Using a local
DTD is much faster than loading the DTD across the net. If you are
running ejbjar behind a firewall you may not even be able to access
the remote DTD. The supported vendor-specific nested elements know the
location of the required DTDs within the vendor class hierarchy and,
in general, this means {\tt <dtd>} elements are not required. It does
mean, however, that the vendor's class hierarchy must be available in
the classpath when Ant is started. If your want to run Ant without
requiring the vendor classes in the classpath, you would need to use a
{\tt <dtd>} element.

\begin{tabular}{|l|p{6cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
publicId & The public Id of the DTD for which the location is being provided & Yes \\ \hline
location & The location of the local copy of the DTD. This can either be a file or a resource loadable from the classpath. & Yes \\ \hline
\end{tabular}

{\bf support}\hfil\break

The {\tt <support>} nested element is used to supply additional classes (files) to be included in the generated jars. 
The {\tt <support>} element is a FileSet, so it can either reference a fileset declared elsewhere or it can be defined in-place with the appropriate {\tt <include>} and {\tt <exclude>} nested elements. The files in the support fileset are added into the generated EJB jar in the same relative location as their location within the support fileset. Note that when ejbjar generates more than one jar file, the support files are added to each one.

{\bf Vendor-specific deployment elements}\hfil\break

Each vendor-specific nested element controls the generation of a
deployable jar specific to that vendor's EJB container. The parameters
for each supported deployment element are detailed here.

{\bf Jboss element}\hfil\break

The jboss element searches for the JBoss specific deployment
descriptors and adds them to the final ejb jar file. JBoss has two
deployment descriptors jboss.xml and jaws.xml (for container manager
persistence only). The JBoss server uses hot deployment and does not
require compilation of additional stubs and skeletons.

\begin{tabular}{|l|p{6cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
destdir & The base directory into which the generated weblogic ready jar files are deposited. Jar files are deposited in directories corresponding to their location within the descriptordir namespace. & Yes \\ \hline
genericjarsuffix & A generic jar is generated as an intermediate step in build the weblogic deployment jar. The suffix used to generate the generic jar file is not particularly important unless it is desired to keep the generic jar file. It should not, however, be the same as the suffix setting. & No, defaults to '-generic.jar'. \\ \hline
suffix & String value appended to the basename of the deployment descriptor to create the filename of the JBoss EJB jar file. & No, defaults to '.jar'. \\ \hline
keepgeneric & This controls whether the generic file used as input to ejbc is retained. & No, defaults to false \\ \hline
\end{tabular}

{\bf Weblogic element}\hfil\break

The weblogic element is used to control the weblogic.ejbc compiler for
generating weblogic EJB jars. Prior to Ant 1.3, the method of locating
CMP descriptors was to use the ejbjar naming convention. So if your
ejb-jar was called, Customer-ejb-jar.xml, your weblogic descriptor was
called Customer- weblogic-ejb-jar.xml and your CMP descriptor had to
be Customer-weblogic-cmp- rdbms-jar.xml. In addition, the {\tt
<type-storage>} element in the weblogic descriptor had to be set to
the standard name META-INF/weblogic-cmp-rdbms- jar.xml, as that is
where the CMP descriptor was mapped to in the generated jar.

There are a few problems with this scheme. It does not allow for more
than one CMP descriptor to be defined in a jar and it is not
compatible with the deployment descriptors generated by some tools.

In Ant 1.3, ejbjar parses the weblogic deployment descriptor to
discover the CMP descriptors, which are then included
automatically. This behaviour is controlled by the newCMP
attribute. Note that if you move to the new method of determining CMP
descriptors, you will need to update your weblogic deployment
descriptor's {\tt <type-storage>} element. In the above example, you
would define this as META-INF/Customer-weblogic-cmp-rdbms-jar.xml.

\begin{tabular}{|l|p{9cm}|p{1.5cm}|} \hline
Attribute & Description & Required \\ \hline
destdir & The base directory into which the generated weblogic ready jar files are deposited. Jar files are deposited in directories corresponding to their location within the descriptordir namespace. & Yes \\ \hline
genericjarsuffix & A generic jar is generated as an intermediate step in build the weblogic deployment jar. The suffix used to generate the generic jar file is not particularly important unless it is desired to keep the generic jar file. It should not, however, be the same as the suffix setting. & No, defaults to '-generic.jar'. \\ \hline
suffix & String value appended to the basename of the deployment descriptor to create the filename of the WebLogic EJB jar file. & No, defaults to '.jar'. \\ \hline
classpath & The classpath to be used when running the weblogic ejbc tool. Note that this tool typically requires the classes that make up the bean to be available on the classpath. Currently, however, this will cause the ejbc tool to be run in a separate VM & No \\ \hline
wlclasspath & Weblogic 6.0 will give a warning if the home and remote interfaces of a bean are on the system classpath used to run weblogic.ejbc. In that case, the standard weblogic classes should be set with this attribute (or equivalent nested element) and the home and remote interfaces located with the standard classpath attribute & No \\ \hline
keepgeneric & This controls whether the generic file used as input to ejbc is retained. & No, defaults to false \\ \hline
compiler & This allows for the selection of a different compiler to be used for the compilation of the generated Java files. This could be set, for example, to Jikes to compile with the Jikes compiler. If this is not set and the build.compiler property is set to jikes, the Jikes compiler will be used. If this is not desired, the value "default" may be given to use the default compiler & No \\ \hline
rebuild & This flag controls whether weblogic.ejbc is always invoked to build the jar file. In certain circumstances, such as when only a bean class has been changed, the jar can be generated by merely replacing the changed classes and not rerunning ejbc. Setting this to false will reduce the time to run ejbjar. & No, defaults to true. \\ \hline
keepgenerated & Controls whether weblogic will keep the generated Java files used to build the class files added to the jar. This can be useful when debugging & No, defaults to false. \\ \hline
args & Any additional arguments to be passed to the weblogic.ejbc tool. & No. \\ \hline
weblogicdtd & Deprecated. Defines the location of the ejb-jar DTD in the weblogic class hierarchy. This should not be necessary if you have weblogic in your classpath. If you do not, you should use a nested {\tt <dtd>} element, described above. If you do choose to use an attribute, you should use a nested {\tt <dtd>} element. & No. \\ \hline
wldtd & Deprecated. Defines the location of the weblogic-ejb-jar DTD which covers the Weblogic specific deployment descriptors. This should not be necessary if you have weblogic in your classpath. If you do not, you should use a nested {\tt <dtd>} element, described above. & No. \\ \hline
\end{tabular}
\begin{tabular}{|l|p{9cm}|p{1.5cm}|} \hline
Attribute & Description & Required \\ \hline
ejbdtd & Deprecated. Defines the location of the ejb-jar DTD in the weblogic class hierarchy. This should not be necessary if you have weblogic in your classpath. If you do not, you should use a nested {\tt <dtd>} element, described above. & No. \\ \hline
newCMP & If this is set to true, the new method for locating CMP descriptors will be used. & No. Defaults to false \\ \hline
oldCMP & Deprecated This is an antonym for newCMP which should be used instead. & No. \\ \hline
noEJBC & If this attribute is set to true, Weblogic's ejbc will not be run on the EJB jar. Use this if you prefer to run ejbc at deployment time. & No. \\ \hline
ejbcclass & Specifies the classname of the ejbc compiler. Normally ejbjar determines the appropriate class based on the DTD used for the EJB. The EJB 2.0 compiler featured in weblogic 6 has, however, been deprecated in version 7. When using with version 7 this attribute should be set to "weblogic.ejbc" to avoid the deprecation warning. & No. \\ \hline
jvmargs & Any additional arguments to be passed to the Virtual Machine running weblogic.ejbc tool. For example to set the memory size, this could be jvmargs="-Xmx128m" & No. \\ \hline
jvmdebuglevel & Sets the weblogic.StdoutSeverityLevel to use when running the Virtual Machine that executes ejbc. Set to 16 to avoid the warnings about EJB Home and Remotes being in the classpath & No. \\ \hline
outputdir & If set ejbc will be given this directory as the output destination rather than a jar file. This allows for the generation of "exploded" jars. & No. \\ \hline
\end{tabular}

The weblogic nested element supports three nested elements. The first
two, {\tt <classpath>} and {\tt <wlclasspath>}, are used to set the
respective classpaths. These nested elements are useful when setting
up class paths using reference Ids. The last, {\tt <sysproperty>},
allows Java system properties to be set during the compiler run. This
turns out to be necessary for supporting CMP EJB compilation in all
environments.

{\bf TOPLink for Weblogic element}\hfil\break

{\em Deprecated}\hfil\break

The toplink element is no longer required. Toplink beans can now be
built with the standard weblogic element, as long as the newCMP
attribute is set to "true"

The TopLink element is used to handle beans which use Toplink for the
CMP operations. It is derived from the standard weblogic element so it
supports the same set of attributes plus these additional attributes

\begin{tabular}{|l|p{9cm}|p{1.5cm}|} \hline
Attribute & Description & Required \\ \hline
toplinkdescriptor & This specifies the name of the TOPLink deployment descriptor file contained in the 'descriptordir' directory. & Yes \\ \hline
toplinkdtd & This specifies the location of the TOPLink DTD file. This can be a file path or a file URL. This attribute is not required, but using a local DTD is recommended. & No, defaults to dtd file at www.objectpeople.com. \\ \hline
\end{tabular}

{\bf Examples}\hfil\break

This example shows ejbjar being used to generate deployment jars using
a Weblogic EJB container. This example requires the naming standard to
be used for the deployment descriptors. Using this format will create
a ejb jar file for each variation of '*-ejb-jar.xml' that is found in
the deployment descriptor directory.
\begin{verbatim}
    <ejbjar srcdir="${build.classes}"
            descriptordir="${descriptor.dir}">
      <weblogic destdir="${deploymentjars.dir}"
                classpath="${descriptorbuild.classpath}"/>
      <include name="**/*-ejb-jar.xml"/>
      <exclude name="**/*weblogic*.xml"/>
    </ejbjar>
\end{verbatim}
If weblogic is not in the Ant classpath, the following example shows how to specify the location of the weblogic DTDs. This example also show the use of a nested classpath element.
\begin{verbatim}
    <ejbjar descriptordir="${src.dir}" srcdir="${build.classes}">
       <weblogic destdir="${deployment.webshop.dir}"
                 keepgeneric="true"
                 args="-g -keepgenerated ${ejbc.compiler}"
                 suffix=".jar"
                 oldCMP="false">
         <classpath>
           <pathelement path="${descriptorbuild.classpath}"/>
         </classpath>
       </weblogic>
       <include name="**/*-ejb-jar.xml"/>
       <exclude name="**/*-weblogic-ejb-jar.xml"/>
       <dtd 
        publicId="-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN"
        location="${weblogic.home}/classes/weblogic/ejb/deployment/xml/ejb-jar.dtd"/>
       <dtd 
        publicId="-//BEA Systems, Inc.//DTD WebLogic 5.1.0 EJB//EN"
        location="${weblogic.home}/classes/weblogic/ejb/deployment/xml/weblogic-ejb-jar.dtd"/>
    </ejbjar>
\end{verbatim}
This example shows ejbjar being used to generate a single deployment
jar using a Weblogic EJB container. This example does not require the
deployment descriptors to use the naming standard. This will create
only one ejb jar file - 'TheEJBJar.jar'.
\begin{verbatim}
    <ejbjar srcdir="${build.classes}"
            descriptordir="${descriptor.dir}"
            basejarname="TheEJBJar">
      <weblogic destdir="${deploymentjars.dir}"
                classpath="${descriptorbuild.classpath}"/>
      <include name="**/ejb-jar.xml"/>
      <exclude name="**/weblogic*.xml"/>
    </ejbjar>
\end{verbatim}
This example shows ejbjar being used to generate deployment jars for a
TOPLink-enabled entity bean using a Weblogic EJB container. This
example does not require the deployment descriptors to use the naming
standard. This will create only one TOPLink-enabled ejb jar 
file --~'Address.jar'.
\begin{verbatim}
    <ejbjar srcdir="${build.dir}"
            destdir="${solant.ejb.dir}"
            descriptordir="${descriptor.dir}"
            basejarname="Address">
            <weblogictoplink destdir="${solant.ejb.dir}"
                    classpath="${java.class.path}"
                    keepgeneric="false"
                    toplinkdescriptor="Address.xml"
                    toplinkdtd="file:///dtdfiles/toplink-cmp_2_5_1.dtd"
                    suffix=".jar"/>
            <include name="**/ejb-jar.xml"/>
            <exclude name="**/weblogic-ejb-jar.xml"/>
    </ejbjar>
\end{verbatim}
This final example shows how you would set-up ejbjar under Weblogic
6.0. It also shows the use of the {\tt <support>} element to add support files
\begin{verbatim}
    <ejbjar descriptordir="${dd.dir}" srcdir="${build.classes.server}">
       <include name="**/*-ejb-jar.xml"/>
       <exclude name="**/*-weblogic-ejb-jar.xml"/>
       <support dir="${build.classes.server}">
            <include name="**/*.class"/>
       </support>
       <weblogic destdir="${deployment.dir}"
                 keepgeneric="true"
                 suffix=".jar"
                 rebuild="false">
         <classpath>
            <pathelement path="${build.classes.server}"/>
         </classpath>
         <wlclasspath>
            <pathelement path="${weblogic.classes}"/>
         </wlclasspath>
       </weblogic>
    </ejbjar>
\end{verbatim}

{\bf WebSphere element}\hfil\break

The websphere element searches for the websphere specific deployment
descriptors and adds them to the final ejb jar file. Websphere has two
specific descriptors for session beans:
\begin{enumerate}
\item ibm-ejb-jar-bnd.xmi
\item ibm-ejb-jar-ext.xmi
\end{enumerate}
and another two for container managed entity beans:
\begin{enumerate}
\item Map.mapxmi
\item Schema.dbxmi
\end{enumerate}
In terms of WebSphere, the generation of container code and stubs is
called deployment. This step can be performed by the websphere element
as part of the jar generation process. If the switch ejbdeploy is on,
the ejbdeploy tool from the websphere toolset is called for every
ejb-jar. Unfortunately, this step only works, if you use the ibm
jdk. Otherwise, the rmic (called by ejbdeploy) throws a
ClassFormatError. Be sure to switch ejbdeploy off, if run ant with sun
jdk.

For the websphere element to work, you have to provide a complete
classpath, that contains all classes, that are required to reflect the
bean classes. For ejbdeploy to work, you must also provide the
classpath of the ejbdeploy tool and set the websphere.home property
(look at the examples below).

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
destdir & The base directory into which the generated weblogic ready jar files are deposited. Jar files are deposited in directories corresponding to their location within the descriptordir namespace. & Yes \\ \hline
ejbdeploy & Decides wether ejbdeploy is called. When you set this to true, be sure, to run ant with the ibm jdk. & No, defaults to true \\ \hline
suffix & String value appended to the basename of the deployment descriptor to create the filename of the WebLogic EJB jar file. & No, defaults to '.jar'. \\ \hline
keepgeneric & This controls whether the generic file used as input to ejbdeploy is retained. & No, defaults to false \\ \hline
rebuild & This controls whether ejbdeploy is called although no changes have occurred. & No, defaults to false \\ \hline
tempdir & A directory, where ejbdeploy will write temporary files & No, defaults to '\_ejbdeploy\_temp'. \\ \hline

\begin{tabular}{l}
dbName \\
dbSchema \\
\end{tabular} &
These options are passed to ejbdeploy. & No \\ \hline
dbVendor & This option is passed to ejbdeploy. Valid options are for example:
\begin{itemize}
\item SQL92
\item SQL99
\item DB2UDBWIN\_V71
\item DB2UDBOS390\_V6
\item DB2UDBAS400\_V4R5
\item ORACLE\_V8
\item INFORMIX\_V92
\item SYBASE\_V1192
\item MYSQL\_V323
\item MSSQLSERVER\_V7
\end{itemize}
This is also used to determine the name of the Map.mapxmi and
Schema.dbxmi files, for example Account-DB2UDBWIN\_V71-Map.mapxmi and
Account-DB2UDBWIN\_V71-Schema.dbxmi. & No \\ \hline
\end{tabular}
\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
\begin{tabular}{l}
codegen \\
quiet \\
novalidate \\
noinform \\
trace \\
use35MappingRules \\
\end{tabular} &
These options are all passed to ejbdeploy. All options except 'quiet' default to false. & No \\ \hline
rmicOptions & This option is passed to ejbdeploy and will be passed on to rmic. & No \\ \hline
\end{tabular}

This example shows ejbjar being used to generate deployment jars for
all deployment descriptors in the descriptor dir:
\begin{verbatim}
     <property name="websphere.home" value="${was4.home}"/>
     <ejbjar srcdir="${build.class}" descriptordir="etc/ejb">
      <include name="*-ejb-jar.xml"/>
      <websphere dbvendor="DB2UDBOS390_V6"
                 ejbdeploy="true"
                 oldCMP="false"
                 tempdir="/tmp"
                 destdir="${dist.server}">
        <wasclasspath>
          <pathelement 
location="${was4.home}/deploytool/itp/plugins/org.eclipse.core.boot/boot.jar"/>
          <pathelement
location="${was4.home}/deploytool/itp/plugins/com.ibm.etools.ejbdeploy/runtime/batch.jar"/>
          <pathelement location="${was4.home}/lib/xerces.jar"/>
          <pathelement location="${was4.home}/lib/ivjejb35.jar"/>
          <pathelement location="${was4.home}/lib/j2ee.jar"/>
          <pathelement location="${was4.home}/lib/vaprt.jar"/>
        </wasclasspath>
      <classpath>
        <path refid="build.classpath"/>
      </classpath>
      </websphere>
      <dtd 
       publicId="-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN"
       location="${lib}/dtd/ejb-jar_1_1.dtd"/>
    </ejbjar>
\end{verbatim}

{\bf iPlanet Application Server (iAS) element}\hfil\break

The {\tt <iplanet>} nested element is used to build iAS-specific stubs and
skeletons and construct a JAR file which may be deployed to the
iPlanet Application Server 6.0. The build process will always
determine if the EJB stubs/skeletons and the EJB-JAR file are up to
date, and it will do the minimum amount of work required.

Like the WebLogic element, a naming convention for the EJB descriptors
is most commonly used to specify the name for the completed JAR
file. For example, if the EJB descriptor ejb/Account-ejb-jar.xml is
found in the descriptor directory, the iplanet element will search for
an iAS-specific EJB descriptor file named ejb/Account-ias-ejb-jar.xml
(if it isn't found, the task will fail) and a JAR file named
ejb/Account.jar will be written in the destination directory. Note
that when the EJB descriptors are added to the JAR file, they are
automatically renamed META-INF/ejb-jar.xml and
META-INF/ias-ejb-jar.xml.

Of course, this naming behaviour can be modified by specifying
attributes in the ejbjar task (for example, basejarname,
basenameterminator, and flatdestdir) as well as the iplanet element
(for example, suffix). Refer to the appropriate documentation for more details.

{\bf Parameters:}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
\tablehead{Attribute & Description & Required \\ \hline}
destdir & The base directory into which the generated JAR files will be written. Each JAR file is written in directories which correspond to their location within the "descriptordir" namespace. & Yes \\ \hline
classpath & The classpath used when generating EJB stubs and skeletons. If omitted, the classpath specified in the "ejbjar" parent task will be used. If specified, the classpath elements will be prepended to the classpath specified in the parent "ejbjar" task. Note that nested "classpath" elements may also be used. & No \\ \hline
keepgenerated & Indicates whether or not the Java source files which are generated by ejbc will be saved or automatically deleted. If "yes", the source files will be retained. If omitted, it defaults to "no". & No \\ \hline
debug & Indicates whether or not the ejbc utility should log additional debugging statements to the standard output. If "yes", the additional debugging statements will be generated. If omitted, it defaults to "no". & No \\ \hline
iashome & May be used to specify the "home" directory for this iAS installation. This is used to find the ejbc utility if it isn't included in the user's system path. If specified, it should refer to the [install-location]/iplanet/ias6/ias directory. If omitted, the ejbc utility must be on the user's system path. & No \\ \hline
suffix & String value appended to the JAR filename when creating each JAR. If omitted, it defaults to ".jar". & No \\ \hline
\end{tabular}

As noted above, the iplanet element supports
additional {\tt <classpath>} nested elements.

{\bf Examples}\hfil\break

This example demonstrates the typical use of the {\tt <iplanet>} nested
element. It will name each EJB-JAR using the "basename" prepended to
each standard EJB descriptor. For example, if the descriptor named
"Account-ejb-jar.xml" is processed, the EJB-JAR will be named
"Account.jar"
\begin{verbatim}
    <ejbjar srcdir="${build.classesdir}"
            descriptordir="${src}">

            <iplanet destdir="${assemble.ejbjar}"
                     classpath="${ias.ejbc.cpath}"/>
            <include name="**/*-ejb-jar.xml"/>
            <exclude name="**/*ias-*.xml"/>
    </ejbjar>
\end{verbatim}
This example demonstrates the use of a nested classpath element as
well as some of the other optional attributes.
\begin{verbatim}
    <ejbjar srcdir="${build.classesdir}"
            descriptordir="${src}">

            <iplanet destdir="${assemble.ejbjar}"
                     iashome="${ias.home}"
                     debug="yes"
                     keepgenerated="yes">
                     <classpath>
                         <pathelement path="."/>
                         <pathelement path="${build.classpath}"/>
                     </classpath>
            </iplanet>
            <include name="**/*-ejb-jar.xml"/>
            <exclude name="**/*ias-*.xml"/>
    </ejbjar>
\end{verbatim}
This example demonstrates the use of basejarname attribute. In this
case, the completed EJB-JAR will be named "HelloWorld.jar" If multiple
EJB descriptors might be found, care must be taken to ensure that the
completed JAR files don't overwrite each other.
\begin{verbatim}
    <ejbjar srcdir="${build.classesdir}"
            descriptordir="${src}"
            basejarname="HelloWorld">

            <iplanet destdir="${assemble.ejbjar}"
                     classpath="${ias.ejbc.cpath}"/>
            <include name="**/*-ejb-jar.xml"/>
            <exclude name="**/*ias-*.xml"/>
    </ejbjar>
\end{verbatim}
This example demonstrates the use of the dtd nested element. If the
local copies of the DTDs are included in the classpath, they will be
automatically referenced without the nested elements. In iAS 6.0 SP2,
these local DTDs are found in the [iAS-install-directory]/APPS
directory. In iAS 6.0 SP3, these local DTDs are found in the
[iAS-install-directory]/dtd directory.
\begin{verbatim}
    <ejbjar srcdir="${build.classesdir}"
            descriptordir="${src}">
            <iplanet destdir="${assemble.ejbjar}">
                     classpath="${ias.ejbc.cpath}"/>
            <include name="**/*-ejb-jar.xml"/>
            <exclude name="**/*ias-*.xml"/>

            <dtd publicId="-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN"
                 location="${ias.home}/APPS/ejb-jar_1_1.dtd"/>
            <dtd publicId="-//Sun Microsystems, Inc.//DTD iAS Enterprise JavaBeans 1.0//EN"
                 location="${ias.home}/APPS/IASEjb_jar_1_0.dtd"/>
    </ejbjar>
\end{verbatim}

{\bf JOnAS (Java Open Application Server) element}\hfil\break

The {\tt <jonas>} nested element is used to build JOnAS-specific stubs and
skeletons thanks to the GenIC specific tool, and construct a JAR file
which may be deployed to the JOnAS Application Server. The build
process will always determine if the EJB stubs/skeletons and the
EJB-JAR file are up to date, and it will do the minimum amount of work
required.

Like the WebLogic element, a naming convention for the EJB descriptors
is most commonly used to specify the name for the completed JAR
file. For example, if the EJB descriptor ejb/Account-ejb-jar.xml is
found in the descriptor directory, the {\tt <jonas>} element will search for
a JOnAS-specific EJB descriptor file named
ejb/Account-jonas-ejb-jar.xml and a JAR file named ejb/Account.jar
will be written in the destination directory. But the {\tt <jonas>} element
can also use the JOnAS naming convention. With the same example as
below, the EJB descriptor can also be named ejb/Account.xml (no base
name terminator here) in the descriptor directory. Then the {\tt <jonas>}
element will search for a JOnAS-specific EJB descriptor file called
ejb/jonas-Account.xml. This convention do not follow strictly the
ejb-jar naming convention recommendation but is supported for backward
compatibility with previous version of JOnAS.

Note that when the EJB descriptors are added to the JAR file, they are
automatically renamed META-INF/ejb-jar.xml and
META-INF/jonas-ejb-jar.xml.

Of course, this naming behavior can be modified by specifying
attributes in the ejbjar task (for example, basejarname,
basenameterminator, and flatdestdir) as well as the iplanet element
(for example, suffix). Refer to the appropriate documentation for more
details.

{\bf Parameters:}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
destdir & The base directory into which the generated JAR files will be written. Each JAR file is written in directories which correspond to their location within the "descriptordir" namespace. & Yes \\ \hline
jonasroot & The root directory for JOnAS. & Yes \\ \hline
classpath & The classpath used when generating EJB stubs and skeletons. If omitted, the classpath specified in the "ejbjar" parent task will be used. If specified, the classpath elements will be prepended to the classpath specified in the parent "ejbjar" task (see also the ORB attribute documentation below). Note that nested "classpath" elements may also be used. & No \\ \hline
keepgenerated & true if the intermediate Java source files generated by GenIC must be deleted or not. If omitted, it defaults to false. & No \\ \hline
nocompil & true if the generated source files must not be compiled via the java and rmi compilers. If omitted, it defaults to false. & No \\ \hline
novalidation & true if the XML deployment descriptors must be parsed without validation. If omitted, it defaults to false. & No \\ \hline
javac & Java compiler to use. If omitted, it defaults to the value of build.compiler property. & No \\ \hline
\end{tabular}
\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
javacopts & Options to pass to the java compiler. & No \\ \hline
rmicopts & Options to pass to the rmi compiler. & No \\ \hline
secpropag & true if the RMI Skel. and Stub. must be modified to implement the implicit propagation of the security context (the transactional context is always provided). If omitted, it defaults to false. & No \\ \hline
verbose & Indicates whether or not to use -verbose switch. If omitted, it defaults to false. & No \\ \hline
additionalargs & Add additional args to GenIC. & No \\ \hline
keepgeneric & true if the generic JAR file used as input to GenIC must be retained. If omitted, it defaults to false. & No \\ \hline
suffix & String value appended to the JAR filename when creating each JAR. If omitted, it defaults to ".jar". & No \\ \hline
orb & Choose your ORB : RMI, JEREMIE, DAVID. If omitted, it defaults to the one present in classpath. If specified, the corresponding JOnAS JAR is automatically added to the classpath. & No \\ \hline
nogenic & If this attribute is set to true, JOnAS's GenIC will not be run on the EJB JAR. Use this if you prefer to run GenIC at deployment time. If omitted, it defaults to false. & No \\ \hline
\end{tabular}

As noted above, the jonas element supports additional {\tt <classpath>}
nested elements.

{\bf Examples}\hfil\break

This example shows ejbjar being used to generate deployment jars using
a JOnAS EJB container. This example requires the naming standard to be
used for the deployment descriptors. Using this format will create a
EJB JAR file for each variation of '*-jar.xml' that is found in the
deployment descriptor directory.
\begin{verbatim}
      <ejbjar srcdir="${build.classes}"
              descriptordir="${descriptor.dir}">
        <jonas destdir="${deploymentjars.dir}"
             jonasroot="${jonas.root}"
             orb="RMI"/>
        <include name="**/*.xml"/>
        <exclude name="**/jonas-*.xml"/>
        <support dir="${build.classes}">
             <include name="**/*.class"/>
        </support>
      </ejbjar>
\end{verbatim}
This example shows ejbjar being used to generate a single deployment jar using a JOnAS EJB container. This example does require the deployment descriptors to use the naming standard. This will create only one ejb jar file - 'TheEJBJar.jar'.
\begin{verbatim}
      <ejbjar srcdir="${build.classes}"
              descriptordir="${descriptor.dir}"
              basejarname="TheEJBJar">
        <jonas destdir="${deploymentjars.dir}"
                  jonasroot="${jonas.root}"
                  suffix=".jar"
                  classpath="${descriptorbuild.classpath}"/>
        <include name="**/ejb-jar.xml"/>
        <exclude name="**/jonas-ejb-jar.xml"/>
      </ejbjar>
\end{verbatim}

\subsection{Echoproperties}

\subsubsection{Description}

Displays all the current properties in the project. The output can be
sent to a file if desired. You can also specify a subset of properties
to save by naming a prefix: only properties starting with this prefix
will be saved. This task can be used as a somewhat contrived means of
returning data from an {\tt <ant>} invocation, but is really for debugging
build files.

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
destfile & If specified, the value indicates the name of the file to send the output of the statement to. The generated output file is compatible for loading by any Java application as a property file. If not specified, then the output will go to the Ant log. & No \\ \hline
prefix & a prefix which is used to filter the properties only those properties starting with this prefix will be echoed. & No \\ \hline

failonerror & By default, the "failonerror" attribute is enabled. If an
error occurs while writing the properties to a file, and this
attribute is enabled, then a BuildException will be thrown, causing
the build to fail. If disabled, then IO errors will be reported as a
log statement, and the build will continue without failure from this
task. & No \\ \hline
\end{tabular}

\subsubsection{Examples}

\begin{verbatim}
  <echoproperties/>
\end{verbatim}
Report the current properties to the log.
\begin{verbatim}
  <echoproperties destfile="my.properties"/>
\end{verbatim}
Report the current properties to the file "my.properties", and will
fail the build if the file could not be created or written to.
\begin{verbatim}
  <echoproperties destfile="my.properties" failonerror="false" />
\end{verbatim}
Report the current properties to the file "my.properties", and will
log a message if the file could not be created or written to, but will
still allow the build to continue.
\begin{verbatim}
  <echoproperties prefix="java."/>
\end{verbatim}
List all properties beginning with "java."

\subsection{FTP}

\subsubsection{Description}

The ftp task implements a basic FTP client that can send, receive,
list, delete files, and create directories. See below for descriptions
and examples of how to perform each task.

Note: This task depends on external libraries not included in the Ant
distribution. See Library Dependencies for more information.

The ftp task makes no attempt to determine what file system syntax is
required by the remote server, and defaults to Unix
standards. remotedir must be specified in the exact syntax required by
the ftp server. If the usual Unix conventions are not supported by the
server, separator can be used to set the file separator that should be
used instead.

See the section on directory based tasks, on how the
inclusion/exclusion of files works, and how to write patterns.

This task does not currently use the proxy information set by the
{\tt <setproxy>} task, and cannot go through a firewall via socks.

Warning: for the get and delete actions to work properly with a
Windows 2000 ftp server, it needs to be configured to generate Unix
style listings, and not the default MS-DOS listing. Or someone needs
to write the code to parse MS-DOS listings -any takers?

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
server & the address of the remote ftp server. & Yes \\ \hline
port & the port number of the remote ftp server. Defaults to port 21. & No \\ \hline
userid & the login id to use on the ftp server. & Yes \\ \hline
password & the login password to use on the ftp server. & Yes \\ \hline
remotedir & the directory to which to upload files on the ftp server. & No \\ \hline
action & the ftp action to perform, defaulting to "send". Currently supports "put", "get", "del", "list", "chmod" and "mkdir". & No \\ \hline
binary & selects binary-mode ("yes") or text-mode ("no") transfers. Defaults to "yes" & No \\ \hline
passive & selects passive-mode ("yes") transfers. Defaults to "no" & No \\ \hline
verbose & displays information on each file transferred if set to "yes". Defaults to "no". & No \\ \hline
depends & transfers only new or changed files if set to "yes". Defaults to "no". & No \\ \hline
newer & a synonym for depends. & No \\ \hline
separator & sets the file separator used on the ftp server. Defaults to "/". & No \\ \hline
umask & sets the default file permissions for new files, unix only. & No \\ \hline
chmod & sets or changes file permissions for new or existing files, unix only. If used with a put action, chmod will be issued for each file. & No \\ \hline
listing & the file to write results of the "list" action. Required for the "list" action, ignored otherwise. & No \\ \hline
ignoreNoncriticalErrors & flag which permits the task to ignore some non-fatal error codes sent by some servers during directory creation: wu-ftp in particular. Default: false & No \\ \hline
skipFailedTransfers & flag which enables unsuccessful file put, delete and get operations to be skipped with a warning and the remainder of the files still transferred. Default: false & No \\ \hline
\end{tabular}

\subsubsection{Sending Files}

The easiest way to describe how to send files is with a couple of examples:
\begin{verbatim}
  <ftp server="ftp.apache.org"
       userid="anonymous"
       password="me@myorg.com">
    <fileset dir="htdocs/manual"/>
  </ftp>
\end{verbatim}
Logs in to ftp.apache.org as anonymous and uploads all files in the
htdocs/manual directory to the default directory for that user.
\begin{verbatim}
  <ftp server="ftp.apache.org"
       remotedir="incoming"
       userid="anonymous"
       password="me@myorg.com"
       depends="yes"
  >
    <fileset dir="htdocs/manual"/>
  </ftp>
\end{verbatim}
Logs in to ftp.apache.org as anonymous and uploads all new or changed
files in the htdocs/manual directory to the incoming directory
relative to the default directory for anonymous.
\begin{verbatim}
  <ftp server="ftp.apache.org"
       port="2121"
       remotedir="/pub/incoming"
       userid="coder"
       password="java1"
       depends="yes"
       binary="no"
  >
    <fileset dir="htdocs/manual">
      <include name="**/*.html"/>
    </fileset>
  </ftp>
\end{verbatim}
Logs in to ftp.apache.org at port 2121 as coder with password java1
and uploads all new or changed HTML files in the htdocs/manual
directory to the /pub/incoming directory. The files are transferred in
text mode. Passive mode has been switched on to send files from behind
a firewall.
\begin{verbatim}
  <ftp server="ftp.nt.org"
       remotedir="c:\uploads"
       userid="coder"
       password="java1"
       separator="\"
       verbose="yes"

  >
    <fileset dir="htdocs/manual">
      <include name="**/*.html"/>
    </fileset>
  </ftp>
\end{verbatim}
Logs in to the Windows-based ftp.nt.org as coder with password java1
and uploads all HTML files in the htdocs/manual directory to the
c:${\backslash}{\backslash}$uploads directory. 
Progress messages are displayed as each file is uploaded.

{\bf Getting Files}\hfil\break

Getting files from an FTP server works pretty much the same way as
sending them does. The only difference is that the nested filesets use
the remotedir attribute as the base directory for the files on the FTP
server, and the dir attribute as the local directory to put the files
into. The file structure from the FTP site is preserved on the local
machine.
\begin{verbatim}
  <ftp action="get"
       server="ftp.apache.org"
       userid="anonymous"
       password="me@myorg.com">
    <fileset dir="htdocs/manual">
      <include name="**/*.html"/>
    </fileset>
  </ftp>
\end{verbatim}

Logs in to ftp.apache.org as anonymous and recursively downloads all
.html files from default directory for that user into the
htdocs/manual directory on the local machine.

.
Deleting Files

As you've probably guessed by now, you use nested fileset elements to
select the files to delete from the remote FTP server. Again, the
filesets are relative to the remote directory, not a local
directory. In fact, the dir attribute of the fileset is ignored
completely.
\begin{verbatim}
  <ftp action="del"
       server="ftp.apache.org"
       userid="anonymous"
       password="me@myorg.com">
    <fileset>
      <include name="**/*.tmp"/>
    </fileset>
  </ftp>
\end{verbatim}
Logs in to ftp.apache.org as anonymous and tries to delete all *.tmp files from the default directory for that user. If you don't have permission to delete a file, a BuildException is thrown.
Listing Files
\begin{verbatim}
  <ftp action="list"
       server="ftp.apache.org"
       userid="anonymous"
       password="me@myorg.com" 
       listing="data/ftp.listing">
    <fileset>
      <include name="**"/>
    </fileset>
  </ftp>
\end{verbatim}
This provides a file listing in data/ftp.listing of all the files on
the FTP server relative to the default directory of the anonymous
user. The listing is in whatever format the FTP server normally lists
files.

\subsubsection{Creating Directories}

Note that with the mkdir action, the directory to create is specified
using the remotedir attribute.
\begin{verbatim}
  <ftp action="mkdir"
       server="ftp.apache.org"
       userid="anonymous"
       password="me@myorg.com" 
       remotedir="some/remote/dir"/>
\end{verbatim}
This creates the directory some/remote/dir beneath the default root
directory. As with all other actions, the directory separator
character must be correct according to the desires of the FTP server.

\subsection{IContract}

\subsubsection{Description}

Instruments Java classes with iContract DBC preprocessor.
The task can generate a properties file for iControl, a graphical user
interface that lets you turn on/off assertions. iControl generates a
control file that you can refer to from this task using the
controlfile attribute.

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
srcdir & Location of the java files. & Yes \\ \hline
instrumentdir & Indicates where the instrumented source files should go. & Yes \\ \hline
repositorydir & Indicates where the repository source files should go. & Yes \\ \hline
builddir & Indicates where the compiled instrumented classes should go. Defaults to the value of instrumentdir. NOTE: Don't use the same directory for compiled instrumented classes and uninstrumented classes. It will break the dependency checking. (Classes will not be reinstrumented if you change them). & No \\ \hline
repbuilddir & Indicates where the compiled repository classes should go. Defaults to the value of repositorydir. & No \\ \hline
pre & Indicates whether or not to instrument for preconditions. Defaults to true unless controlfile is specified, in which case it defaults to false. & No \\ \hline
post & Indicates whether or not to instrument for postconditions. Defaults to true unless controlfile is specified, in which case it defaults to false. & No \\ \hline
invariant & Indicates whether or not to instrument for invariants. Defaults to true unless controlfile is specified, in which case it defaults to false. & No \\ \hline
failthrowable & The full name of the Throwable (Exception) that should be thrown when an assertion is violated. Defaults to java.lang.Error & No \\ \hline
verbosity & Indicates the verbosity level of iContract. Any combination of error*,warning*,note*,info*,progress*,debug* (comma separated) can be used. Defaults to error* & No \\ \hline
quiet & Indicates if iContract should be quiet. Turn it off if many your classes extend uninstrumented classes and you don't want warnings about this. Defaults to false & No \\ \hline
updateicontrol & If set to true, it indicates that the properties file for iControl in the current directory should be updated (or created if it doesn't exist). Defaults to false. & No \\ \hline
controlfile & The name of the control file to pass to iContract. Consider using iControl to generate the file. Default is not to pass a file. & Only if updateicontrol=true \\ \hline
classdir & Indicates where compiled (unistrumented) classes are located. This is required in order to properly update the icontrol.properties file, not for instrumentation. & Only if updateicontrol=true \\ \hline
targets & Name of the file that will be generated by this task, which lists all the classes that iContract will instrument. If specified, the file will not be deleted after execution. If not specified, a file will still be created, but it will be deleted after execution. & No \\ \hline
\end{tabular}

Note: iContract will use the java compiler indicated by the project's
build.compiler property. See documentation of the Javac task for more
information. Nested includes and excludes are also supported.

\subsubsection{Example}

Note: iContract will use the java compiler indicated by the project's
build.compiler property. See documentation of the Javac task for more
information.

Nested includes and excludes can be done very much the same way as any
subclass of MatchingTask.

\subsubsection{Example}
\begin{verbatim}
 <icontract
    srcdir="${build.src}"
    instrumentdir="${build.instrument}"
    repositorydir="${build.repository}"
    builddir="${build.instrclasses}"
    updateicontrol="true"
    classdir="${build.classes}"
    controlfile="control"
    targets="targets"
    verbosity="error*,warning*"
    quiet="true"
 >
    <classpath refid="compile-classpath"/>
 </icontract>
\end{verbatim}

\subsection{Jarlib-available}

\subsubsection{Description}

Check whether an extension is present in a fileset or an
extensionSet. If the extension is present then a property is set.

Note that this task works with extensions as defined by the "Optional
Package" specification. For more information about optional packages,
see the document Optional Package Versioning in the documentation
bundle for your Java2 Standard Edition package, in file
guide/extensions/versioning.html or online at
http://java.sun.com/j2se/1.3/docs/guide/extensions/versioning.html.

See the Extension and ExtensionSet documentation for further details

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
property & The name of property to set if extensions is available. & Yes \\ \hline
file & The file to check for extension  & No, one of file, nested ExtensionSet or nested fileset must be present. \\ \hline
\end{tabular}

\subsubsection{Parameters specified as nested elements}

{\bf extension}\hfil\break

Extension the extension to search for.

{\bf fileset}\hfil\break

FileSets are used to select sets of files to check for extension.

{\bf extensionSet}\hfil\break

ExtensionSets is the set of extensions to search for extension in.

{\bf Examples}\hfil\break

Search for extension in single file
\begin{verbatim}
  <jarlib-available property="myext.present" file="myfile.jar">
    <extension
      extensionName="org.apache.tools.ant"
      specificationVersion="1.4.9"
      specificationVendor="Apache Software Foundation"/>
  </jarlib-available>
\end{verbatim}
Search for extension in single file refencing external Extension
\begin{verbatim}
  <extension id="myext"
    extensionName="org.apache.tools.ant"
    specificationVersion="1.4.9"
    specificationVendor="Apache Software Foundation"/>

  <jarlib-available property="myext.present" file="myfile.jar">
    <extension refid="myext"/>
  </jarlib-available>
\end{verbatim}
Search for extension in fileset
\begin{verbatim}
  <extension id="myext"
    extensionName="org.apache.tools.ant"
    specificationVersion="1.4.9"
    specificationVendor="Apache Software Foundation"/>

  <jarlib-available property="myext.present">
    <extension refid="myext"/>
    <fileset dir="lib">
      <include name="*.jar"/>
    </fileset>
  </jarlib-available>
\end{verbatim}
Search for extension in extensionSet
\begin{verbatim}
  <extension id="myext"
    extensionName="org.apache.tools.ant"
    specificationVersion="1.4.9"
    specificationVendor="Apache Software Foundation"/>

  <jarlib-available property="myext.present">
    <extension refid="myext"/>
    <extensionSet id="exts3">
      <libfileset
        includeUrl="false"
        includeImpl="true"
        dir="lib">
        <include name="*.jar"/>
      </libfileset>
    </extensionSet>
  </jarlib-available>
\end{verbatim}

\subsection{Jarlib-display}

\subsubsection{Description}

Display the "Optional Package" and "Package Specification" information
contained within the specified jars.

Note that this task works with extensions as defined by the "Optional
Package" specification. For more information about optional packages,
see the document Optional Package Versioning in the documentation
bundle for your Java2 Standard Edition package, in file
guide/extensions/versioning.html or online at
http://java.sun.com/j2se/1.3/docs/guide/extensions/versioning.html.

See the Extension and ExtensionSet documentation for further details

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
file & The file to display extension information about. & No, but one of file or fileset must be present. \\ \hline
\end{tabular}

\subsubsection{Parameters specified as nested elements}

{\bf fileset}\hfil\break

FileSets contain list of files to display Extension information about.

{\bf Examples}\hfil\break

Display Extension info for a single file
\begin{verbatim}
  <jarlib-display file="myfile.jar">
\end{verbatim}
Display Extension info for a fileset
\begin{verbatim}
  <jarlib-display>
    <fileset dir="lib">
      <include name="*.jar"/>
    </fileset>
  </jarlib-display>
\end{verbatim}

\subsection{Jarlib-manifest}

\subsubsection{Description}

Task to generate a manifest that declares all the dependencies in
manifest. The dependencies are determined by looking in the specified
path and searching for Extension / "Optional Package" specifications
in the manifests of the jars.

Note that this task works with extensions as defined by the "Optional
Package" specification. For more information about optional packages,
see the document Optional Package Versioning in the documentation
bundle for your Java2 Standard Edition package, in file
guide/extensions/versioning.html or online at
http://java.sun.com/j2se/1.3/docs/guide/extensions/versioning.html.

See the Extension and ExtensionSet documentation for further details

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
destfile & The file to generate Manifest into & Yes. \\ \hline
\end{tabular}

\subsubsection{Parameters specified as nested elements}

{\bf extension}\hfil\break

Extension the extension that this library implements.

{\bf depends}\hfil\break

ExtensionSets containing all dependencies for jar.

{\bf options}\hfil\break

ExtensionSets containing all optional dependencies for jar. (Optional dependencies will be used if present else they wilkl be ignored)

\subsubsection{Examples}

Basic Manifest generated for single Extension

\begin{verbatim}
<extension id="e1"
    extensionName="MyExtensions"
    specificationVersion="1.0"
    specificationVendor="Peter Donald"
    implementationVendorID="vv"
    implementationVendor="Apache"
    implementationVersion="2.0"
    implementationURL="http://somewhere.com"/>

<jarlib-manifest destfile="myManifest.txt">
    <extension refid="e1"/>
</jarlib-manifest>
\end{verbatim}

Search for extension in fileset

A large example with required and optional dependencies
\begin{verbatim}
<extension id="e1"
    extensionName="MyExtensions"
    specificationVersion="1.0"
    specificationVendor="Peter Donald"
    implementationVendorID="vv"
    implementationVendor="Apache"
    implementationVersion="2.0"
    implementationURL="http://somewhere.com"/>

<extensionSet id="option.ext">
    <libfileset dir="lib/option">
        <include name="**/*.jar"/>
    </libfileset>
</extensionSet>

<extensionSet id="depends.ext">
    <libfileset dir="lib/required">
        <include name="*.jar"/>
    </libfileset>
</extensionSet>

<jarlib-manifest destfile="myManifest.txt">
    <extension refid="e1"/>
    <depends refid="depends.ext"/>
    <options refid="option.ext"/>
</jarlib-manifest>
\end{verbatim}

\subsection{Jarlib-resolve}

\subsubsection{Description}

Try to locate a jar to satisfy an extension and place location of jar
into property. The task allows you to add a number of resolvers that
are capable of locating a library for a specifc extension. Each
resolver will be attempted in specified order until library is found
or no resolvers are left. If no resolvers are left and failOnError is
true then a BuildException will be thrown.

Note that this task works with extensions as defined by the "Optional
Package" specification. For more information about optional packages,
see the document Optional Package Versioning in the documentation
bundle for your Java2 Standard Edition package, in file
guide/extensions/versioning.html or online at
http://java.sun.com/j2se/1.3/docs/guide/extensions/versioning.html.

See the Extension and ExtensionSet documentation for further details

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
property & The name of property to set to library location. & Yes \\ \hline
failOnError & True if failure to locate library should result in build exception. & No, defaults to true. \\ \hline
checkExtension & True if librarys returned by nested resolvers should be checked to see if they supply extension. & No, defaults to true. \\ \hline
\end{tabular}

\subsubsection{Parameters specified as nested elements}

{\bf extension}\hfil\break

Extension the extension to resolve. Must be present

{\bf location}\hfil\break

The location sub element allows you to look for a library in a
location relative to project directory.

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
location & The pathname of library. & Yes \\ \hline
\end{tabular}

{\bf url}\hfil\break

The url resolver allows you to download a library from a URL to a local file.

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
url & The URL to download. & Yes \\ \hline
destfile & The file to download URL into. & No, But one of destfile or destdir must be present \\ \hline
destdir & The directory in which to place downloaded file. & No, But one of destfile or destdir must be present \\ \hline
\end{tabular}

{\bf ant}\hfil\break

The ant resolver allows you to run a ant build file to generate a library.

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
antfile & The build file. & Yes \\ \hline
destfile & The file that the ant build creates. & Yes \\ \hline
target & The target to run in build file. & No \\ \hline
\end{tabular}

\subsubsection{Examples}

Resolve Extension to file. If file does not exist or file does not
implement extension then throw an exception.
\begin{verbatim}
  <extension id="dve.ext"
    extensionName="org.realityforge.dve"
    specificationVersion="1.2"
    specificationVendor="Peter Donald"/>

  <jarlib-resolve property="dve.library">
    <extension refid="dve.ext"/>
    <location location="/opt/jars/dve.jar"/>
  </jarlib-resolve>
\end{verbatim}
Resolve Extension to url. If url does not exist or can not write to destfile or files does not implement extension then throw an exception.
\begin{verbatim}
  <extension id="dve.ext"
    extensionName="org.realityforge.dve"
    specificationVersion="1.2"
    specificationVendor="Peter Donald"/>

  <jarlib-resolve property="dve.library">
    <extension refid="dve.ext"/>
    <url url="http://www.realityforge.net/jars/dve.jar" destfile="lib/dve.jar"/>
  </jarlib-resolve>
\end{verbatim}
Resolve Extension to file produce by ant build. If file does not get
produced or ant file is missing or build fails then throw an exception
(Note does not check that library implements extension).
\begin{verbatim}
  <extension id="dve.ext"
    extensionName="org.realityforge.dve"
    specificationVersion="1.2"
    specificationVendor="Peter Donald"/>

  <jarlib-resolve property="dve.library" checkExtension="false">
    <extension refid="dve.ext"/>
    <ant antfile="../dve/build.xml" target="main" destfile="lib/dve.jar"/>
  </jarlib-resolve>
\end{verbatim}
Resolve Extension via multiple methods. First check local file to see
if it implements extension. If it does not then try to build it from
source in parralel directory. If that fails then finally try to
download it from a website. If all steps fail then throw a build
exception.
\begin{verbatim}
  <extension id="dve.ext"
    extensionName="org.realityforge.dve"
    specificationVersion="1.2"
    specificationVendor="Peter Donald"/>

  <jarlib-resolve property="dve.library">
    <extension refid="dve.ext"/>
    <location location="/opt/jars/dve.jar"/>
    <ant antfile="../dve/build.xml" target="main" destfile="lib/dve.jar"/>
    <url url="http://www.realityforge.net/jars/dve.jar" destfile="lib/dve.jar"/>
  </jarlib-resolve>
\end{verbatim}

\subsection{JavaCC}

\subsubsection{Description}

Invokes the JavaCC compiler compiler on a grammar file.

To use the javacc task, set the target attribute to the name of the
grammar file to process. You also need to specify the directory
containing the JavaCC installation using the javacchome attribute, so
that ant can find the JavaCC classes. Optionally, you can also set the
outputdirectory to write the generated file to a specific
directory. Otherwise javacc writes the generated files to the
directory containing the grammar file.

This task only invokes JavaCC if the grammar file is newer than the
generated Java files. javacc assumes that the Java class name of the
generated parser is the same as the name of the grammar file, ignoring
the .jj. If this is not the case, the javacc task will still work, but
it will always generate the output files.

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
target & The grammar file to process. & Yes \\ \hline
javacchome & The directory containing the JavaCC distribution. & Yes \\ \hline
outputdirectory & The directory to write the generated files to. If not set, the files are written to the directory containing the grammar file. & No \\ \hline
buildparser & Sets the BUILD\_PARSER grammar option. This is a boolean option. & No \\ \hline
buildtokenmanager & Sets the BUILD\_TOKEN\_MANAGER grammar option. This is a boolean option. & No \\ \hline
cachetokens & Sets the CACHE\_TOKENS grammar option. This is a boolean option. & No \\ \hline
choiceambiguitycheck & Sets the CHOICE\_AMBIGUITY\_CHECK grammar option. This is an integer option. & No \\ \hline
commontokenaction & Sets the COMMON\_TOKEN\_ACTION grammar option. This is a boolean option. & No \\ \hline
debuglookahead & Sets the DEBUG\_LOOKAHEAD grammar option. This is a boolean option. & No \\ \hline
\end{tabular}
\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
debugparser & Sets the DEBUG\_PARSER grammar option. This is a boolean option. & No \\ \hline
debugtokenmanager & Sets the DEBUG\_TOKEN\_MANAGER grammar option. This is a boolean option. & No \\ \hline
errorreporting & Sets the ERROR\_REPORTING grammar option. This is a boolean option. & No \\ \hline
forcelacheck & Sets the FORCE\_LA\_CHECK grammar option. This is a boolean option. & No \\ \hline
ignorecase & Sets the IGNORE\_CASE grammar option. This is a boolean option. & No \\ \hline
javaunicodeescape & Sets the JAVA\_UNICODE\_ESCAPE grammar option. This is a boolean option. & No \\ \hline
lookahead & Sets the LOOKAHEAD grammar option. This is an integer option. & No \\ \hline
optimizetokenmanager & Sets the OPTIMIZE\_TOKEN\_MANAGER grammar option. This is a boolean option. & No \\ \hline
otherambiguitycheck & Sets the OTHER\_AMBIGUITY\_CHECK grammar option. This is an integer option. & No \\ \hline
sanitycheck & Sets the SANITY\_CHECK grammar option. This is a boolean option. & No \\ \hline
static & Sets the STATIC grammar option. This is a boolean option. & No \\ \hline
unicodeinput & Sets the UNICODE\_INPUT grammar option. This is a boolean option. & No \\ \hline
usercharstream & Sets the USER\_CHAR\_STREAM grammar option. This is a boolean option. & No \\ \hline
usertokenmanager & Sets the USER\_TOKEN\_MANAGER grammar option. This is a boolean option. & No \\ \hline
\end{tabular}

\subsubsection{Example}
\begin{verbatim}
<javacc 
    target="src/Parser.jj" 
    outputdirectory="build/src"
    javacchome="c:/program files/JavaCC" 
    static="true"
/>
\end{verbatim}
This invokes JavaCC on grammar file src/Parser.jj, writing the
generated files to build/src. The grammar option STATIC is set to true
when invoking JavaCC.

\subsection{Javah}

\subsubsection{Description}

Generates JNI headers from a Java class.

When this task executes, it will generate the C header and source
files that are needed to implement native methods. JNI operates
differently depending on whether JDK1.2 (or later) or pre-JDK1.2
systems are used.

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
class & the fully-qualified name of the class (or classes, separated by commas) & Yes \\ \hline
outputFile & concatenates the resulting header or source files for all the classes listed into this file & Yes \\ \hline
destdir & sets the directory where javah saves the header files or the stub & files. \\ \hline
force & specifies that output files should always be written (JDK1.2 only) & No \\ \hline
old & specifies that old JDK1.0-style header files should be generated (otherwise output file contain JNI-style native method function prototypes) (JDK1.2 only) & No \\ \hline
stubs & generate C declarations from the Java object file (used with old) & No \\ \hline
verbose & causes Javah to print a message concerning the status of the generated files & No \\ \hline
classpath & the classpath to use. & No \\ \hline
bootclasspath & location of bootstrap class files. & No \\ \hline
extdirs & location of installed extensions. & No \\ \hline
\end{tabular}

Either outputFile or destdir must be supplied, but not both. 
Examples
\begin{verbatim}
  <javah destdir="c" class="org.foo.bar.Wibble"/>
\end{verbatim}
makes a JNI header of the named class, using the JDK1.2 JNI
model. Assuming the directory 'c' already exists, the file
org\_foo\_bar\_Wibble.h is created there. If this file already exists, it
is left unchanged.
\begin{verbatim}
  <javah outputFile="wibble.h">
    <class name="org.foo.bar.Wibble,org.foo.bar.Bobble"/>
  </javah>
\end{verbatim}
is similar to the previous example, except the output is written to a
file called wibble.h in the current directory.
\begin{verbatim}
  <javah destdir="c" force="yes">
    <class name="org.foo.bar.Wibble"/>
    <class name="org.foo.bar.Bobble"/>
    <class name="org.foo.bar.Tribble"/>
  </javah>
\end{verbatim}
writes three header files, one for each of the classes named. Because
the force option is set, these header files are always written when
the Javah task is invoked, even if they already exist.
\begin{verbatim}
  <javah destdir="c" verbose="yes" old="yes" force="yes">
    <class name="org.foo.bar.Wibble"/>
    <class name="org.foo.bar.Bobble"/>
    <class name="org.foo.bar.Tribble"/>
  </javah>
  <javah destdir="c" verbose="yes" stubs="yes" old="yes" force="yes">
    <class name="org.foo.bar.Wibble"/>
    <class name="org.foo.bar.Bobble"/>
    <class name="org.foo.bar.Tribble"/>
  </javah>
\end{verbatim}
writes the headers for the three classes using the 'old' JNI format,
then writes the corresponding .c stubs. The verbose option will cause
Javah to describe its progress.

\subsection{JspC}

\subsubsection{Description}

Ant task to run the JSP compiler and turn JSP pages into Java source.

It can be used to precompile JSP pages for fast initial invocation of
JSP pages, deployment on a server without the full JDK installed, or
simply to syntax check the pages without deploying them. In most
cases, a javac task is usually the next stage in the build
process. The task does basic dependency checking to prevent
unnecessary recompilation -this checking compares source and
destination timestamps, and does not factor in class or taglib
dependencies, or {\tt <jsp:include>} references.

By default the task uses the Jasper JSP compiler. This means the task
needs jasper.jar and jasper-runtime.jar, which come with builds of
Tomcat 4/Catalina from the Jakarta Tomcat project. We recommend Tomcat
version 4.1.x for the most robust version of jasper.

There are many limitations with this task which partially stem from
the many versions of Jasper, others from implementation 'issues' in
the task (i.e. nobody's willingness to radically change large bits of
it to work around jasper). Because of this and the fact that JSP pages
do not have to be portable across implementations -or versions of
implementations- this task is better used for validating JSP pages
before deployment, rather than precompiling them. For that, just
deploy and run your httpunit junit tests after deployment to compile
and test your pages, all in one go.

\subsubsection{Parameters}

The Task has the following attributes:

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
destdir & Where to place the generated files. They are located under here according to the given package name. & Yes \\ \hline
srcdir & Where to look for source jsp files. & Yes \\ \hline
verbose & The verbosity integer to pass to the compiler. Default="0" & No \\ \hline
package & Name of the destination package for generated java classes. & No \\ \hline
compiler & class name of a JSP compiler adapter, such as "jasper" or "jasper41" & No -defaults to "jasper" \\ \hline
ieplugin & Java Plugin classid for Internet Explorer. & No \\ \hline
mapped & (boolean) Generate separate write() calls for each HTML line in the JSP. & No \\ \hline
classpath & The classpath to use to run the jsp compiler. This can also be specified by the nested element classpath Path). & No, but it seems to work better when used \\ \hline
classpathref & A Reference. As per classpath & No \\ \hline
failonerror & flag to control action on compile failures: default=yes & No \\ \hline
uribase & The uri context of relative URI references in the JSP pages. If it does not exist then it is derived from the location of the file relative to the declared or derived value of uriroot. & No \\ \hline
uriroot & The root directory that uri files should be resolved against. & No \\ \hline
compiler & Class name of jsp compiler adapter to use. Defaults to the standard adapter for Jasper. & No \\ \hline
compilerclasspath & The classpath used to find the compiler adapter specified by the compiler attribute. & No \\ \hline
webinc & Output file name for the fraction of web.xml that lists servlets. & No \\ \hline
webxml & File name for web.xml to be generated & No \\ \hline
\end{tabular}

The mapped option will, if set to true, split the JSP text content
into a one line per call format. There are comments above and below
the mapped write calls to localize where in the JSP file each line of
text comes from. This can lead to a minor performance degradation (but
it is bound by a linear complexity). Without this options all adjacent
writes are concatenated into a single write.

The ieplugin option is used by the {\tt <jsp:plugin>} tags. If the Java
Plug-in COM Class-ID you want to use changes then it can be specified
here. This should not need to be altered.

uriroot specifies the root of the web application. This is where all
absolute uris will be resolved from. If it is not specified then the
first JSP page will be used to derive it. To derive it each parent
directory of the first JSP page is searched for a WEB-INF directory,
and the directory closest to the JSP page that has one will be
used. If none can be found then the directory Jasperc was called from
will be used. This only affects pages translated from an explicitly
declared JSP file -including references to taglibs

uribase is used to establish the uri context of relative URI
references in the JSP pages. If it does not exist then it is derived
from the location of the file relative to the declared or derived
value of uriroot. This only affects pages translated from an
explicitly declared JSP file.

\subsubsection{Parameters specified as nested elements}

This task is a directory based task, like javac, so the jsp files to
be compiled are located as java files are by javac. That is, elements
such as includes and excludes can be used directly inside the task
declaration.

Elements specific to the jspc task are:-

{\bf classpath}\hfil\break

The classpath used to compile the JSP pages, specified as for any other classpath.

{\bf classpathref}\hfil\break

a reference to an existing classpath

{\bf webapp}\hfil\break

Instructions to jasper to build an entire web application. The base
directory must have a WEB-INF subdirectory beneath it. When used, the
task hands off all dependency checking to the compiler.

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
basedir & the base directory of the web application & Yes \\ \hline
\end{tabular}

\subsubsection{Example}

\begin{verbatim}
<jspc srcdir="${basedir}/src/war"
      destdir="${basedir}/gensrc"
      package="com.i3sp.jsp"
      compiler="jasper41"
      verbose="9">
  <include name="**/*.jsp" />
</jspc>
\end{verbatim}
Build all jsp pages under src/war into the destination /gensrc, in a
package heirarchy beginning with com.i3sp.jsp.
\begin{verbatim}
<jspc
      destdir="interim"
      verbose="1"
      srcdir="src"
      compiler="jasper41"
      package="com.i3sp.jsp">
  <include name="**/*.jsp" />
</jspc>
<depend
         srcdir="interim"
         destdir="build"
         cache="build/dependencies"
         classpath="lib/taglibs.jar"/>
<javac
         srcdir="interim"
         destdir="build"
         classpath="lib/taglibs.jar"
         debug="on"/>
\end{verbatim}
Generate jsp pages then javac them down to bytecodes. Include
lib/taglib jar in the java compilation. Dependency checking is used to
scrub the java files if class dependencies indicate it is needed.

\subsubsection{Notes}

Using the package attribute it is possible to identify the resulting
java files and thus do full dependency checking - this task should
only rebuild java files if their jsp file has been modified. However,
this only works with some versions of jasper. By default the checking
supports tomcat 4.0.x with the "jasper" compiler, set the compiler to
"jasper41" for the tomcat4.1.x dependency checking. Even when it does
work, changes in .TLD imports or in compile time includes do not get
picked up.

Jasper generates JSP pages against the JSP1.2 specification -an
implementation of version 2.3 of the servlet specification is needed
to compile or run the java code.

\subsection{JDepend}

\subsubsection{Description}

Invokes the JDepend parser.

This parser "traverses a set of Java source file directories and
generates design quality metrics for each Java package". It allows to
"automatically measure the quality of a design in terms of its
extensibility, reusability, and maintainability to effectively manage
and control package dependencies."

Source file directories are defined by nested {\tt <sourcespath>}, see
nested elements.

Optionally, you can also set the outputfile name where the output is
stored. By default the task writes its report to the standard output.

The task requires at least the JDepend 1.2 version.

Note: whereas the JDepend tool can be customized to exclude some
packages, the current jdepend And Task does not have parameters to
allow these exclusions. Read JDepend specific documentation for that
purpose.

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
outputfile & The output file name. If not set, the output is printed on the standard output. & No \\ \hline
format & The format to write the output in. The default is "text", the alternative is "xml" & No \\ \hline
fork & Run the tests in a separate VM. & No, default is "off" \\ \hline
haltonerror & Stop the build process if an error occurs during the jdepend analysis. & No, default is "off" \\ \hline
timeout & Cancel the operation if it doesn't finish in the given time (measured in milliseconds). (Ignored if fork is disabled.) & No \\ \hline
jvm & The command used to invoke the Java Virtual Machine, default is 'java'. The command is resolved by java.lang.Runtime.exec(). (Ignored if fork is disabled.) & No, default "java" \\ \hline
dir & The directory to invoke the VM in. (Ignored if fork is disabled) & No \\ \hline
classpathref & the classpath to use, given as reference to a PATH defined elsewhere. & No \\ \hline
\end{tabular}

\subsubsection{Nested Elements}

jdepend supports two nested elements {\tt <classpath>} and {\tt <sourcespath>},
that represent PATH like structures.

{\tt <sourcespath>} is used to define the paths of the source code to analyze.

\subsubsection{Examples}

\begin{verbatim}
<jdepend classpathref="base.path">
    <sourcespath>
        <pathelement location="src"/>
    </sourcespath>
</jdepend>
\end{verbatim}
This invokes JDepend on the src directory, writing the output on the
standard output. The classpath is defined using a classpath reference.
\begin{verbatim}
<jdepend outputfile="docs/jdepend.xml" fork="yes" format="xml">
    <sourcespath>
        <pathelement location="src"/>
    </sourcespath>
    <classpath>
        <pathelement location="classes"/>
        <pathelement location="lib/jdepend.jar"/>
    </classpath>
</jdepend>
\end{verbatim}
This invokes JDepend in a separate VM on the src and testsrc
directories, writing the output to the <docs/jdepend.xml> file in xml
format. The classpath is defined using nested elements.

\subsection{JJTree}

\subsubsection{Description}

Invokes the JJTree preprocessor for the JavaCC compiler compiler. It
inserts parse tree building actions at various places in the JavaCC
source that it generates. The output of JJTree is run through JavaCC
to create the parser.

To use the jjtree task, set the target attribute to the name of the
jjtree grammar file to process. You also need to specify the directory
containing the JavaCC installation using the javacchome attribute, so
that ant can find the JavaCC classes. Optionally, you can also set the
outputdirectory to write the generated file to a specific
directory. Otherwise jjtree writes the generated JavaCC grammar file
to the directory containing the JJTree grammar file.

This task only invokes JJTree if the grammar file is newer than the
generated JavaCC file.

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
target & The jjtree grammar file to process. & Yes \\ \hline
javacchome & The directory containing the JavaCC distribution. & Yes \\ \hline
outputdirectory & The directory to write the generated file to. If not set, the files are written to the directory containing the grammar file.  & No \\ \hline
buildnodefiles & Sets the BUILD\_NODE\_FILES grammar option. This is a boolean option. & No \\ \hline
multi & Sets the MULTI grammar option. This is a boolean option. & No \\ \hline
nodedefaultvoid & Sets the NODE\_DEFAULT\_VOID grammar option. This is a boolean option. & No \\ \hline
nodefactory & Sets the NODE\_FACTORY grammar option. This is boolean option. & No \\ \hline
nodescopehook & Sets the NODE\_SCOPE\_HOOK grammar option. This is a boolean option. & No \\ \hline
nodeusesparser & Sets the NODE\_USES\_PARSER grammar option. This is a boolean option. & No \\ \hline
static & Sets the STATIC grammar option. This is a boolean option. & No \\ \hline
visitor & Sets the VISITOR grammar option. This is a boolean option. & No \\ \hline
nodepackage & Sets the NODE\_PACKAGE grammar option. This is a string option. & No \\ \hline
visitorexception & Sets the VISITOR\_EXCEPTION grammar option. This is a string option. & No \\ \hline
nodeprefix & Sets the NODE\_PREFIX grammar option. This is a string option. & No \\ \hline
\end{tabular}

\subsubsection{Example}

\begin{verbatim}
<jjtree 
    target="src/Parser.jjt" 
    outputdirectory="build/src"
    javacchome="c:/program files/JavaCC" 
    nodeusesparser="true"
/>
\end{verbatim}
This invokes JJTree on grammar file src/Parser.jjt, writing the
generated grammar file, Parser.jj, file to build/src. The grammar
option NODE\_USES\_PARSER is set to true when invoking JJTree.

\subsection{Jlink}

{\em Deprecated}\hfil\break

This task has been deprecated. Use the zipfileset and zipgroupfileset
attributes of the Jar task or Zip task instead.

\subsubsection{Description}

Links entries from sub-builds and libraries.

The jlink task can be used to build jar and zip files, similar to the
jar task. However, jlink provides options for controlling the way
entries from input files are added to the output file. Specifically,
capabilities for merging entries from multiple zip or jar files is
available.

If a mergefile is specified directly (eg. at the top level of a
mergefiles pathelement) and the mergefile ends in ".zip" or ".jar",
entries in the mergefile will be merged into the outfile. A file with
any other extension will be added to the output file, even if it is
specified in the mergefiles element. Directories specified in either
the mergefiles or addfiles element are added to the output file as you
would expect: all files in subdirectories are recursively added to the
output file with appropriate prefixes in the output file (without
merging).

In the case where duplicate entries and/or files are found among the
files to be merged or added, jlink merges or adds the first entry and
ignores all subsequent entries.

jlink ignores META-INF directories in mergefiles. Users should supply
their own manifest information for the output file.

It is possible to refine the set of files that are being jlinked. This
can be done with the includes, includesfile, excludes, excludesfile,
and defaultexcludes attributes on the addfiles and mergefiles nested
elements. With the includes or includesfile attribute you specify the
files you want to have included by using patterns. The exclude or
excludesfile attribute is used to specify the files you want to have
excluded. This is also done with patterns. And finally with the
defaultexcludes attribute, you can specify whether you want to use
default exclusions or not. See the section on directory based tasks,
on how the inclusion/exclusion of files works, and how to write
patterns. The patterns are relative to the base directory.

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
outfile & the path of the output file. & Yes \\ \hline
compress & whether or not the output should be compressed. true, yes, or on result in compressed output. If omitted, output will be uncompressed (inflated). & No \\ \hline
mergefiles & files to be merged into the output, if possible. & At least one of mergefiles \\ \hline
addfiles   & files to be added to the output.                 & At least one of addfiles \\ \hline
\end{tabular}

\subsubsection{Examples}
The following will merge the entries in mergefoo.jar and mergebar.jar
into out.jar. mac.jar and pc.jar will be added as single entries to out.jar.
\begin{verbatim}
<jlink compress="false" outfile="out.jar">
   <mergefiles>
     <pathelement path="${build.dir}/mergefoo.jar"/>
     <pathelement path="${build.dir}/mergebar.jar"/>
   </mergefiles>
   <addfiles>
     <pathelement path="${build.dir}/mac.jar"/>
     <pathelement path="${build.dir}/pc.zip"/>
   </addfiles>
</jlink>
\end{verbatim}
Non-deprecated alternative to the above:
\begin{verbatim}
<jar compress="false" destfile="out.jar">
  <zipgroupfileset dir="${build.dir}">
    <include name="mergefoo.jar"/>
    <include name="mergebar.jar"/>
  </zipgroupfileset>
  <fileset dir="${build.dir}">
    <include name="mac.jar"/>
    <include name="pc.jar"/>
  </fileset>
</jar>
\end{verbatim}
Suppose the file foo.jar contains two entries: bar.class and
barnone/myClass.zip. Suppose the path for file foo.jar is
build/tempbuild/foo.jar. The following example will provide the entry
tempbuild/foo.jar in the out.jar.
\begin{verbatim}
<jlink compress="false" outfile="out.jar">
   <mergefiles>
     <pathelement path="build/tempbuild"/>
   </mergefiles>
</jlink>
\end{verbatim}
However, the next example would result in two top-level entries in
out.jar, namely bar.class and barnone/myClass.zip
\begin{verbatim}
<jlink compress="false" outfile="out.jar">
   <mergefiles>
     <pathelement path="build/tempbuild/foo.jar"/>
   </mergefiles>
</jlink>
\end{verbatim}

\subsection{JProbe Coverage}
\begin{verbatim}
JProbe

by

    * Stephane Bailliez (sbailliez@imediation.com)
\end{verbatim}

This task runs the tools from the JProbe suite.
For more information, visit http://www.sitraka.com. An evaluation
version is available for download if you already don't own it.

This task has been written using JProbe Suite Server Side 3.0.

It is highly recommended to read the JProbe documentation to
understand the values of the command line arguments described
below. This document is less complete than the manual, it only gives
the basic information and is not intended as a replacement to the
manual.

\subsubsection{Tasks}
\begin{tabular}{l|l}
JPCoverage & Measure coverage of Java code. \\
JPCovMerge & Merge different snapshots into one. \\
JPCovReport & Create a report from a snapshot \\
\end{tabular}

\subsubsection{JPCoverage}

Perform code covering functions by comparing source code line
execution to the program’s source code as a whole.

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
home & The directory where JProbe is intalled. & Yes \\ \hline
vm & Indicates which virtual machine to run. Must be one of "jdk117", "jdk118" or "java2".If "java2" is specified, the user is also required to specify a path via javaexe, otherwise it will check if the current executing VM is 1.2+ and use its java.home property to determine its location. & No, default to embedded VM if 1.2+ \\ \hline
javaexe & The path to the java executable. & No, use only for java2 vm. \\ \hline
applet & Run an applet. The default is false, unless the file under analysis ends with htm or html. & No, default is "false". \\ \hline
seedname & Seed name for the temporary snapshot files (files will be named seed.jpc, seed1.jpc, seed2.jpc, ...) & No, default to "snapshot" \\ \hline
exitprompt & Toggles display of the console prompt: "Press Enter to close this window." "always": Always displays the prompt. "never": Never displays the prompt. "error": Only displays prompt after an error. & No, default is "never" \\ \hline
finalsnapshot & Type of snapshot to send at program termination. Must be one of "none","coverage","all" & No, default to "coverage" \\ \hline
recordfromstart & Must be one of "coverage", "all", "none". If you want Coverage to start analyzing as soon as the program begins to run, use "all". If not, select "none". & No, default to "coverage" \\ \hline
warnlevel & Set warning level (0-3, where 0 is the least amount of warnings). & No, default to 0 \\ \hline
snapshotdir & The path to the directory where snapshot files are stored. Choose a directory that is reachable by both the remote and local computers, and enter the same path on the command line and in the viewer. & No, default to current directory \\ \hline
workingdir & The physical path to the working directory for the VM. & No, default is current directory. \\ \hline
tracknatives & Test native methods. Note that testing native methods with Java 2 disables the JIT & No, default to "false". \\ \hline
classname & the name of the class to analyze. & Yes \\ \hline
\end{tabular}

\subsubsection{Nested Elements}

{\bf classpath}\hfil\break

jpcoverage supports a nested {\tt <classpath>} element, that represents a
PATH like structure.

{\bf jvmarg}\hfil\break

Additional parameters may be passed to the VM via nested {\tt <jvmarg>}
attributes, for example:
\begin{verbatim}
<jpcoverage home="c:\jprobe" classname="MyClass">
  <jvmarg value="-classic"/>
  <classpath path="."/>
</jpcoverage>
\end{verbatim}
would run the coverage on "MyClass" in classic mode VM.

{\tt <jvmarg>} allows all attributes described in Command line arguments.

{\bf arg}\hfil\break

Parameters may be passed to the executed class via nested {\tt <arg>}
attributes, as described in Command line arguments.

{\bf socket}\hfil\break

Define a host and port to connect to if you want to do remote viewing.

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
host & the host name/ip of the machine on which the Viewer is running & No, default to localhost \\ \hline
port & The port number on which you will connect to the Viewer & No, default to 4444 \\ \hline
\end{tabular}

{\bf filters}\hfil\break

Defines class/method filters based on pattern matching. The syntax is
filters is similar to a fileset.

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
defaultexclude & As a default, the coverage excludes all classes and methods. Default filters are equivalent to
\begin{verbatim}
  <filters>
    <exclude class="*" method="*"/>
  </filters>
\end{verbatim}
& No, default to "true" \\ \hline
\end{tabular}


As seen above, nested elements are include and exclude with a name attribute.

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
    class & The class mask as a simple regular expression & No, defaults to "*" \\ \hline
    method & The method mask as a simple regular expression & No, defaults to "*" \\ \hline
    enabled & is the filter enabled? & No, defaults to true \\ \hline
\end{tabular}

{\bf Example of filters}\hfil\break
\begin{verbatim}
<filters>
    <include class="com.mycompany.*" method="*"/>
    <exclude class="com.mycompany.MyClass" method="test*"/>
</filters>
\end{verbatim}

reports the coverage on all packages, classes and methods from
com.mycompany except all methods starting by test on the class MyClass
in the package com.mycompany

{\bf triggers}\hfil\break

Define a number of events to use for interacting with the collection of data performed during coverage. For example you may run a whole application but only decide to collect data once it reaches a certain method and once it exits another one.

The only type of nested element is the method element (triggers are
performed on method) and it has the following attributes:

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
name & The name of the method(s) as a regular expression. The name is the fully qualified name on the form package.classname.method & Yes \\ \hline
event & the event on the method that will trigger the action. Must be "enter" or "exit". & Yes \\ \hline
action & the action to execute. Must be one of "clear", "pause", "resume", "snapshot", "suspend", or "exit". They respectively clear recording, pause recording, resume recording, take a snapshot, suspend the recording and exit the program. & Yes \\ \hline
\end{tabular}

{\bf Example of triggers}\hfil\break
\begin{verbatim}
<triggers>
  <method name="ClassName.*()" event="enter" action="snapshot"/>
  <method name="ClassName.MethodName()" event="exit" action="exit"/>  
</triggers>
\end{verbatim}
Will take a snapshot when it enters any method of the class ClassName
and will exit the program once it exits the method MethodName of the
same class.

\subsubsection{JPCovMerge}

{\bf Description}\hfil\break

Perform the merge of several snapshots into a single one.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
home & The directory where JProbe is installed. & Yes \\ \hline
tofile & the output filename that will be the result of the name. & Yes \\ \hline
verbose & Perform the merge in verbose mode giving details about the snapshot processing. & No. Default to false \\ \hline
\end{tabular}

jpcovmerge collects snapshots using the nested {\tt <FileSet>} element.
Example of merge
\begin{verbatim}
<jpcovmerge home="c:\jprobe" tofile="merge.jpc" verbose="true">
  <fileset dir="./snapshots">
    <include name="snap*.jpc"/>
  </fileset>
</jpcovmerge>
\end{verbatim}
would run the merge in verbose mode on all snapshot files starting by
snap in the directory snapshots. The resulting file will be named
merge.jpc.

\subsubsection{JPCovReport}

{\bf Description}\hfil\break

Generate a readable/printable report of a snapshot. Note that you will
need Jakarta Oro in Ant classpath, to run the reference feature.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
home & The directory where JProbe is intalled. & Yes \\ \hline
format & The format of the generated report. Must be "xml", "html" or "text" & No, default to "html" \\ \hline
type & The type of report to be generated. Must be "executive", "summary", "detailed" or "verydetailed" & No. Default to "detailed" \\ \hline
percent & A numeric value for the threshold for printing methods. Must be between 0 and 100. & No, default to 100 \\ \hline
snapshot & The name of the snapshot file that is the source to the report. & Yes \\ \hline
tofile & The name of the generated output file & Yes \\ \hline
includesource & Include text of the source code lines. Only applies to format="xml" and type="verydetailed" & No. Defaults to "yes" \\ \hline
\end{tabular}

{\bf sourcepath}\hfil\break

Path to source files can be set via nested sourcepath elements that are PATH like structures.
reference (only applies to format="xml")

A reference is a set of classes whose coverage information will be
checked against. Since Coverage is only able to give you information
about loaded classes, it will only report classes that were at least
used in some points in your tests, therefore you will not be able to
know what classes are not exercised at all during your tests. The
reference is an additional feature that will analyze the bytecode of
all classes in a given classpath that match some filters and modify
the XML report accordingly. In short, it will:

\begin{itemize}
\item remove the classes that do not exists in the reference classpath. (For example you might have in your report some helper test classes that you do not want to appear in the report, but are unable to filter without adding hundred of filters for all your classes).
\item add classes that exists in the reference set and match the filters but are not reported.
\item remove abstract methods that are incorrectly reported in JProbe 3.0 (should be fixed in a later SP)
\item remove classes/methods that do not match the filters.
\end{itemize}

{\bf classpath}

    Path to the reference set of files can be set via nested classpath elements that are PATH like structures.

{\bf filters}\hfil\break

    Nested elements are include and exclude with a class and  method attribute.

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
    class & The class mask as a simple regular expression & No, default to * \\ \hline
    method & The method mask as a simple regular expression & No, default to * \\ \hline
\end{tabular}

{\bf Example of report}\hfil\break
\begin{verbatim}
<jpcovreport home="c:\jprobe" snapshot="merge.jpc" 
  format="xml" tofile="result.xml">
  <sourcepath path="./src"/>
  <reference>
    <classpath path="./bin/classes"/>
    <filters>
      <include class="com.mycompany.*"/>
      <exclude class="com.mycompany.MyClass" method="test*"/>
    </filters>
  </reference>
</jpcovreport>
\end{verbatim}
would generate the report of the file merge.jpc and write it to
result.xml using the source path src. As well, it will modify the
result.xml by analyzing all classes in the ./bin/classes that are port
of the package com.mycompany except the method that start by test from
the class MyClass.

{\bf Recommendation}\hfil\break

If you generate your main code and your testcases in a separate
directory, say bin/classes and test/classes. You should mostly end up
with a reference such as:
\begin{verbatim}
<reference>
    <classpath path="./bin/classes"/>
</reference>
\end{verbatim}
With such a reference, your XML report will be cleaned up against
parasite classes from your testcases (that as a common practice,
generally match the exact package structure of the class you
exercise).

{\bf HTML reports}\hfil\break

You will find in Ant etc directory a stylesheet called
coverage-frames.xsl. This file can be used to generate a framed report
a la javadoc similar to the one for JUnit. It needs either Xalan 1.2.2
or Xalan 2.x.

Xalan 1.2.2 (you must have xalan.jar and bsf.jar in your classpath)
\begin{verbatim}
<style processor="xalan" in="./reports/xml/results.xml" out="./reports/html/dummy.file"
 style="${ant.home}/etc/coverage-frames.xsl">
    <param name="output.dir" expression="'${basedir}/reports/html'"/>
</style>
\end{verbatim}
Xalan 2.x (note the parameter without single quote)
\begin{verbatim}
<style processor="trax" in="./reports/xml/results.xml" out="./reports/html/dummy.file"
 style="${ant.home}/etc/coverage-frames.xsl">
  <param name="output.dir" expression="${basedir}/reports/html"/>
</style>
\end{verbatim}

\subsection{JUnit}

\subsection{Description}

This task runs tests from the JUnit testing framework. The latest
version of the framework can be found at http://www.junit.org. This
task has been tested with JUnit 3.0 up to JUnit 3.8.1; it won't work
with versions prior to JUnit 3.0.

Note: This task depends on external libraries not included in the Ant
distribution. See Library Dependencies for more information.

Note: You must have junit.jar and the class files for the {\tt <junit>} task
in the same classpath. You can do one of:

\begin{enumerate}
\item Put both junit.jar and the optional tasks jar file in ANT\_HOME/lib.
\item Do not put either in ANT\_HOME/lib, and instead include their locations in your CLASSPATH environment variable.
\item Do neither of the above, and instead, specify their locations using a {\tt <classpath>} element in the build file. See the FAQ for details. 
\end{enumerate}

Tests are defined by nested test or batchtest tags (see nested elements).

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
printsummary & Print one-line statistics for each testcase. Can take the values on, off, and withOutAndErr. withOutAndErr is the same as on but also includes the output of the test as written to System.out and System.err. & No; default is off. \\ \hline
fork & Run the tests in a separate VM. & No; default is off. \\ \hline
haltonerror & Stop the build process if an error occurs during the test run. & No; default is off. \\ \hline
errorproperty & The name of a property to set in the event of an error. & No \\ \hline
haltonfailure & Stop the build process if a test fails (errors are considered failures as well). & No; default is off. \\ \hline
failureproperty & The name of a property to set in the event of a failure (errors are considered failures as well). & No. \\ \hline
filtertrace & Filter out Junit and Ant stack frames from error and failure stack traces. & No; default is on. \\ \hline
timeout & Cancel the individual tests if they don't finish in the given time (measured in milliseconds). Ignored if fork is disabled. & No \\ \hline
maxmemory & Maximum amount of memory to allocate to the forked VM. Ignored if fork is disabled. & No \\ \hline
jvm & The command used to invoke the Java Virtual Machine, default is 'java'. The command is resolved by java.lang.Runtime.exec(). Ignored if fork is disabled. & No; default is java. \\ \hline
dir & The directory in which to invoke the VM. Ignored if fork is disabled. & No \\ \hline
newenvironment & Do not propagate the old environment when new environment variables are specified. Ignored if fork is disabled. & No; default is false. \\ \hline
includeantruntime & Implicitly add the Ant classes required to run the tests and JUnit to the classpath in forked mode. & No; default is true. \\ \hline
showoutput & Send any output generated by tests to Ant's logging system as well as to the formatters. By default only the formatters receive the output. & No \\ \hline
\end{tabular}

By using the errorproperty and failureproperty attributes, it is 
possible to perform setup work (such as starting an external server), 
execute the test, clean up, and still fail the build in the event of a failure.

The filtertrace attribute condenses error and failure stack traces before reporting them. It works with both the plain and XML formatters. It filters out any lines that begin with the following string patterns:
\begin{verbatim}
   "junit.framework.TestCase"
   "junit.framework.TestResult"
   "junit.framework.TestSuite"
   "junit.framework.Assert."
   "junit.swingui.TestRunner"
   "junit.awtui.TestRunner"
   "junit.textui.TestRunner"
   "java.lang.reflect.Method.invoke("
   "org.apache.tools.ant."
\end{verbatim}
\subsubsection{Nested Elements}

The {\tt <junit>} task supports a nested {\tt <classpath>} element
that represents a PATH like structure.

{\bf jvmarg}\hfil\break

If fork is enabled, additional parameters may be passed to the new VM
via nested {\tt <jvmarg>} elements. For example:
\begin{verbatim}
<junit fork="yes">
  <jvmarg value="-Djava.compiler=NONE"/>
  ...
</junit>
\end{verbatim}
would run the test in a VM without JIT.

{\tt <jvmarg>} allows all attributes described in Command-line Arguments.

{\bf sysproperty}\hfil\break

Use nested {\tt <sysproperty>} elements to specify system properties
required by the class. These properties will be made available to the
VM during the execution of the test (either ANT's VM or the forked VM,
if fork is enabled). The attributes for this element are the same as
for environment variables.
\begin{verbatim}
<junit fork="no">
  <sysproperty key="basedir" value="${basedir}"/>
  ...
</junit>
\end{verbatim}
would run the test in ANT's VM and make the basedir property available
to the test.

{\bf env}\hfil\break

It is possible to specify environment variables to pass to the forked
VM via nested {\tt <env>} elements. For a description of 
the {\tt <env>} element's
attributes, see the description in the exec task.

Settings will be ignored if fork is disabled.

{\bf formatter}\hfil\break

The results of the tests can be printed in different formats. Output
will always be sent to a file, unless you set the usefile attribute to
false. The name of the file is determined by the name of the test and
can be set by the outfile attribute of {\tt <test>}.

There are three predefined formatters - one prints the test results in
XML format, the other emits plain text. The formatter named brief will
only print detailed information for testcases that failed, while plain
gives a little statistics line for all test cases. Custom formatters
that need to implement\hfil\break
org.apache.tools.ant.taskdefs.optional.junit.JUnitResultFormatter can
be specified.

If you use the XML formatter, it may not include the same output that
your tests have written as some characters are illegal in XML
documents and will be dropped.

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
\begin{tabular}{l} \hline
type \\
classname \\
\end{tabular} &
\begin{tabular}{p{7cm}} \hline
Use a predefined formatter (either xml, plain, or brief).  \\  \hline
Name of a custom formatter class. \\
\end{tabular} & Exactly one of these. \\ \hline

extension & Extension to append to the output filename. & Yes, if classname has been used. \\ \hline
usefile & Boolean that determines whether output should be sent to a file. & No; default is true. \\ \hline
\end{tabular}

{\bf test}\hfil\break

Defines a single test class.

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
name & Name of the test class. & Yes \\ \hline
fork & Run the tests in a separate VM. Overrides value set in {\tt <junit>}. & No \\ \hline
haltonerror & Stop the build process if an error occurs during the test run. Overrides value set in {\tt <junit>}. & No \\ \hline
errorproperty & The name of a property to set in the event of an error. Overrides value set in {\tt <junit>}. & No \\ \hline
haltonfailure & Stop the build process if a test fails (errors are considered failures as well). Overrides value set in {\tt <junit>}. & No \\ \hline
failureproperty & The name of a property to set in the event of a failure (errors are considered failures as well). Overrides value set in {\tt <junit>}. & No \\ \hline
filtertrace & Filter out Junit and Ant stack frames from error and failure stack traces. Overrides value set in {\tt <junit>}. & No; default is on. \\ \hline
todir & Directory to write the reports to. & No; default is the current directory. \\ \hline
outfile & Base name of the test result. The full filename is determined by this attribute and the extension of formatter. & No; default is TEST-name, where name is the name of the test specified in the name attribute. \\ \hline
if & Only run test if the named property is set. & No \\ \hline
unless & Only run test if the named property is not set. & No \\ \hline
\end{tabular}

Tests can define their own formatters via nested {\tt <formatter>} elements.

{\bf batchtest}\hfil\break

Define a number of tests based on pattern matching.

batchtest collects the included files from any number of nested
{\tt <fileset>}s. It then generates a test class name for each file that
ends in .java or .class.

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
fork & Run the tests in a separate VM. Overrides value set in {\tt <junit>}. & No \\ \hline
haltonerror & Stop the build process if an error occurs during the test run. Overrides value set in {\tt <junit>}. & No \\ \hline
errorproperty & The name of a property to set in the event of an error. Overrides value set in {\tt <junit>}. & No \\ \hline
haltonfailure & Stop the build process if a test fails (errors are considered failures as well). Overrides value set in {\tt <junit>}. & No \\ \hline
failureproperty & The name of a property to set in the event of a failure (errors are considered failures as well). Overrides value set in {\tt <junit>} & No \\ \hline
filtertrace & Filter out Junit and Ant stack frames from error and failure stack traces. Overrides value set in {\tt <junit>}. & No; default is on. \\ \hline
todir & Directory to write the reports to. & No; default is the current directory. \\ \hline
if & Only run tests if the named property is set. & No \\ \hline
unless & Only run tests if the named property is not set. & No \\ \hline
\end{tabular}

Batchtests can define their own formatters via nested
{\tt <formatter>} elements.

{bf Examples}\hfil\break
\begin{verbatim}
<junit>
  <test name="my.test.TestCase"/>
</junit>
\end{verbatim}
Runs the test defined in my.test.TestCase in the same VM. No output
will be generated unless the test fails.
\begin{verbatim}
<junit printsummary="yes" fork="yes" haltonfailure="yes">
  <formatter type="plain"/>
  <test name="my.test.TestCase"/>
</junit>
\end{verbatim}
Runs the test defined in my.test.TestCase in a separate VM. At the end
of the test, a one-line summary will be printed. A detailed report of
the test can be found in TEST-my.test.TestCase.txt. The build process
will be stopped if the test fails.
\begin{verbatim}
<junit printsummary="yes" haltonfailure="yes">
  <classpath>
    <pathelement location="${build.tests}"/>
    <pathelement path="${java.class.path}"/>
  </classpath>

  <formatter type="plain"/>

  <test name="my.test.TestCase" haltonfailure="no" outfile="result">
    <formatter type="xml"/>
  </test>

  <batchtest fork="yes" todir="${reports.tests}">
    <fileset dir="${src.tests}">
      <include name="**/*Test*.java"/>
      <exclude name="**/AllTests.java"/>
    </fileset>
  </batchtest>
</junit>
\end{verbatim}
Runs my.test.TestCase in the same VM, ignoring the given CLASSPATH;
only a warning is printed if this test fails. In addition to the plain
text test results, for this test a XML result will be output to
result.xml. Then, for each matching file in the directory defined for
\$\{src.tests\} a test is run in a separate VM. If a test fails, the
build process is aborted. Results are collected in files named
TEST-name.txt and written to \$\{reports.tests\}.

\subsection{JUnitReport}

Merge the individual XML files generated by the JUnit task and
eventually apply a stylesheet on the resulting merged document to
provide a browsable report of the testcases results.

Note: This task depends on external libraries not included in the Ant
distribution. See Library Dependencies for more information.

\subsubsection{Requirements}

The task needs Xalan 2.x; although Xalan 1.2.2 does work, but as
Xalan1 is not supported, we do not recommend this.

If you do you use Xalan 1.2.2 you will need a compatible (older)
version of Xerces. as well as BSF(bsf.jar). Again, using Xalan 2 is
simpler and supported.

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
tofile & The name of the XML file that will aggregate all individual XML testsuite previously generated by the JUnit task. & No. Default to TESTS-TestSuites.xml \\ \hline
todir & The directory where should be written the file resulting from the individual XML testsuite aggregation. & No. Default to current directory \\ \hline
\end{tabular}

\subsubsection{Nested Elements}

{\bf fileset}\hfil\break

junitreport collects individual xml files generated by the JUnit task
using the nested {\tt <FileSet>} element.

{\bf report}\hfil\break

Generate a browsable report based on the document created by the merge.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
format & The format of the generated report. Must be "noframes" or "frames". & No, default to "frames" \\ \hline
styledir & The directory where the stylesheets are defined. They must be conforming to the following conventions:
\begin{itemize}
\item frames format: the stylesheet must be named junit-frames.xsl.
\item noframes format: the stylesheet must be named junit-noframes.xsl.
\end{itemize}
& No. Default to embedded stylesheets. \\ \hline
todir & The directory where the files resulting from the transformation should be written to. & No. Default to current directory \\ \hline
\end{tabular}

{\bf Example of report}\hfil\break
\begin{verbatim}
<junitreport todir="./reports">
  <fileset dir="./reports">
    <include name="TEST-*.xml"/>
  </fileset>
  <report format="frames" todir="./report/html"/>
</junitreport>
\end{verbatim}
would generate a TESTS-TestSuites.xml file in the directory reports
and generate the default framed report in the directory report/html.

\subsection{Metamata Metrics}
\begin{verbatim}
MMetrics

    * Stephane Bailliez (sbailliez@imediation.com)
\end{verbatim}

\subsubsection{Requirements}

This task requires Metamata Development environment 2.0/Webgain
Quality Analyzer 2.0. An evaluation version is available at
Webgain. (Though you will not be able to use Metrics from the command
line if you do not have a registered version). You also need a TRaX
compliant processor(such as Xalan 2.x) via JAXP 1.1

\subsubsection{Description}

Invokes the Metamata Metrics / WebGain Quality Analyzer source code
analyzer on a set of Java files.

mmetrics will compute the metrics of a set of Java files and write the
results to an XML file. As a convenience, a stylesheet is given in etc
directory, so that an HTML report can be generated from the XML file.

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
metamatahome & The home directory containing the Metamata distribution. & Yes \\ \hline
tofile & The XML were the resulting metrics will be written to. & Yes \\ \hline
granularity & Metrics granularity of the source files. Must be either files (compilation-units), types (types and compilation-units) or methods (methods, types and compilation-units). & Yes \\ \hline
maxmemory & Set the maximum memory for the JVM. this is a convenient way to set the -mx or -Xmx argument. & No \\ \hline
\end{tabular}

\subsubsection{Nested elements}

For specifying the source code to analyze, you can either use a path
or fileset elements (though a single path element is preferred, see
note below).

{\bf jvmarg}\hfil\break

Additional parameters may be passed to the VM via nested
{\tt  <jvmarg>} attributes. {\tt <jvmarg>} allows all attributes described
in Command line arguments.

{\bf classpath}\hfil\break

Sets class path (also source path unless one explicitly set).
Overrides METAPATH/CLASSPATH environment variables. The classpath
element represents a PATH like structure.

{\bf sourcepath}\hfil\break

Sets source path. Overrides the SOURCEPATH environment variable. The
sourcepath element represents a PATH like structure.

{\bf path}\hfil\break

Sets the list of directories to analyze the code for metrics.;It
represents a PATH structure.

{\bf fileset}\hfil\break

Sets a set of files to analyze for metrics.source It represents a FILESET structure.

Note: For the sake of readability, it is highly recommended to analyze
for a single unique directory instead than using filesets or several
directories. Otherwise there will be multiple metrics outputs without
any way to know what metrics refers to what source. Chance are also
that the XML handler that does some heuristic will be confused by the
different outputs.

{\bf Example}\hfil\break
\begin{verbatim}
  <mmetrics tofile="mmetrics.xml"
          metamatahome="c:/metamata"
          granularity="methods">
    <classpath>
      <pathelement location="c:/metamata/examples/metricsexamples"/>
    </classpath>
    <sourcepath>
      <pathelement location="c:/metamata/examples/metricsexamples"/>
    </sourcepath>
    <path>
      <pathelement location="c:/metamata/examples/metricsexamples"/>
    </path>
  </mmetrics>
\end{verbatim}
This invokes Metamata Metrics installed in c:/metamata on the metrics example. (Note that here, classpath and sourcepath are not normally not needed)
Generating a report
As a convenience, there is an XSL file(mmetrics-frames.xsl) that allows you to generate a full framed HTML report of the metrics. You can find it in the etc directory of Ant. As it uses the Xalan redirect extensions, you will need Xalan and Xerces to run it. The stylesheet takes an output.dir parameter (otherwise it will be generated in the current directory), it can be run in Ant as follows:
\begin{verbatim}
<style in=java "${metrics.xml}" style="mmetrics-frames.xsl" out="null.tmp">
    <param name="output.dir" expression="${report.dir}"/>
</style>
\end{verbatim}

\subsection{Metamata Audit}
\begin{verbatim}
MAudit

    * Stephane Bailliez (sbailliez@imediation.com)
\end{verbatim}
\subsubsection{Requirements}

This task requires Metamata Development environment 2.0/Webgain
Quality Analyzer 2.0. An evaluation version is available at Webgain. ,
Jakarta Oro and a XML parser (via JAXP).

\subsubsection{Description}

Invokes the Metamata Audit/ Webgain Quality Analyzer on a set of Java
files.

maudit performs static analysis of the Java source code and byte code
files to find and report errors of style and potential problems
related to performance, maintenance and robustness. . As a
convenience, a stylesheet is given in etc directory, so that an HTML
report can be generated from the XML file.

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
tofile & The XML file to which the Audit result should be written to. & Yes \\ \hline
metamatahome & The home directory containing the Metamata distribution. & Yes \\ \hline
fix & Automatically fix certain errors (those marked as fixable in the manual). & No.Default to false. \\ \hline
list & Creates listing file for each audited file. A .maudit file will be generated in the same location as the source file. & No. Default to false. \\ \hline
unused & Finds declarations unused in search paths. It will look for unused global declarations in the source code within a use domain specified by the searchpath element. & No. Default to false. \\ \hline
maxmemory & Set the maximum memory for the JVM. this is a convenient way to set the -mx or -Xmx argument. & No \\ \hline
\end{tabular}

\subsubsection{Nested elements}

{\bf jvmarg}\hfil\break

Additional parameters may be passed to the VM via nested {\tt <jvmarg>}
attributes. {\tt <jvmarg>} allows all attributes described in Command line
arguments.

You can avoid using the {\tt <jvmarg>} by adding these empty entries to
metamata.properties located at \$\{metamata.home\}/bin
\begin{verbatim}
metamata.classpath=
metamata.sourcepath=
metamata.baseclasspath=
\end{verbatim}

{\bf classpath}\hfil\break

Sets class path (also source path unless one explicitly
set). Overrides METAPATH/CLASSPATH environment variables. The
classpath element represents a PATH like structure.

{\bf sourcepath}\hfil\break

Sets source path. Overrides the SOURCEPATH environment variable. The
sourcepath element represents a PATH like structure.

{\bf sourcepath}\hfil\break

Sets the search path to use as the use domain when looking for unused
global declarations. The searchpath element represents a PATH like
structure.

{\bf fileset}\hfil\break

Sets the Java files to audit via a FILESET structure. Whatever the
filter is, only the files that ends with .java will be included for
processing. Note that the base directory used for the fileset MUST be
the root of the source files otherwise package names deduced from the
file path will be incorrect.

{\bf Example}\hfil\break
\begin{verbatim}
  <maudit tofile="c:/metamata/examples/auditexamples/audit.xml"
          metamatahome="c:/metamata" fix="yes">
    <classpath>
      <pathelement location="c:/metamata/examples/auditexamples"/>
    </classpath>
    <sourcepath>
      <pathelement location="c:/metamata/examples/auditexamples"/>
    </sourcepath>
    <fileset dir="c:/metamata/examples/auditexamples">
        <include name="*.java"/>
    </fileset>
  </maudit>
\end{verbatim}
This invokes Metamata Audit installed in c:/metamata on the audit
examples and fix automatically the fixable errors.

\subsubsection{Generating a report}

As a convenience, there is an XSL file(mmetrics-frames.xsl) that
allows you to generate a full framed HTML report of the metrics. You
can find it in the etc directory of Ant. As it uses the Xalan redirect
extensions, you will need Xalan and Xerces to run it. The stylesheet
takes an output.dir parameter (otherwise it will be generated in the
current directory), it can be run in Ant as follows:
\begin{verbatim}
<style in=java "${audit.xml}" style="maudit-frames.xsl" out="null.tmp">
    <param name="output.dir" expression="${report.dir}"/>
</style>
\end{verbatim}

\subsection{MimeMail}

{\em Deprecated}\hfil\break

This task has been deprecated. Use the mail task instead.

\subsubsection{Description}

Sends SMTP mail with MIME attachments. JavaMail and Java Activation
Framework are required for this task.

Multiple files can be attached using FileSets.

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
\begin{tabular}{l}
message \\
messageFile \\
\end{tabular} &
\begin{tabular}{p{6.5cm}}
The message body  \\
A filename to read and used as the message body \\ \hline
\end{tabular} &
No, but only one of of 'message' or 'messageFile' may be specified.  If not specified, a fileset must be provided. \\ \hline

messageMimeType & MIME type to use for 'message' or 'messageFile' when attached. & No, defaults to "text/plain" \\ \hline

\begin{tabular}{l}
tolist \\
cclist \\
bcclist \\
\end{tabular} &
\begin{tabular}{p{6.5cm}}
Comma-separated list of To: recipients \\
Comma-separated list of CC: recipients  \\
Comma-separated list of BCC: recipients  \\
\end{tabular} &
Yes, at least one of 'tolist', 'cclist', or 'bcclist' must be specified. \\ \hline

mailhost & Host name of the mail server. & No, default to "localhost" \\ \hline
subject & Email subject line. & No \\ \hline
from & Email address of sender. & Yes \\ \hline
failonerror & Stop the build process if an error occurs sending the e-mail. & No, default to "true" \\ \hline
\end{tabular}

\subsubsection{Examples}

{\bf Send a single HTML file as the body of a message}\hfil\break
\begin{verbatim}
    <mimemail messageMimeType="text/html" messageFile="overview-summary.html"
        tolist="you" subject="JUnit Test Results: ${TODAY}" from="me"/>
\end{verbatim}
{\bf Sends all files in a directory as attachments}\hfil\break
\begin{verbatim}
    <mimemail message="See attached files" 
     tolist="you" subject="Attachments" from="me">
        <fileset dir=".">
            <include name="dist/*.*"/>
        </fileset>
    </mimemail>
\end{verbatim}

\subsection{MParse}
\begin{verbatim}
MParse

by

    * Stephane Bailliez (sbailliez@imediation.com)
\end{verbatim}

\subsubsection{Requirements}

This task requires Metamata Development environment 2.0 freely
available at Metamata.

\subsubsection{Description}

Invokes the Metamata MParse compiler compiler on a grammar file.

To use the mparse task, set the target attribute to the name of the
grammar file to process. You also need to specify the directory
containing the Metamata installation using the metamatahome attribute,
so that Ant can find the MParse classes.

This task only invokes MParse if the grammar file is newer than the
generated Java files. MParse assumes that the Java class name of the
generated parser is the same as the name of the grammar file, less the
.jj extension.

For additional information about MParse, please consult the online
manual available here (PDF)

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
target & The .jj grammar file to process. It will only be processed if the grammar is newer than the corresponding .java file. & Yes \\ \hline
metamatahome & The home directory containing the Metamata distribution. & Yes \\ \hline
verbose & Enable all messages & No \\ \hline
debugparser & Enables parser debugging & No \\ \hline
debugscanner & Enables scanner debugging & No \\ \hline
cleanup & Remove the intermediate Sun JavaCC file created during the transformation of the grammar file. & No. Default to false \\ \hline
maxmemory & Set the maximum memory for the JVM. this is a convenient way to set the -mx or -Xmx argument. & No \\ \hline
\end{tabular}

\subsubsection{Nested elements}

{\bf jvmarg}\hfil\break

Additional parameters may be passed to the VM via nested {\tt <jvmarg>}
attributes. {\tt <jvmarg>} allows all attributes described in Command line
arguments.

{\bf classpath}\hfil\break

Sets class path (also source path unless one explicitly
set). Overrides METAPATH/CLASSPATH environment variables.  The
classpath element represents a PATH like structure.

{\bf sourcepath}\hfil\break

Sets source path. Overrides the SOURCEPATH environment variable. The
sourcepath element represents a PATH like structure.

\subsubsection{Example}
\begin{verbatim}
  <mparse target="c:/metamata/examples/parseexamples/javagrammars/singlefile/JavaParser.jj"
          metamatahome="c:/metamata" cleanup="true">
    <classpath>
      <pathelement location="c:/metamata/examples/"/>
    </classpath>
  </mparse>
\end{verbatim}
This invokes Metamata MParse installed in c:/metamata on one of the
grammar file example (JavaParser.jj) and cleans up the intermediate
Sun JavaCC file.

\subsection{Native2Ascii}

\subsubsection{Description}

Converts files from native encodings to ASCII with escaped Unicode. A
common usage is to convert source files maintained in a native
operating system encoding, to ASCII prior to compilation.

Files in the directory src are converted from a native encoding to
ASCII. By default, all files in the directory are converted. However,
conversion may be limited to selected files using includes and
excludes attributes. For more information on file matching patterns,
see the section on directory based tasks. If no encoding is specified,
the default encoding for the JVM is used. If ext is specified, then
output files are renamed to use it as a new extension. More
sophisticated file name translations can be achieved using a nested
{\tt <mapper>} element. By default an identity mapper will be used. If dest
and src point to the same directory, the ext attribute or a nested
{\tt <mapper>} is required.

This task forms an implicit File Set, and supports all attributes of
{\tt <fileset>} (dir becomes src) as well as nested {\tt <include>},
{\tt <exclude>}, and {\tt <patternset>} elements.

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
reverse & Reverse the sense of the conversion, i.e. convert from ASCII to native & No \\ \hline
encoding & The native encoding the files are in (default is the default encoding for the JVM) & No \\ \hline
src & The directory to find files in (default is basedir) & No \\ \hline
dest & The directory to output file to & Yes \\ \hline
ext & File extension to use in renaming output files & No \\ \hline
defaultexcludes & indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline
includes & comma- or space-separated list of patterns of files that must be included. All files are included when omitted. & No \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & No \\ \hline
excludes & comma- or space-separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & No \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
<native2ascii encoding="EUCJIS" src="srcdir" dest="srcdir"
   includes="**/*.eucjis" ext=".java"/>
\end{verbatim}    
Converts all files in the directory srcdir ending in .eucjis from the
EUCJIS encoding to ASCII and renames them to end in .java.

\begin{verbatim}
<native2ascii encoding="EUCJIS" src="native/japanese" dest="src"
   includes="**/*.java"/>
\end{verbatim}    
Converts all the files ending in .java in the directory
native/japanese to ASCII, placing the results in the directory
src. The names of the files remain the same.

\subsection{NetRexxC}

\subsubsection{Description}

Compiles a NetRexx source tree within the running (Ant) VM.

The source and destination directory will be recursively scanned for
NetRexx source files to compile. Only NetRexx files that have no
corresponding class file or where the class file is older than the
java file will be compiled.

Files in the source tree are copied to the destination directory,
allowing support files to be located properly in the classpath. The
source files are copied because the NetRexx compiler cannot produce
class files in a specific directory via parameters

The directory structure of the source tree should follow the package
hierarchy.

It is possible to refine the set of files that are being
compiled/copied. This can be done with the includes, includesfile,
excludes, excludesfile and defaultexcludes attributes. With the
includes or includesfile attribute you specify the files you want to
have included by using patterns. The exclude or excludesfile attribute
is used to specify the files you want to have excluded. This is also
done with patterns. And finally with the defaultexcludes attribute,
you can specify whether you want to use default exclusions or not. See
the section on directory based tasks, on how the inclusion/exclusion
of files works, and how to write patterns.

This task forms an implicit FileSet and supports all attributes of
<fileset> (dir becomes srcdir) as well as the nested <include>,
<exclude> and <patternset> elements.

All properties except classpath, 
srcdir and destDir are also available as properties 
in the form ant.netrexxc.attributename, eg.
\begin{verbatim}
<property name="ant.netrexxc.verbose" value="noverbose"/>
\end{verbatim}
or from the command line as
ant -Dant.netrexxc.verbose=noverbose ...

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
binary & Whether literals are treated as the java binary type rather than the NetRexx types & No \\ \hline
classpath & The classpath to use during compilation & No \\ \hline
comments & Whether comments are passed through to the generated java source & No \\ \hline
compact & Whether error messages come out in compact or verbose format. Default is the compact format. & No \\ \hline
compile & Whether the NetRexx compiler should compile the generated java code & No \\ \hline
console & Whether or not messages should be displayed on the 'console' & No \\ \hline
crossref & Whether variable cross references are generated & No \\ \hline
decimal & Whether decimal arithmetic should be used for the NetRexx code & No \\ \hline
defaultexcludes & indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline
destDir & the destination directory into which the NetRexx source files should be copied and then compiled & Yes \\ \hline
diag & Whether diagnostic information about the compile is generated & No \\ \hline
excludes & comma- or space-separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & No \\ \hline
explicit & Whether variables must be declared explicitly before use & No \\ \hline
format & Whether the generated java code is formatted nicely or left to match NetRexx line numbers for call stack debugging & No \\ \hline
includes & comma- or space-separated list of patterns of files that must be included. All files are included when omitted. & No \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & No \\ \hline
java & Whether the generated java code is produced & No \\ \hline
keep & Sets whether the generated java source file should be kept after compilation. The generated files will have an extension of .java.keep, not .java & No \\ \hline
logo & Whether the compiler text logo is displayed when compiling & No \\ \hline
replace & Whether the generated .java file should be replaced when compiling & No \\ \hline
savelog & Whether the compiler messages will be written to NetRexxC.log as well as to the console & No \\ \hline
\end{tabular}
\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
sourcedir & Tells the NetRexx compiler to store the class files in the same directory as the source files. The alternative is the working directory & No \\ \hline
srcDir & Set the source dir to find the source NetRexx files & Yes \\ \hline
strictargs & Tells the NetRexx compiler that method calls always need parentheses, even if no arguments are needed, e.g. aStringVar.getBytes vs. aStringVar.getBytes() & No \\ \hline
strictassign & Tells the NetRexx compile that assignments must match exactly on type & No \\ \hline
strictcase & Specifies whether the NetRexx compiler should be case sensitive or not & No \\ \hline
strictimport & Whether classes need to be imported explicitly using an import statement. By default the NetRexx compiler will import certain packages automatically & No \\ \hline
strictprops & Whether local properties need to be qualified explicitly using this & No \\ \hline
strictsignal & Whether the compiler should force catching of exceptions by explicitly named types & No \\ \hline
symbols & Whether debug symbols should be generated into the class file & No \\ \hline
time & Asks the NetRexx compiler to print compilation times to the console & No \\ \hline
trace & Turns on or off tracing and directs the resultant trace output & No \\ \hline
utf8 & Tells the NetRexx compiler that the source is in UTF8 & No \\ \hline
verbose & Whether lots of warnings and error messages should be generated & No \\ \hline
suppressMethodArgumentNotUsed & Tells whether we should filter out the \&Method argument not used\& messages in strictargs mode. & no \\ \hline
suppressPrivatePropertyNotUsed & Tells whether we should filter out the \&Private Property defined, but not used\& messages in strictargs mode. & no \\ \hline
suppressVariableNotUsed & Tells whether we should filter out the \&Variable set but not used\& messages in strictargs mode. Please be careful with this one, as you can hide errors behind it! & no \\ \hline
\end{tabular}
\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
suppressExceptionNotSignalled & Tells whether we should filter out the \&Exception is declared, but not signalled within the method\& messages in strictsignal mode. & no \\ \hline
suppressDeprecation & Tells wether we should filter out any deprecation-messages of the compiler out. & no \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
    <netrexxc srcDir="/source/project" includes="vnr/util/*" 
     destDir="/source/project/build" classpath="/source/project2/proj.jar" 
     comments="true" crossref="false" replace="true" keep="true"/>
\end{verbatim}

\subsection{Perforce Tasks}
\begin{verbatim}
Perforce Tasks User Manual

by

    * Les Hughes (leslie.hughes@rubus.com)
    * Kirk Wylie (kirk@radik.com)

Version 1.1 - 2001/01/09
\end{verbatim}

These tasks provide an interface to the Perforce SCM. 

The org.apache.tools.ant.taskdefs.optional.perforce package
consists of a simple framework to support p4 functionality as 
well as some Ant tasks encapsulating frequently used (by me :-) p4 commands.
However, the addition of new p4 commands is a pretty simple task
(see the source). Although it is possible to use these commands on the
desktop, they were primarily intended to be used by automated build systems.

Note: These tasks require the oro 2.0.XXX regular expression package. 
Simply download this package and copy the jakarta-oro-2.0.XXX.jar file
into Ant's lib directory. You will also need the Perforce client 
executable (p4 or p4.exe but not p4win.exe) in your path.

\subsubsection{The Tasks}
\begin{itemize}
\item P4Sync Synchronise a workspace to a depot
\item P4Change Request a new changelist from the Perforce server
\item P4Edit Open files for edit (checkout)
\item P4Submit Submit a changelist to the Perforce server (checkin)
\item P4Have List current files in client view, useful for reporting
\item P4Label Create a label reflecting files in the current workspace
\item P4Counter Obtain or set the value of a counter
\item P4Reopen Move files between changelists
\item P4Revert Revert files
\item P4Add Add files
\end{itemize}

\subsubsection{General P4 Properties}

Each p4 task requires a number of settings, either through build-wide
properties, individual attributes or environment variables. These are

\begin{tabular}{|l|l|l|p{3cm}|p{1.7cm}|} \hline
Property  & Attribute & Env Var  & Description & Default \\ \hline
p4.port   & port      & P4PORT   & The p4d server and port to connect to & perforce:1666 \\ \hline
p4.client & client    & P4CLIENT & The p4 client spec to use & The logged in username \\ \hline
p4.user   & user      & P4USER   & The p4 username & The logged in username \\ \hline
--        & view      & --       & The client, branch or label view to operate upon. 
See the p4 user guide for more info. & {\tt //...} \\ \hline
\end{tabular}

Your local installation of Perforce may require other settings (e.g.
P4PASSWD, P4CONFIG). At the moment, these can only be set outside of
Ant, as environment variables.

Additionally, you may also specify the following attributes:

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
failonerror & Specifies whether to stop the build (true|yes|on) or keep going (false|no|off) if an error is returned from the p4 command. & No; defaults to true. \\ \hline
\end{tabular}

\subsubsection{Examples}

Setting in the environment:-
(Unix csh)
\begin{verbatim}
setenv P4PORT myperforcebox:1666
\end{verbatim}
(Unix sh et al)
\begin{verbatim}
P4USER=myp4userid; export P4USER
\end{verbatim}
Using build properties:-
\begin{verbatim}
<property name="p4.client" value="nightlybuild"/>
\end{verbatim}
Using task attributes:-
\begin{verbatim}
<p4Whatever
        port="myserver:1666"
        client="smoketest"
        user="smoketestdude"
        .
        .
        .
/>
\end{verbatim}
For more information regarding the underlying 'p4' commands you are
referred to the Perforce Command Reference available from the Perforce
website.

{\bf Taskdefs}\hfil\break

Standard taskdefs (for you to copy'n'paste) -- normally this is done
automatically if you install this optional task.
\begin{verbatim}
    <taskdef name="p4sync" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Sync"/>
    <taskdef name="p4change" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Change"/>
    <taskdef name="p4edit" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Edit"/>
    <taskdef name="p4submit" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Submit"/>
    <taskdef name="p4have" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Have"/>
    <taskdef name="p4label" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Label"/>
    <taskdef name="p4counter" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Counter"/>
    <taskdef name="p4reopen" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Reopen"/>
    <taskdef name="p4revert" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Revert"/>
    <taskdef name="p4add" classname="org.apache.tools.ant.taskdefs.optional.perforce.P4Add"/>
\end{verbatim}

{\bf Task Descriptions}\hfil\break

\subsubsection{P4Sync}

{\bf Description}\hfil\break

Synchronize the current workspace with the depot.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
force & force a refresh of files, if this attribute has been set. & no - if ommitted, it will be off, otherwise a refresh will be forced. \\ \hline
label & sync client to label & no \\ \hline
\end{tabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<p4sync label="nightlybuild-0.0123" force="foo"/>
<p4sync view="//depot/projects/projectfoo/main/src/..."/>
\end{verbatim}

\subsubsection{P4Change}

{\bf Description}\hfil\break

Request a new changelist from the Perforce server. This task sets the
\$\{p4.change\} property which can then be passed to P4Submit, P4Edit, or
P4Add.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
description & Description for ChangeList. If none specified, it will default to "AutoSubmit By Ant" & No. \\ \hline
\end{tabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<p4change description="Change Build Number in Script">
\end{verbatim}

\subsubsection{P4Edit}

{\bf Description:}\hfil\break

Open file(s) for edit. P4Change should be used to obtain a new
changelist for P4Edit as, although P4Edit can open files to the
default change, P4Submit cannot yet submit it.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
view & The filespec to request to edit & Yes \\ \hline
change & An existing changelist number to assign files to. & No, but see above. \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
<p4edit
    view="//depot/projects/projectfoo/main/src/Blah.java..."
    change="${p4.change}"/>
\end{verbatim}

\subsubsection{P4Submit}
{\bf Description:}\hfil\break

Submit a changelist, usually obtained from P4Change.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
change & The changelist number to submit & Yes \\ \hline
\end{tabular}
\subsubsection{Examples}

\begin{verbatim}
<p4submit change="${p4.change}"/>
\end{verbatim}

\subsubsection{P4Have}

{\bf Description:}\hfil\break

List handy file info reflecting the current client contents.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
& None & -- -- \\ \hline
\end{tabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<p4have/>
\end{verbatim}

\subsubsection{P4Label}

{\bf Description:}\hfil\break

Create a new label and set contents to reflect current client file revisions.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
name & The name of the label & Yes \\ \hline
view & client view to use for label & No \\ \hline
desc & Label Description & No \\ \hline
lock & Lock the label once created. & No \\ \hline
\end{tabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<p4label
        name="NightlyBuild:${DSTAMP}:${TSTAMP}" 
        desc="Auto Nightly Build"
        lock="locked"
/>
\end{verbatim}

\subsubsection{P4Counter}

{\bf Description}\hfil\break

Obtain or set the value of a counter. When used in its base form
(where only the counter name is provided), the counter value will be
printed to the output stream. When the value is provided, the counter
will be set to the value provided. When a property name is provided,
the property will be filled with the value of the counter. You may not
specify to both get and set the value of the counter in the same Task.

The user performing this task must have Perforce "review" permissions
as defined by Perforce protections in order for this task to succeed.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
name & The name of the counter & Yes \\ \hline
value & The new value for the counter & No \\ \hline
property & The property to be set with the value of the counter & No \\ \hline
\end{tabular}

{\bf Examples}\hfil\break

Print the value of the counter named "last-clean-build" to the output stream:
\begin{verbatim}
<p4counter name="last-clean-build"/>
\end{verbatim}
Set the value of the counter based on the value of the "TSTAMP" property:
\begin{verbatim}
<p4counter name="last-clean-build" value="${TSTAMP}"/>
\end{verbatim}
Set the value of the "p4.last.clean.build" property to the current value of the "last-clean-build" counter:
\begin{verbatim}
<p4counter name="last-clean-build" property="${p4.last.clean.build}"/>
\end{verbatim}

\subsubsection{P4Reopen}

{\bf Description:}\hfil\break

Move (or reopen in Perforce speak) checkout files between changelists.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
tochange & The changelist to move files to. & Yes \\ \hline
\end{tabular}

{\bf Examples}\hfil\break

Move all open files to the default changelist
\begin{verbatim}
<p4reopen view="//..." tochange="default"/>
\end{verbatim}
Create a new changelist then reopen into it, any files from the view
//projects/foo/main/...
\begin{verbatim}
<p4change description="Move files out of the way"/>
<p4reopen view="//projects/foo/main/..." tochange="${p4.change}"/>
\end{verbatim}

\subsubsection{P4Revert}

{\bf Description:}\hfil\break

Reverts files.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
change & The changelist to revert. & No \\ \hline
revertOnlyUnchanged & Revert only unchanged files (p4 revert -a) & No \\ \hline
\end{tabular}

{\bf Examples}\hfil\break
Revert everything!
\begin{verbatim}
<p4revert view="//..."/>
\end{verbatim}
Revert any unchanged files in the default change
\begin{verbatim}
<p4revert change="default" revertonlyunchanged="true"/>
\end{verbatim}

\subsubsection{P4Add}

{\bf Description:}\hfil\break

Adds files specified in nested fileset children.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
commandlength & A positive integer specifying the maximum length of the commandline when calling Perforce to add the files. Defaults to 450, higher values mean faster execution, but also possible failures. & No \\ \hline
changelist & If specified the open files are associated with the specified pending changelist number; otherwise the open files are associated with the default changelist. & No \\ \hline
\end{tabular}

{\bf Examples}\hfil\break
Require a changelist, add all java files starting from a directory, and submit
\begin{verbatim}
<p4change/>
<p4add commandlength="20000" changelist="${p4.change}">
    <fileset dir="../dir/src/" includes="**/*.java"/>
<p4add>
<p4submit change="${p4.change}"/>
\end{verbatim}

{\bf Change History}\hfil\break
\begin{tabular}{|l|l|p{6cm}|} \hline
Sept 2000 & -- & Internal Release within Rubus \\ \hline
Nov 2000 & V1.0 & Initial Release donated to ASF :-) \\ \hline
Jan 2001 & V1.1 & fixed cross platform (NT/Unix) bug
refactored p4 output handling code
refactored exec'ing code \\ \hline
\end{tabular}

\subsection{PropertyFile}
\begin{verbatim}
PropertyFile

by

    * Thomas Christen (chr@active.ch)
    * Jeremy Mawson (jem@loftinspace.com/au)
\end{verbatim}

Ant provides an optional task for editing property files. This is very
useful when wanting to make unattended modifications to configuration
files for application servers and applications. Currently, the task
maintains a working property file with the ability to add properties
or make changes to existing ones. However, any comments are lost.

\subsubsection{PropertyFile Task}

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
file & Location of the property file to be edited & Yes \\ \hline
comment & Header for the file itself & no \\ \hline
\end{tabular}

{\bf Parameters specified as nested elements}\hfil\break

{\bf Entry}\hfil\break

Use nested {\tt <entry>} elements to specify 
actual modifications to the property file itself.

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
key & Name of the property name/value pair & Yes \\ \hline
\begin{tabular}{l}
value \\ \hline
default \\ \hline
\end{tabular} &
\begin{tabular}{p{6.5cm}}
Value to set (=), to add (+) or subtract (-)  \\
 Initial value to set for a property if it is not already
defined in the property file.
For type date, an additional keyword is allowed: "now" \\
\end{tabular} &
At least one must be specified \\ \hline

type & Regard the value as : int, date or string (default) & No \\ \hline
operation & "+" or "=" (default) for all datatypes "-" (for date and int only). & No \\ \hline
pattern & For int and date type only. If present, Values will be parsed and formatted accordingly. & No \\ \hline
unit & The unit of the value to be applied to date +/- operations. Valid Values are:
\begin{itemize}
\item millisecond
\item second
\item minute
\item hour
\item day (default)
\item week
\item month
\item year
\end{itemize}
This only applies to date types using a +/- operation. & No \\ \hline
\end{tabular}

The rules used when setting a property value are shown below.  The
operation occurs after these rules are considered.
\begin{itemize}
\item If only value is specified, the property is set to it regardless of its previous value.
\item If only default is specified and the property previously existed in the property file, it is unchanged.
\item If only default is specified and the property did not exist in the property file, the property is set to default.
\item If value and default are both specified and the property previously existed in the property file, the property is set to value.
\item If value and default are both specified and the property did not exist in the property file, the property is set to default.
\end{itemize}
 
{\bf Examples}\hfil\break

The following changes the my.properties file. Assume my.properties
look like:
\begin{verbatim}
# A comment
akey=novalue
\end{verbatim}
After running, the file would now look like
\begin{verbatim}
#Thu Nov 02 23:41:47 EST 2000
akey=avalue
adate=2000/11/02 23\:41
anint=1
formated.int=0014
formated.date=028 17\:34
\end{verbatim}
The slashes conform to the expectations of the Properties class. The
file will be stored in a manner so that each character is examined and
escaped if necessary. Note that the original comment is now
lost. Please keep this in mind when running this task against heavily
commented properties files. It may be best to have a commented version
in the source tree, copy it to a deployment area, and then run the
modifications on the copy. Future versions of PropertyFile will
hopefully eliminate this shortcoming.
\begin{verbatim}
<propertyfile
    file="my.properties"
    comment"My properties">
  <entry  key="akey" value="avalue"/>
  <entry  key="adate" type="date" value="now"/>
  <entry  key="anint" type="int" operation="+"/>
  <entry  key="formated.int" type="int" default="0013" operation="+" pattern="0000"/>
  <entry  key="formated.date" type="date" value="now" pattern="DDD HH:mm"/>
</propertyfile>
\end{verbatim}
To produce dates relative from today :
\begin{verbatim}
<propertyfile
    file="my.properties"
    comment="My properties">
  <entry  key="formated.date-1"
      type="date" default="now" pattern="DDD"
      operation="-" value="1"/>
  <entry  key="formated.tomorrow"
      type="date" default="now" pattern="DDD"
      operation="+" value="1"/>
</propertyfile>
\end{verbatim}
Concatenation of strings :
\begin{verbatim}
<propertyfile
    file="my.properties"
    comment="My properties">
  <entry  key="progress" default="" operation="+" value="."/>
</propertyfile>
\end{verbatim}
Each time called, a "." will be appended to "progress"

\subsection{Pvcs}
\begin{verbatim}
by

    * Thomas Christensen (tchristensen@nordija.com)
    * Don Jeffery (donj@apogeenet.com)

Version 1.1 - 2001/06/27

Problems with UNC pathnames and the use of () 
in paths are fixed and an updateonly argument introduced.

Version 1.0 - 2001/01/31

Initial release.
\end{verbatim}
Note: Before using this task, the user running ant must have access to
the commands of PVCS (get and pcli) and must have access to the
repository. Note that the way to specify the repository is platform
dependent so use property to specify location of repository.  

The pvcs task allows the user of ant to extract the latest edition of
the source code from a PVCS repository. PVCS is a version control
system developed by Merant.  This version has been tested agains PVCS
version 6.5 and 6.6 under Windows and Solaris.

\subsubsection{Pvcs Task}

{\bf Description}\hfil\break

The pvcs task is set to point at a PVCS repository and optionally a
project within that repository, and can from that specification get
the latest version of the files contained by the repository.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
repository & The location of the repository (see your PVCS manuals) & Yes \\ \hline
pvcsproject & The project within the PVCS repository to extract files from ("/" is root project and that is default if this attribute isn't specified) & No \\ \hline
label & Only files marked with this label are extracted. & No \\ \hline
promotiongroup & Only files within this promotion group are extracted. Using both the label and the promotiongroup tag will cause the files in the promotion group and with that label to be extracted. & No \\ \hline
force & If set to yes all files that exists and are writable are overwritten. Default no causes the files that are writable to be ignored. This stops the PVCS command get to stop asking questions! & No \\ \hline
workspace & By specifying a workspace, the files are extracted to that location. A PVCS workspace is a name for a location of the workfiles and isn't as such the location itself. You define the location for a workspace using the PVCS GUI clients. If this isn't specified the default workspace for the current user is used. & No \\ \hline
pvcsbin & On some systems the PVCS executables pcli and get are not found in the PATH. In such cases this attribute should be set to the bin directory of the PVCS installation containing the executables mentioned before. If this attribute isn't specified the tag expects the executables to be found using the PATH environment variable. & No \\ \hline
ignorereturncode & If set to true the return value from executing the pvcs commands are ignored. & No \\ \hline
updateonly & If set to true files are gotten only if newer than existing local files. & No \\ \hline
filenameformat & The format of your folder names in a format suitable for java.text.MessageFormat. Defaults to {0}-arc({1}). Repositories where the archive extension is not -arc should set this. & No \\ \hline
linestart & Used to parse the output of the pcli command. 
It defaults to "P:. The parser already knows about / 
and $\backslash$, this property is useful in cases where the repository 
is accessed on a Windows platform via a drive letter mapping. & No \\ \hline
\end{tabular}

{\bf Nested Elements}\hfil\break

{\bf pvcsproject element}\hfil\break

pvcs supports a nested <pvcsproject> element, that represents a
project within the PVCS repository to extract files from. By nesting
multiple <pvcsproject> elements under the <pvcs> task, multiple
projects can be specified.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
name & The name of the pvcs project & Yes \\ \hline
\end{tabular}

{\bf Examples}\hfil\break
The following set-up extracts the latest version of the files in the pvcs repository.
\begin{verbatim}
  <!-- =================================================================== -->
  <!-- Get the latest version                                              -->
  <!-- =================================================================== -->
  <target name="getlatest">
    <pvcs repository="/mnt/pvcs" pvcsproject="/myprj"/>
  </target>
\end{verbatim}
Now run:
ant getlatest

This will cause the following output to appear:
\begin{verbatim}
  getlatest:
  [pvcs] PVCS Version Manager (VMGUI) v6.6.10 (Build 870) for Windows NT/80x86
  [pvcs] Copyright 1985-2000 MERANT. All rights reserved.
  [pvcs] PVCS Version Manager (get) v6.6.10 (Build 870) for Windows NT/80x86
  [pvcs] Copyright 1985-2000 MERANT. All rights reserved.
  [pvcs] c:\myws\myprj\main.java <- C:\mypvcs\archives\myprj\main.java-arc
  [pvcs] rev 1.1
  [pvcs] c:\myws\myprj\apache\tool.java <- 
                             C:\mypvcs\archives\myprj\apache\tools.java-arc
  [pvcs] rev 1.5

  BUILD SUCCESSFUL

  Total time: 19 seconds
\end{verbatim}
This next example extracts the latest version of the files in the pvcs
repository from two projects using nested <pvcsproject> elements.
\begin{verbatim}
  <!-- ===================================================================-->
  <!-- Get latest from myprj and myprj2                                   -->
  <!-- ===================================================================-->
  <target name="getlatest2">
    <pvcs repository="/mnt/pvcs">
      <pvcsproject name="/myprj"/>
      <pvcsproject name="/myprj2"/>
    </pvcs>
  </target>
\end{verbatim}
Now run:
ant getlatest2

This will cause the following output to appear:
\begin{verbatim}
  getlatest2:
  [pvcs] PVCS Version Manager (VMGUI) v6.6.10 (Build 870) for Windows NT/80x86
  [pvcs] Copyright 1985-2000 MERANT.  All rights reserved.
  [pvcs] PVCS Version Manager (get) v6.6.10 (Build 870) for Windows NT/80x86
  [pvcs] Copyright 1985-2000 MERANT.  All rights reserved.
  [pvcs] c:\myws\myprj\main.java <- C:\mypvcs\archives\myprj\main.java-arc
  [pvcs] rev 1.1
  [pvcs] c:\myws\myprj\apache\tool.java <- C:\mypvcs\archives\myprj\apache\tool.java-arc
  [pvcs] rev 1.5
  [pvcs] c:\myws\myprj2\apache\tool2.java <- C:\mypvcs\archives\myprj2\apache\tool2.java-arc
  [pvcs] rev 1.2

  BUILD SUCCESSFUL

  Total time: 22 seconds
\end{verbatim}

\subsection{RenameExtensions}

{\em Deprecated}

This task has been deprecated. Use the move task with a glob mapper instead.

\subsubsection{Description}

Renames files in the srcDir directory ending with the fromExtension
string so that they end with the toExtension string. Files are only
replaced if replace is true

See the section on directory based tasks, on how the
inclusion/exclusion of files works, and how to write patterns. This
task forms an implicit FileSet and supports all attributes of
{\tt <fileset>} (dir becomes srcDir) as well as the nested {\tt <include>},
{\tt <exclude>} and {\tt <patternset>} elements.

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
defaultexcludes & indicates whether default excludes should be used or not ("yes"/"no"). Default excludes are used when omitted. & No \\ \hline
excludes & comma- or space-separated list of patterns of files that must be excluded. No files (except default excludes) are excluded when omitted. & No \\ \hline
excludesfile & the name of a file. Each line of this file is taken to be an exclude pattern & No \\ \hline
fromExtention & The string that files must end in to be renamed & Yes \\ \hline
includes & comma- or space-separated list of patterns of files that must be included. All files are included when omitted. & No \\ \hline
includesfile & the name of a file. Each line of this file is taken to be an include pattern & No \\ \hline
replace & Whether the file being renamed to should be replaced if it already exists & No \\ \hline
srcDir & The starting directory for files to search in & Yes \\ \hline
toExtension & The string that renamed files will end with on completion & Yes \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
    <renameext srcDir="/source/project1" includes="**" 
     excludes="**/samples/*" fromExtension=".java.keep" 
     toExtension=".java" replace="true"/>
\end{verbatim}

\subsection{ReplaceRegExp}

\subsubsection{Description}

ReplaceRegExp is a directory based task for replacing the occurrence
of a given regular expression with a substitution pattern in a
selected file or set of files.

Similar to regexp type mappers this task needs a supporting regular
expression library and an implementation of
org.apache.tools.ant.util.regexp.Regexp. Ant comes with
implementations for the java.util.regex package of JDK 1.4,
jakarta-regexp and jakarta-ORO, but you will still need the library
itself.

There are cross-platform issues for matches related to line
terminator. For example if you use \$ to anchor your regular expression
on the end of a line the results might be very different depending on
both your platform and the regular expression library you use. It is
'highly recommended' that you test your pattern on both Unix and
Windows platforms before you rely on it.
\begin{itemize}
\item Jakarta Oro defines a line terminator as '\\n' and is consistent with Perl.
\item Jakarta RegExp uses a system-dependant line terminator.
\item JDK 1.4 uses '\\n', '\\r\\n', '\\u0085', '\\u2028', '\\u2029' as a default but is configured in the wrapper to use only '\\n' (UNIX\_LINE)
\end{itemize}
We strongly recommend that you use Jakarta Oro.

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
file & file for which the regular expression should be replaced. & Yes if no nested {\tt <fileset>} is used \\ \hline
match & The regular expression pattern to match in the file(s) & Yes, if no nested {\tt <regexp>} is used \\ \hline
replace & The substitution pattern to place in the file(s) in place of the regular expression. & Yes, if no nested {\tt <substitution>} is used \\ \hline
flags & The flags to use when matching the regular expression. For more information, consult the Perl5 syntax
g : Global replacement. Replace all occurences found
i : Case Insensitive. Do not consider case in the match
m : Multiline. Treat the string as multiple lines of input, using "{\tt caret}" and "\$" as the start or end of any line, respectively, rather than start or end of string.
s : Singleline. Treat the string as a single line of input, using "." to match any character, 
including a newline, which normally, it would not match. & No \\ \hline
byline & Process the file(s) one line at a time, executing the replacement on one line at a time (true/false). This is useful if you want to only replace the first occurence of a regular expression on each line, which is not easy to do when processing the file as a whole. Defaults to false. & No \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
  <replaceregexp file="${src}/build.properties"
                         match="OldProperty=(.*)"
                         replace="NewProperty=\1"
                         byline="true"/>
\end{verbatim}

replaces occurrences of the property name "OldProperty" with
"NewProperty" in a properties file, preserving the existing value, in
the file \$\{src\}/build.properties

\subsubsection{Parameters specified as nested elements}

This task supports a nested FileSet element.

This task supports a nested Regexp element to specify the regular
expression. You can use this element to refer to a previously defined
regular expression datatype instance.
\begin{verbatim}
    <regexp id="id" pattern="expression"/>
    <regexp refid="id"/> 
\end{verbatim}
This task supports a nested Substitution element to specify the
substitution pattern. You can use this element to refer to a
previously defined substitution pattern datatype instance.
\begin{verbatim}
    <substitution id="id" pattern="expression"/>
    <substitution refid="id"/> 
\end{verbatim}

{\bf Examples}\hfil\break
\begin{verbatim}
<replaceregexp byline="true">
  <regexp pattern="OldProperty=(.*)"/>
  <substitution expression="NewProperty=\1"/>
  <fileset dir=".">
   <includes="*.properties"/>
  </fileset>
 </replaceregexp>
\end{verbatim}
replaces occurrences of the property name "OldProperty" with
"NewProperty" in a properties file, preserving the existing value, in
all files ending in .properties in the current directory
\begin{verbatim}
<replaceregexp match="\s+" replace=" " flags="g" byline="true">
    <fileset dir="${html.dir}" includes="**/*.html" />
</replaceregexp>
\end{verbatim}
replaces all whitespaces (blanks, tabs, etc) by one blank remaining
the line separator. So with input
\begin{verbatim}
<html>    <body>
<<TAB>><h1>    T E S T   </h1>  <<TAB>>    
<<TAB>> </body></html>
\end{verbatim}
would converted to
\begin{verbatim}
<html> <body>
 <h1> T E S T </h1> </body></html>
\end{verbatim}

\subsection{Rpm}

\subsubsection{Description}

A basic task for invoking the rpm executable to build a Linux
installation file. The task currently only works on Linux or other
Unix platforms with rpm support.

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
specFile & The name of the spec File to be used. & Yes \\ \hline
topDir & this is the directory which will have the expected subdirectories, SPECS, SOURCES, BUILD, SRPMS. If this isn't specified, the baseDir value is used & No \\ \hline
cleanBuildDir & This will remove the generated files in the BUILD directory. & No \\ \hline
removeSpec & this will remove the spec file from SPECS & No \\ \hline
removeSource & Flag (optional, default=false) to remove the sources after the build. See the the --rmsource option of rpmbuild. & No \\ \hline
command & very similar idea to the cvs task. the default is "-bb" & No \\ \hline
output &/error where standard output and error go & No \\ \hline
\end{tabular}

\subsection{ServerDeploy}
\begin{verbatim}
by

    * Christopher A. Longo (cal@cloud9.net)
    * Cyrille Morvan (cmorvan@ingenosya.com)
\end{verbatim}

At present the tasks support:
\begin{itemize}
\item Weblogic servers
\item JOnAS 2.4 Open Source EJB server
\end{itemize}
Over time we expect further optional tasks to support additional J2EE Servers.

\begin{tabular}{|l|l|} \hline
Task & Application Servers \\ \hline
serverdeploy &
\begin{tabular}{ll} \hline
Nested & Elements \\ \hline
generic & Generic task \\
jonas & JOnAS 2.4 \\
weblogic & Weblogic \\
\end{tabular} \\ \hline
\end{tabular}

\subsubsection{ServerDeploy element}

{\bf Description:}\hfil\break

The serverdeploy task is used to run a "hot" deployment tool for
vendor-specific J2EE server. The task requires nested elements which
define the attributes of the vendor-specific deployment tool being
executed. Vendor-specific deployment tools elements may enforce rules
for which attributes are required, depending on the tool.

{\bf Parameters:}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
action & This is the action to be performed. For most cases this will be "deploy". Some tools support additional actions, such as "delete", "list", "undeploy", "update"... & Yes \\ \hline
source & A fully qualified path/filename of the component to be deployed. This may be an .ear, .jar, .war, or any other type that is supported by the server. & Tool dependant \\ \hline
\end{tabular}

{\bf Nested Elements}\hfil\break

The serverdeploy task supports a nested classpath element to set the classpath.

\subsubsection{Vendor-specific nested elements}

{\bf Parameters used for all tools:}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
classpath & The classpath to be passed to the JVM running the tool. The classpath may also be supplied as a nested element. & Tool dependant \\ \hline
server & The address or URL for the server where the component will be deployed. & Tool dependant \\ \hline
username & The user with privileges to deploy applications to the server. & Tool dependant \\ \hline
password & The password of the user with privileges to deploy applications to the server. & Tool dependant \\ \hline
\end{tabular}

Also supported are nested vendor-specific elements.

\subsubsection{Generic element}

This element is provided for generic Java-based deployment tools. The
generic task accepts (but does not require) nested arg and jvmarg
elements. A JVM will be spawned with the provided attributes. It is
recommended that a vendor-specific element be used over the generic
one if at all possible.

The following attributes are supported by the generic element.

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
classname & This is the fully qualified classname of the Java based deployment tool to execute. & Yes \\ \hline
\end{tabular}

{\bf Nested Elements}\hfil\break

The generic element supports nested {\tt <arg>} and {\tt <jvmarg>} elements.

{\bf Example}\hfil\break

This example shows the use of generic deploy element to deploy a
component using a Java based deploy tool:
\begin{verbatim}
    <serverdeploy action="deploy" source="${lib.dir}/ejb_myApp.ear">
        <generic classname="com.yamato.j2ee.tools.deploy.DeployTool"
            classpath="${classpath}"
            username="${user.name}"
            password="${user.password}">
            <arg value="-component=WildStar"/>
            <arg value="-force"/>
            <jvmarg value="-ms64m"/>
            <jvmarg value="-mx128m"/>
        </generic>
    </serverdeploy>
\end{verbatim}

\subsubsection{WebLogic element}

The WebLogic element contains additional attributes to run the
weblogic.deploy deployment tool.

Valid actions for the tool are deploy, undeploy, list, update, and delete.

If the action is deploy or update, the application and source
attributes must be set. If the action is undeploy or delete, the
application attribute must be set. If the username attribute is
omitted, it defaults to "system". The password attribute is required
for all actions.

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
application & This is the name of the application being deployed & Yes \\ \hline
component & This is the component string for deployment targets. 
It is in the form {\tt <component>:<target1>,<target2>...} Where 
component is the archive name (minus the .jar, .ear, .war extension). 
Targets are the servers where the components will be deployed & no \\ \hline
debug & If set to true, additional information will be printed during the deployment process. & No \\ \hline
\end{tabular}

{\bf Examples}\hfil\break

This example shows the use of serverdeploy to deploy a component to a
WebLogic server:
\begin{verbatim}
    <serverdeploy action="deploy" source="${lib.dir}/ejb_myApp.ear">
        <weblogic application="myapp"
            server="t3://myserver:7001"
            classpath="${weblogic.home}/lib/weblogic.jar"
            username="${user.name}"
            password="${user.password}"
            component="ejb_foobar:myserver,productionserver"
            debug="true"/>
    </serverdeploy>
\end{verbatim}
This example shows serverdeploy being used to delete a component from
a WebLogic server:
\begin{verbatim}
    <serverdeploy action="delete" source="${lib.dir}/ejb_myApp.jar"/>
        <weblogic application="myapp"
            server="t3://myserver:7001"
            classpath="${weblogic.home}/lib/weblogic.jar"
            username="${user.name}"
            password="${user.password}"/>
    </serverdeploy>
\end{verbatim}

\subsubsection{JOnAS (Java Open Applicaton Server) element}

The JOnAS element contains additional attributes to run the JonasAdmin
deployment tool.

Valid actions for the tool are deploy, undeploy, list and update.

You can't use user and password property with this task.

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
jonasroot & The root directory for JOnAS. & Yes \\ \hline
orb & Choose your ORB : RMI, JEREMIE, DAVID, ... If omitted, it defaults to the one present in classpath. The corresponding JOnAS JAR is automatically added to the classpath. If your orb is DAVID (RMI/IIOP) you must specify davidhost and davidport properties. & No \\ \hline
davidhost & The value for the system property : david.CosNaming.default\_host . & No \\ \hline
davidport & The value for the system property : david.CosNaming.default\_port . & No \\ \hline
classname & This is the fully qualified classname of the Java based deployment tool to execute. Default to org.objectweb.jonas.adm.JonasAdmin & No \\ \hline
\end{tabular}

{\bf Nested Elements}\hfil\break

The jonas element supports nested {\tt <arg>} and {\tt <jvmarg>} elements.

\subsubsection{Examples}

This example shows the use of serverdeploy to deploy a component to a
JOnAS server:
\begin{verbatim}
    <serverdeploy action="deploy" source="${lib.dir}/ejb_myApp.jar">
        <jonas server="MyJOnAS" jonasroot="${jonas.root}">

           <classpath>
               <pathelement path="${jonas.root}/lib/RMI_jonas.jar"/>
               <pathelement path="${jonas.root}/config/"/>
           </classpath>
        </jonas>
    </serverdeploy>
\end{verbatim}
This example shows serverdeploy being used to list the components from
a JOnAS server and a WebLogic server:
\begin{verbatim}
    <serverdeploy action="list"/>
        <jonas jonasroot="${jonas.root}" orb="JEREMIE"/>
        <weblogic application="myapp"
            server="t3://myserver:7001"
            classpath="${weblogic.home}/lib/weblogic.jar"
            username="${user.name}"
            password="${user.password}"/>
    </serverdeploy>
\end{verbatim}

\subsection{Setproxy}

\subsubsection{Setproxy Task}

Sets Java's web proxy properties, so that tasks and code run in the
same JVM can have through-the-firewall access to remote web sites, and
remote ftp sites. Apache Ant
 
{\bf Description}\hfil\break

Sets Java's web proxy properties, so that tasks and code run in the
same JVM can have through-the-firewall access to remote web sites, and
remote ftp sites. You can nominate an http and ftp proxy, or a socks
server, reset the server settings, or do nothing at all.

{\bf Examples}\hfil\break
\begin{verbatim}
<setproxy/>

    do nothing

<setproxy proxyhost="firewall"/>

    set the proxy to firewall:80

<setproxy proxyhost="firewall" proxyport="81"/>

    set the proxy to firewall:81

<setproxy proxyhost=""/>

    stop using the http proxy; don't change the socks settings

<setproxy socksproxyhost="socksy"/>

    use socks via socksy:1080

<setproxy socksproxyhost=""/>

    stop using the socks server 
\end{verbatim}
 
{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Type \\ \hline
nonProxyHosts & A list of hosts to bypass the proxy on. These should be separated with the vertical bar character '|'. Only in Java 1.4 does ftp use this list. e.g. fozbot.corp.sun.com|*.eng.sun.com. & String \\ \hline
proxyHost & the HTTP/ftp proxy host. Set this to "" for the http proxy option to be disabled & String \\ \hline
proxyPort & the HTTP/ftp proxy port number; default is 80 & int \\ \hline
socksProxyHost & The name of a Socks server. Set to "" to turn socks proxying off. & String \\ \hline
socksProxyPort & Set the ProxyPort for socks connections. The default value is 1080 & int \\ \hline
\end{tabular}
 
Parameters as nested elements

\subsection{Script}

\subsubsection{Description}

Execute a script in a BSF supported language.

Note: This task depends on external libraries not included in the Ant
distribution. See Library Dependencies for more information.

All items (tasks, targets, etc) of the running project are accessible
from the script, using either their name or id attributes (as long as
their names are considered valid Java identifiers, that is). The name
"project" is a pre-defined reference to the Project, which can be used
instead of the project name.

BeanShell users: This task now natively supports the BeanShell
scripting language, using language="beanshell". The BeanShell engine
is still required.

Scripts can do almost anything a task written in Java could do.

\subsubsection{Parameters}

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
language & The programming language the script is written in. Must be a supported BSF language & Yes \\ \hline
src & The location of the script as a file, if not inline & No \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
<project name="squares" default="main" basedir=".">

  <target name="setup">

    <script language="javascript"> <![CDATA[

      for (i=1; i<=10; i++) {
        echo = squares.createTask("echo");
        main.addTask(echo);
        echo.setMessage(i*i);
      }

    ]]> </script>

  </target>

  <target name="main" depends="setup"/>

</project>
\end{verbatim}
generates
\begin{verbatim}
setup:

main:
1
4
9
16
25
36
49
64
81
100

BUILD SUCCESSFUL
\end{verbatim}
Another example, using references by id and two different scripting languages:
\begin{verbatim}
<project name="testscript" default="main">
  <target name="sub">
    <echo id="theEcho"/>
  </target>

  <target name="sub1">
    <script language="netrexx"><![CDATA[
      theEcho.setMessage("In sub1")
      sub.execute
    ]]></script>
  </target>

  <target name="sub2">
    <script language="javascript"><![CDATA[
      theEcho.setMessage("In sub2");
      sub.execute();
    ]]></script>
  </target>

  <target name="main" depends="sub1,sub2"/>
</project>
\end{verbatim}
generates

sub1:
In sub1

sub2:
In sub2

main:

BUILD SUCCESSFUL

\subsection{Sound}

\subsubsection{Description}

Plays a sound-file at the end of the build, according to whether the
build failed or succeeded. You can specify either a specific
sound-file to play, or, if a directory is specified, the <sound> task
will randomly select a file to play. Note: At this point, the random
selection is based on all the files in the directory, not just those
ending in appropriate suffixes for sound-files, so be sure you only
have sound-files in the directory you specify.

Unless you are running on Java 1.3 or later, you need the Java Media
Framework on the classpath (javax.sound).

{\bf Nested Elements}\hfil\break

{\bf success}\hfil\break

Specifies the sound to be played if the build succeeded.

{\bf fail}\hfil\break

Specifies the sound to be played if the build failed.

\subsubsection{Nested Element Parameters}

The following attributes may be used on the <success> and {\tt <fail>} elements:

\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
Attribute & Description & Required \\ \hline
source & the path to a sound-file directory, or the name of a specific sound-file, to be played. & Yes \\ \hline
loops & the number of extra times to play the sound-file; default is 0. & No \\ \hline
duration & the amount of time (in milliseconds) to play the sound-file. & No \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
<target name="fun" if="fun" unless="fun.done">
  <sound>
    <success source="${user.home}/sounds/bell.wav"/>
    <fail source="${user.home}/sounds/ohno.wav" loops="2"/>
  </sound>
  <property name="fun.done" value="true"/>
</target>
\end{verbatim}
plays the bell.wav sound-file if the build succeeded, or the 
ohno.wav sound-file if the build failed, three times, if the 
fun property is set to true. If the target is a dependency of 
an "initialization" target that other targets depend on, the 
fun.done property prevents the target from being executed more than once.
\begin{verbatim}
<target name="fun" if="fun" unless="fun.done">
  <sound>
    <success source="//intranet/sounds/success"/>
    <fail source="//intranet/sounds/failure"/>
  </sound>
  <property name="fun.done" value="true"/>
</target>
\end{verbatim}
randomly selects a sound-file to play when the build succeeds or fails. 

\subsection{SourceOffSite}
\begin{verbatim}
by

    * Jesse Stockall

Version 1.1 2002/01/23
\end{verbatim}

These tasks provide an interface to the Microsoft Visual SourceSafe
SCM via SourceGear's SourceOffSite product. SourceOffSite is an add-on
to Microsoft's VSS, that allows remote development teams and
tele-commuters that need fast and secure read/write access to a
centralized SourceSafe database via any TCP/IP connection. SOS
provides Linux ,Solaris \& Windows clients. The
org.apache.tools.ant.taskdefs.optional.sos package consists of a
simple framework to support SOS functionality as well as some Ant
tasks encapsulating frequently used SOS commands. Although it is
possible to use these commands on the desktop, they were primarily
intended to be used by automated build systems. These tasks have been
tested with SourceOffSite version 3.5.1 connecting to VisualSourceSafe
6.0. The tasks have been tested with Linux, Solaris \& Windows2000.

\subsubsection{The Tasks}

\begin{itemize}
\item[sosget] Retrieves a read-only copy of the specified project or file.
\item[soslabel] Assigns a label to the specified project.
\item[soscheckin] Updates VSS with changes made to a checked out file or project, and unlocks the VSS master copy.
\item[soscheckout] Retrieves a read-write copy of the specified project or file, locking the VSS master copy
\end{itemize}

\subsubsection{Task Descriptions}

{\bf SOSGet}\hfil\break

{\bf Description}\hfil\break

Task to perform GET commands with SOS

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
soscmd & Directory which contains soscmd(.exe)
soscmd(.exe) must be in the path if this is not specified & No \\ \hline
vssserverpath & path to the srcsafe.ini -- 
e.g. ${\backslash}{\backslash}$server${\backslash}$vss${\backslash}$srcsafe.ini & Yes \\ \hline
sosserverpath & address \& port of the SOS server - eg. 192.168.0.1:8888 & Yes \\ \hline
projectpath & SourceSafe project path without the "\$" & Yes \\ \hline
file & Filename to act upon If no file is specified then act upon the project & No \\ \hline
username & SourceSafe username & Yes \\ \hline
password & SourceSafe password & No \\ \hline
localpath & Override the working directory and get to the specified path & No \\ \hline
soshome & The path to the SourceOffSite home directory & No \\ \hline
nocompress & true or false - disable compression & No \\ \hline
recursive & true or false - Only works with the GetProject command & No \\ \hline
version & a version number to get - Only works with the GetFile command & No \\ \hline
label & a label version to get - Only works with the GetProject command & No \\ \hline
nocache & true or false - Only needed if SOSHOME is set as an environment variable & No \\ \hline
verbose & true or false - Status messages are displayed & No \\ \hline
\end{tabular}

{\bf Example}\hfil\break
\begin{verbatim}
<sosget verbose="true"
        recursive="true"
        username="build"
        password="build"
        localpath="tmp"
        projectpath="/SourceRoot/project1"
        sosserverpath="192.168.10.6:8888"
        vssserverpath="d:\vss\srcsafe.ini"/>
\end{verbatim}
Connects to a SourceOffsite server on 192.168.10.6:8888 with
build,build as the username \& password. The SourceSafe database
resides on the same box as the SOS server \& the VSS database is at
"d:${\backslash}{\backslash}$vss\\srcsafe.ini" Does a recursive GetProject on
\$/SourceRoot/project1, using tmp as the working directory.

{\bf SOSLabel}\hfil\break

{\bf Description}\hfil\break

Task to perform Label commands with SOS

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
soscmd & Directory which contains soscmd(.exe)
soscmd(.exe) must be in the path if this is not specified & No \\ \hline
vssserverpath & path to the srcsafe.ini -- 
e.g. ${\backslash}{\backslash}$server${\backslash}$vss${\backslash}$srcsafe.ini & Yes \\ \hline
sosserverpath & address and port of the SOS server - eg. 192.168.0.1:8888 & Yes \\ \hline
projectpath & SourceSafe project path without the "\$" & Yes \\ \hline
username & SourceSafe username & Yes \\ \hline
password & SourceSafe password & No \\ \hline
label & The label to apply to a project & Yes \\ \hline
comment & A comment to be applied to all files being labeled & No \\ \hline
verbose & true or false - Status messages are displayed & No \\ \hline
\end{tabular}

{\bf Example}\hfil\break
\begin{verbatim}
<soslabel username="build"
          password="build"
          label="test label"
          projectpath="/SourceRoot/project1
          sosserverpath="192.168.10.6:8888"
          vssserverpath="d:\vss\srcsafe.ini"/>
\end{verbatim}
Connects to a SourceOffsite server on 192.168.10.6:8888 with
build,build as the username \& password. The SourceSafe database
resides on the same box as the SOS server \& the VSS database is at
"d:${\backslash}{\backslash}$vss${\backslash}$srcsafe.ini". 
Labels the \$/SourceRoot/project1 project with
"test label".

{\bf SOSCheckIn}\hfil\break

{\bf Description}\hfil\break

Task to perform CheckIn commands with SOS

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
soscmd & Directory which contains soscmd(.exe)
soscmd(.exe) must be in the path if this is not specified & No \\ \hline
vssserverpath & path to the srcsafe.ini -- 
e.g. ${\backslash}{\backslash}$server${\backslash}{\backslash}$vss${\backslash}{\backslash}$srcsafe.ini & Yes \\ \hline
sosserverpath & address and port of the SOS server - eg. 192.168.0.1:8888 & Yes \\ \hline
projectpath & SourceSafe project path without the "\$" & Yes \\ \hline
file & Filename to act & upon \\ \hline
If & no file is specified then act upon the project & No \\ \hline
username & SourceSafe username & Yes \\ \hline
password & SourceSafe password & No \\ \hline
localpath & Override the working directory and get to the specified path & No \\ \hline
soshome & The path to the SourceOffSite home directory & No \\ \hline
nocompress & true or false - disable compression & No \\ \hline
recursive & true or false - Only works with the CheckOutProject command & No \\ \hline
nocache & true or false - Only needed if SOSHOME is set as an environment variable & No \\ \hline
verbose & true or false - Status messages are displayed & No \\ \hline
comment & A comment to be applied to all files being checked in & No \\ \hline
\end{tabular}

{\bf Example}\hfil\break
\begin{verbatim}
<soscheckin username="build"
            password="build"
            file="foobar.txt"
            verbose="true"
            comment="comment abc"
            projectpath="/SourceRoot/project1"
            sosserverpath="server1:8888"
            vssserverpath="\\server2\vss\srcsafe.ini"/>
\end{verbatim}
Connects to a SourceOffsite server on server1:8888 with build,build as
the username \& password. The SourceSafe database resides on a
different box (server2) \& the VSS database is on a share called
"vss". Checks-in only the "foobar.txt" file adding a comment of
"comment abc". Extra status messages will be displayed on screen.

{\bf SOSCheckOut}\hfil\break

{\bf Description}\hfil\break

Task to perform CheckOut commands with SOS

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
soscmd & Directory which contains soscmd(.exe)
soscmd(.exe) must be in the path if this is not specified & No \\ \hline
vssserverpath & path to the srcsafe.ini - eg. ${\backslash}{\backslash}$server${\backslash}$vss${\backslash}$srcsafe.ini & Yes \\ \hline
sosserverpath & address and port of the SOS server - eg. 192.168.0.1:8888 & Yes \\ \hline
projectpath & SourceSafe project path without the "\$" & Yes \\ \hline
file & Filename to act upon If no file is specified then act upon the project & No \\ \hline
username & SourceSafe username & Yes \\ \hline
password & SourceSafe password & No \\ \hline
localpath & Override the working directory and get to the specified path & No \\ \hline
soshome & The path to the SourceOffSite home directory & No \\ \hline
nocompress & true or false - disable compression & No \\ \hline
recursive & true or false - Only works with the CheckOutProject command & No \\ \hline
nocache & true or false - Only needed if SOSHOME is set as an environment variable & No \\ \hline
verbose & true or false - Status messages are displayed & No \\ \hline
\end{tabular}

{\bf Example}\hfil\break
\begin{verbatim}
<soscheckout soscmd="/usr/local/bin"
             verbose="true"
             username="build"
             password="build"
             projectpath="/SourceRoot/project1"
             sosserverpath="192.168.10.6:8888"
             vssserverpath="\\server2\vss\srcsafe.ini"/>
\end{verbatim}
Connects to a SourceOffsite server on server1:8888 with build,build as
the username \& password. The SourceSafe database resides on a
different box (server2) \& the VSS database is on a share called
"vss". Checks-out "project1", Only the "project1" directory will be
locked as the recursive option was not set. Extra status messages will
be displayed on screen. The soscmd(.exe) file to be used resides in
/usr/local/bin.

\subsection{Splash}
\begin{verbatim}
by Les Hughes (leslie.hughes@rubus.com)
\end{verbatim}

\subsubsection{Description}

This task creates a splash screen. The splash screen is displayed for
the duration of the build and includes a handy progress bar as well.
Use in conjunction with the sound task to provide interest whilst
waiting for your builds to complete...

\subsubsection{Parameters}

\begin{tabular}{|l|p{8cm}|c|p{2cm}|} \hline
Attribute & Description & Required & Default\\ \hline
imageurl & A URL pointing to an image to display. & No & antlogo.gif from the classpath \\ \hline
showduration & Initial period to pause the build to show the splash in milliseconds. & No & 5000 ms \\ \hline
\end{tabular}

\subsubsection{Deprecated properties}

The following properties can be used to configure the proxy settings
to retrieve an image from behind a firewall. However, the settings
apply not just to this task, but to all following tasks. Therefore
they are now mostly deprecated in preference to the <setproxy> task,
that makes it clear to readers of the build exactly what is going on.
We say mostly as this task's support includes proxy authentication, so
you may still need to use its proxy attributes.

\begin{tabular}{|l|p{8cm}|c|c|} \hline
useproxy & Use a proxy to access imgurl. Note: Only tested on JDK 1.2.2 and above & No & None \\ \hline
proxy & IP or hostname of the proxy server & No & None \\ \hline
port & Proxy portnumber & No & None \\ \hline
user & User to authenticate to the proxy as. & No & None \\ \hline
password & Proxy password & No & None \\ \hline
\end{tabular}

\subsubsection{Examples}
\begin{verbatim}
<splash/>
\end{verbatim}
Splash images/ant\_logo\_large.gif from the classpath.
\begin{verbatim}
<splash imageurl="http://jakarta.apache.org/images/jakarta-logo.gif"
           useproxy="true"
           showduration="5000"/>
\end{verbatim}
Splashes the jakarta logo, for an initial period of 5 seconds.

\subsection{Starteam Tasks}

The tasks are:
\begin{itemize}
\item STCheckout
\item STCheckin
\item STLabel
\item STList
\item StarTeam (deprecated)
\end{itemize}

These tasks make use of functions from the StarTeam API. As a result
they are only available to licensed users of StarTeam. You must have
starteam-sdk.jar in your classpath to run these tasks. For more
information about the StarTeam API and how to license it, see the
StarBase web site.

\subsubsection{Common Parameters for All Starteam Tasks}

The following parameters, having to do with making the connection to a
StarTeam project, are common to all the following tasks except the
deprecated StarTeam task.

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
username & The username of the account used to log in to the StarTeam server. & yes \\ \hline
password & The password of the account used to log in to the StarTeam server. & yes \\ \hline
URL & A string of the form servername:portnum/project/view which enables user to set all of these elements in one string. & Either this ... \\ \hline
\begin{tabular}{l}
servername \\
serverport \\
projectname \\
viewname \\
\end{tabular} &
\begin{tabular}{p{7.5cm}} \hline
The name of the StarTeam server. 
The port number of the StarTeam server. \\ 
The name of the StarTeam project on which to operate. \\
The name of the view in the StarTeam project on which to operate. \\
\end{tabular} &
... or all four of these must be defined. \\ \hline
\end{tabular}

\subsubsection{STCheckout}

{\bf Description}\hfil\break

Checks out files from a StarTeam project.

The includes and excludes attributes function differently from other
tasks in Ant. Inclusion/exclusion by folder is NOT supported.

{\bf Parameters}\hfil\break

See also the required common StarTeam parameters.

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
rootstarteamfolder & The root of the subtree in the StarTeam repository from which to check out files. Defaults to the root folder of the view ('/'). & no \\ \hline
rootlocalfolder & The local folder which will be the root of the tree to which files are checked out. If this is not supplied, then the StarTeam "default folder" associated with rootstarteamfolder is used. & no \\ \hline
createworkingdirs & creates local folders even when the corresponding StarTeam folder is empty. Defaults to "true". & no \\ \hline
deleteuncontrolled & if true, any files NOT in StarTeam will be deleted. Defaults to "true". & no \\ \hline
includes & Only check out files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes. & no \\ \hline
excludes & Do not check out files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes. & no \\ \hline
label & Check out files as of this label. The label must exist in starteam or an exception will be thrown. If not specified, the most recent version of each file will be checked out. & no \\ \hline
recursive & Indicates if subfolders should be searched for files to check out. Defaults to "true". & no \\ \hline
forced & If true, checkouts will occur regardless of the status that StarTeam is maintaining for the file. If rootlocalfolder is set then this should be set "true" as otherwise the checkout will be based on statuses which do not relate to the target folder. Defaults to "false". & no \\ \hline

\begin{tabular}{l}
locked \\
unlocked \\
\end{tabular} &
\begin{tabular}{p{7.5cm}}
If true, file will be locked against changes by other users. 
If false (default) has no effect. \\ 
If true, file will be unlocked so that other users may change it.
This is a way to reverse changes that have not yet been checked in. 
If false (default) has no effect. \\
\end{tabular} &
Either or neither, but not both, may be true. \\ \hline
\end{tabular}

{\bf Examples}\hfil\break
\begin{verbatim}
  <stcheckout servername="STARTEAM" 
              serverport="49201"
              projectname="AProject" 
              viewname="AView"
              username="auser"
              password="secret"
              rootlocalfolder="C:\dev\buildtest\co"
              force="true"
  />
\end{verbatim}
The minimum necessary to check out files out from a StarTeam
server. This will check out all files in the AView view of the
AProject project to C:${\backslash}{\backslash}$dev\\buildtest\\co. Empty folders in StarTeam
will have local folders created for them and any non-StarTeam files
found in the tree will be deleted.
\begin{verbatim}
  <stcheckout URL="STARTEAM:49201/Aproject/AView" 
              username="auser"
              password="secret"
              rootlocalfolder="C:\dev\buildtest\co"
              forced="true"
  />
\end{verbatim}
And this is a simpler way of accomplishing the same thing as the
previous example, using the URL attribute.
\begin{verbatim}
  <stcheckout URL="STARTEAM:49201/Aproject/AView" 
              username="auser"
              password="secret"
              rootlocalfolder="C:\dev\buildtest\co"
              rootstarteamfolder="\Dev"
              excludes="*.bak *.old"
              label="v2.6.001"
              forced="true"
  />
\end{verbatim}
This will check out all files from the Dev folder and below that do
not end in .bak or .old with the label v2.6.001.
\begin{verbatim}
  <stcheckout URL="STARTEAM:49201/Aproject/AView"
              username="auser"
              password="secret"
              rootlocalfolder="C:\dev\buildtest\co"
              includes="*.htm,*.html"
              excludes="index.*"
              forced="true"
  />
\end{verbatim}
This is an example of overlapping includes and excludes
attributes. Because excludes takes precedence over includes, files
named index.html will not be checked out by this command.
\begin{verbatim}
  <stcheckout URL="STARTEAM:49201/Aproject/AView"
              username="auser"
              password="secret"
              rootlocalfolder="C:\dev\buildtest\co"
              includes="*.htm,*.html"
              excludes="index.*"
              forced="true"
              recursive="false"
  />
\end{verbatim}
This example is like the previous one, but will only check out files
in C:${\backslash}{\backslash}$dev${\backslash}{\backslash}$buildtest${\backslash}{\backslash}$co, 
because of the turning off of the recursive
attribute.
\begin{verbatim}
  <stcheckout URL="STARTEAM:49201/Aproject/AView"
              username="auser"
              password="secret"
              rootstarteamfolder="src/java"
              rootlocalfolder="C:\dev\buildtest\co"
              forced="true"
  />



  <stcheckout URL="STARTEAM:49201/Aproject/AView"
              username="auser"
              password="secret"
              rootstarteamfolder="src/java"
  />



 <stcheckout URL="STARTEAM:49201/Aproject/AView"
             username="auser"
             password="secret"
             rootstarteamfolder="src/java"
             rootlocalfolder="C:\dev\buildtest\co\src\java"
             forced="true"
  />
\end{verbatim}
In the preceding three examples, assuming that the AProject project
has a default folder of "C:${\backslash}{\backslash}$work${\backslash}{\backslash}$AProject", the first example will
check out the tree of files rooted in the src/java folder of the AView
view of the AProject in the StarTeam repository to a local tree rooted
at C:${\backslash}{\backslash}$dev${\backslash}{\backslash}$buildtest${\backslash}{\backslash}$co, 
the second to a tree rooted at
C:${\backslash}{\backslash}$work${\backslash}{\backslash}$AProject${\backslash}{\backslash}$src${\backslash}{\backslash}$java 
(since no rootlocalfolder is specified) and
the third to a tree rooted 
at C:${\backslash}{\backslash}$dev${\backslash}{\backslash}$buildtest${\backslash}{\backslash}$co${\backslash}{\backslash}$src${\backslash}{\backslash}$java. 
Note also, that since the second example does not set "forced" true, only those
files which the repository considers out-of-date will be checked out.

\subsubsection{STCheckin}

{\bf Description}\hfil\break

Checks files into a StarTeam project. Optionally adds files and in the
local tree that are not managed by the repository to its control.

The includes and excludes attributes function differently from other
tasks in Ant. Inclusion/exclusion by folder is NOT supported.

Parameters

See also the required common StarTeam parameters.

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
rootstarteamfolder & The root of the subtree in the StarTeam repository into which to files will be checked. Defaults to the root folder of the view ('/'). & no \\ \hline
rootlocalfolder & The local folder which will be the root of the tree to which files are checked out. If this is not supplied, then the StarTeam "default folder" associated with rootstarteamfolder is used. & no \\ \hline
comment & Checkin comment to be saved with the file. & no \\ \hline
adduncontrolled & if true, any files or folders NOT in StarTeam will be added to the repository. Defaults to "false". & no \\ \hline
includes & Only check in files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes. & no \\ \hline
excludes & Do not check in files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes. & no \\ \hline
recursive & Indicates if subfolders should be searched for files to check in. Defaults to "false". & no \\ \hline
forced & If true, checkins will occur regardless of the status that StarTeam is maintaining for the file. If rootlocalfolder is set then this should be set "true" as otherwise the checkin will be based on statuses which do not relate to the target folder. Defaults to "false". & no \\ \hline
unlocked & If true, file will be unlocked so that other users may change it. If false (default) lock status will not change. & no \\ \hline
\end{tabular}

{\bf Examples}\hfil\break
\begin{verbatim}
  <stcheckin servername="STARTEAM" 
             serverport="49201"
             projectname="AProject" 
             viewname="AView"
             username="auser"
             password="secret"
             rootlocalfolder="C:\dev\buildtest\co"
             forced="true"
  />
\end{verbatim}
The minimum necessary to check files into a StarTeam server. This will
check all files on the local tree rooted at C:${\backslash}{\backslash}$dev${\backslash}{\backslash}$buildtest${\backslash}{\backslash}$co into
the AView view of the AProject project in the repository. For files
and folders in the local tree but not in starteam, nothing will be
done. Since the forced attribute is set, the files which are checked
in will be checked in without regard to what the StarTeam repository
considers their status to be. This is a reasonable choice of
attributes since StarTeam's status for a file is calculated based on
the local file in the StarTeam default directory, not on the directory
we are actually working with.
\begin{verbatim}
  <stcheckin URL="STARTEAM:49201/Aproject/AView" 
             username="auser"
             password="secret"
             rootlocalfolder="C:\dev\buildtest\co"
             forced="true"
  />
\end{verbatim}
And this is a simpler way of giving the same commands as the command
above using the URL shortcut.
\begin{verbatim}
  <stcheckin URL="STARTEAM:49201/Aproject/AView" 
             username="auser"
             password="secret"
             rootlocalfolder="C:\dev\buildtest\co"
             rootstarteamfolder="\Dev"
             excludes="*.bak *.old"
             forced="true"
  />
\end{verbatim}
This will check all files in to the Dev folder and below that do not
end in .bak or .old from the tree rooted 
at"C:${\backslash}{\backslash}$dev${\backslash}{\backslash}$buildtest${\backslash}{\backslash}$co" .
\begin{verbatim}
  <stcheckin URL="STARTEAM:49201/Aproject/AView"
             username="auser"
             password="secret"
             rootlocalfolder="C:\dev\buildtest\co"
             includes="*.htm,*.html"
             excludes="index.*"
             forced="true"
  />
\end{verbatim}
This is an example of overlapping includes and excludes
attributes. Because excludes takes precedence over includes, files
named index.html will not be checked in by this command.
\begin{verbatim}
  <stcheckin URL="STARTEAM:49201/Aproject/AView"
             username="auser"
             password="secret"
             rootlocalfolder="C:\dev\buildtest\co"
             rootstarteamfolder="src/java"
             includes="*.htm,*.html"
             excludes="index.*"
             forced="true"
             recursive="false"
  />
\end{verbatim}
This example is like the previous one, but will only check in files
from C:${\backslash}{\backslash}$dev${\backslash}{\backslash}$buildtest${\backslash}{\backslash}$, 
because of the turning off of the recursive
attribute.
\begin{verbatim}
  <stcheckin URL="STARTEAM:49201/Aproject/AView"
             username="auser"
             password="secret"
             rootlocalfolder="C:\dev\buildtest\co"
             rootstarteamfolder="src/java"
             includes="version.txt"
             forced="true"
             recursive="false"
  />
\end{verbatim}
This example is like the previous one, but will only check only in one
file, C:${\backslash}{\backslash}$dev${\backslash}{\backslash}$buildtest${\backslash}{\backslash}$\\version.txt to the StarTeam folder src/java.
\begin{verbatim}
  <stcheckin URL="STARTEAM:49201/Aproject/AView"
             username="auser"
             password="secret"
             rootlocalfolder="C:\dev\buildtest\co"
             rootstarteamfolder="src/java"
             includes="version.java"
             forced="true"
             recursive="false"
             addUncontrolled="true"
             comment="Fix Bug #667"
  />
\end{verbatim}
This example is like the previous one, but will only check only in one
file, C:${\backslash}{\backslash}$dev${\backslash}{\backslash}$buildtest${\backslash}{\backslash}$\\version.java to the StarTeam folder
src/java. Because the addUncontrolled attribute has been set, if
StarTeam does not already control this file in this location, it will
be added to the repository. Also, it will write a comment to the
repository for this version of the file.
\begin{verbatim}
  <stcheckin URL="STARTEAM:49201/Aproject/AView"
             username="auser"
             password="secret"
             rootstarteamfolder="src/java"
             rootlocalfolder="C:\dev\buildtest\co"
             forced="true"
  />



  <stcheckin URL="STARTEAM:49201/Aproject/AView"
             username="auser"
             password="secret"
             rootstarteamfolder="src/java"
  />



 <stcheckin URL="STARTEAM:49201/Aproject/AView"
             username="auser"
             password="secret"
             rootstarteamfolder="src/java"
             rootlocalfolder="C:\dev\buildtest\co\src\java"
             forced="true"
  />
\end{verbatim}
In the preceding three examples, assuming that the AProject project
has a default folder of C:${\backslash}{\backslash}$work${\backslash}{\backslash}$buildtest${\backslash}{\backslash}$\\AProject, the first
example will check in files from a tree rooted at C:${\backslash}{\backslash}$dev${\backslash}{\backslash}$buildtest${\backslash}{\backslash}$,
the second from a tree rooted at
C:${\backslash}{\backslash}$work${\backslash}{\backslash}$buildtest${\backslash}{\backslash}$\\AProject\\src\\java, and the third from a tree
rooted at C:${\backslash}{\backslash}$dev${\backslash}{\backslash}$buildtest${\backslash}{\backslash}$\\src\\java all to a tree rooted at
src/java

\subsubsection{STLabel}

{\bf Description}\hfil\break

Creates a view label in StarTeam at the specified view. The label will
be classified by StarTeam as a "build label". This task will fail if
there already exexists in viewname a label with the same name as the
label parameter.

{\bf Parameters}\hfil\break

See also the required common StarTeam parameters.

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
label & The name to be given to the label & yes \\ \hline
lastbuild & The timestamp of the build that will be stored with the label. Must be formatted yyyyMMddHHmmss & yes \\ \hline
description & A description of the label to be stored in the StarTeam project. & no \\ \hline
\end{tabular}

{\bf Examples}\hfil\break

This example shows the use of this tag. It will create a label named
Version 6.2 with "Thorough description" as its description.
\begin{verbatim}
  <tstamp>
    <format property="nowstamp" pattern="yyyyMMddHHmmss" locale="en"/>
  </tstamp>  
  <stlabel URL="STARTEAM:49201/Aproject/AView"
           username="auser"
           password="secret"
           label="Version 6.2"
           lastbuild="${nowstamp}"
           description="Thorough description"
  />
\end{verbatim}

\subsubsection{STList}

{\bf Description}\hfil\break

Produces a listing of the contents of the StarTeam repository at the
specified view and StarTeamFolder. The listing will contain the name
of the user, if any, who has the file locked, the size of the file,
its lastModifiedDate in the repository, and the name of the
file. Unless the rootLocalFolder is specified, listing will also show
the status of the local file in the default local directory relative
to the repository.

{\bf Parameters}\hfil\break

See also the required common StarTeam parameters.

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
rootstarteamfolder & The root of the subtree in the StarTeam repository to be listed. Defaults to the root folder of the view ('/'). & no \\ \hline
rootlocalfolder & The local folder which will be the root of the tree to which files are compared. If this is not supplied, then the StarTeam "default folder" associated with rootstarteamfolder is used and a status field will appear in the listing. Otherwise, the status field will not appear. & no \\ \hline
includes & Only list files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes. & no \\ \hline
excludes & Do not list files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes. & no \\ \hline
label & List files, dates, and statuses as of this label. The label must exist in starteam or an exception will be thrown. If not specified, the most recent version of each file will be listed. & no \\ \hline
recursive & Indicates if subfolders should be searched for files to list. Defaults to "true". & no \\ \hline
\end{tabular}

{\bf Examples}\hfil\break
\begin{verbatim}
  <stlist url="WASHINGTON:49201/build"
          username="auser"
          password="secret"
 />
\end{verbatim}
The above command might produce the following listing:
\begin{verbatim}
   [stlist] Folder: Build (Default folder: C:/work/build)
   [stlist] Folder: dev (Default folder: C:/work/build/dev)
   [stlist] Out of date  Sue Developer        1/1/02 7:25:47 PM CST     4368 build.xml
   [stlist] Missing      George Hacker        1/1/02 7:25:49 PM CST       36 Test01.properties
   [stlist] Current                           1/1/02 7:25:49 PM CST     4368 build2.xml
   [stlist] Folder: test (Default folder C:/work/build/dev/test)
   [stlist] Missing                           1/1/02 7:25:50 PM CST     4368 build2.xml
\end{verbatim}
while adding a rootlocalfolder and an excludes param ...
\begin{verbatim}
  <stlist url="WASHINGTON:49201/build"
          username="auser"
          password="secret"
          rootlocalfolder="srcdir2"
          excludes="*.properties"
 />
\end{verbatim}
might produce this listing. The status is missing because we are not
going against the default folder.
\begin{verbatim}
   [stlist] overriding local folder to srcdir2
   [stlist] Folder: Build (Local folder: srcdir2)
   [stlist] Folder: dev (Local folder: srcdir2/dev)
   [stlist] Sue Developer        1/1/02 7:25:47 PM CST     4368 build.xml
   [stlist]                      1/1/02 7:25:49 PM CST     4368 build2.xml
   [stlist] Folder: test (Local folder: srcdir2/dev/test)
   [stlist]                      1/1/02 7:25:50 PM CST     4368 build2.xml
\end{verbatim}

\subsubsection{Starteam}

{\em Deprecated}

This task has been deprecated. Use the STCheckout task instead.

{\bf Description}\hfil\break

Checks out files from a StarTeam project.

The includes and excludes attributes function differently from other
tasks in Ant. Multiple patterns must be separated by spaces, not
commas. See the examples for more information.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
username & The username of the account used to log in to the StarTeam server. & yes \\ \hline
password & The password of the account used to log in to the StarTeam server. & yes \\ \hline
servername & The name of the StarTeam server. & yes \\ \hline
serverport & The port number of the StarTeam server. & yes \\ \hline
projectname & The name of the StarTeam project. & yes \\ \hline
viewname & The name of the view in the StarTeam project. & yes \\ \hline
targetfolder & The folder to which files are checked out. What this precisely means is determined by the targetFolderAbsolute param. & yes \\ \hline
targetFolderAbsolute & Determines how targetfolder is interpreted, that is, whether the StarTeam "default folder" for the project is factored in (false) or whether targetFolder is a complete mapping to foldername (true). If "true", the target tree will be rooted at targetfolder+"default folder". If false, the target tree will be rooted at targetfolder. Defaults to "false". & no \\ \hline
foldername & The subfolder in the project from which to check out files. & no \\ \hline
force & Overwrite existing folders if this is set to "true". Defaults to "false". & no \\ \hline
recursion & Indicates if subfolders should be searched for files to check out. Defaults to "true". & no \\ \hline
verbose & Provides progress information. Defaults to "false". & no \\ \hline
includes & Only check out files that match at least one of the patterns in this list. Patterns must be separated by spaces. Patterns in excludes take precedence over patterns in includes. & no \\ \hline
excludes & Do not check out files that match at least one of the patterns in this list. Patterns must be separated by spaces. Patterns in excludes take precedence over patterns in includes. & no \\ \hline
\end{tabular}

{\bf Examples}\hfil\break
\begin{verbatim}
  <starteam servername="STARTEAM" 
            serverport="49201"
            projectname="AProject" 
            viewname="AView"
            username="auser"
            password="secret"
            targetfolder="C:\dev\buildtest\co"
  />
\end{verbatim}
The minimum necessary to check out files out from a StarTeam
server. This will check out all files in the AView view of the
AProject project to C:${\backslash}{\backslash}$dev${\backslash}{\backslash}$buildtest${\backslash}{\backslash}$.
\begin{verbatim}
  <starteam servername="STARTEAM" 
            serverport="49201"
            projectname="AProject" 
            viewname="AView"
            username="auser"
            password="secret"
            targetfolder="C:\dev\buildtest\co"
            foldername="\Dev"
            excludes="*.bak *.old"
            force="true"
  />
\end{verbatim}
This will checkout all files from the Dev folder and below that do not
end in .bak or .old. The force flag will cause any existing files to
be overwritten by the version in StarTeam.
\begin{verbatim}
  <starteam servername="STARTEAM" 
            serverport="49201"
            projectname="AProject" 
            viewname="AView"
            username="auser"
            password="secret"
            targetfolder="C:\dev\buildtest\co"
            includes="*.htm *.html"
            excludes="index.*"
  />
\end{verbatim}
This is an example of overlapping includes and excludes
attributes. Because excludes takes precedence over includes, files
named index.html will not be checked out by this command.
\begin{verbatim}
 <starteam servername="STARTEAM" 
            serverport="49201"
            projectname="AProject" 
            foldername="src/java"
            viewname="AView"
            username="auser"
            password="secret"
            targetfolder="C:\dev\buildtest\co"
            targetfolderabsolute="true"
  />



 <starteam servername="STARTEAM" 
            serverport="49201"
            projectname="AProject" 
            foldername="src/java"
            viewname="AView"
            username="auser"
            password="secret"
            targetfolder="C:\dev\buildtest\co"
            targetfolderabsolute ="false"
  />



 <starteam servername="STARTEAM" 
            serverport="49201"
            projectname="AProject" 
            foldername="src/java"
            viewname="AView"
            username="auser"
            password="secret"
            targetfolder="C:\dev\buildtest\co\src\java"
            targetfolderabsolute="true"
  />
\end{verbatim}
In the preceding three examples, assuming that the AProject project
has a default folder of "AProject", the first example will check the
files located in starteam under src/java out to a tree rooted at
C:${\backslash}{\backslash}$dev${\backslash}{\backslash}$buildtest${\backslash}{\backslash}$, the second to a tree rooted at
C:${\backslash}{\backslash}$dev${\backslash}{\backslash}$buildtest${\backslash}{\backslash}$\\AProject\\src\\java and the third to a tree rooted
at C:${\backslash}{\backslash}$dev${\backslash}{\backslash}$buildtest${\backslash}{\backslash}$\\src\\java.

\subsection{Stylebook}

{\bf Description}\hfil\break

This executes the apache Stylebook documentation generator. Unlike the
commandline version of this tool, all three arguments are required to
run stylebook.

Note: This task depends on external libraries not included in the Ant
distribution. See Library Dependencies for more information.

Being extended from <Java>, all the parent's attributes and options
are available. Do not set any apart from the classpath as they are not
guaranteed to be there in future.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
book & the book xml file that the documentation generation starts from & Yes \\ \hline
skindirectory & the directory that contains the stylebook skin & Yes \\ \hline
targetdirectory & the destination directory where the documentation is generated & Yes \\ \hline
\end{tabular}

The user can also specify the nested <classpath> element which defines
classpath in which the task is executed.

{\bf Examples}\hfil\break
\begin{verbatim}
<stylebook targetdirectory="build/docs" 
           book="src/xdocs/book.xml" 
           skindirectory="src/skins/myskin"/>
\end{verbatim}
The above will generate documentation in build/docs starting from the
book src/xdocs/book.xml and using the skin located in directory
src/skins/myskin.

\subsection{Telnet}

{\bf Description}\hfil\break

Task to automate a remote telnet session. The task uses nested <read>
to indicate strings to wait for, and <write> tags to specify text to
send.

If you do specify a userid and password, the system will assume a
common unix prompt to wait on. This behavior can be easily
over-ridden.

Note: This task depends on external libraries not included in the Ant
distribution. See Library Dependencies for more information.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
userid & the login id to use on the telnet server. & Only if password is specified \\ \hline
password & the login password to use on the telnet server. & Only if userid is specified \\ \hline
server & the address of the remote telnet server. & Yes \\ \hline
port & the port number of the remote telnet server. Defaults to port 23. & No \\ \hline
initialCR & send a cr after connecting ("yes"). Defaults to "no". & No \\ \hline
timeout & set a default timeout to wait for a response. Specified in seconds. Default is no timeout. & No \\ \hline
\end{tabular}

{\bf Nested Elements}\hfil\break

The commands to send to the server, and responses to wait for, are
described as nested elements.

{\bf read}\hfil\break

declare (as a text child of this element) a string to wait for. The
element supports the timeout attribute, which overrides any timeout
specified for the task as a whole. It also has a string attribute,
which is an alternative to specifying the string as a text element.

Always declare an opening and closing <read> element to ensure that
statements are not sent before the connection is ready, and that the
connection is not broken before the final command has completed.

{\bf write}\hfil\break

describes the text to send to the server. The echo boolean attribute
controls whether the string is echoed to the local log; this is "true"
by default

{\bf Examples}\hfil\break

A simple example of connecting to a server and running a command. This
assumes a prompt of "ogin:" for the userid, and a prompt of "assword:"
for the password.
\begin{verbatim}
<telnet userid="bob" password="badpass" server="localhost">
   <read>/home/bob</read>
   <write>ls</write>
   <read string="/home/bob"/>
</telnet>
\end{verbatim}
This task can be rewritten as:
\begin{verbatim}
<telnet server="localhost">
   <read>ogin:</read>
   <write>bob</write>
   <read>assword:</read>
   <write>badpass</write>
   <read>/home/bob</read>
   <write>ls</write>
   <read>/home/bob</read>
</telnet>
\end{verbatim}
A timeout can be specified at the <telnet> level or at the <read>
level. This will connect, issue a sleep command that is suppressed
from displaying and wait 10 seconds before quitting.
\begin{verbatim}
<telnet userid="bob" password="badpass" server="localhost" timeout="20">
   <read>/home/bob</read>
   <write echo="false">sleep 15</write>
   <read timeout="10">/home/bob</read>
</telnet>
\end{verbatim}
The task can be used with other ports as well:
\begin{verbatim}
<telnet port="80" server="localhost" timeout="20">
   <read/>
   <write>GET / http/0.9</write>
   <write/>
   <read timeout="10">&lt;/HTML&gt;</read>
</telnet>
\end{verbatim}
To use this task against the WinNT telnet service, you need to
configure the service to use classic authentication rather than NTLM
negotiated authentication. This can be done in the Telnet Server Admin
app: select "display/change registry settings", then "NTLM", then set
the value of NTLM to 1.

\subsection{Test}

{\bf Description}\hfil\break

This is a primitive task to execute a unit test in the org.apache.testlet framework.

This task is deprectated as the Testlet framework has been abandoned
in favor of JUnit by the Avalon community.

Note: This task depends on external libraries not included in the Ant
distribution. See Library Dependencies for more information.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
showSuccess & a boolean value indicating whether tests should display a message on success & No \\ \hline
showBanner & a boolean value indicating whether a banner should be displayed when starting testlet engine & No \\ \hline
forceShowTrace & a boolean indicating that a stack trace is displayed on any failure & No \\ \hline
showTrace & a boolean indicating that a stack trace is displayed on error (but not normal failure) & No \\ \hline
\end{tabular}

The user can also specify the nested <classpath> element which defines
classpath in which the task is executed. The user also specifies a
subelement per testlet executed which has content that specifies
tasklet classname.

{\bf Examples}\hfil\break
\begin{verbatim}
<test showSuccess="false" showBanner="false" showTrace="true" forceShowTrace="true">
   <classpath refid="test.classpath"/>
   <testlet>org.foo.MyTestlet</testlet>
   <testlet>org.foo.MyOtherTestlet</testlet>
</test>
\end{verbatim}
The above will run the testlets org.foo.MyTestlet and org.foo.MyOtherTestlet

\subsection{Translate}

{\bf Description}\hfil\break

Identifies keys in files delimited by special tokens and translates
them with values read from resource bundles.

A resource bundle contains locale-specific key-value pairs. A resource
bundle is a hierarchical set of property files. A bundle name makes up
its base family name. Each file that makes up this bundle has this
name plus its locale. For example, if the resource bundle name is
MyResources, the file that contains German text will take the name
MyResources\_de. In addition to language, country and variant are also
used to form the files in the bundle.

The resource bundle lookup searches for resource files with various
suffixes on the basis of (1) the desired locale and (2) the default
locale (basebundlename), in the following order from lower-level (more
specific) to parent-level (less specific):
\begin{verbatim}
basebundlename + "_" + language1 + "_" + country1 + "_" + variant1
basebundlename + "_" + language1 + "_" + country1
basebundlename + "_" + language1
basebundlename
basebundlename + "_" + language2 + "_" + country2 + "_" + variant2
basebundlename + "_" + language2 + "_" + country2
basebundlename + "_" + language2
\end{verbatim}
The file names generated thus are appended with the string
".properties" to make up the file names that are to be used.

File encoding is supported. The encoding scheme of the source files,
destination files and the bundle files can be specified. Destination
files can be exlicitly overwritten using the forceoverwrite
attribute. If forceoverwrite is false, the destination file is
overwritten only if either the source file or any of the files that
make up the bundle have been modified after the destination file was
last modified.

FileSets are used to select files to translate.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
todir & Destination directory where destination files are to be created. & Yes \\ \hline
starttoken & The starting token to identify keys. & Yes \\ \hline
endtoken & The ending token to identify keys. & Yes \\ \hline
bundle & Family name of resource bundle. & Yes \\ \hline
bundlelanguage & Locale specific language of resource bundle. Defaults to default locale's language. & No \\ \hline
bundlecountry & Locale specific country of resource bundle. Defaults to default locale's country. & No \\ \hline
bundlevariant & Locale specific variant of resource bundle. Defaults to the default variant of the country and language being used. & No \\ \hline
srcencoding & Source file encoding scheme. Defaults to system default file encoding. & No \\ \hline
destencoding & Destination file encoding scheme. Defaults to source file encoding. & No \\ \hline
bundleencoding & Resource Bundle file encoding scheme. Defaults to source file encoding. & No \\ \hline
forceoverwrite & Overwrite existing files even if the destination files are newer. Defaults to "no". & No \\ \hline
\end{tabular}

{\bf Parameters specified as nested elements}\hfil\break

{\bf fileset}\hfil\break

FileSets are used to select files that contain keys for which value
translated files are to be generated.

{\bf Examples}\hfil\break

Translate source file encoded in english into its japanese equivalent
using a resource bundle encoded in japanese.
\begin{verbatim}
  <translate toDir="$(dest.dir}/ja"
        starttoken="#"
        endtoken="#"
        bundle="resource/BaseResource"
        bundlelanguage="ja"
        forceoverwrite="yes"
        srcencoding="ISO8859_1"
        destencoding="SJIS"
        bundleencoding="SJIS">
        <fileset dir="${src.dir}">
            <include name="**/*.jsp"/>
        </fileset>
  </translate>
\end{verbatim}

\subsection{Visual Age for Java Tasks}

At the moment there are three tasks which help integrating the VAJ
repository contents into an external build process:

\begin{enumerate}
\item VAJLoad\hfil\break
loads specified versions into the workspace

\item VAJExport\hfil\break
exports specified packages into the file system

\item VAJImport\hfil\break
imports specified files into the workspace
\end{enumerate}

These tasks are described in detail below.

\subsubsection{VAJLoad}

{\bf Description:}\hfil\break

Loads a specified VAJ project version into the workspace.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
remote &
name and port of a remote tool server. (format: {\tt <servername>:<port no>}).
If this attribute is set, the tasks will be executed on the specified tool server. 
& no \\ \hline
\end{tabular}

{\bf Parameters specified as nested elements}\hfil\break

{\bf vajproject}\hfil\break

Attribute Description Required
name name of the VAJ project to load into the workspace yes
version name of the requested version yes

{\bf Example}\hfil\break
\begin{verbatim}
<vajload remote="localhost:32767">
    <vajproject name="My Testcases" version="1.7beta"/>
    <vajproject name="JUnit" version="3.2"/>
</vajload>
\end{verbatim}

\subsubsection{VAJExport}

{\bf Description:}\hfil\break

Exports Java source files, class files and/or resources from the
workspace to the file system. Exports can be specified by giving the
VAJ project name and package name(s). This works very similar to
FileSets.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
destdir & location to store the exported files & yes \\ \hline
exportSources & export source files (default: "yes") & no \\ \hline
exportResources & export resource files (default: "yes") & no \\ \hline
exportClasses & export class files (default: "no") & no \\ \hline
exportDebugInfo & include debug info in exported class files (default: "no") & no \\ \hline
defaultexcludes &
use default excludes when exporting (default: "yes").
Default excludes are: IBM*/**, Java class libraries/**, Sun class libraries*/**, JSP Page Compile Generated Code/**, VisualAge*/** 
& no \\ \hline
overwrite & overwrite existing files (default: "yes") & no \\ \hline
remote &
name and port of a remote tool server. (format: {\tt <servername>:<port no>}).
If this attribute is set, the tasks will be executed on the specified tool server. 
& no \\ \hline
\end{tabular}

{\bf Parameters specified as nested elements}\hfil\break

{\bf include}\hfil\break

specifies the packages to include into the export

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
name & name of the VAJ project and package to export.
The first element of the name must be the project name,
then the package name elements separated by '/'. & yes \\ \hline
\end{tabular}

{\bf exclude}\hfil\break

specifies the packages to exclude from the export

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
name & name of the VAJ project/package not to export & yes \\ \hline
\end{tabular}
{\bf Example}\hfil\break
\begin{verbatim}
<vajexport destdir="${src.dir}" exportResources="no">
    <include name="MyProject/**"/>
    <exclude name="MyProject/test/**"/>
</vajexport>
\end{verbatim}
This example exports all packages in the VAJ project 'MyProject',
except packages starting with 'test'.

{\bf Default Excludes}\hfil\break

The default excludes are:
\begin{verbatim}
   IBM*/**
    Java class libraries/**
    Sun class libraries*/**
    JSP Page Compile Generated Code/**
    VisualAge*/**
\end{verbatim}

\subsubsection{VAJImport}

{\bf Description:}\hfil\break

Imports Java source files, class files and/or resources from the file
system into VAJ. These imports can be specified with a fileset.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
vajProject & imported files are added to this VAJ project & yes \\ \hline
importSources & import source files (default: "yes") & no \\ \hline
importResources & import resource files (default: "yes") & no \\ \hline
importClasses & import class files (default: "no") & no \\ \hline
remote &
name and port of a remote tool server. (format: <servername>:<port no>).
If this attribute is set, the tasks will be executed on the specified tool server. 
& no \\ \hline
\end{tabular}

{\bf Parameters specified as nested elements}\hfil\break

{\bf fileset}\hfil\break

A FileSet specifies the files to import.

{\bf Example}\hfil\break
\begin{verbatim}
<vajimport project="Test" importClasses="true">
    <fileset dir="${import.dir}">
        <include name="com/sample/**/*.class"/>
        <exclude name="com/sample/test/**"/>
    </fileset>
</vajimport>
\end{verbatim}
This example imports all class files in the directory
\$\{import.dir\}/com/sample excluding those in the subdirectory test

\subsubsection{The Plugin}

The tasks are usable within VAJ by running the
org.apache.tools.ant.Main class, but this is quite inconvenient.
Therefore a small GUI is provided which allows selecting a build file
and executing its targets. This Plugin is accessible from the VAJ
Tools menu (see Usage).

{\bf Installation}\hfil\break

At the moment the installation has it's rough edges. If something
described below doesn't work for You, it's probably not Your fault but
incomplete/wrong instructions. In this case, please contact one of the
authors.

We assume C:${\backslash}{\backslash}$IBMVJava as VAJ install
directory. If You have installed it elsewhere, adapt the paths below.

{\bf Plugin}\hfil\break
\begin{itemize}
\item install the Visual Age IDE Tools 
(via {\tt File->Quick Start->Add feature->'IBM IDE Utility class libraries'}
\item import an appropriate XML parser to VAJ (we use Xerces 1.2.0 and are happy with it). Unfortunately the XML parser delivered with VAJ (in the project 'IBM XML Parser for Java') doesn't work with Ant. You have to remove that project (temporarily) from the workspace before importing another XML implementation.
\item import the Ant sources and resources into VAJ.
\item Create the directory C:${\backslash}{\backslash}$IBMVJava${\backslash}{\backslash}$ide${\backslash}{\backslash}$tools${\backslash}{\backslash}$org-apache-tools-ant.
\item export the Ant and XML parser class and resource files into this directory. Be sure to select class files and resources. Sources don't have to be exported. Some optional tasks have errors and can't be exported when You don't have the necessary packages in Your workspace (e.g. junit task, ejbc task). If You need this tasks either import these packages into VAJ, too, or copy the .class files directly from the binary distribution.
\item copy default.ini (in ant${\backslash}{\backslash}$src\...${\backslash}{\backslash}$taskdefs${\backslash}{\backslash}$optional${\backslash}{\backslash}$ide) to C:${\backslash}{\backslash}$IBMVJava${\backslash}{\backslash}$ide${\backslash}{\backslash}$tools${\backslash}{\backslash}$org-apache-tools-ant${\backslash}{\backslash}$default.ini.
\item if you want to access this help from the Workbench, create the directory C:${\backslash}{\backslash}$IBMVJava${\backslash}{\backslash}$ide${\backslash}{\backslash}$tools${\backslash}{\backslash}$org-apache-tools-ant${\backslash}{\backslash}$doc and copy the files VAJAntTool.html, toolmenu.gif and anttool1.gif to it.
\item VAJ has to be restarted to recognize the new tool.
\item Now if You open the context menu of a project, You should see the entry 'Ant Build' in the Tools submenu (see Usage).
\item Make sure the tool works as expected. Now You can remove Ant and the imported XML parser from Your workspace (and optionally add the IBM parser again). 
\end{itemize}

{\bf Servlets for Remote Tool Access}\hfil\break

\begin{itemize}
\item For a good introduction into the VAJ Remote Tool Access see the great introduction 
from Glenn McAllister at\hfil\break
{\tt http://www7.software.ibm.com/vad.nsf/Data/Document4366}. 
It is highly recommended to read this article before doing the installation (to understand what you do :-) ).
\item insert the following lines into C:${\backslash}{\backslash}$IBMVJava${\backslash}{\backslash}$ide${\backslash}{\backslash}$tools${\backslash}{\backslash}$com-ibm-ivj-toolserver${\backslash}{\backslash}$servlets${\backslash}{\backslash}$servlet.properties. Typically this file is empty. If not, be careful not to delete the other lines.
\begin{verbatim}
servlet.vajload.code=org.apache.tools.ant.taskdefs.optional.ide.VAJLoadServlet
servlet.vajexport.code=org.apache.tools.ant.taskdefs.optional.ide.VAJExportServlet
servlet.vajimport.code=org.apache.tools.ant.taskdefs.optional.ide.VAJImportServletName
\end{verbatim}

\item export the following classes from the package org.apache.tools.ant 
to C:${\backslash}{\backslash}$IBMVJava${\backslash}{\backslash}$ide${\backslash}{\backslash}$tools${\backslash}{\backslash}$com-ibm-ivj-toolserver${\backslash}{\backslash}$servlets${\backslash}{\backslash}$:
\begin{verbatim}
      BuildException
      DirectoryScanner
      FileScanner
      Location
\end{verbatim}

\item export the following classes from the package 
org.apache.tools.ant.taksdefs.optional.ide 
to C:${\backslash}{\backslash}$IBMVJava${\backslash}{\backslash}$ide${\backslash}{\backslash}$tools${\backslash}{\backslash}$com-ibm-ivj-toolserver${\backslash}{\backslash}$servlets${\backslash}{\backslash}$:
\begin{verbatim}
      VAJUtil
      VAJExportServlet
      VAJImportServlet
      VAJLoadServlet
      VAJLocalUtil
      VAJProjectDescription
      VAJToolsServlet
      VAJWorkspaceScanner
\end{verbatim}
\item configure the Remote Access (via {\tt Window->Options...}, then choose
  'Remote Access To Tool API') as shown in the following picture:

\vskip 0.5cm
\indent\hbox{\hskip -3.0cm}\vbox{\vskip -40mm
\vbox{\vskip 3.3cm
\includegraphics{remacc.ps}
}}

\end{itemize}

Now you should be able to execute VAJ Tasks from the command line.

{\bf Usage}\hfil\break

{\bf Plugin}\hfil\break

When the tool is installed correctly and your Ant build file is
configured, it is really easy to use.

Go to your Workbench, select the project you want to deploy and open
its context menu. In the submenu Tools you should find the new entry
Ant Build. Klick it to start the tool!

\vskip 0.5cm
\indent\hbox{\hskip -1.0cm}\vbox{\vskip -40mm
\vbox{\vskip 4.3cm
\includegraphics{toolmenu.ps}
}}

After a short time this frame should pop up:

\vskip 0.5cm
\indent\hbox{\hskip -1.0cm}\vbox{\vskip -40mm
\vbox{\vskip 4.3cm
\includegraphics{anttool1.ps}
}}

This frame contains the following elements:
\begin{itemize}
\item A menubar with some options described later
\item The name of your selected VAJ project
\item An entry field for the Ant XML buildfile with a browse [...] button. The full qualified filename, including the directory is needed here.
\item A list with tasks specified in the buildfile. Until your first save of the build info (described later), this list will be empty. When loading a build file by the ( Re)Load  button, this list is filled with all tasks which have a description attribute. The task you select in this list will be executed when pressing the Execute  button.
\item A pulldown box for specifying the log level.
\item Four buttons. Two of them I have already described. The other are the Stop button to cancel a running build and the third one is just the Close button to exit our small tool!
\item Note that the build is canceled on the next console output after pressing the Stop button, not directly after pressing it.
\end{itemize}

After you have set up your buildprocess you might find it useful to
save the data you've just entered, so we implemented an option to save
it to the repository into your selected project. Make sure that you
have an open edition of your project before selecting Save BuildInfo
To Repository from the File menu. Now your information is saved to
this edition of your project and will be loaded automatically the next
time you start Ant Build.  If you have closed the log window
accidentally, it can be reopened with the Log item in the File menu,
and if you want to know who developed this, just select About in the
Help menu.

{\bf Servlets for Remote Tool Access}\hfil\break

With the servlets installed and the remote access running you can use
Ant from the command line without any restrictions. Just make sure the
remote attribute in your build file is set correctly.

\subsubsection{Frequently Asked Questions}

\hfil\break
{\bf Q: If I try to load a build file, I get the error "Can't load default task list". Why?}\hfil\break
A: Ant not only contains class files, but also resource files. This messsage appears if the file
.../org/apache/tools/ant/taskdefs/defaults.properties is missing. Make sure that you import/export not only java/class files, but also all resource files when importing/exporting Ant.

\hfil\break
{\bf Q: I want to load, export and build more then one Visual Age project to one jar! How to?}\hfil\break
A: The VA tasks are able to load and export several Projects all at once. You can choose whatever project you like for storing the tool information, it doesn't really matter

\hfil\break
{\bf Q: When I load my build file, the list of targets is empty. Why?}\hfil\break
A: You need to add the optional "description" parameter to the targets you want to come up in the list. Then reload the build file in the "ant build" tool. We chose to display only targets with description to allow the build file developer to distinguish between targets for end users and helper targets.

\hfil\break
{\bf Q: Is there a sample build file available?}\hfil\break
A: Now you can find an example in this manual

\hfil\break
{\bf Q: Why does it export my entire workspace when I've already implicitly selected a project when starting the Tool?}\hfil\break
A: This selection does not carry into the buildfile you are using. Set the Project name at the beginning of the "includes" parameter.

\hfil\break
{\bf Q: When I import Ant into my Workspace, I get Problems reported. Can I ignore them?}\hfil\break
A: It depends on the problems reported, and what you want to do with Ant. Problems you can't ignore:
\begin{itemize}
\item Classes from javax.xml.parser missing - install a compatible parser (e installation)
\item Classes from com.ibm.ivj.util missing - install the Visual Age IDE Utility feature (see installation).
\item Errors in optional tasks you use within your build file
\end{itemize}

\hfil\break
{\bf Q: I want to use the same buildfile both within Visual Age and from the command line using my regular Ant environment. What do I need to be aware of?}\hfil\break
A: You have to specifie a remote server via the 'remote' attribute. Otherwise the three Visual Age tasks won't work when executing Ant from the command line.

\hfil\break
{\bf Q: I can export packages from project 'ABC', but not from project 'XYZ'! Why?}\hfil\break
A: Common reasons are:
\begin{itemize}
\item The project is excluded by the default excludes (see attribute 'defaultexcludes' of VAJExport)
\item When looking at the project in the workspace, it is often difficult to distinguish between project name and version name (e.g. as in 'My GUI Components Java 2 3.5'). Check if you have the right project name by switching off the version name display temporarilly.
\end{itemize}

\hfil\break
{\bf Q: How do I control the import/export of sourcefiles, compiled files and project resources explicity?}\hfil\break
A: Via the Boolean values exportClasses (default false) exportSources (default true) and exportResources (default true). In some situations, Resources are not exported correctly without this being explicity set. VAJ doesn't export resources correctly if a package contains only resources (see below).

\subsubsection{Known Problems}
\begin{itemize}
\item Exporting a package containing just resources doesn't work.
This is a VAJ Tool API bug. Workaround: create a dummy class and set 
'exportSources' to false. 
\end{itemize}

\subsubsection{VisualAge for Java Versions}

This tool integration has been tested with versions 3.02 and 3.5 of
VisualAge for Java. It should run with the 2.x Versions, too, but we
didn't try. The graphical user interface is built with AWT so it is
JDK independent by now.

\subsubsection{History}
\begin{verbatim}
1.0 2000/09/11 Initial Version
1.1 2001/02/14 Added Task documentation and more FAQs 
               (thanks to Richard Bourke for the FAQ additions)
1.2 2001/07/02

Added documentation of new remote feature.
Minor corrections.
\end{verbatim}

\subsection{Microsoft Visual SourceSafe Tasks}

\subsubsection{The Tasks}

vssget  Retrieves a copy of the specified VSS file(s).
vsslabel Assigns a label to the specified version or current version of a file or project.
vsshistory Shows the history of a file or project in VSS.
vsscheckin Updates VSS with changes made to a checked out file, and unlocks the VSS master copy.
vsscheckout Copies a file from the current project to the current folder, for the purpose of editing.
vssadd Adds a new file into the VSS Archive
vsscp Change the current project being used in VSS
vsscreate Creates a project in VSS.

\subsubsection{Task Descriptions}

{\bf VssGet}\hfil\break

{\bf Description}\hfil\break

Task to perform GET commands to Microsoft Visual SourceSafe.

If you specify two or more attributes from version, date and label
only one will be used in the order version, date, label.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline

vsspath & SourceSafe path which specifies the project/file(s) you wish to perform the action on. You should not specify the leading dollar-sign - it is prepended by Ant automatically. & Yes \\ \hline
login & username[,password] - The username and password needed to get access to VSS. Note that you may need to specify both (if you have a password) - Ant/VSS will hang if you leave the password out and VSS does not accept login without a password. & No \\ \hline
localpath & Override the working directory and get to the specified path & No \\ \hline
ssdir & directory where ss.exe resides. By default the task expects it to be in the PATH. & No \\ \hline
serverPath & directory where ss.ini resides. & No \\ \hline
writable & true or false<; default false/td> & No \\ \hline
recursive & true or false; default false. Note however that in the SourceSafe UI , there is a setting accessed via Tools/Options/GeneralTab called "Act on projects recursively". If this setting is checked, then the recursive attribute is effectively ignored, and the get will always be done recursively & No \\ \hline
\begin{tabular}{l}
version \\
date \\
label \\
\end{tabular} &
\begin{tabular}{p{7.cm}}
a version number to get \\
a date stamp to get at \\
a label to get for \\
\end{tabular} & 
No, only one of these allowed \\ \hline
quiet & suppress output (off by default) & No \\ \hline
autoresponse & What to respond with (sets the -I option). By default, -I- is used; values of Y or N will be appended to this. & No \\ \hline
\end{tabular}

Note that only one of version, date or label should be specified

{\bf Examples}\hfil\break
\begin{verbatim}
<vssget localPath="C:\mysrc\myproject"
        recursive="true" 
        label="Release1"
        login="me,mypassword"
        vsspath="/source/aProject"
        writable="true"/>
\end{verbatim}
Does a get on the VSS-Project \$/source/myproject using the username me
and the password mypassword. It will recursively get the files which
are labeled Release1 and write them to the local directory
C:${\backslash}{\backslash}$mysrc${\backslash}{\backslash}$myproject. The local files will be writable.

\subsubsection{VssLabel}

{\bf Description}\hfil\break

Task to perform LABEL commands to Microsoft Visual SourceSafe.

Assigns a label to the specified version or current version of a file
or project.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
vsspath & SourceSafe path which specifies the project/file(s) you wish to perform the action on. You should not specify the leading dollar-sign - it is prepended by Ant automatically. & Yes \\ \hline
login & username[,password] - The username and password needed to get access to VSS. Note that you may need to specify both (if you have a password) - Ant/VSS will hang if you leave the password out and VSS does not accept login without a password. & No \\ \hline
ssdir & directory where ss.exe resides. By default the task expects it to be in the PATH. & No \\ \hline
serverPath & directory where srssafe.ini resides. & No \\ \hline
label & A label to apply to the hierarchy & Yes \\ \hline
version & An existing file or project version to label. By default the current version is labelled. & No \\ \hline
comment & The comment to use for this label. Empty or '-' for no comment. & No \\ \hline
\end{tabular}

autoresponse What to respond with (sets the -I option). By default,
-I- is used; values of Y or N will be appended to this. No

{\bf Examples}\hfil\break
\begin{verbatim}
<vsslabel vsspath="/source/aProject"
          login="me,mypassword"
          label="Release1"/>
\end{verbatim}
Labels the current version of the VSS project \$/source/aProject with
the label Release1 using the username me and the password mypassword.
\begin{verbatim}
<vsslabel vsspath="/source/aProject/myfile.txt"
          version="4"
          label="1.03.004"/>
\end{verbatim}
Labels version 4 of the VSS file \$/source/aProject/myfile.txt with the
label 1.03.004. If this version already has a label, the operation
(and the build) will fail.

\subsubsection{VssHistory}

{\bf Description}\hfil\break

Task to perform HISTORY commands to Microsoft Visual SourceSafe.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
vsspath & SourceSafe path which specifies the project/file(s) you wish to perform the action on. You should not specify the leading dollar-sign - it is prepended by Ant automatically. & Yes \\ \hline
login & username[,password] - The username and password needed to get access to VSS. Note that you may need to specify both (if you have a password) - Ant/VSS will hang if you leave the password out and VSS does not accept login without a password. & No \\ \hline
ssdir & directory where ss.exe resides. By default the task expects it to be in the PATH. & No \\ \hline
serverPath & directory where srssafe.ini resides. & No \\ \hline
fromDate & Start date for comparison & See below \\ \hline
toDate & End date for comparison & See below \\ \hline
dateFormat & Format of dates in fromDate and toDate. Used when calculating dates with the numdays attribute. This string uses the formatting rules of SimpleDateFormat. Defaults to DateFormat.SHORT. & No \\ \hline
fromLabel & Start label for comparison & No \\ \hline
toLabel & Start label for comparison & No \\ \hline
numdays & The number of days for comparison. See & below \\ \hline
output & File to write the diff. & No \\ \hline
recursive & true or false & No \\ \hline
style & brief, codediff, default or nofile. The default is default. & No \\ \hline
user & Name the user whose changes we would like to see & No \\ \hline
\end{tabular}

{\bf Specifying the time-frame}\hfil\break

There are different ways to specify what time-frame you wish to evaluate:
\begin{itemize}
\item Changes between two dates: Specify both fromDate and toDate
\item Changes before a date: Specify toDate
\item Changes after a date: Specify fromDate
\item Changes X Days before a date: Specify toDate and (negative!) numDays
\item Changes X Days after a date: Specify fromDate and numDays
\end{itemize}

{\bf Examples}\hfil\break
\begin{verbatim}
<vsshistory vsspath="/myProject" recursive="true" 
            fromLabel="Release1"
            toLabel="Release2"/>
\end{verbatim}
Shows all changes between "Release1" and "Release2".
\begin{verbatim}
<vsshistory vsspath="/myProject" recursive="true" 
            fromDate="01.01.2001"
            toDate="31.03.2001"/>
\end{verbatim}
Shows all changes between January 1st 2001 and March 31st 2001 (in
Germany, date must be specified according to your locale).
\begin{verbatim}
<tstamp>
  <format property="to.tstamp" pattern="M-d-yy;h:mma" />
</tstamp>

<vsshistory vsspath="/myProject" recursive="true" 
            numDays="-14"
            dateFormat="M-d-yy;h:mma"
            toDate="${to.tstamp}"/>
\end{verbatim}
Shows all changes in the 14 days before today.

\subsubsection{VssCheckin}

{\bf Description}\hfil\break
Task to perform CHECKIN commands to Microsoft Visual SourceSafe.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
vsspath & SourceSafe path which specifies the project/file(s) you wish to perform the action on. You should not specify the leading dollar-sign - it is prepended by Ant automatically. & Yes \\ \hline
login & username[,password] - The username and password needed to get access to VSS. Note that you may need to specify both (if you have a password) - Ant/VSS will hang if you leave the password out and VSS does not accept login without a password. & No \\ \hline
localpath & Override the working directory and get to the specified path & No \\ \hline
ssdir & directory where ss.exe resides. By default the task expects it to be in the PATH. & No \\ \hline
serverPath & directory where srssafe.ini resides. & No \\ \hline
writable & true or false & No \\ \hline
recursive & true or false & No \\ \hline
comment & Comment to use for the files that where checked in. & No \\ \hline
autoresponse & 'Y', 'N' or empty. Specify how to reply to questions from VSS. & No \\ \hline
\end{tabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<vsscheckin vsspath="/test/test*"
            localpath="D:\build\"
            comment="Modified by automatic build"/>
\end{verbatim}
Checks in the file(s) named test* in the project test using the local
directory D:${\backslash}{\backslash}$build.

\subsubsection{VssCheckout}

{\bf Description}\hfil\break

Task to perform CHECKOUT commands to Microsoft Visual SourceSafe.

If you specify two or more attributes from version, date and label
only one will be used in the order version, date, label.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
vsspath & SourceSafe path which specifies the project/file(s) you wish to perform the action on. You should not specify the leading dollar-sign - it is prepended by Ant automatically. & Yes \\ \hline
login & username[,password] - The username and password needed to get access to VSS. Note that you may need to specify both (if you have a password) - Ant/VSS will hang if you leave the password out and VSS does not accept login without a password. & No \\ \hline
localpath & Override the working directory and get to the specified path & No \\ \hline
ssdir & directory where ss.exe resides. By default the task expects it to be in the PATH. & No \\ \hline
serverPath & directory where srssafe.ini resides. & No \\ \hline
writable & true or false & No \\ \hline
recursive & true or false & No \\ \hline
\begin{tabular}{l}
version \\
date \\
label \\
\end{tabular} &
\begin{tabular}{p{7.5cm}}
a version number to get \\
a date stamp to get at \\
a label to get for \\
\end{tabular} &
No, only one of these allowed \\ \hline
\end{tabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<vsscheckout vsspath="/test"
             localpath="D:\build"
             recursive="true"
             login="me,mypass"/>
\end{verbatim}
Does a recursive checkout of the project test to the 
directory D:${\backslash}{\backslash}$build.

\subsubsection{VssAdd}

{\bf Description}\hfil\break

Task to perform ADD commands to Microsoft Visual SourceSafe.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
localpath & Specify the local file(s) to add to VSS & Yes \\ \hline
login & username[,password] - The username and password needed to get access to VSS. Note that you may need to specify both (if you have a password) - Ant/VSS will hang if you leave the password out and VSS does not accept login without a password. & No \\ \hline
ssdir & directory where ss.exe resides. By default the task expects it to be in the PATH. & No \\ \hline
serverPath & directory where srssafe.ini resides. & No \\ \hline
writable & true or false & No \\ \hline
recursive & true or false & No \\ \hline
comment & Comment to use for the files that where checked in. & No \\ \hline
autoresponse & 'Y', 'N' or empty. Specify how to reply to questions from VSS. & No \\ \hline
\end{tabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<vssadd localpath="D:\build\build.00012.zip"
            comment="Added by automatic build"/>
\end{verbatim}
Add the file named build.00012.zip into the project current working
directory (see vsscp).

\subsubsection{VssCp}

{\bf Description}\hfil\break

Task to perform CP (Change Project) commands to Microsoft Visual SourceSafe.

This task is typically used before a VssAdd in order to set the target project

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
vsspath & SourceSafe path which specifies the project you wish to make the current project. You should not specify the leading dollar-sign - it is prepended by Ant automatically. & Yes \\ \hline
login & username[,password] - The username and password needed to get access to VSS. Note that you may need to specify both (if you have a password) - Ant/VSS will hang if you leave the password out and VSS does not accept login without a password. & No \\ \hline
ssdir & directory where ss.exe resides. By default the task expects it to be in the PATH. & No \\ \hline
serverPath & directory where srssafe.ini resides. & No \\ \hline
\end{tabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<vsscp vsspath="/Projects/ant"/>
\end{verbatim}
Sets the current VSS project to \$/Projects/ant.

\subsubsection{VssCreate}

{\bf Description}\hfil\break

Task to perform CREATE commands to Microsoft Visual Source Safe.

Creates a new project in VSS.

{\bf Parameters}\hfil\break

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
login & username,password & No \\ \hline
vsspath & SourceSafe path of project to be created & Yes \\ \hline
ssdir & directory where ss.exe resides. By default the task expects it to be in the PATH. & No \\ \hline
quiet & suppress output (off by default) & No \\ \hline
failOnError & fail if there is an error creating the project (true by default) & No \\ \hline
autoresponse & What to respond with (sets the -I option). By default, -I- is used; values of Y or N will be appended to this. & No \\ \hline
comment & The comment to use for this label. Empty or '-' for no comment. & No \\ \hline
\end{tabular}

{\bf Examples}\hfil\break
\begin{verbatim}
<vsscreate vsspath="/existingProject/newProject"/>
\end{verbatim}
Creates the VSS-Project \$/existingProject/newProject.

\subsection{Weblogic JSP Compiler}

\subsubsection{Description}

Class to precompile JSP's using weblogic's jsp compiler (weblogic.jspc)
Tested only on Weblogic 4.5.1 - NT4.0 and Solaris 5.7,5.8

\subsubsection{Parameters}

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
src & root of source tree for JSP, ie, the document root for your weblogic server & Yes \\ \hline
dest & root of destination directory, what you have set as WorkingDir in the weblogic properties & Yes \\ \hline
package & start package name under which your JSP's would be compiled & Yes \\ \hline
classpath & Class path to use when compiling jsp's & Yes \\ \hline
\end{tabular}

A classpath should be set which contains the weblogic classes as well as all application classes
referenced by the JSP. The system classpath is also appended when the jspc is called, so you may
choose to put everything in the classpath while calling Ant. However, since presumably the JSP's will reference
classes being build by Ant, it would be better to explicitly add the classpath in the task

The task checks timestamps on the JSP's and the generated classes, and compiles
only those files that have changed.

It follows the weblogic naming convention of putting classes in\hfil\break
\_dirName/\_fileName.class for dirname/fileName.jsp

{\bf Example}\hfil\break
\begin{verbatim}
<target name="jspcompile" depends="compile">
  <wljspc src="c:\\weblogic\\myserver\\public_html" 
    dest="c:\\weblogic\\myserver\\serverclasses" package="myapp.jsp">
    <classpath>
      <pathelement location="${weblogic.classpath}"/>
      <pathelement path="${compile.dest}"/>
    </classpath>
  </wljspc>
</target>
\end{verbatim}

\subsubsection{Limitations}
\begin{itemize}
\item This works only on weblogic 4.5.1
\item It compiles the files thru the Classic compiler only.
\item Since it is my experience that weblogic jspc throws out of memory error on being given too many files at one go, it is called multiple times with one jsp file each.
\end{itemize}

\subsection{XmlValidate}

\subsubsection{Description}

This task checks xml files are valid (or only well formed). The task
uses the SAX2 parser implementation provided by JAXP by default
(probably the one that is used by Ant itself), but one can specify any
SAX1/2 parser if needed.

This task supports the use of nested xmlcatalog elements and/or nested
{\tt <dtd>} elements which are used to resolve DTDs and entities.

\subsubsection{Parameters}

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
file & the file(s) you want to check. (optionally can use an embedded fileset) & No \\ \hline
lenient & if true, only check the xml document is well formed (ignored if the specified parser is as SAX1 parser) & No \\ \hline
classname & the parser to use. & No \\ \hline
classpathref & where to find the parser class. Optionally can use an embedded classpath element. & No \\ \hline
failonerror & fails on a error if set to true (defaults to true). & No \\ \hline
warn & log parser warn events. & No \\ \hline
\end{tabular}

\subsubsection{Nested Elements}

{\bf dtd}\hfil\break
{\tt <dtd>} is used to specify different locations for DTD resolution.

\begin{tabular}{|l|p{8cm}|p{2cm}|} \hline
Attribute & Description & Required \\ \hline
publicId & Public ID of the DTD to resolve & Yes \\ \hline
location & Location of the DTD to use, which can be a file, a resource, or a URL & Yes \\ \hline
\end{tabular}

{\bf xmlcatalog}\hfil\break

The xmlcatalog element is used to perform Entity resolution.

\subsubsection{Examples}
\begin{verbatim}
<xmlvalidate file="toto.xml"/>

<xmlvalidate failonerror="no" lenient="yes" warn="yes"
             classname="org.apache.xerces.parsers.SAXParser">
             classpath="lib/xerces.jar">
  <fileset dir="src" includes="style/*.xsl"/>  
</xmlvalidate>
    
<xmlvalidate file="struts-config.xml" warn="false">
  <dtd publicId="-//Apache Software Foundation//DTD Struts Configuration 1.0//EN"
       location="struts-config_1_0.dtd"/>
</xmlvalidate>

<xmlvalidate failonerror="no">
  <fileset dir="${project.dir}" includes="**/*.xml"/>
  <xmlcatalog refid="mycatalog"/>
</xmlvalidate>

<xmlvalidate failonerror="no">
  <fileset dir="${project.dir}" includes="**/*.xml"/>
  <xmlcatalog>
       <dtd 
         publicId="-//ArielPartners//DTD XML Article V1.0//EN"
         location="com/arielpartners/knowledgebase/dtd/article.dtd"/>
  </xmlcatalog>
</xmlvalidate>
\end{verbatim}
\chapter{Concepts and Types}

\section{Concepts}
\subsection{build.sysclasspath}

The value of the build.sysclasspath property control how the system
classpath, ie. the classpath in effect when Ant is run, affects the
behaviour of classpaths in Ant. The default behavior varies from Ant
to Ant task.

The values and their meanings are: 

\begin{tabular}{|l|p{7cm}|}  \hline
only & Only the system classpath is
used and classpaths specified in build files, etc are ignored. This
situation could be considered as the person running the build file
knows more about the environment than the person writing the build
file \\ \hline

ignore & The system classpath is ignored. This situation is the
reverse of the above. The person running the build trusts the build
file writer to get the build file right \\ \hline

last & The classpath is
concatenated to any specified classpaths at the end. This is a
compromise, where the build file writer has priority.  \\ \hline

first & Any
specified classpaths are concatenated to the system classpath. This is
the other form of compromise where the build runner has priority. \\ \hline
\end{tabular}

\subsection{Common Attributes of all Tasks}

All tasks share the following attributes:

\begin{tabular}{|l|p{7cm}|c|}  \hline
Attribute & Description & Required  \\ \hline
id & Unique identifier for this task instance, 
can be used to reference this task in scripts. & No \\ \hline

taskname & A different name for this task instance - will show up in the
logging output. & No \\ \hline

description & Room for your comments & No  \\ \hline
\end{tabular}

\section{Core Types}
\subsection{Description}

\subsubsection{Description}
Allows for a description of the project to be specified that will be
included in the output of the ant -projecthelp command.

\subsubsection{Parameters}
(none)

\subsubsection{Examples}  
\begin{verbatim}
<description>
This buildfile is used to build the Foo subproject within 
the large, complex Bar project.
</description>
\end{verbatim}

\subsection{Directory-based Tasks}

Some tasks use directory trees for the actions they perform. For
example, the javac task, which compiles a directory tree with .java
files into {\tt .class} files, is one of these directory-based
tasks. Because some of these tasks do so much work with a directory
tree, the task itself can act as an implicit FileSet.

Whether the fileset is implicit or not, it can often be very useful to
work on a subset of the directory tree. This section describes how you
can select a subset of such a directory tree when using one of these
directory-based tasks.

Ant gives you two ways to create a subset of files in a fileset, both
of which can be used at the same time:
\begin{enumerate}
\item Only include files and directories that match any include patterns and
do not match any exclude patterns in a given PatternSet.

\item Select files based on selection criteria defined by a collection of
selector nested elements.
\end{enumerate}

\subsubsection{Patternset}
We said that Directory-based tasks can sometimes act as an implicit
{\tt <fileset>}, but in addition to that, a FileSet acts as an implicit
{\tt <patternset>}.

The inclusion and exclusion elements of the implicit PatternSet can be
specified inside the directory-based task (or explicit fileset) via
either:

\begin{itemize}
\item the attributes includes and excludes. 

\item nested elements {\tt <include>} and {\tt <exclude>}.

\item external files specified with the
attributes includesfile and excludesfile. 

\item external files specified with the nested elements {\tt <includesfile>}
and {\tt <excludesfile>}.
\end{itemize}
When dealing with an external file, each line 
of the file is taken as a pattern that is added to the list of include
or exclude patterns.

When both inclusion and exclusion are used, only files/directories
that match at least one of the include patterns and don't match any of
the exclude patterns are used. If no include pattern is given, all
files are assumed to match the include pattern (with the possible
exception of the default excludes).

{\bf Patterns}\hfil\break
As described earlier, patterns are used for the inclusion and
exclusion of files. These patterns look very much like the patterns
used in DOS and UNIX:

'*' matches zero or more characters, '?' matches one character.

{\bf Examples:}\hfil\break

*.java matches .java, x.java and FooBar.java, but not FooBar.xml (does
not end with .java).

?.java matches x.java, A.java, but not .java or xyz.java (both don't
have one character before .java).

Combinations of *'s and ?'s are allowed.

Matching is done per-directory. This means that first the first
directory in the pattern is matched against the first directory in the
path to match. Then the second directory is matched, and so on. For
example, when we have the pattern /?abc/*/*.java and the path
/xabc/foobar/test.java, the first ?abc is matched with xabc, then * is
matched with foobar, and finally *.java is matched with
test.java. They all match, so the path matches the pattern.

To make things a bit more flexible, we add one extra feature, which
makes it possible to match multiple directory levels. This can be used
to match a complete directory tree, or a file anywhere in the
directory tree. To do this, ** must be used as the name of a
directory. When ** is used as the name of a directory in the pattern,
it matches zero or more directories. For example: /test/** matches all
files/directories under /test/, such as /test/x.java, or
/test/foo/bar/xyz.html, but not /xyz.xml.

There is one "shorthand" - if a pattern ends with / or \, then ** is
appended. For example, mypackage/test/ is interpreted as if it were
mypackage/test/**.

{\bf Example patterns}\hfil\break

\begin{tabular}{|l|p{8cm}|} \hline
**/CVS/* & Matches all files in CVS directories that can be located
anywhere in the directory tree.\hfil\break
Matches: \hfil\break
      CVS/Repository\hfil\break
      org/apache/CVS/Entries\hfil\break
      org/apache/jakarta/tools/ant/CVS/Entries\hfil\break
      \hfil\break
But not: \hfil\break
      org/apache/CVS/foo/bar/Entries (foo/bar/\hfil\break
      part does not match)\hfil\break \\ \hline 
 
org/apache/jakarta/** &
Matches all files in the org/apache/jakarta directory tree.\hfil\break
Matches: \hfil\break
      org/apache/jakarta/tools/ant/docs/index.html\hfil\break
      org/apache/jakarta/test.xml\hfil\break
      \hfil\break
But not: \hfil\break
      org/apache/xyz.java\hfil\break
      \hfil\break
(jakarta/ part is missing). \hfil\break \\ \hline
org/apache/**/CVS/* &
Matches all files in CVS directories that are located anywhere in the
directory tree under org/apache.\hfil\break
\hfil\break
Matches: \hfil\break
      org/apache/CVS/Entries\hfil\break
      org/apache/jakarta/tools/ant/CVS/Entries\hfil\break
      \hfil\break
But not: \hfil\break
      org/apache/CVS/foo/bar/Entries\hfil\break
      \hfil\break
(foo/bar/ part does not match) \hfil\break \\ hline
**/test/** &
Matches all files that have a test element in their path, including
test as a filename. \\ \hline
\end{tabular}

When these patterns are used in inclusion and exclusion, you have a
powerful way to select just the files you want.

\subsubsection{Selectors}

The {\tt <fileset>}, whether implicit or explicit in the directory-based
task, also acts as an {\tt <and>} selector container. This can be used to
create arbitrarily complicated selection criteria for the files the
task should work with. See the Selector documentation for more
information.

\subsubsection{Standard Tasks/Filesets}

Many of the standard tasks in ant take one or more filesets which
follow the rules given here. This list, a subset of those, is a list
of standard ant tasks that can act as an implicit fileset:
\begin{verbatim}
<checksum> 
<copydir> (deprecated) 
<delete> 
<dependset> 
<fixcrlf> 
<javac> 
<replace> 
<rmic> 
<style> (aka <xslt>) 
<tar> 
<zip> 
<ddcreator> 
<ejbjar> 
<ejbc> 
<cab> 
<icontract> 
<native2ascii> 
<netrexxc> 
<renameextensions> 
<depend> 
<ilasm> 
<csc> 
<vbc> 
<translate> 
<vajexport> 
<image> 
<jlink> (deprecated) 
<jspc> 
<wljspc> 
\end{verbatim}
Examples
\begin{verbatim}
<copy todir="${dist}">
  <fileset dir="${src}"
           includes="**/images/*"
           excludes="**/*.gif"
  />
</copy>
\end{verbatim}
This copies all files in directories called images that are located in
the directory tree defined by \$\{src\} to the destination directory
defined by \$\{dist\}, but excludes all *.gif files from the copy.
\begin{verbatim}
<copy todir="${dist}">
  <fileset dir="${src}">
    <include name="**/images/*"/>
    <exclude name="**/*.gif"/>
  </fileset>
</copy>
\end{verbatim}
The same as the example above, but expressed using nested elements.

\begin{verbatim}
<delete dir="${dist}">
    <include name="**/images/*"/>
    <exclude name="**/*.gif"/>
</delete>
\end{verbatim}

Deleting the original set of files, the delete task can act as an
implicit fileset.

Default Excludes
There are a set of definitions that are excluded by default from all
directory-based tasks. They are:
\begin{verbatim}
     **/*~
     **/#*#
     **/.#*
     **/%*%
     **/._*
     **/CVS
     **/CVS/**
     **/.cvsignore
     **/SCCS
     **/SCCS/**
     **/vssver.scc
     **/.svn
     **/.svn/**
     **/.DS_Store
\end{verbatim}
If you do not want these default excludes applied, you may disable
them with the defaultexcludes="no" attribute.

\subsection{DirSet}

DirSets are groups of directories. These directories can be found in a
directory tree starting in a base directory and are matched by
patterns taken from a number of PatternSets. DirSets can appear inside
tasks that support this feature or at the same level as target (i.e.,
as children of {\tt <project>}).

PatternSets can be specified as nested {\tt <patternset>} elements. In
addition, DirSet holds an implicit PatternSet and supports the nested
{\tt <include>}, {\tt <includesfile>}, {\tt <exclude>} 
and {\tt <excludesfile>} elements of
{\tt <patternset>} directly, as well as {\tt <patternset>}'s attributes.

\begin{tabular}{|l|p{7cm}|p{2cm}|} \hline
Attribute & Description & Required  \\ \hline

dir & The root of the directory tree of this DirSet. & Yes  \\ \hline

includes & A comma- or space-separated list of patterns of directories
that must be included; all directories are included when omitted. & No \\ \hline

includesfile & The name of a file; each line of this file is taken to be
an include pattern. & No \\ \hline

excludes & A comma- or space-separated list of patterns of directories
that must be excluded; no directories are excluded when omitted. & No \\ \hline

excludesfile & The name of a file; each line of this file is taken to be
an exclude pattern. & No \\ \hline

casesensitive & Specifies whether case-sensitivty should be applied
(true|yes|on or false|no|off). & No; defaults to true. \\ \hline

followsymlinks & Shall symbolic links be followed? Defaults to true. See
fileset's documentation. & No \\ \hline

\end{tabular}

Examples
\begin{verbatim}
<dirset dir="${build.dir}">
  <include name="apps/**/classes"/>
  <exclude name="apps/**/*Test*"/>
</dirset>
\end{verbatim}

Groups all directories named classes found under the apps subdirectory
of {\tt \$\{build.dir\}}, except those that have the text Test in their name.
\begin{verbatim}
<dirset dir="${build.dir}">
  <patternset id="non.test.classes">
    <include name="apps/**/classes"/>
    <exclude name="apps/**/*Test*"/>
  </patternset>
</dirset>
\end{verbatim}
Groups the same directories as the above example, but also establishes
a PatternSet that can be referenced in other {\tt <dirset>} elements, rooted
at a different directory.
\begin{verbatim}
<dirset dir="${debug_build.dir}">
  <patternset refid="non.test.classes"/>
</dirset>
\end{verbatim}

Groups all directories in directory {\tt \$\{debug\_build.dir\}}, using the same
patterns as the above example.

\subsection{FileList}

FileLists are explicitly named lists of files. Whereas FileSets act as
filters, returning only those files that exist in the file system and
match specified patterns, FileLists are useful for specifying files
that may or may not exist. Multiple files are specified as a list of
files, relative to the specified directory, with no support for
wildcard expansion (filenames with wildcards will be included in the
list unchanged). FileLists can appear inside tasks that support this
feature or at the same level as {\tt <target>} (i.e., as children of
{\tt <project>}).

\begin{tabular}{|l|p{5cm}|c|} \hline
Attribute & Description & Required \\ \hline
dir       & The base directory of this FileList. & Yes \\ \hline
files     & The list of file names. & Yes \\ \hline
\end{tabular}

{\bf Examples}
\begin{verbatim}
<filelist 
    id="docfiles" 
    dir="${doc.src}"
    files="foo.xml,bar.xml"/> 
\end{verbatim}
The files ${doc.src}/foo.xml and ${doc.src}/bar.xml. 
Note that these files may not (yet) actually exist.
\begin{verbatim}
<filelist 
    id="docfiles" 
    dir="${doc.src}"
    files="foo.xml
           bar.xml"/> 
\end{verbatim}
Same files as the example above.
\begin{verbatim}
<filelist refid="docfiles"/> 
\end{verbatim}
Same files as the example above.

\subsection{FileSet}

FileSets are groups of files. These files can be found in a directory
tree starting in a base directory and are matched by patterns taken
from a number of PatternSets and Selectors. FileSets can appear inside
tasks that support this feature or at the same level as target - i.e.,
as children of project.

PatternSets can be specified as nested {\tt <patternset>} elements. In
addition, FileSet holds an implicit PatternSet and supports the nested
{\tt <include>}, {\tt <includesfile>}, {\tt <exclude>} and 
{\tt <excludesfile>} elements of
PatternSet directly, as well as PatternSet's attributes.

Selectors are available as nested elements.within the FileSet. If any
of the selectors within the FileSet do not select the file, the file
is not considered part of the FileSet. This makes FileSets euqivalent
to an {\tt <and>} selector container.

\begin{tabular}{|l|p{8cm}|c|} \hline
Attribute & Description & Required  \\ \hline

dir & the root of the directory tree of this FileSet. & Yes \\ \hline

defaultexcludes & indicates whether default excludes should be used or
not (yes | no); default excludes are used when omitted. & No \\ \hline

includes & comma- or space-separated list of patterns of files that must
be included; all files are included when omitted. & No \\ \hline

includesfile & the name of a file; each line of this file is taken to be
an include pattern. & No \\ \hline

excludes & comma- or space-separated list of patterns of files that must
be excluded; no files (except default excludes) are excluded when
omitted. & No \\ \hline

excludesfile & the name of a file; each line of this file is taken to be
an exclude pattern. & No \\ \hline

casesensitive & Must the file system be treated in a case sensitive way?
Defaults to true. & No \\ \hline

followsymlinks & Shall symbolic links be followed? Defaults to true. See
the note below. & No \\ \hline

\end{tabular}

Note: All files/directories for which the canonical path is different
from its path are considered symbolic links. On Unix systems this
usually means the file really is a symbolic links but it may lead to
false results on other platforms.

{\bf Examples}
\begin{verbatim}
<fileset dir="${server.src}" casesensitive="yes">
  <include name="**/*.java"/>
  <exclude name="**/*Test*"/>
</fileset>
\end{verbatim}
Groups all files in directory {\tt \$\{server.src\}}
that are Java source files
and don't have the text Test in their name.
\begin{verbatim}
<fileset dir="${server.src}" casesensitive="yes">
  <patternset id="non.test.sources">
    <include name="**/*.java"/>
    <exclude name="**/*Test*"/>
  </patternset>
</fileset>
\end{verbatim}

Groups the same files as the above example, but also establishes a
PatternSet that can be referenced in other 
{\tt <fileset>} elements, rooted at a different directory.
\begin{verbatim}
<fileset dir="${client.src}" >
  <patternset refid="non.test.sources"/>
</fileset>
\end{verbatim}

Groups all files in directory {\tt \$\{client.src\}}, using 
the same patterns as the above example.
\begin{verbatim}
<fileset dir="${server.src}" casesensitive="yes">
  <filename name="**/*.java"/>
  <filename name="**/*Test*" negate="true"/>
</fileset>
\end{verbatim}
Groups the same files as the top example, but using the 
{\tt <filename>} selector.
\begin{verbatim}
<fileset dir="${server.src}" casesensitive="yes">
  <filename name="**/*.java"/>
  <not>
    <filename name="**/*Test*"/>
  </not>
</fileset>
\end{verbatim}
Groups the same files as the previous example using a combination of
the {\tt <filename>} selector and the <not> selector container.

\subsection{File Mappers}

Some tasks take source files and create target files. Depending on the
task, it may be quite obvious which name a target file will have
(using javac, you know there will be .class files for your .java
files) - in other cases you may want to specify the target files,
either to help Ant or to get an extra bit of functionality.

While source files are usually specified as filesets, you don't
specify target files directly - instead, you tell Ant how to find the
target file(s) for one source file. An instance of
org.apache.tools.ant.util.FileNameMapper is responsible for this. It
constructs target file names based on rules that can be parameterized
with from and to attributes - the exact meaning of which is
implementation-dependent.

These instances are defined in {\tt <mapper>} elements with the following
attributes:\hfil\break
\hfil\break
\begin{tabular}{|l|p{7cm}|p{3cm}|} \hline
{\bf Attribute} & {\bf Description} & {\bf Required} \\ \hline

type         & specifies one of the built-in implementations. 
& Exactly one of both \\ \hline
classname    & specifies the implementation by class name. & Exactly one of both \\ \hline

classpath    & the classpath to use when looking up classname. & No  \\ \hline
classpathref & the classpath to use, given as reference to a path defined elsewhere. & No  \\ \hline
from         & the from attribute for the given implementation. & Depends on implementation. \\ \hline
to           & the to attribute for the given implementation. & Depends on implementation.  \\ \hline
\end{tabular}

Note that Ant will not automatically
convert / or ${\backslash}$ characters in the
to and from attributes to the correct directory separator of your
current platform. If you need to specify this separator, use
{\tt \$\{file.separator\}} instead.

\subsubsection{Parameters specified as nested elements}

The classpath can be specified
via a nested {\tt <classpath>}, as well - that is, a path-like structure.

The built-in mapper types are:
\begin{itemize}
\item[identity] The target file name is identical 
to the source file name. Both to and
from will be ignored.

{\bf Examples:}\hfil\break
\begin{verbatim}
<mapper type="identity"/>
\end{verbatim}
\begin{tabular}{|l|l|} \hline
Source file name & Target file name \\ \hline
A.java           & A.java \\ \hline
foo/bar/B.java   & foo/bar/B.java \\ \hline
C.properties     & C.properties \\ \hline
Classes/dir/dir2/A.properties & Classes/dir/dir2/A.properties \\ \hline
\end{tabular}

\item[flatten] The target file name is identical 
to the source file name, with all
leading directory information stripped off. Both to and from will be
ignored.

{\bf Examples:}\hfil\break
\begin{verbatim}
<mapper type="flatten"/>
\end{verbatim}
\begin{tabular}{|l|l|} \hline
Source file name & Target file name  \\ \hline
A.java & A.java  \\ \hline
foo/bar/B.java  & B.java  \\ \hline
C.properties & C.properties  \\ \hline
Classes/dir/dir2/A.properties & A.properties  \\ \hline
\end{tabular}

\item[merge] The target file name will always be the same, 
as defined by to - from will be ignored.

{\bf Examples:}\hfil\break
\begin{verbatim}
<mapper type="merge" to="archive.tar"/>
\end{verbatim}
\begin{tabular}{|l|l|} \hline
Source file name & Target file name  \\ \hline
A.java            & archive.tar  \\ \hline
foo/bar/B.java  & archive.tar  \\ \hline
C.properties    & archive.tar  \\ \hline
Classes/dir/dir2/A.properties & archive.tar  \\ \hline
\end{tabular}

\item[glob] Both to and from define patterns
that may contain at most one *. For
each source file that matches the from pattern, a target file name
will be constructed from the to pattern by substituting the * in the
to pattern with the text that matches the * in the from
pattern. Source file names that don't match the from pattern will be
ignored.

{\bf Examples: }\hfil\break
\begin{verbatim}
<mapper type="glob" from="*.java" to="*.java.bak"/>
\end{verbatim}
\begin{tabular}{|l|l|} \hline
Source file name & Target file name  \\ \hline
A.java & A.java.bak  \\ \hline
foo/bar/B.java & foo/bar/B.java.bak  \\ \hline
C.properties & ignored  \\ \hline
Classes/dir/dir2/A.properties & ignored  \\ \hline
\end{tabular}
\begin{verbatim}
<mapper type="glob" from="C*ies" to="Q*y"/>
\end{verbatim}
\begin{tabular}{|l|l|} \hline
Source file name & Target file name  \\ \hline
A.java & ignored  \\ \hline
foo/bar/B.java & ignored  \\ \hline
C.properties & Q.property  \\ \hline
Classes/dir/dir2/A.properties & Qlasses/dir/dir2/A.property  \\ \hline
\end{tabular}

\item[regexp]
Both to and from define regular expressions. If the source file name
matches the from pattern, the target file name will be constructed
from the to pattern, using ${\backslash}$0 
to ${\backslash}$9 as back-references for the full
match (${\backslash}$0) or the matches of the subexpressions
in parentheses. Source
files not matching the from pattern will be ignored.

Note that you need to escape a dollar-sign (\$) with another
dollar-sign in Ant.

The regexp mapper needs a supporting library and an implementation of
org.apache.tools.ant.util.regexp.RegexpMatcher that hides the
specifics of the library. Ant comes with implementations for the
java.util.regex package of JDK 1.4, jakarta-regexp and jakarta-ORO. If
you compile from sources and plan to use one of them, make sure the
libraries are in your CLASSPATH. For information about using
gnu.regexp or gnu.rex with Ant, see this article.

This means, you need optional.jar from the Ant release you are using
and one of the supported regular expression libraries. Make sure, both
will be loaded from the same classpath, that is either put them into
your CLASSPATH, {\tt ANT\_HOME}/lib directory or a nested 
{\tt <classpath>} element
of the mapper - you cannot have optional.jar in {\tt ANT\_HOME}/lib and the
library in a nested {\tt <classpath>}.

Ant will choose the regular-expression library based on the following
algorithm:

If the system property {\tt ant.regexp.matcherimpl} has been set, it is
taken as the name of the class implementing
org.apache.tools.ant.util.regexp.RegexpMatcher that should be used.

If it has not been set, first try the JDK 1.4 classes, then
jakarta-ORO and finally try jakarta-regexp.
\end{itemize}

Examples: 
\begin{verbatim}
<mapper type="regexp" from="^(.*)\.java$$" to="\1.java.bak"/>
\end{verbatim}
\begin{tabular}{|l|l|} \hline
Source file name & Target file name \\ \hline
A.java A.        & java.bak  \\ \hline
foo/bar/B.java   & foo/bar/B.java.bak \\ \hline
C.properties     & ignored \\ \hline
Classes/dir/dir2/A.properties & ignored \\ \hline
\end{tabular}
\begin{verbatim}
<mapper type="regexp" from="^(.*)/([^/]+)/([^/]*)$$" to="\1/\2/\2-\3"/>
\end{verbatim}
\begin{tabular}{|l|l|} \hline
Source file name & Target file name \\ \hline
A.java           & ignored \\ \hline
foo/bar/B.java   & foo/bar/bar-B.java \\ \hline
C.properties     & ignored \\ \hline
Classes/dir/dir2/A.properties & Classes/dir/dir2/dir2-A.properties \\ \hline
\end{tabular}
\begin{verbatim}
<mapper type="regexp" from="^(.*)\.(.*)$$" to="\2.\1"/>
\end{verbatim}
\begin{tabular}{|l|l|} \hline
Source file name & Target file name \\ \hline
A.java           & java.A \\ \hline
foo/bar/B.java   & java.foo/bar/B \\ \hline
C.properties     & properties.C \\ \hline
Classes/dir/dir2/A.properties & properties.Classes/dir/dir2/A \\ \hline
\end{tabular}

{\bf package}\hfil\break
Sharing the same syntax as the glob mapper, the package mapper
replaces directory separators found in the matched source pattern with
dots in the target pattern placeholder. This mapper is particularly
useful in combination with {\tt <uptodate>} and {\tt <junit>} output.

Example: 
\begin{verbatim}
<mapper type="package"
        from="*Test.java" to="TEST-*Test.xml"/>
\end{verbatim}

Source file name Target file name 

org/apache/tools/ant/util/PackageMapperTest.java
TEST-org.apache.tools.ant.util.PackageMapperTest.xml

org/apache/tools/ant/util/Helper.java ignored 

\subsection{Filter Chains and Filter Readers}

Look at Unix pipes - they offer you so much flexibility - say you
wanted to copy just those lines that contained the 
string {\tt blee} from
the first 10 lines of a file 'foo' to a file 'bar' - you would do
something like
\begin{verbatim}
cat foo|head -n10|grep blee > bar 
\end{verbatim}

Ant was not flexible enough. There was no way for the 
{\tt <copy>} task to
do something similar. If you wanted the {\tt <copy>} task to get the first
10 lines, you would have had to create special attributes:

\begin{verbatim}
<copy file="foo" tofile="bar" head="10" contains="blee"/> 
\end{verbatim}

The obvious problem thus surfaced: Ant tasks would not be able to
accomodate such data transformation attributes as they would be
endless. The task would also not know in which order these attributes
were to be interpreted. That is, must the task execute the contains
attribute first and then the head attribute or vice-versa? What Ant
tasks needed was a mechanism to allow pluggable filter (data
tranformer) chains. Ant would provide a few filters for which there
have been repeated requests. Users with special filtering needs would
be able to easily write their own and plug them in.

The solution was to refactor data transformation oriented tasks to
support FilterChains. A FilterChain is a group of ordered
FilterReaders. Users can define their own FilterReaders by just
extending the java.io.FilterReader class. Such custom FilterReaders
can be easily plugged in as nested elements of 
{\tt <filterchain>} by using
{\tt <filterreader>} elements.

Example: 
\begin{verbatim}
<copy file="${src.file}" tofile="${dest.file}">
  <filterchain>
    <filterreader classname="your.extension.of.java.io.FilterReader">
      <param name="foo" value="bar"/>
    </filterreader>
    <filterreader classname="another.extension.of.java.io.FilterReader">
      <classpath>
        <pathelement path="${classpath}"/>
      </classpath>
      <param name="blah" value="blee"/>
      <param type="abra" value="cadabra"/>
    </filterreader>
  </filterchain>
</copy>
\end{verbatim}

Ant provides some built-in filter readers. These filter readers can
also be declared using a syntax similar to the above syntax. However,
they can be declared using some simpler syntax also.

Example: 
\begin{verbatim}
<loadfile srcfile="${src.file}" property="${src.file.head}">
  <filterchain>
    <headfilter lines="15"/>
  </filterchain>
</loadfile>
\end{verbatim}
is equivalent to: 
\begin{verbatim}
<loadfile srcfile="${src.file}" property="${src.file.head}">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.HeadFilter">
      <param name="lines" value="15"/>
    </filterreader>
  </filterchain>
</loadfile>
\end{verbatim}
The following built-in tasks support nested {\tt <filterchain>} elements.
\begin{verbatim}
Copy,
LoadFile,
LoadProperties,
Move
\end{verbatim}
A FilterChain is formed by defining zero or 
more of the following nested elements.
FilterReader
ClassConstants
ExpandProperties
HeadFilter
LineContains
LineContainsRegExp
PrefixLines
ReplaceTokens
StripJavaComments
StripLineBreaks
StripLineComments
TabsToSpaces
TailFilter

FilterReader
The filterreader element is the generic way to define a filter. 
User defined filter elements are defined in the build file using this. 
Please note that built in filter readers can also be defined using
this syntax. A FilterReader element must be supplied with a class name
as an attribute value. The class resolved by this name must 
extend java.io.FilterReader. If the custom filter reader needs to 
be parameterized, it must implement 
org.apache.tools.type.Parameterizable. Attribute Description Required 
classname The class name of the filter reader. Yes 

Nested Elements: {\tt <filterreader>} supports {\tt <classpath>} and
{\tt <param>} as nested elements. Each {\tt <param>} element may take in the
following attributes - name, type and value.

The following FilterReaders are supplied with the default distribution. 

ClassConstants
This filters basic constants defined in a Java Class, and outputs them in lines composed of the format name=value 


Example:
This loads the basic constants defined in a Java class as Ant properties. 
\begin{verbatim}
<loadproperties srcfile="foo.class">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.ClassConstants"/>
  </filterchain>
</loadproperties>
\end{verbatim}
Convenience method: 
\begin{verbatim}
<loadproperties srcfile="foo.class">
  <filterchain>
    <classconstants/>
  </filterchain>
</loadproperties>
\end{verbatim}
ExpandProperties
If the data contains data that represents Ant properties (of the form
\$\{...\}), that is substituted with the property's actual value.

Example:
This results in the property modifiedmessage holding the value "All
these moments will be lost in time, like teardrops in the rain"
\begin{verbatim}
<echo
  message="All these moments will be lost in time, like teardrops in the ${weather}"
  file="loadfile1.tmp"
  />
<property name="weather" value="rain" />
<loadfile property="modifiedmessage" srcFile="loadfile1.tmp">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.ExpandProperties"/>
  </filterchain>
</loadfile>
\end{verbatim}
Convenience method: 
\begin{verbatim}
<echo
  message="All these moments will be lost in time, like teardrops in the ${weather}"
  file="loadfile1.tmp"
  />
<property name="weather" value="rain" />
<loadfile property="modifiedmessage" srcFile="loadfile1.tmp">
  <filterchain>
    <expandproperties/>
  </filterchain>
</loadfile>
\end{verbatim}

HeadFilter
This filter reads the first few lines from the data supplied to it. Parameter Name Parameter Value Required 
lines Number of lines to be read. Defaults to "10" No 

Example:

This stores the first 15 lines of the supplied data in the property
{\tt \$\{src.file.head\}}
\begin{verbatim}
<loadfile srcfile="${src.file}" property="${src.file.head}">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.HeadFilter">
      <param name="lines" value="15"/>
    </filterreader>
  </filterchain>
</loadfile>
\end{verbatim}
Convenience method: 
\begin{verbatim}
<loadfile srcfile="${src.file}" property="${src.file.head}">
  <filterchain>
    <headfilter lines="15"/>
  </filterchain>
</loadfile>
\end{verbatim}

LineContains
This filter includes only those lines that contain all the
user-specified strings. Parameter Type Parameter Value Required
contains Substring to be searched for. Yes

Example:
This will include only those lines that contain foo and bar. 
\begin{verbatim}
<filterreader classname="org.apache.tools.ant.filters.LineContains">
  <param type="contains" value="foo"/>
  <param type="contains" value="bar"/>
</filterreader>
\end{verbatim}
Convenience method: 
\begin{verbatim}
<linecontains>
  <contains value="foo">
  <contains value="bar">
</linecontains>
\end{verbatim}
LineContainsRegExp
Filter which includes only those lines that contain the user-specified
regular expression matching strings. Parameter Type Parameter Value
Required regexp Pattern of the substring to be searched for. Yes

Example:
This will fetch all those lines that contain the pattern foo 
\begin{verbatim}
<filterreader classname="org.apache.tools.ant.filters.LineContainsRegExp">
  <param type="regexp" value="foo*"/>
</filterreader>
\end{verbatim}
Convenience method: 
\begin{verbatim}
<linecontainsregexp>
  <regexp pattern="foo*">
</linecontainsregexp>
\end{verbatim}
PrefixLines
Attaches a prefix to every line. Parameter Name Parameter Value Required 
prefix Prefix to be attached to lines. Yes 

Example:
This will attach the prefix Foo to all lines. 
\begin{verbatim}
<filterreader classname="org.apache.tools.ant.filters.PrefixLines">
  <param name="prefix" value="Foo"/>
</filterreader>
\end{verbatim}
Convenience method: 
\begin{verbatim}
<prefixlines prefix="Foo"/>
\end{verbatim}
ReplaceTokens
This filter reader replaces all strings that are sandwiched between
begintoken and endtoken with user defined values. Parameter Type
Parameter Name Parameter Value Required tokenchar begintoken Character
marking the beginning of a token. Defaults to @ No tokenchar endtoken
Character marking the end of a token. Defaults to @ No token User
defined String. User defined search String Yes

Example:
This replaces occurences of the string @DATE@ in the data with today's
date and stores it in the property \$\{src.file.replaced\}
\begin{verbatim}
<tstamp/>
<loadfile srcfile="${src.file}" property="${src.file.replaced}">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.ReplaceTokens">
      <param type="token" name="DATE" value="${TODAY}"/>
    </filterreader>
  </filterchain>
</loadfile>
\end{verbatim}
Convenience method: 
\begin{verbatim}
<tstamp/>
<loadfile srcfile="${src.file}" property="${src.file.replaced}">
  <filterchain>
    <replacetokens>
      <token key="DATE" value="${TODAY}"/>
    </replacetokens>
  </filterchain>
</loadfile>
\end{verbatim}

StripJavaComments
This filter reader strips away comments from the data, using Java
syntax guidelines. This filter does not take in any parameters.

Example:
\begin{verbatim}
<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.StripJavaComments"/>
  </filterchain>
</loadfile>
\end{verbatim}
Convenience method: 
\begin{verbatim}
<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}">
  <filterchain>
    <stripjavacomments/>
  </filterchain>
</loadfile>
\end{verbatim}
StripLineBreaks
This filter reader strips away specific characters from the data
supplied to it. Parameter Name Parameter Value Required linebreaks
Characters that are to be stripped out. Defaults to
"${\backslash}$r${\backslash}$n" No


Examples:
This strips the '${\backslash}$r' and '${\backslash}$n' characters. 
\begin{verbatim}
<loadfile srcfile="${src.file}" property="${src.file.contents}">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.StripLineBreaks"/>
  </filterchain>
</loadfile>
\end{verbatim}
Convenience method: 
\begin{verbatim}
<loadfile srcfile="${src.file}" property="${src.file.contents}">
  <filterchain>
    <striplinebreaks/>
  </filterchain>
</loadfile>
\end{verbatim}
This treats the '(' and ')' characters as line break characters and
strips them.
\begin{verbatim}
<loadfile srcfile="${src.file}" property="${src.file.contents}">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.StripLineBreaks">
      <param name="linebreaks" value="()"/>
    </filterreader>
  </filterchain>
</loadfile>
\end{verbatim}
StripLineComments
This filter removes all those lines that begin with strings that
represent comments as specified by the user. Parameter Type Parameter
Value Required comment Strings that identify a line as a comment when
they appear at the start of the line. Yes

Examples:
This removes all lines that begin with \#, --, REM, rem and // 
\begin{verbatim}
<filterreader classname="org.apache.tools.ant.filters.StripLineComments">
  <param type="comment" value="#"/>
  <param type="comment" value="--"/>
  <param type="comment" value="REM "/>
  <param type="comment" value="rem "/>
  <param type="comment" value="//"/>
</filterreader>
\end{verbatim}
Convenience method: 
\begin{verbatim}
<striplinecomments>
  <comment value="#"/>
  <comment value="--"/>
  <comment value="REM "/>
  <comment value="rem "/>
  <comment value="//"/>
</striplinecomments>
\end{verbatim}
TabsToSpaces
This filter replaces tabs with spaces Parameter Name Parameter Value
Required lines tablength Defaults to "8" No

Examples:
This replaces tabs in {\tt \$\{src.file\}} with spaces. 
\begin{verbatim}
<loadfile srcfile="${src.file}" property="${src.file.notab}">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.TabsToSpaces"/>
  </filterchain>
</loadfile>
\end{verbatim}
Convenience method: 
\begin{verbatim}
<loadfile srcfile="${src.file}" property="${src.file.notab}">
  <filterchain>
    <tabstospaces/>
  </filterchain>
</loadfile>
\end{verbatim}

TailFilter
This filter reads the last few lines from the data supplied to
it. Parameter Name Parameter Value Required lines Number of lines to
be read. Defaults to "10" No

Examples:
This stores the last 15 lines of the supplied data in the 
property \$\{src.file.tail\} 
\begin{verbatim}
<loadfile srcfile="${src.file}" property="${src.file.tail}">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.TailFilter">
      <param name="lines" value="15"/>
    </filterreader>
  </filterchain>
</loadfile>
\end{verbatim}
Convenience method: 
\begin{verbatim}
<loadfile srcfile="${src.file}" property="${src.file.tail}">
  <filterchain>
    <tailfilter lines="15"/>
  </filterchain>
</loadfile>
\end{verbatim}
This stores the last 5 lines of the first 15 lines of the supplied data 
in the property \$\{src.file.mid\} 
\begin{verbatim}
<loadfile srcfile="${src.file}" property="${src.file.mid}">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.HeadFilter">
      <param name="lines" value="15"/>
    </filterreader>
    <filterreader classname="org.apache.tools.ant.filters.TailFilter">
      <param name="lines" value="5"/>
    </filterreader>
  </filterchain>
</loadfile>
\end{verbatim}
Convenience method: 
\begin{verbatim}
<loadfile srcfile="${src.file}" property="${src.file.mid}">
  <filterchain>
    <headfilter lines="15"/>
    <tailfilter lines="5"/>
  </filterchain>
</loadfile>
\end{verbatim}

\subsection{FilterSet}

FilterSets are groups of filters. Filters can be defined as
token-value pairs or be read in from a file. FilterSets can appear
inside tasks that support this feature or at the same level as
{\tt <target>} - i.e., as children of {\tt <project>}.

FilterSets support the id and refid attributes. You can define a
FilterSet with an id attribute and then refer to that definition from
another FilterSet with a refid attribute. It is also possible to nest
filtersets into filtersets to get a set union of the contained
filters.

In addition, FilterSets can specify begintoken and/or endtoken
attributes to define what to match.

Filtersets are used for doing replacements in tasks such as 
{\tt <copy>}, etc.

Filterset
Attribute Description Default Required 
begintoken The string marking the beginning of a token (eg., @DATE@). @ No 
endtoken The string marking the end of a token (eg., @DATE@). @ No 

Filter
Attribute Description Required 
token The token to replace (eg., @DATE@) Yes 
value The value to replace it with (eg., Thursday, April 26, 2001). Yes 

Filtersfile
Attribute Description Required 
file A properties file of name-value pairs from which to load the tokens. Yes 

Examples
You are copying the version.txt file to the dist directory from the build directory but wish to replace the token @DATE@ with today's date.
\begin{verbatim}
<copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt">
  <filterset>
    <filter token="DATE" value="${TODAY}"/>
  </filterset>
</copy>
\end{verbatim}

You are copying the version.txt file to the dist directory from the
build directory but wish to replace the token %DATE* with today's date.
\begin{verbatim}
<copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt">
  <filterset begintoken="%" endtoken="*">
    <filter token="DATE" value="${TODAY}"/>
  </filterset>
</copy>
\end{verbatim}
Copy all the docs but change all dates and appropriate notices as stored in a file.
\begin{verbatim}
<copy toDir="${dist.dir}/docs">
  <fileset dir="${build.dir}/docs">
    <include name="**/*.html">
  </fileset>
  <filterset begintoken="%" endtoken="*">
    <filtersfile file="${user.dir}/dist.properties"/>
  </filterset>
</copy>
\end{verbatim}
Define a FilterSet and reference it later.
\begin{verbatim}
<filterset id="myFilterSet" begintoken="%" endtoken="*">
  <filter token="DATE" value="${TODAY}"/>
</filterset>

<copy file="${build.dir}/version.txt" toFile="${dist.dir}/version.txt">
  <filterset refid="myFilterSet"/>
</copy>
\end{verbatim}

\subsection{PatternSet}

Patterns can be grouped to sets and later be referenced by their id
attribute. They are defined via a patternset element, which can appear
nested into a FileSet or a directory-based task that constitutes an
implicit FileSet. In addition, patternsets can be defined as a stand
alone element at the same level as target — i.e., as children of
project as well as as children of target.

Patterns can be specified by nested {\tt <include>}, or {\tt
<exclude>} elements or the following attributes.

Attribute Description 
includes comma- or space-separated list of patterns of files that must be included. All files are included when omitted. 
includesfile the name of a file; each line of this file is taken to be an include pattern. You can specify more than one include file by using a nested includesfile elements. 
excludes comma- or space-separated list of patterns of files that must be excluded; no files (except default excludes) are excluded when omitted. 
excludesfile the name of a file; each line of this file is taken to be an exclude pattern. You can specify more than one exclude file by using a nested excludesfile elements. 

Parameters specified as nested elements
include and exclude
Each such element defines a single pattern for files to include or exclude.

Attribute Description Required 
name the pattern to in/exclude. Yes 
if Only use this pattern if the named property is set. No 
unless Only use this pattern if the named property is not set. No 

includesfile and excludesfile
If you want to list the files to include or exclude external to your build file, you should use the includesfile/excludesfile attributes or elements. Using the attribute, you can only specify a single file of each type, while the nested elements can be specified more than once - the nested elements also support if/unless attributes you can use to test the existance of a property.

Attribute Description Required 
name the name of the file holding the patterns to in/exclude. Yes 
if Only read this file if the named property is set. No 
unless Only read this file if the named property is not set. No 

patternset
Patternsets may be nested within one another, adding the nested patterns to the parent patternset.

Examples
\begin{verbatim}
<patternset id="non.test.sources">
  <include name="**/*.java"/>
  <exclude name="**/*Test*"/>
</patternset>
\end{verbatim}
Builds a set of patterns that matches all .java files that do not
contain the text Test in their name. This set can be referred to via
{\tt <patternset refid="non.test.sources"/>},
by tasks that support this feature, or by FileSets.

Note that while the includes and excludes attributes accept multiple
elements separated by commas or spaces, the nested {\tt <include>} and
{\tt <exclude>} elements expect their name attribute to hold a single
pattern.

The nested elements allow you to use if and unless arguments to
specify that the element should only be used if a property is set, or
that it should be used only if a property is not set.

For example
\begin{verbatim}
<patternset id="sources">
  <include name="std/**/*.java"/>
  <include name="prof/**/*.java" if="professional"/>
  <exclude name="**/*Test*"/>
</patternset>
\end{verbatim}
will only include the files in the sub-directory prof if the property
professional is set to some value.

The two sets
\begin{verbatim}
<patternset includesfile="some-file"/>
\end{verbatim}
and
\begin{verbatim}
<patternset>
  <includesfile name="some-file"/> 
<patternset/>
\end{verbatim}
are identical. The include patterns will be read from the file
some-file, one pattern per line.
\begin{verbatim}
<patternset>
  <includesfile name="some-file"/> 
  <includesfile name="${some-other-file}" 
                if="some-other-file"
  /> 
<patternset/>
\end{verbatim}

will also read include patterns from the file the property
some-other-file points to, if a property of that name has been
defined.

\subsection{Path-like Structures}

You can specify PATH- and CLASSPATH-type references using both ":" and
";" as separator characters. Ant will convert the separator to the
correct character of the current operating system.

Wherever path-like values need to be specified, a nested element can
be used. This takes the general form of:
\begin{verbatim}
    <classpath>
      <pathelement path="${classpath}"/>
      <pathelement location="lib/helper.jar"/>
    </classpath>
\end{verbatim}
The location attribute specifies a single file or directory relative to the project's base directory (or an absolute filename), while the path attribute accepts colon- or semicolon-separated lists of locations. The path attribute is intended to be used with predefined paths - in any other case, multiple elements with location attributes should be preferred.

As a shortcut, the {\tt <classpath>} tag supports path and location
attributes of its own, so:
\begin{verbatim}
    <classpath>
      <pathelement path="${classpath}"/>
    </classpath>
\end{verbatim}
can be abbreviated to:
\begin{verbatim}
    <classpath path="${classpath}"/>
\end{verbatim}
In addition, DirSets, FileSets, and FileLists can be specified via 
nested {\tt <dirset>}, {\tt <fileset>}, 
and {\tt <filelist>} elements, respectively. 

Note: The order in which the files building up a FileSet are added to
the path-like structure is not defined.
\begin{verbatim}
    <classpath>
      <pathelement path="${classpath}"/>
      <fileset dir="lib">
        <include name="**/*.jar"/>
      </fileset>
      <pathelement location="classes"/>
      <dirset dir="${build.dir}">
        <include name="apps/**/classes"/>
        <exclude name="apps/**/*Test*"/>
      </dirset>
      <filelist refid="third-party_jars">
    </classpath>
\end{verbatim}
This builds a path that holds the value of \$\{classpath\}, followed by
all jar files in the lib directory, the classes directory, all
directories named classes under the apps subdirectory 
of \$\{build.dir\},
except those that have the text Test in their name, and the files
specified in the referenced FileList.

If you want to use the same path-like structure for several tasks, you
can define them with a {\tt <path>} element at the same level as targets,
and reference them via their id attribute - see References for an
example.

A path-like structure can include a reference to another path-like
structure via nested {\tt <path>} elements:
\begin{verbatim}
    <path id="base.path">
      <pathelement path="${classpath}"/>
      <fileset dir="lib">
        <include name="**/*.jar"/>
      </fileset>
      <pathelement location="classes"/>
    </path>

    <path id="tests.path">
      <path refid="base.path"/>
      <pathelement location="testclasses"/>
    </path>
\end{verbatim}
The shortcuts previously mentioned for <classpath> are also valid for
{\tt <path>}. For example:
\begin{verbatim}
    <path id="base.path">
      <pathelement path="${classpath}"/>
    </path>
\end{verbatim}
can be written as: 
\begin{verbatim}
    <path id="base.path" path="${classpath}"/>
\end{verbatim}
Command-line Arguments
Several tasks take arguments that will be passed to another process on the command line. To make it easier to specify arguments that contain space characters, nested arg elements can be used.

Attribute Description Required 
value a single command-line argument; can contain space
characters. Exactly one of these.  file The name of a file as a single
command-line argument; will be replaced with the absolute filename of
the file.  path A string that will be treated as a path-like string as
a single command-line argument; you can use ; or : as path separators
and Ant will convert it to the platform's local conventions.  line a
space-delimited list of command-line arguments.

It is highly recommended to avoid the line version when possible. Ant
will try to split the command line in a way similar to what a (Unix)
shell would do, but may create something that is very different from
what you expect under some circumstances.

Examples
\begin{verbatim}
  <arg value="-l -a"/>
\end{verbatim}
is a single command-line argument containing a space character.
\begin{verbatim}
  <arg line="-l -a"/>
\end{verbatim}
represents two separate command-line arguments.
\begin{verbatim}
  <arg path="/dir;/dir2:\dir3"/>
\end{verbatim}

is a single command-line argument with the 
value ${\backslash}$dir;${\backslash}$dir2;${\backslash}$dir3 on
DOS-based systems and /dir:/dir2:/dir3 on Unix-like systems.

References
The id attribute of the buildfile's elements can be used to refer to
them. This can be useful if you are going to replicate the same
snippet of XML over and over again - using a {\tt <classpath>} structure
more than once, for example.

The following example:
\begin{verbatim}
<project ... >
  <target ... >
    <rmic ...>
      <classpath>
        <pathelement location="lib/"/>
        <pathelement path="${java.class.path}/"/>
        <pathelement path="${additional.path}"/>
      </classpath>
    </rmic>
  </target>

  <target ... >
    <javac ...>
      <classpath>
        <pathelement location="lib/"/>
        <pathelement path="${java.class.path}/"/>
        <pathelement path="${additional.path}"/>
      </classpath>
    </javac>
  </target>
</project>
\end{verbatim}
could be rewritten as:
\begin{verbatim}
<project ... >
  <path id="project.class.path">
    <pathelement location="lib/"/>
    <pathelement path="${java.class.path}/"/>
    <pathelement path="${additional.path}"/>
  </path>

  <target ... >
    <rmic ...>
      <classpath refid="project.class.path"/>
    </rmic>
  </target>

  <target ... >
    <javac ...>
      <classpath refid="project.class.path"/>
    </javac>
  </target>
</project>
\end{verbatim}
All tasks that use nested elements for PatternSets, FileSets or
path-like structures accept references to these structures as well.

\subsection{Selectors}

Selectors are a mechanism whereby the files that make up a fileset can
be selected based on criteria other than filename as provided by the
{\tt <include>} and {\tt <exclude>} tags.

How to use a Selector
A selector is an element of FileSet, and appears within it. It can
also be defined outside of any target by using the {\tt <selector>} tag and
then using it as a reference.

Different selectors have different attributes. Some selectors can
contain other selectors, and these are called Selector
Containers. There is also a category of selectors that allow
user-defined extensions, called Custom Selectors. The ones built in to
Ant are called Core Selectors.

Core Selectors
Core selectors are the ones that come standard with Ant. They can be used within a fileset and can be contained within Selector Containers.

The core selectors are:

\begin{tabular}{|l|p{7 cm}|} \hline
{\tt <contains>} & Select files that contain a particular text string \\ \hline
{\tt <date>} & Select files that have been modified either before or after a particular date and time \\ \hline
{\tt <depend>} & Select files that have been modified more recently than equivalent files elsewhere \\ \hline
{\tt <depth>} & Select files that appear so many directories down in a directory tree \\ \hline
{\tt <filename>} & Select files whose name matches a particular pattern. Equivalent to the include and exclude elements of a patternset. \\ \hline
{\tt <present>} & Select files that either do or do not exist in some other location \\ \hline
{\tt <size>} & Select files that are larger or smaller than a particular number of bytes. \\ \hline
\end{tabular}

Contains Selector

The {\tt <contains>} tag in a FileSet limits the files defined by that
fileset to only those which contain the string specified by the text
attribute.

Attribute Description Required 
text Specifies the text that every file must contain  Yes 
casesensitive Whether to pay attention to case when looking for the string in the text attribute. Default is true.  No 

Here is an example of how to use the Contains Selector:
\begin{verbatim}
<fileset dir="${doc.path}" includes="**/*.html">
    <contains text="script" casesensitive="no"/>
</fileset>
\end{verbatim}
Selects all the HTML files that contain the string script.

Date Selector
The {\tt <date>} tag in a FileSet will put a limit on the files
specified by the include tag, so that tags whose last modified date
does not meet the date limits specified by the selector will not end
up being selected.

Attribute Description Required 
datetime Specifies the date and time to test for using a string of the
format MM/DD/YYYY HH:MM AM\_or\_PM.  At least one of the two.
millis The number of milliseconds since 1970 that should be tested for. It is usually much easier to use the datetime attribute.  
granularity The number of milliseconds leeway to give before deciding whether a files modification time matches a date. This is needed because not every file system supports tracking the last modified time to the millisecond level. The file will be selected provided the condition could be true were the granularity added or subtracted from the actual time. Default is 0 milliseconds except on Windows systems, where it is 2000 milliseconds (2 seconds).  No 
when Indicates how to interpret the date, whether the files to be selected are those whose last modified times should be before, after, or equal to the specified value. Acceptable values for this attribute are: 
before - select files whose last modified date is before the indicated date 
after - select files whose last modified date is after the indicated date 
equal - select files whose last modified date is this exact date 
The default is equal.  No 

Here is an example of how to use the Date Selector:
\begin{verbatim}
<fileset dir="${jar.path}" includes="**/*.jar">
    <date datetime="01/01/2001 12:00 AM" when="before"/>
</fileset>
\end{verbatim}
Selects all JAR files which were last modified before midnight January 1, 2001.

Depend Selector
The {\tt <depend>} tag selects files whose last modified date is later than
another, equivalent file in another location.

The {\tt <depend>} tag supports the use of a contained 
{\tt <mapper>} element to
define the location of the file to be compared against. 
If no {\tt <mapper>}
element is specified, the identity type mapper is used.

Attribute Description Required 

targetdir The base directory to look for the files to compare
against. The precise location depends on a combination of this
attribute and the {\tt <mapper>} element, if any.  Yes

granularity The number of milliseconds leeway to give before deciding
a file is out of date. This is needed because not every file system
supports tracking the last modified time to the millisecond
level. Default is 0 milliseconds except on Windows systems, where it
is 2000 milliseconds (2 seconds).  No

Here is an example of how to use the Depend Selector:
\begin{verbatim}
<fileset dir="${ant.1.5}/src/main" includes="**/*.java">
    <depend targetdir="${ant.1.4.1}/src/main"/>
</fileset>
\end{verbatim}
Selects all the Java source files which were modified in the 1.5 release. 

Depth Selector

The {\tt <depth>} tag selects files based on how many directy levels deep
they are in relation to the base directory of the fileset.

Attribute Description Required 
min The minimum number of directory levels below the base directory that a file must be in order to be selected. Default is no limit.  At least one of the two. 
max The maximum number of directory levels below the base directory that a file can be and still be selected. Default is no limit.  

Here is an example of how to use the Depth Selector:
\begin{verbatim}
<fileset dir="${doc.path}" includes="**/*">
    <depth max="1"/>
</fileset>
\end{verbatim}
Selects all files in the base directory and one directory below that.

Filename Selector

The {\tt <filename>} tag acts like the {\tt <include>} and {\tt <exclude>}
tags within a fileset. By using a selector instead, however, one can
combine it with all the other selectors using whatever selector
container is desired.

Attribute Description Required 
name The name of files to select. The name parameter can contain the standard Ant wildcard characters.  Yes 
casesensitive Whether to pay attention to case when looking at file names. Default is "true".  No 
negate Whether to reverse the effects of this filename selection, therefore emulating an exclude rather than include tag. Default is "false".  No 

Here is an example of how to use the Filename Selector:
\begin{verbatim}
<fileset dir="${doc.path}" includes="**/*">
    <filename name="**/*.css"/>
</fileset>
\end{verbatim}
Selects all the cascading style sheet files.

Present Selector

The {\tt <present>} tag selects files that have an equivalent file in
another directory tree.

The {\tt <present>} tag supports the use of a contained 
{\tt {\tt <mapper>}} element to
define the location of the file to be tested against. If no {\tt <mapper>}
element is specified, the identity type mapper is used.

Attribute Description Required 

targetdir The base directory to look for the files to compare
against. The precise location depends on a combination of this
attribute and the {\tt <mapper>} element, if any.  Yes

present Whether we are requiring that a file is present in the src directory tree only, or in both the src and the target directory tree. Valid values are: 
srconly - select files only if they are in the src directory tree but not in the target directory tree 
both - select files only if they are present both in the src and target directory trees 
Default is both. Setting this attribute to "srconly" is equivalent to wrapping the selector in 
the {\tt <not>} selector container.  No 

Here is an example of how to use the Present Selector:
\begin{verbatim}
<fileset dir="${ant.1.5}/src/main" includes="**/*.java">
    <present present="srconly" targetdir="${ant.1.4.1}/src/main"/>
</fileset>
\end{verbatim}
Selects all the Java source files which are new in the 1.5 release. 

Size Selector

The {\tt <size>} tag in a FileSet will put a limit on the files specified by
the include tag, so that tags which do not meet the size limits
specified by the selector will not end up being selected.

Attribute Description Required 
value The size of the file which should be tested for.  Yes 
units The units that the value attribute is expressed in. When using the standard single letter SI designations, such as "k","M", or "G", multiples of 1000 are used. If you want to use power of 2 units, use the IEC standard: "Ki" for 1024, "Mi" for 1048576, and so on. The default is no units, which means the value attribute expresses the exact number of bytes.  No 
when Indicates how to interpret the size, whether the files to be selected should be larger, smaller, or equal to that value. Acceptable values for this attribute are: 
less - select files less than the indicated size 
more - select files greater than the indicated size 
equal - select files this exact size 
The default is equal.  No 

Here is an example of how to use the Size Selector:
\begin{verbatim}
<fileset dir="${jar.path}">
  <patternset>
    <include name="**/*.jar"/>
  </patternset>
  <size value="4" units="Ki" when="more"/>
</fileset>
\end{verbatim}
Selects all JAR files that are larger than 4096 bytes.

Selector Containers
To create more complex selections, a variety of selectors that contain
other selectors are available for your use. They combine the
selections of their child selectors in various ways.

The selector containers are:

\begin{tabular}{|l|p{8 cm}|} \hline
{\tt <and>} & select a file only if all the contained selectors select it. \\ \hline
{\tt <majority>} & select a file if a majority of its selectors select it. \\ \hline
{\tt <none>} & select a file only if none of the contained selectors select it. \\ \hline
{\tt <not>} & can contain only one selector, and reverses what it selects and doesn't select. \\ \hline
{\tt <or>} & selects a file if any one of the contained selectors selects it. \\ \hline
{\tt <selector>} & contains only one selector and forwards all requests to it without alteration. This is the selector to use if you want to define a reference. 
     It is usable as an element of {\tt <project>}. \\ \hline
\end{tabular}

All selector containers can contain any other selector, 
including other containers, as an element. Using containers, 
the selector tags can be arbitrarily deep. 
Here is a complete list of allowable selector 
elements within a container:
\begin{verbatim}
<and>
<contains>
<custom> 
<date> 
<depend> 
<depth> 
<filename> 
<majority> 
<none> 
<not> 
<or> 
<present> 
<selector> 
<size> 
\end{verbatim}
And Selector
The {\tt <and>} tag selects files that are selected by all of the elements
it contains. It returns as soon as it finds a selector that does not
select the file, so it is not guaranteed to check every selector.

Here is an example of how to use the And Selector:
\begin{verbatim}
<fileset dir="${dist}" includes="**/*.jar">
    <and>
        <size value="4" units="Ki" when="more"/>
        <date datetime="01/01/2001 12:00 AM" when="before"/>
    </and>
</fileset>
\end{verbatim}
Selects all the JAR file larger than 4096 bytes which haven't been
update since the last millenium.

Majority Selector
The {\tt <majority>} tag selects files provided that a majority of the
contained elements also select it. Ties are dealt with as specified by
the allowtie attribute.

Attribute Description Required 
allowtie Whether files should be selected if there are an even number of selectors selecting them as are not selecting them. Default is true.  No 

Here is an example of how to use the Majority Selector:
\begin{verbatim}
<fileset dir="${docs}" includes="**/*.html">
    <majority>
        <contains text="project" casesensitive="false"/>
        <contains text="taskdef" casesensitive="false"/>
        <contains text="IntrospectionHelper" casesensitive="true"/>
    </majority>
</fileset>
\end{verbatim}
Selects all the HTML files which contain at least two of the three
phrases "project", "taskdef", and "IntrospectionHelper" (this last
phrase must match case exactly).

None Selector

The {\tt <none>} tag selects files that are not selected by any of the
elements it contains. It returns as soon as it finds a selector that
selects the file, so it is not guaranteed to check every selector.

Here is an example of how to use the None Selector:
\begin{verbatim}
<fileset dir="${src}" includes="**/*.java">
    <none>
        <present targetdir="${dest}"/>
        <present targetdir="${dest}">
            <mapper type="glob" from="*.java" to="*.class"/>
        </present>
    </none>
</fileset>
\end{verbatim}
Selects only Java files which do not have equivalent java or class
files in the dest directory.

Not Selector
The {\tt <not>} tag reverses the meaning of the single selector it contains. 

Here is an example of how to use the Not Selector:
\begin{verbatim}
<fileset dir="${src}" includes="**/*.java">
    <not>
        <contains text="test"/>
    </not>
</fileset>
\end{verbatim}
Selects all the files in the src directory that do not contain the
string "test".

Or Selector

The {\tt <or>} tag selects files that are selected by any one of the
elements it contains. It returns as soon as it finds a selector that
selects the file, so it is not guaranteed to check every selector.

Here is an example of how to use the Or Selector:
\begin{verbatim}
<fileset dir="${basedir}">
    <or>
        <depth max="0"/>
        <filename name="*.png"/>
        <filename name="*.gif"/>
        <filename name="*.jpg"/>
    </or>
</fileset>
\end{verbatim}

Selects all the files in the top directory along with all the image
files below it.

Selector Reference

The {\tt <selector>} tag is used to create selectors that can be reused
through references. It is the only selector which can be used outside
of any target, as an element of the {\tt <project>} tag. It can contain only
one other selector, but of course that selector can be a container.

Here is an example of how to use the Selector Reference:
\begin{verbatim}
<project default="all" basedir="./ant">

    <selector id="completed">
        <none>
            <depend targetdir="build/classes">
                <mapper type="glob" from="*.java" to="*.class"/>
            </depend>
            <depend targetdir="docs/manual/api">
                <mapper type="glob" from="*.java" to="*.html"/>
            </depend>
        </none>
    </selector>

    <target>
        <zip>
            <fileset dir="src/main" includes="**/*.java">
                <selector refid="completed"/>
            </fileset>
        </zip>
    </target>

</project>
\end{verbatim}
Zips up all the Java files which have an up-to-date equivalent class
file and javadoc file associated with them.

Custom Selectors

You can write your own selectors and use them within the selector
containers by specifying them within the <custom> tag.

First, you have to write your selector class in Java. The only
requirement it must meet in order to be a selector is that it
implements the\hfil\break
{\tt org.apache.tools.ant.types.selectors.FileSelector}
interface, which contains a single method. See Programming Selectors
in Ant for more information.

Once that is written, you include it in your build file by using the
{\tt <custom>} tag.

Attribute Description Required 
classname The name of your class that implements org.apache.tools.ant.types.selectors.FileSelector.  Yes 
classpath The classpath to use in order to load the custom selector class. If neither this classpath nor the classpathref are specified, the class will be loaded from the classpath that Ant uses.  No 
classpathref A reference to a classpath previously defined. If neither this reference nor the classpath above are specified, the class will be loaded from the classpath that Ant uses.  No 

Here is how you use {\tt <custom>} to use your class as a selector: 
\begin{verbatim}
<fileset dir="${mydir}" includes="**/*">
    <custom classname="com.mydomain.MySelector">
        <param name="myattribute" value="myvalue"/>
    </custom>
</fileset>
\end{verbatim}

A number of core selectors can also be used as custom selectors by
specifying their attributes using {\tt <param>} elements. These are

Contains Selector with classname org.apache.tools.ant.types.selectors.ContainsSelector 
Date Selector with classname org.apache.tools.ant.types.selectors.DateSelector 
Depth Selector with classname org.apache.tools.ant.types.selectors.DepthSelector 
Filename Selector with classname org.apache.tools.ant.types.selectors.FilenameSelector 
Size Selector with classname org.apache.tools.ant.types.selectors.SizeSelector 

Here is the example from the Depth Selector section rewritten to use
the selector through {\tt <custom>}.

\begin{verbatim}
<fileset dir="${doc.path}" includes="**/*">
    <custom classname="org.apache.tools.ant.types.selectors.DepthSelector">
        <param name="max" value="1"/>
    </custom>
</fileset>
\end{verbatim}
Selects all files in the base directory and one directory below that.

For more details concerning writing your own selectors, consult
Programming Selectors in Ant.

\subsection{XMLCatalog}

An XMLCatalog is a catalog of public resources such as DTDs or
entities that are referenced in an XML document. Catalogs are
typically used to make web references to resources point to a locally
cached copy of the resource.

This allows the XML Parser, XSLT Processor or other consumer of XML
documents to efficiently allow a local substitution for a resource
available on the web.

This data type provides a catalog of resource locations based on the
OASIS "Open Catalog" standard. The catalog entries are used both for
Entity resolution and URI resolution, in accordance with the
org.xml.sax.EntityResolver and javax.xml.transform.URIResolver
interfaces as defined in the Java API for XML Processing (JAXP)
Specification.

For example, in a web.xml file, the DTD is referenced as: 
\begin{verbatim}
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
  "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
\end{verbatim}

The XML processor, without XMLCatalog support, would need to retrieve
the DTD from the URL specified whenever validation of the document was
required.

This can be very time consuming during the build process, especially
where network throughput is limited. Alternatively, you can do the
following:

Copy web-app\_2\_2.dtd onto your local disk somewhere (either in the filesystem or even embedded inside a jar or zip file on the classpath). 

Create an {\tt <xmlcatalog>} with a {\tt <dtd>} 
element whose location attribute points to the file.

Success! The XML processor will now use the local copy instead of
calling out to the internet.

XMLCatalogs can appear inside tasks that support this feature or at
the same level as target - i.e., as children of project for reuse
across different tasks, e.g. XML Validation and XSLT
Transformation. The XML Validate task uses XMLCatalogs for entity
resolution. The XSLT Transformation task uses XMLCatalogs for both
entity and URI resolution.

XMLCatalogs are specified as either a reference to another XMLCatalog, defined previously in a build file, or as a list of dtd or entity locations. A separate classpath for entity resolution may be specified inline via nested classpath elements; otherwise the system classpath is used for this as well.

XMLCatalogs can also be nested inside other XMLCatalogs. For example, a "superset" XMLCatalog could be made by including several nested XMLCatalogs that referred to other, previously defined XMLCatalogs.

Currently, only {\tt <dtd>} and {\tt <entity>}
elements may be specified inline;
these roughly correspond to OASIS catalog entry types PUBLIC and URI
respectively.

Entity/DTD/URI Resolution Algorithm
When an entity, DTD, or URI is looked up by the XML processor, the XMLCatalog searches its list of entries to see if any match. That is, it attempts to match the publicId attribute of each entry with the PublicID or URI of the entity to be resolved. Assuming a matching entry is found, XMLCatalog then executes the following steps: 
1. Filesystem lookup
The location is first looked up in the filesystem. If the location is a relative path, the ant project basedir attribute is used as the base directory. If the location specifies an absolute path, it is used as is. Once we have an absolute path in hand, we check to see if a valid and readable file exists at that path. If so, we are done. If not, we proceed to the next step.

2. Classpath lookup
The location is next looked up in the classpath. Recall that jar files are merely fancy zip files. For classpath lookup, the location is used as is (no base is prepended). We use a Classloader to attempt to load the resource from the classpath. For example, if hello.jar is in the classpath and it contains foo/bar/blat.dtd it will resolve an entity whose location is foo/bar/blat.dtd. Of course, it will not resolve an entity whose location is blat.dtd. 

3. URL-space lookup
Finally, we attempt to make a URL out of the location. At first this may seem like this would defeat the purpose of XMLCatalogs -- why go back out to the internet? But in fact, this can be used to (in a sense) implement HTTP redirects, substituting one URL for another. The mapped-to URL might also be served by a local web server. If the URL resolves to a valid and readable resource, we are done. Otherwise, we give up. In this case, the XML processor will perform its normal resolution algorithm. Depending on the processor configuration, further resolution failures may or may not result in fatal (i.e. build-ending) errors.

XMLCatalog attributes
Attribute Description Required 
id a unique name for an XMLCatalog, used for referencing the XMLCatalog's contents from another XMLCatalog No 
refid the id of another XMLCatalog whose contents you would like to be used for this XMLCatalog No 

XMLCatalog nested elements
dtd/entity
The dtd and entity elements used to specify XMLCatalogs are identical in their structure

Attribute Description Required 
publicId The public identifier used when defining a dtd or entity, e.g. "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"  Yes 
location The location of the local replacement to be used for the public identifier specified. This may be specified as a file name, resource name found on the classpath, or a URL. Relative paths will be resolved according to the base, which by default is the Ant project basedir.  Yes 

classpath

The classpath to use for entity resolution. 
The nested {\tt <classpath>} is
a path-like structure.

Examples

Set up an XMLCatalog with a single dtd referenced locally in a user's
home directory:
\begin{verbatim}
    <xmlcatalog>
        <dtd 
            publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
            location="/home/dion/downloads/docbook/docbookx.dtd"/>
    </xmlcatalog>
\end{verbatim}
Set up an XMLCatalog with a multiple dtds to be found either in the
filesystem (relative to the Ant project basedir) or in the classpath:
\begin{verbatim}
    <xmlcatalog id="commonDTDs">
        <dtd 
            publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
            location="docbook/docbookx.dtd"/>
        <dtd 
            publicId="-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
            location="web-app_2_2.dtd"/>
    </xmlcatalog>
\end{verbatim}
Set up an XMLCatalog with a combination of DTDs and entities as well as a nested XMLCatalog:
\begin{verbatim}
    <xmlcatalog id="allcatalogs">
        <dtd 
            publicId="-//ArielPartners//DTD XML Article V1.0//EN"
            location="com/arielpartners/knowledgebase/dtd/article.dtd"/>
        <entity 
            publicId="LargeLogo"
            location="com/arielpartners/images/ariel-logo-large.gif"/>
        <xmlcatalog refid="commonDTDs"/>
    </xmlcatalog>
\end{verbatim}
To reference the above XMLCatalog in an xslt task:
\begin{verbatim}
    <xslt basedir="${source.doc}"
           destdir="${dest.xdocs}"
           extension=".xml"
           style="${source.xsl.converter.docbook}"
           includes="**/*.xml"
           force="true">
        <xmlcatalog refid="allcatalogs"/>
    </xslt>
\end{verbatim}

\section{Optional Types}

\subsection{ClassFileSet}

A classfileset is a specialised type of fileset which, given a set of
"root" classes, will include all of the class files upon which the
root classes depend. This is typically used to create a jar with all
of the required classes for a particular application.

classfilesets are typically used by reference. They are declared with
an "id" value and this is then used as a reference where a normal
fileset is expected.

This type requires the jakarta-BCEL library. 

Attributes
The class fileset support the following attributes in addition to those supported by the standard fileset: 

Attribute Description Required 
rootclass A single root class name No 

Nested Elements
Root

When more than one root class is required, multiple nested 
{\tt <root>} elements may be used

Attribute Description Required 
classname The fully qualified name of the root class Yes 

RootFileSet

A root fileset is used to add a set of root classes from a fileset. In
this case the entries in the fileset are expected to be Java class
files. The name of the Java class is determined by the relative
location of the classfile in the fileset. So, the file
org/apache/tools/ant/Project.class corresponds to the Java class
org.apache.tools.ant.Project.

Examples
\begin{verbatim}
<classfileset id="reqdClasses" dir="${classes.dir}">
  <root classname="org.apache.tools.ant.Project" />
</classfileset>
\end{verbatim}
This example creates a fileset containing all the class files upon which the org.apache.tools.ant.Project class depends. This fileset could then be used to create a jar. 
\begin{verbatim}
<jar destfile="minimal.jar">
  <fileset refid="reqdClasses"/>
</jar>

<classfileset id="reqdClasses" dir="${classes.dir}">
  <rootfileset dir="${classes.dir}" includes="org/apache/tools/ant/Project*.class"/>
</classfileset>
\end{verbatim}

This example constructs the classfileset using all the class with
names starting with Project in the org.apache.tools.ant package

\subsection{Extension Package}

Utility type that represents either an available "Optional Package"
(formerly known as "Standard Extension") as described in the manifest
of a JAR file, or the requirement for such an optional package.

Note that this type works with extensions as defined by the "Optional
Package" specification. For more information about optional packages,
see the document Optional Package Versioning in the documentation
bundle for your Java2 Standard Edition package, in file
guide/extensions/versioning.html or online at
http://java.sun.com/j2se/1.3/docs/guide/extensions/versioning.html.

Attributes
The extension type supports the following attributes: 

Attribute Description Required 
extensionName The name of extension yes 
specificationVersion The version of extension specification (Must be in dewey decimal aka dotted decimal notation. 3.2.4) no 
specificationVendor The specification vendor no 
implementationVersion The version of extension implementation (Must be in dewey decimal aka dotted decimal notation. 3.2.4) no 
implementationVendor The implementation vendor no 
implementationVendorId The implementation vendor ID no 
implementationURL The url from which to retrieve extension. no 

Examples
\begin{verbatim}
<extension id="e1"
    extensionName="MyExtensions"
    specificationVersion="1.0"
    specificationVendor="Peter Donald"
    implementationVendorID="vv"
    implementationVendor="Apache"
    implementationVersion="2.0"
    implementationURL="http://somewhere.com/myExt.jar"/>
\end{verbatim}
Fully specifiec extension object.
\begin{verbatim}
<extension id="e1"
    extensionName="MyExtensions"
    specificationVersion="1.0"
    specificationVendor="Peter Donald"/>
\end{verbatim}
Extension object that just species the specification details.

\subsection{Set of Extension Packages}

Utility type that represents a set of Extensions.

Note that this type works with extensions as defined by the "Optional
Package" specification. For more information about optional packages,
see the document Optional Package Versioning in the documentation
bundle for your Java2 Standard Edition package, in file
guide/extensions/versioning.html or online at
http://java.sun.com/j2se/1.3/docs/guide/extensions/versioning.html.

Nested Elements
extension
Extension object to add to set.

fileset
FileSets all files contained contained within set that are jars and
implement an extension are added to extension set.

LibFileSet
All files contained contained within set that are jars and implement an extension are added to extension set. However the extension information may be modified by attributes of libfileset

Examples
\begin{verbatim}
<extension id="e1"
    extensionName="MyExtensions"
    specificationVersion="1.0"
    specificationVendor="Peter Donald"
    implementationVendorID="vv"
    implementationVendor="Apache"
    implementationVersion="2.0"
    implementationURL="http://somewhere.com/myExt.jar"/>

<libfileset id="lfs"
               includeUrl="true"
               includeImpl="false"
               dir="tools/lib">
  <include name="*.jar"/>
</libfileset>

<extensionSet id="exts">
  <libfileset dir="lib">
    <include name="*.jar"/>
  </libfileset>
  <libfileset refid="lfs"/>
  <extension refid="e1"/>
</extensionSet>
\end{verbatim}
\chapter{Loggers and Listeners}

\section{Overview}

Ant has two related features to allow the build process to be
monitored: listeners and loggers.

Listeners
A listener is alerted of the following events:

build started 
build finished 
target started 
target finished 
task started 
task finished 
message logged 
Loggers
Loggers extend the capabilities of listeners and add the following features:

Receives a handle to the standard output and error print streams and therefore can log information to the console or the -logfile specified file. 
Logging level (-quiet, -verbose, -debug) aware 
Emacs-mode aware 
Built-in Listeners/Loggers
Classname Description Type 
org.apache.tools.ant.DefaultLogger The logger used implicitly unless overridden with the -logger command-line switch. BuildLogger 
org.apache.tools.ant.NoBannerLogger This logger omits output of empty target output. BuildLogger 
org.apache.tools.ant.listener.MailLogger Extends DefaultLogger such that output is still generated the same, and when the build is finished an e-mail can be sent. BuildLogger 
org.apache.tools.ant.listener.AnsiColorLogger Colorifies the build output. BuildLogger 
org.apache.tools.ant.listener.Log4jListener Passes events to Log4j for highly customizable logging. BuildListener 
org.apache.tools.ant.XmlLogger Writes the build information to an XML file. BuildLogger 

DefaultLogger
Simply run Ant normally, or:

ant -logger org.apache.tools.ant.DefaultLogger

NoBannerLogger
Removes output of empty target output.

ant -logger org.apache.tools.ant.NoBannerLogger

MailLogger
The MailLogger captures all output logged through DefaultLogger (standard Ant output) and will send success and failure messages to unique e-mail lists, with control for turning off success or failure messages individually.

Properties controlling the operation of MailLogger:

Property Description Required 
MailLogger.mailhost  Mail server to use No, default "localhost" 
MailLogger.from Mail "from" address Yes, if mail needs to be sent 
MailLogger.failure.notify  Send build failure e-mails? No, default "true" 
MailLogger.success.notify  Send build success e-mails? No, default "true" 
MailLogger.failure.to  Address(es) to send failure messages to, comma-separated Yes, if failure mail is to be sent 
MailLogger.success.to  Address(es) to send success messages to, comma-separated Yes, if success mail is to be sent 
MailLogger.failure.subject  Subject of failed build No, default "Build Failure" 
MailLogger.success.subject  Subject of successful build No, default "Build Success" 
MailLogger.properties.file  Filename of properties file that will override other values. No 

ant -logger org.apache.tools.ant.listener.MailLogger

AnsiColorLogger
The AnsiColorLogger adds color to the standard Ant output by prefixing and suffixing ANSI color code escape sequences to it. It is just an extension of DefaultLogger and hence provides all features that DefaultLogger does.

AnsiColorLogger differentiates the output by assigning different colors depending upon the type of the message.

If used with the -logfile option, the output file will contain all the necessary escape codes to display the text in colorized mode when displayed in the console using applications like cat, more, etc.

This is designed to work on terminals that support ANSI color codes. It works on XTerm, ETerm, Win9x Console (with ANSI.SYS loaded.), etc.

NOTE: It doesn't work on WinNT even when a COMMAND.COM console loaded with ANSI.SYS is used.

If the user wishes to override the default colors with custom ones, a file containing zero or more of the custom color key-value pairs must be created. The recognized keys and their default values are shown below:
\begin{verbatim}
AnsiColorLogger.ERROR_COLOR=2;31
AnsiColorLogger.WARNING_COLOR=2;35
AnsiColorLogger.INFO_COLOR=2;36
AnsiColorLogger.VERBOSE_COLOR=2;32
AnsiColorLogger.DEBUG_COLOR=2;34
\end{verbatim}
Each key takes as value a color combination defined as Attribute;Foreground;Background. In the above example, background value has not been used.

This file must be specfied as the value of a system variable named
ant.logger.defaults and passed as an argument using the -D option to
the java command that invokes the Ant application. An easy way to
achieve this is to add -Dant.logger.defaults= /path/to/your/file to
the {\tt ANT\_OPTS} environment variable. Ant's launching script recognizes
this flag and will pass it to the java command appropriately.

Format:
\begin{verbatim}
AnsiColorLogger.*=Attribute;Foreground;Background
\end{verbatim}
Attribute is one of the following:
\begin{verbatim}
0 -> Reset All Attributes (return to normal mode)
1 -> Bright (Usually turns on BOLD)
2 -> Dim
3 -> Underline
5 -> link
7 -> Reverse
8 -> Hidden
\end{verbatim}
Foreground is one of the following:
\begin{verbatim}
30 -> Black
31 -> Red
32 -> Green
33 -> Yellow
34 -> Blue
35 -> Magenta
36 -> Cyan
37 -> White
\end{verbatim}
Background is one of the following:
\begin{verbatim}
40 -> Black
41 -> Red
42 -> Green
43 -> Yellow
44 -> Blue
45 -> Magenta
46 -> Cyan
47 -> White
ant -logger org.apache.tools.ant.listener.AnsiColorLogger
\end{verbatim}
Log4jListener
Passes build events to Log4j, using the full classname's of the generator of each build event as the category:

build started / build finished - org.apache.tools.ant.Project 
target started / target finished - org.apache.tools.ant.Target 
task started / task finished - the fully qualified classname of the task 
message logged - the classname of one of the above, so if a task logs a message, its classname is the category used, and so on. 
All start events are logged as INFO.  Finish events are either logged as INFO or ERROR depending on whether the build failed during that stage. Message events are logged according to their Ant logging level, mapping directly to a corresponding Log4j level.

ant -listener org.apache.tools.ant.listener.Log4jListener

XmlLogger
Writes all build information out to an XML file named log.xml, or the value of the XmlLogger.file property if present, when used as a listener. When used as a logger, it writes all output to either the console or to the value of -logfile. Whether used as a listener or logger, the output is not generated until the build is complete, as it buffers the information in order to provide timing information for task, targets, and the project. 

By default the XML file creates a reference to an XSLT file "log.xsl" in the current directory; look in {\tt ANT\_HOME}/etc for one of these. You can set the property ant.XmlLogger.stylesheet.uri to provide a uri to a style sheet. this can be a relative or absolute file path, or an http URL. If you set the property to the empty string, "", no XSLT transform is declared at all. 

ant -listener org.apache.tools.ant.XmlLogger
ant -logger org.apache.tools.ant.XmlLogger -verbose -logfile build\_log.xml

Writing your own
See the Build Events section for developers.

Notes:

A listener or logger should not write to standard output or error -
Ant captures these internally and may cause an infinite loop.

\chapter{Editor/IDE Integration}

All the modern Java IDEs support Ant almost out the box, with the
notable exception of JBuilder Personal.

\section{Antidote}

Version 0.1 (2001/02/13)

Authors: Simeon H.K. Fitch 

\subsection{Overview}

Antidote is the Ant subproject for developing a graphical user
interface to facilitate the efficient use of Ant. In general, its
purpose is to allow the quick generation, modification, and use of Ant
build files, helping the user define a build process and track down
build problems. It is not meant to be an IDE, but an enabler for the
powerful features available in Ant, particularly for novice users, or
users who want a rapid way of controlling their build process.

Status
Antidote is still in the early stages of development, but does have a set of usable features, including:

Reading Ant build files. 
Selecting targets and executing them. 
Context highlighted build status console. 
Modification of (some) build file components. 
Saving modified build file. 
Current development tasks include:

A more complete set of target and task editing capabilities. 
A wizard for creating basic build files, including importing existing code bases. 
Better build progress monitoring. 
The Antidote source distribution comes with requirements and design documentation that better cover the details of application architecture, how to develop against it, and what the long term goals are. Furthermore, there is a TODO file listing the detailed, near-term tasks that need accomplishing.

Getting Involved
The source code for Antidote is located in a separate Module (ant-antidote) in CVS. All the existing documentation can be found there where new contributors should read:

Design Overview 
Feature List 
Idea Refinement 
New Module HOWTO 
Static Class Diagrams 
Online discussions about Antidote occur on the Ant developer mailing list. The application infrastructure is fairly complete, but there are almost unlimited opportunities for feature contributions.

Aspiring contributors new to the project should (carefully) read the following for details on the contribution process:

Get Involved 
Project Guidelines 
Source Repositories (how to contribute patches) 

\section {AntRunner for JBuilder}

Documentation may be found at
{\tt http://antrunner.sourceforge.net/}

\section{AntWork Plugin for the Jext - Java Text Editor}

by
\begin{verbatim}
Klaus Hartlage (KHartlage@t-online.de) 
Version $Revision: 1.3.2.1 $ - $Date: 2002/09/03 15:27:58 $
\end{verbatim}

You can download the plugin at:
ftp://jext.sourceforge.net/pub/jext/plugins/AntWork.zip

Installation instructions from the Readme.txt:
You have to enable the Jext Console to see the Ant output (menu: Edit->Options... - General Panel), because the Ant messages are redirected to the Jext console.

You can configure the Ant call in the Jext menu: Edit->Options... - Plugin Options - Antwork Plugin Panel; here you can set the ant home directory and the path to your build file.

You can start AntWork in the menu: Plugins->Ant->Work Now! In the appearing dialog box you can enter the target which you want to compile.

If a javac error occurs in the ant run an error-list opens within
Jext. With a double-click on the error-message you jump to the error
in the specified java text file.

\section{Emacs}

Emacs JDE has built-in text ANT integration: selection of target
through text field, execution, hyperlink to compilation
errors. Installation: built-in JDE 2.2.8 or later. Configuration:
through customize menu "Jde Build Function"

\section{IDEA}

IDEA has built-in GUI ANT integration: GUI selection of targets,
execution, hyperlink to compilation errors

NetBeans NetBeans 3.4 has very good Ant integration indeed. 

jEdit jEdit is an open source java IDE with some great plugins for
Java dev, a good XML editor and the Antfarm plugin to execute targets
in a build file.

Eclipse Eclipse is IBM's counterpoint to NetBeans; an open source IDE
with Java and ant support.

VisualAge for Java

WebSphere Studio Application Developer

\chapter{Developing with Ant}

\section{Writing Your Own Task}

It is very easy to write your own task:

Create a Java class that extends org.apache.tools.ant.Task or another class that was desgined to be extended. 
For each attribute, write a setter method. The setter method must be a public void method that takes a single argument. The name of the method must begin with set, followed by the attribute name, with the first character of the name in uppercase, and the rest in lowercase. That is, to support an attribute named file you create a method setFile. Depending on the type of the argument, Ant will perform some conversions for you, see below. 
If your task shall contain other tasks as nested elements (like parallel), your class must implement the interface org.apache.tools.ant.TaskContainer. If you do so, your task can not support any other nested elements. See below. 
If the task should support character data (text nested between the start end end tags), write a public void addText(String) method. Note that Ant does not expand properties on the text it passes to the task. 
For each nested element, write a create, add or addConfigured method. A create method must be a public method that takes no arguments and returns an Object type. The name of the create method must begin with create, followed by the element name. An add (or addConfigured) method must be a public void method that takes a single argument of an Object type with a no-argument constructor. The name of the add (addConfigured) method must begin with add (addConfigured), followed by the element name. For a more complete discussion see below. 
Write a public void execute method, with no arguments, that throws a BuildException. This method implements the task itself. 
The Life-cycle of a Task
The task gets instantiated using a no-argument constructor, at parser time. This means even tasks that are never executed get instantiated. 
The task gets references to its project and location inside the buildfile via its inherited project and location variables. 
If the user specified an id attribute to this task, the project registers a reference to this newly created task, at parser time. 
The task gets a reference to the target it belongs to via its inherited target variable. 
init() is called at parser time. 
All child elements of the XML element corresponding to this task are created via this task's createXXX() methods or instantiated and added to this task via its addXXX() methods, at parser time. 
All attributes of this task get set via their corresponding setXXX methods, at runtime. 
The content character data sections inside the XML element corresponding to this task is added to the task via its addText method, at runtime. 
All attributes of all child elements get set via their corresponding setXXX methods, at runtime. 
execute() is called at runtime. While the above initialization steps only occur once, the execute() method may be called more than once, if the task is invoked more than once. For example, if target1 and target2 both depend on target3, then running 'ant target1 target2' will run all tasks in target3 twice. 
Conversions Ant will perform for attributes
Ant will always expand properties before it passes the value of an attribute to the corresponding setter method.

The most common way to write an attribute setter is to use a java.lang.String argument. In this case Ant will pass the literal value (after property expansion) to your task. But there is more! If the argument of you setter method is

boolean, your method will be passed the value true if the value specified in the build file is one of true, yes, or on and false otherwise. 
char or java.lang.Character, your method will be passed the first character of the value specified in the build file. 
any other primitive type (int, short and so on), Ant will convert the value of the attribute into this type, thus making sure that you'll never receive input that is not a number for that attribute. 
java.io.File, Ant will first determine whether the value given in the build file represents an absolute path name. If not, Ant will interpret the value as a path name relative to the project's basedir. 
org.apache.tools.ant.types.Path, Ant will tokenize the value specified in the build file, accepting : and ; as path separators. Relative path names will be interpreted as relative to the project's basedir. 
java.lang.Class, Ant will interpret the value given in the build file as a Java class name and load the named class from the system class loader. 
any other type that has a constructor with a single String argument, Ant will use this constructor to create a new instance from the value given in the build file. 
A subclass of org.apache.tools.ant.types.EnumeratedAttribute, Ant will invoke this classes setValue method. Use this if your task should support enumerated attributes (attributes with values that must be part of a predefined set of values). See org/apache/tools/ant/taskdefs/FixCRLF.java and the inner AddAsisRemove class used in setCr for an example. 
What happens if more than one setter method is present for a given attribute? A method taking a String argument will always lose against the more specific methods. If there are still more setters Ant could chose from, only one of them will be called, but we don't know which, this depends on the implementation of your Java virtual machine.

Supporting nested elements
Let's assume your task shall support nested elements with the name inner. First of all, you need a class that represents this nested element. Often you simply want to use one of Ant's classes like org.apache.tools.ant.types.FileSet to support nested fileset elements.

Attributes of the nested elements or nested child elements of them will be handled using the same mechanism used for tasks (i.e. setter methods for attributes, addText for nested text and create/add/addConfigured methods for child elements).

Now you have a class NestedElement that is supposed to be used for
your nested {\tt <inner>} elements, you have three options:

public NestedElement createInner() 
public void addInner(NestedElement anInner) 
public void addConfiguredInner(NestedElement anInner) 
What is the difference?

Option 1 makes the task create the instance of NestedElement, there
are no restrictions on the type. For the options 2 and 3, Ant has to
create an instance of NestedInner before it can pass it to the task,
this means, NestedInner must have a public no-arg constructor. This is
the only difference between options 1 and 2.

The difference between 2 and 3 is what Ant has done to the object before it passes it to the method. addInner will receive an object directly after the constructor has been called, while addConfiguredInner gets the object after the attributes and nested children for this new object have been handled.

What happens if you use more than one of the options? Only one of the methods will be called, but we don't know which, this depends on the implementation of your Java virtual machine.

TaskContainer
The TaskContainer consists of a single method, addTask that basically is the same as an add method for nested elements. The task instances will be configured (their attributes and nested elements have been handled) when your task's execute method gets invoked, but not before that.

When we said execute would be called, we lied ;-). In fact, Ant will call the perform method in org.apache.tools.ant.Task, which in turn calls execute. This method makes sure that Build Events will be triggered. If you execute the task instances nested into your task, you should also invoke perform on these instances instead of execute.

Example

Let's write our own task, which prints a message on the System.out
stream. The task has one attribute, called message.
\begin{verbatim}
package com.mydomain;

import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.Task;

public class MyVeryOwnTask extends Task {
    private String msg;

    // The method executing the task
    public void execute() throws BuildException {
        System.out.println(msg);
    }

    // The setter for the "message" attribute
    public void setMessage(String msg) {
        this.msg = msg;
    }
}
\end{verbatim}
It's really this simple ;-)

Adding your task to the system is rather simple too:

Make sure the class that implements your task is in the classpath when starting Ant. 

Add a {\tt <taskdef>} element to your project. This actually adds your task
to the system.

Use your task in the rest of the buildfile. 
Example
\begin{verbatim}
<?xml version="1.0"?>

<project name="OwnTaskExample" default="main" basedir=".">
  <taskdef name="mytask" classname="com.mydomain.MyVeryOwnTask"/>

  <target name="main">
    <mytask message="Hello World! MyVeryOwnTask works!"/>
  </target>
</project>
\end{verbatim}
Example 2

To use a task directly from the buildfile which created it, place the
{\tt <taskdef>} declaration inside a target after the compilation. Use the
classpath attribute of {\tt <taskdef>} to point to where the code has just
been compiled.

\begin{verbatim}
<?xml version="1.0"?>

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

  <target name="build" >
    <mkdir dir="build"/>
    <javac srcdir="source" destdir="build"/>
  </target>

  <target name="declare" depends="build">
    <taskdef name="mytask"
        classname="com.mydomain.MyVeryOwnTask"
        classpath="build"/>
  </target>

  <target name="main" depends="declare">
    <mytask message="Hello World! MyVeryOwnTask works!"/>
  </target>
</project>
\end{verbatim}
Another way to add a task (more permanently), is to add the task name
and implementing class name to the default.properties file in the
org.apache.tools.ant.taskdefs package. Then you can use it as if it
were a built-in task.

Build Events

Ant is capable of generating build events as it performs the tasks
necessary to build a project. Listeners can be attached to Ant to
receive these events. This capability could be used, for example, to
connect Ant to a GUI or to integrate Ant with an IDE.

To use build events you need to create an ant Project object. You can then call the addBuildListener method to add your listener to the project. Your listener must implement the org.apache.tools.antBuildListener interface. The listener will receive BuildEvents for the following events

Build started 
Build finished 
Target started 
Target finished 
Task started 
Task finished 
Message logged 
If you wish to attach a listener from the command line you may use the -listener option. For example:

ant -listener org.apache.tools.ant.XmlLogger
will run Ant with a listener that generates an XML representation of the build progress. This listener is included with Ant, as is the default listener, which generates the logging to standard output.

Note: A listener must not access System.out and System.err directly since ouput on these streams is redirected by Ant's core to the build event system. Accessing these streams can cause an infinite loop in Ant. Depending on the version of Ant, this will either cause the build to terminate or the Java VM to run out of Stack space. A logger, also, may not access System.out and System.err directly. It must use the streams with which it has been configured. 


--------------------------------------------------------------------------------

Source code integration
The other way to extend Ant through Java is to make changes to
existing tasks, which is positively encouraged. Both changes to the
existing source and new tasks can be incorporated back into the Ant
codebase, which benefits all users and spreads the maintenance load
around.  Please consult the Getting Involved pages on the Jakarta web
site for details on how to fetch the latest source and how to submit
changes for reincorporation into the source tree.

Ant also has some task guidelines which provides some advice to people
developing and testing tasks. Even if you intend to keep your tasks to
yourself, you should still read this as it should be informative.

\section{Tasks Desgined for Extension}

These classes are desgined to be extended. Always start here when writting your own task. Class  Description  
Task  Base class for all tasks.  
AbstractCvsTask  Another task can extend this with some customized output processing  
JDBCTask  Handles JDBC configuration needed by SQL type tasks.  
MatchingTask  This is an abstract task that should be used by all those tasks that require to include or exclude files based on pattern matching.  
Pack  Abstract Base class for pack tasks.  
Unpack  Abstract Base class for unpack tasks.  

\section{Build Events}

Ant is capable of generating build events as it performs the tasks
necessary to build a project. Listeners can be attached to Ant to
receive these events. This capability could be used, for example, to
connect Ant to a GUI or to integrate Ant with an IDE.

To use build events you need to create an ant Project object. You can
then call the addBuildListener method to add your listener to the
project. Your listener must implement the
org.apache.tools.antBuildListener interface. The listener will receive
BuildEvents for the following events

Build started 
Build finished 
Target started 
Target finished 
Task started 
Task finished 
Message logged 
If you wish to attach a listener from the command line you may use the -listener option. For example:

ant -listener org.apache.tools.ant.XmlLogger
will run Ant with a listener that generates an XML representation of the build progress. This listener is included with Ant, as is the default listener, which generates the logging to standard output.

Note: A listener must not access System.out and System.err directly since ouput on these streams is redirected by Ant's core to the build event system. Accessing these streams can cause an infinite loop in Ant. Depending on the version of Ant, this will either cause the build to terminate or the Java VM to run out of Stack space. A logger, also, may not access System.out and System.err directly. It must use the streams with which it has been configured. 

\section{Source code integration}

The other way to extend Ant through Java is to make changes to
existing tasks, which is positively encouraged. Both changes to the
existing source and new tasks can be incorporated back into the Ant
codebase, which benefits all users and spreads the maintenance load
around.  Please consult the Getting Involved pages on the Jakarta web
site for details on how to fetch the latest source and how to submit
changes for reincorporation into the source tree.

Ant also has some task guidelines which provides some advice to people
developing and testing tasks. Even if you intend to keep your tasks to
yourself, you should still read this as it should be informative.

\section{InputHandler}

\subsection{Overview}

When a task wants to prompt a user for input, it doesn't simply read
the input from the console as this would make it impossible to embed
Ant in an IDE. Instead it asks an implementation of the
org.apache.tools.ant.input.InputHandler interface to prompt the user
and hand the user input back to the task.

To do this, the task creates an InputRequest object and passes it to
the InputHandler Such an InputRequest may know whether a given user
input is valid and the InputHandler is supposed to reject all invalid
input.

Exactly one InputHandler instance is associated with every Ant
process, users can specify the implementation using the -inputhandler
command line switch.

InputHandler
The InputHandler interface contains exactly one method

    void handleInput(InputRequest request) 
        throws org.apache.tools.ant.BuildException;

with some pre- and postconditions. The main postcondition is that this method must not return unless the request considers the user input valid, it is allowed to throw an exception in this situation.

Ant comes with two built-in implementations of this interface:

DefaultInputHandler
This is the implementation you get, when you don't use the -inputhandler command line switch at all. This implementation will print the prompt encapsulated in the request object to Ant's logging system and re-prompt for input until the user enters something that is considered valid input by the request object. Input will be read from the console and the user will need to press the Return key.

PropertyFileInputHandler
This implementation is useful if you want to run unattended build processes. It reads all input from a properties file and makes the build fail if it cannot find valid input in this file. The name of the properties file must be specified in the Java system property ant.input.properties.

The prompt encapsulated in a request will be used as the key when looking up the input inside the properties file. If no input can be found, the input is considered invalid and an exception will be thrown.

Note that ant.input.properties must be a Java system property, not an
Ant property. I.e. you cannot define it as a simple parameter to ant,
but you can define it inside the {\tt ANT\_OPTS} environment variable.

InputRequest
Instances of org.apache.tools.ant.input.InputRequest encapsulate the information necessary to ask a user for input and validate this input.

The instances of InputRequest itself will accept any input, but subclasses may use stricter validations. org.apache.tools.ant.input.MultipleChoiceInputRequest should be used if the user input must be part of a predefined set of choices.

\section{Using Ant Tasks Outside of Ant}
\subsection{Rationale}

Ant provides a rich set of tasks for buildfile creators and
administrators. But what about programmers? Can the functionality
provided by Ant tasks be used in java programs?

Yes, and its quite easy. Before getting into the details, however, we
should mention the pros and cons of this approach:

Pros
Robust Ant tasks are very robust. They have been banged on by many people. Ant tasks have been used in many different contexts, and have therefore been instrumented to take care of a great many boundary conditions and potentially obscure errors.  
Cross Platform Ant tasks are cross platform. They have been tested on all of the volume platforms, and several rather unusual ones (Netware and OS/390, to name a few).  
Community Support Using Ant tasks means you have less of your own code to support. Ant code is supported by the entire Apache Ant community.  

Cons
Dependency on Ant Libraries Obviously, if you use an Ant task in your code, you will have to add "ant.jar" to your path. Of course, you could use a code optimizer to remove the unnecessary classes, but you will still probably require a chunk of the Ant core.  
Loss of Flexibility At some point, if you find yourself having to modify the Ant code, it probably makes more sense to "roll your own." Of course, you can still steal some code snippets and good ideas. This is the beauty of open source!  

Example
Let's say you want to unzip a zip file programmatically from java into a certain directory. Of course you could write your own routine to do this, but why not use the Ant task that has already been written?

In my example, I wanted to be able to unzip a file from within an XSLT Transformation. XSLT Transformers can be extended by plugging in static methods in java. I therefore need a function something like this:

/**
 * Unzip a zip file into a given directory.
 *
 * @param zipFilepath A pathname representing a local zip file
 * @param destinationDir where to unzip the archive to
 */
 static public void unzip(String zipFilepath, String destinationDir)

The Ant task to perform this function is org.apache.tools.ant.taskdefs.Expand. All we have to do is create a dummy Ant Project and Target, set the Task parameters that would normally be set in a buildfile, and call execute().

First, let's make sure we have the proper includes:

import org.apache.tools.ant.Project;
import org.apache.tools.ant.Target;
import org.apache.tools.ant.taskdefs.Expand;
import java.io.File;

The function call is actually quite simple:

static public void unzip(String zipFilepath, String destinationDir) {

    final class Expander extends Expand {
        public Expander() {
            project = new Project();
            project.init();
            taskType = "unzip";
            taskName = "unzip";
            target = new Target();
        }       
    }
    Expander expander = new Expander();
    expander.setSrc(new File(zipfile));
    expander.setDest(new File(destdir));
    expander.execute();

In actual practice, you will probably want to add your own error handling code and you may not want to use a local inner class. However, the point of the example is to show how an Ant task can be called programmatically in relatively few lines of code.

The question you are probably asking yourself at this point is: How
would I know which classes and methods have to be called in order to
set up a dummy Project and Target? The answer is: you
don't. Ultimately, you have to be willing to get your feet wet and
read the source code. The above example is merely designed to whet
your appetite and get you started. Go for it!

\chapter{Ant API}

[ tbd ]

\chapter{License}

\begin{verbatim}
/*
 * ============================================================================
 *                   The Apache Software License, Version 1.1
 * ============================================================================
 * 
 *    Copyright (C) 2000-2002 The Apache Software Foundation. All
 *    rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without modifica-
 * tion, are permitted provided that the following conditions are met:
 * 
 * 1. Redistributions of  source code must  retain the above copyright  notice,
 *    this list of conditions and the following disclaimer.
 * 
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 * 
 * 3. The end-user documentation included with the redistribution, if any, must
 *    include  the following  acknowledgment:  "This product includes  software
 *    developed  by the  Apache Software Foundation  (http://www.apache.org/)."
 *    Alternately, this  acknowledgment may  appear in the software itself,  if
 *    and wherever such third-party acknowledgments normally appear.
 * 
 * 4. The names "Ant" and  "Apache Software Foundation"  must not be used to
 *    endorse  or promote  products derived  from this  software without  prior
 *    written permission. For written permission, please contact
 *    apache@apache.org.
 * 
 * 5. Products  derived from this software may not  be called "Apache", nor may
 *    "Apache" appear  in their name,  without prior written permission  of the
 *    Apache Software Foundation.
 * 
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS  FOR A PARTICULAR  PURPOSE ARE  DISCLAIMED.  IN NO  EVENT SHALL  THE
 * APACHE SOFTWARE  FOUNDATION  OR ITS CONTRIBUTORS  BE LIABLE FOR  ANY DIRECT,
 * INDIRECT, INCIDENTAL, SPECIAL,  EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLU-
 * DING, BUT NOT LIMITED TO, PROCUREMENT  OF SUBSTITUTE GOODS OR SERVICES; LOSS
 * OF USE, DATA, OR  PROFITS; OR BUSINESS  INTERRUPTION)  HOWEVER CAUSED AND ON
 * ANY  THEORY OF LIABILITY,  WHETHER  IN CONTRACT,  STRICT LIABILITY,  OR TORT
 * (INCLUDING  NEGLIGENCE OR  OTHERWISE) ARISING IN  ANY WAY OUT OF THE  USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * 
 * This software  consists of voluntary contributions made  by many individuals
 * on behalf of the  Apache Software Foundation.  For more  information  on the 
 * Apache Software Foundation, please see <http://www.apache.org/>.
 *
 */
\end{verbatim}

\chapter{Feedback and Troubleshooting}

If things do not work, especially simple things like ant -version,
then something is wrong with your configuration. Before filing bug
reports and emailing all the ant mailing lists

Check your environment variables. Are {\tt ANT\_HOME} and {\tt JAVA\_HOME} 
correct? If they have quotes or trailing slashes, remove them. 
Unset CLASSPATH; if that is wrong things go horribly wrong. Ant does not need the CLASSPATH variable defined to anything to work. 
Make sure there are no versions of crimson.jar or other XML parsers in JRE/ext 
Is your path correct? is Ant on it? What about JDK/bin? have you tested this? If you are using Jikes, is it on the path? A createProcess error (especially with ID=2 on windows) usually means executable not found on the path. 
Which version of ant are you running? Other applications distribute a copy -it may be being picked up by accident. 
If a task is failing to run is optional.jar in {\tt ANT\_HOME}/lib? Are there any libraries which it depends on missing? 
If a task doesn't do what you expect, run ant -verbose or ant -debug to see what is happening 
If you can't fix your problem, start with the Ant User Mailing List . These are other ant users who will help you learn to use ant. If they cannot fix it then someone may suggest filing a bug report, which will escalate the issue. Remember of course, that support, like all open source development tasks, is voluntary. If you haven't invested time in helping yourself by following the steps above, it is unlikely that anyone will invest the time in helping you. 

Also, if you don't understand something, the Ant User Mailing List is
the place to ask questions. Not the developer list, nor the
individuals whose names appears in the source and documentation. If
they answered all such emails, nobody would have any time to improve
ant.

To provide feedback on this software, please subscribe to the Ant User Mailing List 

If you want to contribute to Ant or stay current with the latest development, join the Ant Development Mailing List 

Archives of both lists can be found at
http://archives.apache.org/eyebrowse/ViewLists. A searchable archive
can be found at http://marc.theaimsgroup.com. If you know of any
additional archive sites, please report them to the lists.


\chapter{Authors}

\begin{verbatim}
Stephane Bailliez (sbailliez@imediation.com) 
Nicola Ken Barozzi (nicolaken@apache.org) 
Jacques Bergeron (jacques.bergeron@dogico.com) 
Stefan Bodewig (stefan.bodewig@freenet.de) 
Patrick Chanezon (chanezon@netscape.com) 
James Duncan Davidson (duncan@x180.com) 
Tom Dimock (tad1@cornell.edu) 
Peter Donald (donaldp@apache.org) 
dIon Gillard (dion@apache.org) 
Erik Hatcher (ehatcher@apache.org) 
Diane Holt (holtdl@yahoo.com) 
Bill Kelly (bill.kelly@softwired-inc.com) 
Arnout J. Kuiper (ajkuiper@wxs.nl) 
Conor MacNeill 
Stefano Mazzocchi (stefano@apache.org) 
Erik Meade (emeade@geekfarm.org) 
Sam Ruby (rubys@us.ibm.com) 
Nico Seessle (nico@seessle.de) 
Jon S. Stevens (jon@latchkey.com) 
Magesh Umasankar 
Roger Vaughn (rvaughn@seaconinc.com) 
Dave Walend (dwalend@cs.tufts.edu) 
Phillip Wells (philwells@rocketmail.com) 
Craeg Strong (cstrong@arielpartners.com) 
Version: 1.5.3
$Id: credits.html,v 1.15.2.8 2003/04/08 14:17:04 conor Exp $
\end{verbatim}

\vfil\eject
\bibliographystyle{plain}
%\bibliography{stds}
\bibliography{test}

\vfil\eject
\printindex
\end{document}
