jakarta-site-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bode...@locus.apache.org
Subject cvs commit: jakarta-site/ant/jakarta-ant/docs P4desc.html ejb.html index.html javacc.html jlink.html junit.html native2ascii.html sql.html
Date Tue, 31 Oct 2000 11:30:30 GMT
bodewig     00/10/31 03:30:25

  Added:       ant/jakarta-ant/docs P4desc.html ejb.html index.html
                        javacc.html jlink.html junit.html native2ascii.html
                        sql.html
  Log:
  Checked in Ant's documentation here. The version at the site should
  contain all documentation bug fixes but not documentation for new
  features in 1.3 - so it is something you cannot find in Ant's own
  repository.
  
  Revision  Changes    Path
  1.1                  jakarta-site/ant/jakarta-ant/docs/P4desc.html
  
  Index: P4desc.html
  ===================================================================
  <html>
  
  <body>
  
  <h2><a name="perforce">Perforce</a></h2>
  
  <h3>Description</h3>
  
  <p>Handles packages/modules retrieved from a <a href="http://www.perforce.com/">Perforce</a> repository.</p>
  
  <h3>Parameters</h3>
  
  <table border="1" cellpadding="2" cellspacing="0">
      <tr>
          <td valign="top"><b>Attribute</b></td>
          <td valign="top"><b>Description</b></td>
          <td align="center" valign="top"><b>Required</b></td>
      </tr>
      <tr>
          <td valign="top">localpath</td>
          <td valign="top">The local path of the file/directory to
          write file(s) to.</td>
          <td align="center" valign="top">Yes</td>
      </tr>
      <tr>
          <td>user</td>
          <td>Specifies the user name, overriding the value of $P4USER,
          $USER, and $USERNAME in the environment.</td>
          <td><p align="center">No</p>
          </td>
      </tr>
      <tr>
          <td>port</td>
          <td>Specifies the server's listen address, overriding the
          value of $P4PORT in the environment and the default (perforce:1666).</td>
          <td><p align="center">No</p>
          </td>
      </tr>
      <tr>
          <td valign="top">version</td>
          <td valign="top">The revision number of the file being
          extracted.</td>
          <td align="center" valign="top">No</td>
      </tr>
      <tr>
          <td valign="top">date</td>
          <td valign="top">Get files as of this date. Either [yyyy/mm/dd]
          or [yyyy/mm/dd:hh:mm:ss]. Note that [yyyy/mm/dd] means [yyyy/mm/dd:00:00:00],
          so if you want to include all events on that day refer to
          the next day.</td>
          <td align="center" valign="top">No</td>
      </tr>
      <tr>
          <td valign="top">label</td>
          <td valign="top">A label from which to check out files.</td>
          <td align="center" valign="top">No</td>
      </tr>
      <tr>
          <td valign="top">force</td>
          <td valign="top">&quot;[true|false]&quot;. Forces
          resynchronization even if the client already has the
          file, and clobbers writable files. This flag doesn't
          affect open files.</td>
          <td align="center" valign="top">No, default &quot;false&quot;</td>
      </tr>
      <tr>
          <td>change</td>
          <td>Gets the file(s) as they were when a specified change
          number was applied.</td>
          <td><p align="center">No</p>
          </td>
      </tr>
  </table>
  
  <h3>Examples</h3>
  
  <pre>  &lt;perforce localpath=&quot;//path/to/source/...&quot;
         force=&quot;true&quot;
         change=&quot;4513&quot;
    /&gt;</pre>
  
  <p>syncs the files in the source directory that are in the
  Perforce repository, as of change number 4513, overwriting any
  modified files in the current source tree is needed.</p>
  
  <pre>  &lt;perforce localpath=&quot;//path/to/source/...&quot; /&gt;</pre>
  
  <p>Syncs with the latest version of the file in the repository.</p>
  </body>
  </html>
  
  
  
  1.1                  jakarta-site/ant/jakarta-ant/docs/ejb.html
  
  Index: ejb.html
  ===================================================================
  <html>
  
  <head>
  <meta http-equiv="Content-Language" content="en-us">
  <title>Ant EJB Tasks</title>
  
  </head>
  
  <body>
  
  <h1>Ant EJB Tasks User Manual</h1>
  <p>by</p>
  <!-- Names are in alphabetical order, on last name -->
  <ul>
    <li>Tim Fennell (<a href="mailto:tfenne@rcn.com">tfenne@rcn.com</a>)</li>
    <li>Conor MacNeill (<a href="mailto:conor@cortexebusiness.com.au">conor@cortexebusiness.com.au</a>)</li>
  </ul>
  
  <p>Version 1.1 - 2000/07/18</p>
  <hr>
  <h2>Table of Contents</h2>
  <ul>
    <li><a href="#introduction">Introduction</a></li>
    <li><a href="#ejbtasks">EJB Tasks</a></li>
  </ul>
  
  <hr>
  <h2><a name="introduction">Introduction</a></h2>
  <p>Ant provides a number of optional tasks for developing 
  <a href="http://java.sun.com/products/ejb">Enterprise Java Beans (EJBs)</a>. 
  In general these tasks are specific to the particular vendor's EJB Server. At present the tasks support
  <a href="http://www.bea.com">Weblogic</a> 4.5.1 and 5.1 EJB servers. Over time we expect further optional tasks 
  to support additional EJB Servers. 
  
  <hr>
  <h2><a name="ejbtasks">EJB Tasks</a></h2>
  <table border="1" cellpadding="5">
   <tr><td>Task</td><td>Application Servers</td></tr>
   <tr><td><a href="#ddcreator">ddcreator</a></td><td>Weblogic 4.5.1</td></tr>
   <tr><td><a href="#ejbc">ejbc</a></td><td>Weblogic 4.5.1</td></tr>
   <tr><td><a href="#wlrun">wlrun</a></td><td>Weblogic 4.5.1 and 5.1</td></tr>
   <tr><td><a href="#wlstop">wlstop</a></td><td>Weblogic 4.5.1 and 5.1</td></tr>
   <tr><td><a href="#ejbjar">ejbjar</a></td><td>Weblogic 5.1</td></tr>
  </table>
  
  <hr>
  <h2><a name="ddcreator">ddcreator</a></h2>
  <h3><b>Description:</b></h3>
  <p>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. 
  
  
  <h3>Parameters:</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">descriptors</td>
      <td valign="top">This is the base directory from which descriptors are selected.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">dest</td>
      <td valign="top">The directory where the serialised deployment descriptors will be written</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">classpath</td>
      <td valign="top">This is the classpath to use to run the underlying weblogic ddcreator tool. 
                       This must include the <code>weblogic.ejb.utils.DDCreator</code> class</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>&lt;ddcreator descriptors=&quot;${dd.dir}&quot; 
             dest=&quot;${gen.classes}&quot; 
             classpath=&quot;${descriptorbuild.classpath}&quot;&gt;
    &lt;include name=&quot;*.txt&quot; /&gt;
  &lt;/ddcreator&gt;</code>
  </pre>
  
  <hr>
  <h2><a name="ejbc">ejbc</a></h2>
  <h3><b>Description:</b></h3>
  <p>The ejbc task will run Weblogic's ejbc tool. This tool will take a serialised 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.
  <p>
  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 serialised deployment descriptors. The standard ant 
  <code>include</code> and <code>exclude</code> constructs can be used to select the deployment descriptors
  to be included. 
  <p>
  Each descriptor is examined to determiune 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 serialised 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.
  <h3>Parameters:</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">descriptors</td>
      <td valign="top">This is the base directory from which the serialised deployment descriptors are selected.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">dest</td>
      <td valign="top">The base directory where the generated classes, RIM stubs and RMI skeletons are written</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">manifest</td>
      <td valign="top">The name of a manifest file to be written. This manifest will contain an entry for each EJB processed</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">src</td>
      <td valign="top">The base directory of the source tree containing the source files of the home interface,
                       remote interface and bean implementation classes.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">classpath</td>
      <td valign="top">This classpath must include both the <code>weblogic.ejbc</code> class and the
                       classfiles of the bean, home interface, remote interface, etc of the bean being
                       processed.</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>&lt;ejbc descriptors=&quot;${gen.classes}&quot;
             src=&quot;${src.dir}&quot; 
             dest=&quot;${gen.classes}&quot;
             manifest=&quot;${build.manifest}&quot; 
             classpath=&quot;${descriptorbuild.classpath}&quot;&gt;
    &lt;include name=&quot;*.ser&quot; /&gt;
  &lt;/ejbc&gt;</code>
  </pre>
  
  <hr>
  <h2><a name="wlrun">wlrun</a></h2>
  <h3><b>Description:</b></h3>
  <p>The <code>wlrun</code> 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.
  
  <h3>Parameters:</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">home</td>
      <td valign="top">The location of the weblogic home that is to be used. This is the location 
                       where weblogic is installed.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">classpath</td>
      <td valign="top">The classpath to be used with the Java Virtual Machine that runs the Weblogic 
                       Server. This is typically set to the Weblogic boot classpath.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">wlclasspath</td>
      <td valign="top">The weblogic classpath used by the Weblogic Server.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">properties</td>
      <td valign="top">The name of the server's properties file within the weblogic home directory
                       used to control the weblogic instance.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">name</td>
      <td valign="top">The name of the weblogic server within the weblogic home which is to be run. 
                       This defaults to &quot;myserver&quot;</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">policy</td>
      <td valign="top">The name of the security policy file within the weblogic home directory that 
                       is to be used. If not specified, the default policy file <code>weblogic.policy</code>
                       is used.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">jvmargs</td>
      <td valign="top">Additional argument string passed to the Java Virtual Machine used to run the
                       Weblogic instance.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">args</td>
      <td valign="top">Additional argument string passed to the Weblogic instance.</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  
  
  <hr>
  <h2><a name="wlstop">wlstop</a></h2>
  <h3><b>Description:</b></h3>
  <p>The <code>wlstop</code> 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. 
  
  <h3>Parameters:</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">classpath</td>
      <td valign="top">The classpath to be used with the Java Virtual Machine that runs the Weblogic 
                       Shutdown comment.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">user</td>
      <td valign="top">The username of the account which will be used to shutdown the server</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">password</td>
      <td valign="top">The password for the account specified in the user parameter.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">url</td>
      <td valign="top">The URL which describes the port to which the server is listening for T3 connections. 
                       For example, t3://localhost:7001</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">delay</td>
      <td valign="top">The delay in seconds after which the server will stop. This defaults to an
                       immediate shutdown.</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  
  
  <hr>
  <h2><a name="ejbjar">ejbjar</a></h2>
  <h3><b>Description:</b></h3>
  <p>This task is designed to support building of arbitrary EJB1.1 jar files. Support is currently
     provided for 'vanilla' EJB1.1 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. Currently, a nested element is provided for building Weblogic 5.1 
     session/entity beans using the weblogic.ejbc tool as well as a nested element for building 
     TOPLink for WebLogic 2.5.1-enabled entity beans.</p>
  
  <p>This task supports two approaches to creating ejb jar files. The first approach assumes a particular 
     naming convention for deployment descriptor files. For an Account bean, for example, the deployment 
     descriptor would be named <code>Account-ejb-jar.xml</code>. This naming convention allows the task to 
     distinguish deployment descriptors without relying on their positioning within a source tree. It is 
     also used to derive the name of the .jar file which is generated. For the example this would be 
     <code>Account.jar</code>. Vendor specific files are assumed to be named in a similar fashion. The 
     deployment descriptor file which defines additional weblogic specific information for the above bean 
     would be <code>Account-weblogic-ejb-jar.xml</code>.
     The second approach does not require a naming convention. This approach uses a specified a jar name 
     for the resultant ejb jar. If the jar name is present, then no naming convention is required. If the
     jar name is not specified, then the default naming convention is expected for the deployment descriptor
     files.
     
  <p>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 EJB1.1
     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. Note that support classes used by the bean but which are not part of the 
     bean's interfaces are not included in the assembled jar. These need to be collected into a
     separate support jar file.</p>
  
  <p>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. Note that at this time the only supported tool is
     Weblogic's ejbc tool.
  
  <p>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.</p>
  
  <h3>Parameters:</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">descriptordir</td>
      <td valign="top">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.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">srcdir</td>
      <td valign="top">The base directory containing the .class files that make up the bean.
                       Note that this can be the same as the descriptordir if all files are
                       in the same directory tree.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">destdir</td>
      <td valign="top">The base directory into which generated jar files are deposited. Jar files are deposited in
                       directories correpsonding 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).</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">basejarname</td>
      <td valign="top">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' attibute) and the resultant ejb jar file (followed by any suffix specified
                       in the nested element).</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">basenameterminator</td>
      <td valign="top">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.</td>
      <td valign="top" align="center">No, defaults to '-'.</td>
    </tr>
    <tr>
      <td valign="top">genericjarsuffix</td>
      <td valign="top">String value appended to the basename of the deployment descriptor to create the filename of the
                       generic EJB jar file.</td>
      <td valign="top" align="center">No, defaults to '-generic.jar'.</td>
    </tr>
  </table>
  
  <h3>Vendor-specific deployment elements</h3>
  
  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.
  
  <h3>Weblogic element</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">destdir</td>
      <td valign="top">The base directory into which the generated weblogic ready jar files are deposited. 
                       Jar files are deposited in directories correpsonding to their location within the 
                       descriptordir namespace. </td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">genericjarsuffix</td>
      <td valign="top">A generic jar is generated as an intermeditate 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.</td>
      <td valign="top" align="center">No, defaults to '-generic.jar'.</td>
    </tr>
    <tr>
      <td valign="top">suffix</td>
      <td valign="top">String value appended to the basename of the deployment descriptor to create the filename of the
                       WebLogic EJB jar file.</td>
      <td valign="top" align="center">No, defaults to '.jar'.</td>
    </tr>
    <tr>
      <td valign="top">classpath</td>
      <td valign="top">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</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">keepgeneric</td>
      <td valign="top">This controls whether the generic fiule used as input to ejbc is retained.</td>
      <td valign="top" align="center">No, defaults to false</td>
    </tr>
  </table>
  
  <h3>TOPLink for Weblogic element</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">destdir</td>
      <td valign="top">The base directory into which the generated weblogic ready jar files are deposited. 
                       Jar files are deposited in directories correpsonding to their location within the 
                       descriptordir namespace. </td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">genericjarsuffix</td>
      <td valign="top">A generic jar is generated as an intermeditate 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.</td>
      <td valign="top" align="center">No, defaults to '-generic.jar'.</td>
    </tr>
    <tr>
      <td valign="top">suffix</td>
      <td valign="top">String value appended to the basename of the deployment descriptor to create the filename of the
                       WebLogic EJB jar file.</td>
      <td valign="top" align="center">No, defaults to '.jar'.</td>
    </tr>
    <tr>
      <td valign="top">classpath</td>
      <td valign="top">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</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">keepgeneric</td>
      <td valign="top">This controls whether the generic file used as input to ejbc is retained.</td>
      <td valign="top" align="center">No, defaults to false</td>
    </tr>
    <tr>
      <td valign="top">toplinkdescriptor</td>
      <td valign="top">This specifes the name of the TOPLink deployment descriptor file contained in the 
                       'descriptordir' directory.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">toplinkdtd</td>
      <td valign="top">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.</td>
      <td valign="top" align="center">No, defaults to dtd file at www.objectpeople.com.</td>
    </tr>
  </table>
  
  
  <h3>Examples</h3>
  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.
  <pre>
      &lt;ejbjar srcdir="${build.classes}"
              descriptordir="${descriptor.dir}"&gt;
        &lt;weblogic destdir="${deploymentjars.dir}"
                  classpath="${descriptorbuild.classpath}"/&gt;
        &lt;include name="**/*-ejb-jar.xml"/&gt;
        &lt;exclude name="**/*weblogic*.xml"/&gt;
      &lt;/ejbjar&gt;
  </pre>
  
  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'.
  <pre>
      &lt;ejbjar srcdir="${build.classes}"
              descriptordir="${descriptor.dir}"
              basejarname="TheEJBJar"&gt;
        &lt;weblogic destdir="${deploymentjars.dir}"
                  classpath="${descriptorbuild.classpath}"/&gt;
        &lt;include name="**/ejb-jar.xml"/&gt;
        &lt;exclude name="**/weblogic*.xml"/&gt;
      &lt;/ejbjar&gt;
  </pre>
  
  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'.
  <pre>
      &lt;ejbjar srcdir="${build.dir}"
              destdir="${solant.ejb.dir}"
              descriptordir="${descriptor.dir}"
              basejarname="Address"&gt;
              &lt;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"/&gt;
              &lt;include name="**/ejb-jar.xml"/&gt;
              &lt;exclude name="**/weblogic-ejb-jar.xml"/&gt;
      &lt;/ejbjar&gt;
  </pre>
  
  </body>
  
  </html>
  
  
  
  
  
  1.1                  jakarta-site/ant/jakarta-ant/docs/index.html
  
  Index: index.html
  ===================================================================
  <html>
  
  <head>
  <meta http-equiv="Content-Language" content="en-us">
  <title>Ant</title>
  </head>
  
  <body>
  
  <p><strong>This document is the User Manual for Ant 1.2. It is based
  on the documentation that shipped with the release of Ant 1.2 but
  contains clarifications and bug fixes committed after the release
  date.</strong></p>
  
  <h1>Ant User Manual</h1>
  <p>by</p>
  <!-- Names are in alphabetical order, on last name -->
  <ul>
    <li>Jacques Bergeron (<a href="mailto:jacques.bergeron@dogico.com">jacques.bergeron@dogico.com</a>)</li>
    <li>Stefan Bodewig (<a href="mailto:stefan.bodewig@epost.de">stefan.bodewig@epost.de</a>)</li>
    <li>Patrick Chanezon (<a href="mailto:chanezon@netscape.com">chanezon@netscape.com</a>)</li>
    <li>James Duncan Davison (<a href="mailto:duncan@x180.com">duncan@x180.com</a>)</li>
    <li>Tom Dimock (<a href="mailto:tad1@cornell.edu">tad1@cornell.edu</a>)</li>
    <li>Bill Kelly (<a href="mailto:bill.kelly@softwired-inc.com">bill.kelly@softwired-inc.com</a>)</li>
    <li>Arnout J. Kuiper (<a href="mailto:ajkuiper@wxs.nl">ajkuiper@wxs.nl</a>)</li>
    <li>Conor MacNeill (<a href="mailto:conor@cortexebusiness.com.au">conor@cortexebusiness.com.au</a>)</li>
    <li>Stefano Mazzocchi (<a href="mailto:stefano@apache.org">stefano@apache.org</a>)</li>
    <li>Sam Ruby (<a href="mailto:rubys@us.ibm.com">rubys@us.ibm.com</a>)</li>
    <li>Nico Seessle (<a href="mailto:nico@seessle.de">nico@seessle.de</a>)</li>
    <li>Roger Vaughn (<a href="mailto:rvaughn@seaconinc.com">rvaughn@seaconinc.com</a>)</li>
    <li>Dave Walend (<a href="mailto:dwalend@cs.tufts.edu">dwalend@cs.tufts.edu</a>)</li>
  </ul>
  
  <p>Version 1.2 - 2000/10/27</p>
  
  <hr>
  <h2>Table of Contents</h2>
  <ul>
    <li><a href="#introduction">Introduction</a></li>
    <li><a href="#getting">Getting Ant</a></li>
    <li><a href="#sysrequirements">System Requirements</a></li>
    <li><a href="#buildingant">Building Ant</a></li>
    <li><a href="#installing">Installing Ant</a></li>
    <li><a href="#running">Running Ant</a></li>
    <li><a href="#buildfile">Writing a simple buildfile</a>
    <li><a href="#directorybasedtasks">Directory based tasks</a></li>
    <li><a href="#tasks">Built in Tasks</a>
    <li><a href="#optionaltasks">Optional Tasks</a>
    <li><a href="#buildevents">Build Events</a>
    <li><a href="#writingowntask">Writing your own task</a></li>
    <li><a href="#faq">FAQ, DTD, external resources</a>
    <li><a href="../LICENSE">License</a></li>
    <li><a href="#feedback">Feedback</a></li>
  </ul>
  
  <hr>
  <h2><a name="introduction">Introduction</a></h2>
  <p>Ant is a Java based build tool. In theory it is kind of like make without
  make's wrinkles.</p>
  <h3>Why?</h3>
  <p>Why another build tool when there is already make, gnumake, nmake, jam, and
  others? Because all of those tools have limitations that its 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 and 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.</p>
  <p>Makefiles are inherently evil as well. Anybody who has worked on them for any
  time has run into the dreaded tab problem. &quot;Is my command not executing
  because I have a space in front of my tab!!!&quot; said the original author of
  Ant way too many times. Tools like Jam took care of this to a great degree, but
  still use yet another format to use and remember.</p>
  <p>Ant is different. Instead a model where it is extended with shell based
  commands, it 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 which implements a particular
  Task interface.</p>
  <p>Granted, this removes some of the expressive power that is inherent by 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 exec rule that
  allows different commands to be executed based on the OS that it is executing
  on.</p>
  
  <hr>
  <h2><a name="getting">Getting Ant</a></h2>
  <h3>Binary edition</h3>
  <p>The latest stable version of Ant can be downloaded from <a
  href="http://jakarta.apache.org/builds/ant/release/v1.2/bin/">
  http://jakarta.apache.org/builds/ant/release/v1.2/bin/</a>.
  If you like living on the edge, you can download the latest version from <a
  href="http://jakarta.apache.org/builds/ant/nightly/">http://jakarta.apache.org/builds/ant/nightly/</a>.</p>
  <h3>Source edition</h3>
  <p>If you prefer the source edition, you can download Ant from <a
  href="http://jakarta.apache.org/builds/ant/release/v1.2/src/">
  http://jakarta.apache.org/builds/ant/release/v1.2/src/</a>
  (latest stable) or from <a
  href="http://jakarta.apache.org/from-cvs/jakarta-tools/">http://jakarta.apache.org/from-cvs/jakarta-ant/</a>
  (current). See the section <a href="#buildingant">Building Ant</a> on how to
  build Ant from the source code.</p>
  
  <hr>
  <h2><a name="sysrequirements">System Requirements</a></h2>
  <p>
    To build and use ant you must have a JAXP compliant XML parser installed and available on your classpath.
    <p>
    If you do not have a JAXP compliant XML parse installed, you may use the reference implementation 
    available from Sun. It is available from <a href="http://java.sun.com/xml">http://java.sun.com/xml</a>.
    Once installed make sure the &quot;jaxp.jar&quot; and &quot;parser.jar&quot; files are in your classpath.
    <p>
    You will also need the JDK installed on your system, version 1.1 or later. 
  
  <hr>  
  <h2><a name="buildingant">Building Ant</a></h2>
  <p>Go to the directory <code>jakarta-ant</code>.</p>
  <p>Make sure the JDK is in you path.</p>
  <p>Set the JAVA_HOME environment variable. This should be set to the
  directory where the JDK is installed. See <a href="#installing">Installing Ant</a>
  for examples on how to do this for your operating system.</p>
  <p>Run <code>bootstrap.bat</code> (Windows) or <code>bootstrap.sh</code> (UNIX)
  to build a bootstrap version of Ant.</p>
  <p>When finished, use</p>
  <blockquote>
    <p><code>build.bat -Dant.dist.dir=&lt;directory to install Ant&gt; dist</code></p>
  </blockquote>
  <p>for Windows, and</p>
  <blockquote>
    <p><code>build.sh -Dant.dist.dir=&lt;directory to install Ant&gt; dist</code></p>
  </blockquote>
  <p>for UNIX, to create a binary distribution of Ant. This distribution can be
  found in the directory you specified.</p>
  <hr>
  <h2><a name="installing">Installing Ant</a></h2>
  <p>The binary distribution of Ant consists of three directories: <code>bin</code>,
  <code>docs</code> and <code>lib</code>. Only the <code>bin</code> and <code>lib</code>
  directory are crucial for running Ant. To run Ant, the following must be done:</p>
  <ul>
    <li>Add the <code>bin</code> directory to your path.</li>
    <li>Set the ANT_HOME environment variable. This should be set to the directory
      which contains the <code>bin</code> and <code>lib</code> directory.</li>
    <li>Set the JAVA_HOME environment variable. This should be set to the
      directory where the JDK is installed.</li>
  </ul>
  <h3>Windows</h3>
  <p>Assume Ant is installed in <code>c:\ant\</code>. The following sets up the
  environment:</p>
  <pre>set ANT_HOME=c:\ant
  set JAVA_HOME=c:\jdk1.2.2
  set PATH=%PATH%;%ANT_HOME%\bin</pre>
  <h3>Unix (bash)</h3>
  <p>Assume Ant is installed in <code>/usr/local/ant</code>. The following sets up
  the environment:</p>
  <pre>export ANT_HOME=/usr/local/ant
  export JAVA_HOME=/usr/local/jdk-1.2.2
  export PATH=${PATH}:${ANT_HOME}/bin</pre>
  <h3>Advanced</h3>
  <p>There are lots of variants that can be used to run Ant. What you need is at
  least the following:</p>
  <p>The classpath for Ant must contain <code>ant.jar</code> and any jars/classes 
  needed for your chosen JAXP compliant XML parser.</p>
  <p>When you need JDK functionality (like a <a href="#javac">javac</a> task, or a
  <a href="#rmic">rmic</a> task), then for JDK 1.1, the <code>classes.zip</code>
  file of the JDK must be added to the classpath; for JDK 1.2 or JDK 1.3, <code>tools.jar</code>
  must be added. The scripts supplied with ant, in the bin directory, will add 
  <code>tools.jar</code> automatically if the JAVA_HOME environment variable is set.</p>
  <p>When you are executing platform specific applications (like the <a
  href="#exec">exec</a> task, or the <a href="#cvs">cvs</a> task), the property <code>ant.home</code>
  must be set to the directory containing a bin directory, which contains the <code>antRun</code> 
  shell script necessary to run execs on Unix.</p>
  <hr>
  <h2><a name="running">Running Ant</a></h2>
  <p>Running Ant is simple, when you installed it as described in the previous
  section. Just type <code>ant</code>.</p>
  <p>When nothing is specified, Ant looks for a <code>build.xml</code>
  file in the current directory. When found, it uses that file as a
  buildfile, otherwise it searches in the parent directory and so on
  until the root of the filesystem has been reached. To make Ant use
  another buildfile, use the commandline option <i>-buildfile
  &lt;file&gt;</i>, where <i>&lt;file&gt;</i> is the buildfile you want
  to use.</p>
  <p>You can also set properties which override properties specified in the
  buildfile (see the <a href="#property">property task</a>). 
  This can be done with the <i>-D&lt;property&gt;=&lt;value&gt;</i>
  option, where <i>&lt;property&gt;</i> is the name of the property and <i>&lt;value&gt;</i>
  the value. This can also be used (and is the only way since Java can not access them) 
  to have access to your environment variables, just pass -DMYVAR=%MYVAR% (Windows) or
  -DMYVAR=$MYVAR (Unix) to Ant, you can then access these variables inside your build-file
  as ${MYVAR}.</p>
  <p>Two more options are <i>-quiet</i> which instructs Ant to print less
  information on the console when running. The option <i>-verbose</i> on the other
  hand makes Ant print more information on the console.</p>
  <p>It is also possible to specify one or more targets that should be executed. When omitted the target that is mentioned in the <i>default</i> attribute of the project is
  used.</p>
  <p>The <i>-projecthelp</i> option gives a list of this projects targets. First those with a description and then those without one.</p>
  <p>Commandline option summary:</p>
  <pre>ant [options] [target [target2 [target3] ...]]
  Options:
  -help                  print this message
  -projecthelp           print project help information
  -version               print the version information and exit
  -quiet                 be extra quiet
  -verbose               be extra verbose
  -debug                 print debugging information
  -emacs                 produce logging information without adornments
  -logfile &lt;file&gt;        use given file for log
  -logger &lt;classname&gt;    the class which is to perform logging
  -listener &lt;classname&gt;  add an instance of class as a project listener
  -buildfile &lt;file&gt;      use given buildfile
  -D&lt;property&gt;=&lt;value&gt;   use value for given property</pre>
  <h3>Examples</h3>
  <blockquote>
    <pre>ant</pre>
  </blockquote>
  <p>runs Ant using the <code>build.xml</code> file in the current directory, on
  the default target.</p>
  <blockquote>
    <pre>ant -buildfile test.xml</pre>
  </blockquote>
  <p>runs Ant using the <code>test.xml</code> file in the current directory, on
  the default target.</p>
  <blockquote>
    <pre>ant -buildfile test.xml dist</pre>
  </blockquote>
  <p>runs Ant using the <code>test.xml</code> file in the current directory, on a
  target called <code>dist</code>.</p>
  <blockquote>
    <pre>ant -buildfile test.xml -Dbuild=build/classes dist</pre>
  </blockquote>
  <p>runs Ant using the <code>test.xml</code> file in the current directory, on a
  target called <code>dist</code>. It also sets the <i>build</i> property to the
  value <i>build/classes</i>.</p>
  <h3>Running Ant by hand</h3>
  <p>When you have installed Ant in the do-it-yourself way, Ant can be started
  with:</p>
  <blockquote>
    <pre>java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]</pre>
  </blockquote>
  
  <p>These instructions actually do exactly the same as the <code>ant</code>
  command. The options and target are the same as when running Ant with the <code>ant</code>
  command. This example assumes you have set up your classpath to include
  <ul>
  <li>ant.jar
  <li>jars/classes for your XML parser
  <li>the JDK's tools.jar
  </ul>
  <hr>
  <h2><a name="buildfile">Writing a simple buildfile</a></h2>
  <p>The buildfile is written in XML. Each buildfile contains one project.</p>
  <p>Each element of the buildfile can have an <code>id</code> attribute and
  can later be referred to by the value supplied to this. The value has
  to be unique.</p>
  <h3>Projects</h3>
  <p>A project has three attributes:</p>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">name</td>
      <td valign="top">the name of the target.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">default</td>
      <td valign="top">the default target to use when no target is supplied.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">basedir</td>
      <td valign="top">the base directory from which all path calculations are
        done. This attribute might be overridden by setting the &quot;basedir&quot;
        property on forehand. When this is done, it might be omitted in the
        project tag.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
  </table>
  <p>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 you want to have
  executed. When no target is given, the project's default is used.</p>
  <h3>Targets</h3>
  <p>A target can depend on other targets. You might have a target for compiling,
  for instance, 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 all these dependencies.</p>
  <p>Ant tries to execute the targets in the <i>depends</i> 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:</p>
  <blockquote>
  <pre>&lt;target name=&quot;A&quot;/&gt;
  &lt;target name=&quot;B&quot; depends=&quot;A&quot;/&gt;
  &lt;target name=&quot;C&quot; depends=&quot;B&quot;/&gt;
  &lt;target name=&quot;D&quot; depends=&quot;C,B,A&quot;/&gt;</pre>
  </blockquote>
  <p>Suppose we want to execute target D. From its <i>depends</i> 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.</p>
  <p>A target gets executed only once. Even when more targets depend on it (see
  the previous example).</p>
  <p>A target has also 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 properties, etc...).  To make target
  <i>sense</i> this property you should add the <i>if</i> (or
  <i>unless</i>) attribute with the name of the property that the target
  should react to, for example</p>
  <blockquote>
    <pre>&lt;target name=&quot;build-module-A&quot; if=&quot;module-A-present&quot;/&gt;</pre>
    <pre>&lt;target name=&quot;build-own-fake-module-A&quot; unless=&quot;module-A-present&quot;/&gt;</pre>
  </blockquote>
  <p>If no <i>if</i> and no <i>unless</i> attribute is present, the target will 
  always be executed.</p>
  <p>It is a good practice to place your <a
  href="#tstamp">tstamp</a> 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 &quot;init&quot;.</p>
  <p>The optional <i>description</i> attribute can be used to provide a one line description of this target that is printed by the <i>-projecthelp</i> commandline option.</p>
  <p>A target has the following attributes:</p>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">name</td>
      <td valign="top">the name of the target.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">depends</td>
      <td valign="top">a comma separated list of names of targets on which this
        target depends.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">if</td>
      <td valign="top">the name of the property that must be set in order for this
        target to execute.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">unless</td>
      <td valign="top">the name of the property that must not be set in order 
        for this target to execute.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">description</td>
      <td valign="top">a short description of this targets function.</td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>
  <h3>Tasks</h3>
  <p>A task is a piece of code that can be executed.</p>
  <p>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.</p>
  <p>Tasks have a common structure:</p>
  <blockquote>
    <pre>&lt;name attribute1=&quot;value1&quot; attribute2=&quot;value2&quot; ... /&gt;</pre>
  </blockquote>
  <p>where name is the name of the task, attribute-x the attribute name, and
  value-x the value of this attribute.</p>
  <p>There is a set of <a href="#tasks">built in tasks</a>, but it is also very
  easy to <a href="#writingowntask">write your own</a>.</p>
  <p>All tasks share a <code>taskname</code> attribute. The value of
  this attribute will be used in the logging messages generated by
  Ant.</p>
  <h3>Properties</h3>
  <p>A project can have a set of properties. These might be set in the buildfile
  by the <a href="#property">property task</a>, or might be set outside Ant. A
  property has a name and a value. Properties might be used in in the value of
  task attributes. This is done by placing the property name between
  &quot;${&quot; and &quot;}&quot; in the attribute value.</p>
  <p>If there is a property called &quot;builddir&quot; with the value
  &quot;build&quot;, then this could be used in an attribute like this: &quot;${builddir}/classes&quot;.
  This is resolved as &quot;build/classes&quot;.</p>
  <h3>Built in Properties</h3>
  <p>Ant provides access to all system properties as if they had been
  defined using a property task, for example ${os.name} expands to the
  name of the operating system.</p>
  <p>In addition Ant knows some built in properties:</p>
  <ul>
    <li>basedir - the absolute path of the project's basedir (as set
      with the basedir attribute of &lt;project&gt;.</li>
    <li>ant.file - the absolute path of the build file.</li>
    <li>ant.java.version - the JVM version Ant detected. Currently it
      can hold the values &quot;1.1&quot;, &quot;1.2&quot; and
      &quot;1.3&quot;.</li>
  </ul>
  <h3>Example</h3>
  <blockquote>
    <pre>
  &lt;project name=&quot;MyProject&quot; default=&quot;dist&quot; basedir=&quot;.&quot;&gt;
  
    &lt;!-- set global properties for this build --&gt;
    &lt;property name=&quot;src&quot; value=&quot;.&quot; /&gt;
    &lt;property name=&quot;build&quot; value=&quot;build&quot; /&gt;
    &lt;property name=&quot;dist&quot;  value=&quot;dist&quot; /&gt;
  
    &lt;target name=&quot;prepare&quot;&gt;
      &lt;!-- Create the time stamp --&gt;
      &lt;tstamp/&gt;
      &lt;!-- Create the build directory structure used by compile --&gt;
      &lt;mkdir dir=&quot;${build}&quot; /&gt;
    &lt;/target&gt;
  
    &lt;target name=&quot;compile&quot; depends=&quot;prepare&quot;&gt;
      &lt;!-- Compile the java code from ${src} into ${build} --&gt;
      &lt;javac srcdir=&quot;${src}&quot; destdir=&quot;${build}&quot; /&gt;
    &lt;/target&gt;
  
    &lt;target name=&quot;dist&quot; depends=&quot;compile&quot;&gt;
      &lt;!-- Create the ${dist}/lib directory --&gt;
      &lt;mkdir dir=&quot;${dist}/lib&quot; /&gt;
  
      &lt;!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file --&gt;
      &lt;jar jarfile=&quot;${dist}/lib/MyProject-${DSTAMP}.jar&quot; basedir=&quot;${build}&quot; /&gt;
    &lt;/target&gt;
  
    &lt;target name=&quot;clean&quot;&gt;
      &lt;!-- Delete the ${build} and ${dist} directory trees --&gt;
      &lt;delete dir=&quot;${build}&quot; /&gt;
      &lt;delete dir=&quot;${dist}&quot; /&gt;
    &lt;/target&gt;
  &lt;/project&gt;
    </pre>
  </blockquote>
  
  <h3>Token Filters</h3>
  <p>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 <a href="#filter">filter task</a>.&nbsp;</p>
  <p>Since this can be a very harmful behavior, the tokens in the files <b>must</b>
  be of the form<i> @token@</i> where <i>token</i> is the token name that is set
  in the 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 with documentation systems.</p>
  <p>Note: in case a token with the format @token@ is found in a file but no
  filter is associated with that token, no changes take place. So, no escaping
  method is present, but as long as you choose appropriate names for your tokens,
  this should not cause problems.</p>
  
  <h3><a name="path">PATH like structures</a></h3>
  <p>You can specify PATH and CLASSPATH variables using both
  &quot;:&quot; and &quot;;&quot; as separator characters, Ant will
  convert it to the correct character of the current operating
  system.</p>
  <p>Wherever PATH like values need to be specified a nested element can
  be used. This takes the general form of</p>
  <pre>
      &lt;classpath&gt;
        &lt;pathelement path=&quot;${classpath}&quot; /&gt;
        &lt;pathelement location=&quot;lib/helper.jar&quot; /&gt;
      &lt;/classpath&gt;
  </pre>
  <p>The <code>location</code> attribute specifies a single file or
  directory relative to the project's base directory (or an absolute
  filename), while the <code>path</code> attribute accepts &quot;:&quot;
  or &quot;;&quot; separated lists of locations. The <code>path</code>
  attribute is intended to be used with predefined paths - in any other
  case multiple elements with <code>location</code> attributes should be
  preferred.</p>
  <p>As a shortcut the surrounding PATH element supports path and
  location attributes of its own, so</p>
  <pre>
      &lt;classpath&gt;
        &lt;pathelement path=&quot;${classpath}&quot; /&gt;
      &lt;/classpath&gt;
  </pre>
  <p>can be abreviated to</p>
  <pre>
      &lt;classpath path=&quot;${classpath}&quot; /&gt;
  </pre>
  <p>In addition, <a href="#fileset">FileSet</a>s can be specified via
  nested <code>&lt;fileset&gt;</code> elements. The order in which the files
  building up FileSet are added to the PATH like structure is not
  defined.</p>
  <pre>
      &lt;classpath&gt;
        &lt;pathelement path=&quot;${classpath}&quot; /&gt;
        &lt;fileset dir=&quot;lib&quot;&gt;
          &lt;include name=&quot;**/*.jar&quot; /&gt;
        &lt;/fileset;&gt;
        &lt;pathelement location=&quot;classes&quot; /&gt;
      &lt;/classpath&gt;
  </pre>
  <p>Builds a PATH which holds the value of <code>${classpath}</code>
  followed by all JAR files in the <code>lib</code> directory, followed
  by the <code>classes</code> directory.</p>
  <p>If you want to use the same PATH like structure for several tasks,
  you can define them with a <code>&lt;path&gt;</code> element at the
  same level as <em>target</em>s and reference them via their
  <em>id</em> attribute - see <a href="#references">References</a> for an
  example.</p>
  <p>A PATH like structure can include a reference to another PATH like
  structure via a nested <code>&lt;path&gt;</code> elements.</p>
  <pre>
      &lt;path id=&quot;base.path&quot;&gt;
        &lt;pathelement path=&quot;${classpath}&quot; /&gt;
        &lt;fileset dir=&quot;lib&quot;&gt;
          &lt;include name=&quot;**/*.jar&quot; /&gt;
        &lt;/fileset;&gt;
        &lt;pathelement location=&quot;classes&quot; /&gt;
      &lt;/path&gt;
  
      &lt;path id=&quot;tests.path&quot;&gt;
        &lt;path refid=&quot;base.path&quot; /&gt;
        &lt;pathelement location=&quot;testclasses&quot; /&gt;
      &lt;/path&gt;
  </pre>
  
  <h3><a name="arg">Command line arguments</a></h3>
  
  <p>Several tasks take arguments that shall be passed to another
  process on the command line. To make it easier to specify arguments
  that contain space characters, nested elements can be used.</p>
  <table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td width="12%" valign="top"><b>Attribute</b></td>
    <td width="78%" valign="top"><b>Description</b></td>
    <td width="10%" valign="top"><b>Required</b></td>
  </tr>
    <tr>
      <td valign="top">value</td> 
      <td valign="top">a single command line argument, can contain space
        characters.</td>
      <td align="center" rowspan="4">Exactly one of these.</td>
    </tr>
    <tr>
      <td valign="top">line</td> 
      <td valign="top">a space delimited list of command line arguments.</td>
    </tr>
    <tr>
      <td valign="top">file</td> 
      <td valign="top">The name of a file as a single command line
        argument. Will be replaced with the absolute filename of the file
        by Ant.</td>
    </tr>
    <tr>
      <td valign="top">path</td> 
      <td valign="top">A string that shall 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.</td>
    </tr>
  </table>
  <h4>Examples</h4>
  <blockquote><pre>
    &lt;arg value=&quot;-l -a&quot; /&gt;
  </pre></blockquote>
  <p>is a single command line argument containing a space character.</p>
  <blockquote><pre>
    &lt;arg line=&quot;-l -a&quot; /&gt;
  </pre></blockquote>
  <p>stands for two separate command line arguments.</p>
  <blockquote><pre>
    &lt;arg path=&quot;/dir;/dir2:\dir3&quot; /&gt;
  </pre></blockquote>
  <p>is a single command line argument with value
  <code>\dir;\dir2;\dir3</code> on DOS based systems and
  <code>/dir:/dir2:/dir3</code> on Unix like systems.</p>
  <h3><a name="references">References</a></h3>
  <p>The <code>id</code> attribute of the buildfile's elements can be
  used to refer to them. This can useful if you are going to replicate
  the same snippet of XML over and over again - using a
  <code>&lt;classpath&gt;</code> structure more than once for
  example.</p>
  <p>The following example</p>
  <blockquote><pre>
  &lt;project ... &gt;
    &lt;target ... &gt;
      &lt;rmic ...&gt;
        &lt;classpath&gt;
          &lt;pathelement location=&quot;lib/&quot; /&gt;
          &lt;pathelement path=&quot;${java.class.path}/&quot; /&gt;
          &lt;pathelement path=&quot;${additional.path}&quot; /&gt;
        &lt;/classpath&gt;
      &lt;/rmic&gt;
    &lt;/target&gt;
  
    &lt;target ... &gt;
      &lt;javac ...&gt;
        &lt;classpath&gt;
          &lt;pathelement location=&quot;lib/&quot; /&gt;
          &lt;pathelement path=&quot;${java.class.path}/&quot; /&gt;
          &lt;pathelement path=&quot;${additional.path}&quot; /&gt;
        &lt;/classpath&gt;
      &lt;/javac&gt;
    &lt;/target&gt;
  &lt;/project&gt;
  </pre></blockquote>
  <p>could be rewritten as</p>
  <blockquote><pre>
  &lt;project ... &gt;
    &lt;path id=&quot;project.class.path&quot;&gt;
      &lt;pathelement location=&quot;lib/&quot; /&gt;
      &lt;pathelement path=&quot;${java.class.path}/&quot; /&gt;
      &lt;pathelement path=&quot;${additional.path}&quot; /&gt;
    &lt;/path&gt;
  
    &lt;target ... &gt;
      &lt;rmic ...&gt;
        &lt;classpath refid=&quot;project.class.path&quot; /&gt;
      &lt;/rmic&gt;
    &lt;/target&gt;
  
    &lt;target ... &gt;
      &lt;javac ...&gt;
        &lt;classpath refid=&quot;project.class.path&quot; /&gt;
      &lt;/javac&gt;
    &lt;/target&gt;
  &lt;/project&gt;
  </pre></blockquote>
  <p>All tasks that use nested elements for <a
  href="#patternset">PatternSet</a>s, <a href="#fileset">FileSet</a>s or
  <a href="#path">PATH like structures</a> accept references to these
  structures as well.</p>
  <hr>
  <h2><a name="directorybasedtasks">Directory based tasks</a></h2>
  <p>Some tasks use directory trees for the task they perform. For instance, the <a
  href="#javac">Javac task</a> which works upon a directory tree with .java files.
  Sometimes it can be very useful to work on a subset of that directory tree. This
  section describes how you can select a subset of such a directory tree.</p>
  <p>Ant gives you two ways to create a subset, both of which can be used at the same
  time:</p>
  <ul>
    <li>Only include files/directories that match at least one pattern of a set of
      patterns</li>
    <li>Exclude files/directories that match at least one pattern a set of
      patterns</li>
  </ul>
  <p>When both inclusion and exclusion are used, only files/directories that match
  the include patterns, and don't match the exclude patterns are used.</p>
  <p>Patterns can be specified inside the buildfile via task attributes or
  nested elements and via external files. Each line of the external file
  is taken as pattern that is added to the list of include or exclude 
  patterns.</p>
  <h3>Patterns</h3>
  <p>As described earlier, patterns are used for the inclusion and exclusion.
  These patterns look very much like the patterns used in DOS and UNIX:</p>
  <p>'*' matches zero or more characters, '?' matches one character.</p>
  <p>Examples:</p>
  <p>'*.java' matches '.java', 'x.java' and 'FooBar.java', but not 'FooBar.xml'
  (does not end with '.java').</p>
  <p>'?.java' matches 'x.java', 'A.java', but not '.java' or 'xyz.java' (both
  don't have one character before '.java').</p>
  <p>Combinations of '*'s and '?'s are allowed.</p>
  <p>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 directories are matched, and so on. E.g. when we have the pattern '/?abc/*/*.java'
  and the path '/xabc/foobar/test.java', then 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.</p>
  <p>Too 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 instance:
  '/test/**' matches all files/directories under '/test/', such as '/test/x.java',
  or '/test/foo/bar/xyz.html', but not '/xyz.xml'.</p>
  <p>There is one &quot;shorthand&quot;, if a pattern ends with '/' or '\', then '**'
  is appended. E.g. &quot;mypackage/test/&quot; is interpreted as were it &quot;mypackage/test/**&quot;.</p>
  <p>Examples:</p>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top">**/CVS/*</td>
      <td valign="top">Matches all files in CVS directories, that can be located
        anywhere in the directory tree.
        <p>Matches:</p>
        <p>CVS/Repository<br>
        org/apache/CVS/Entries<br>
        org/apache/jakarta/tools/ant/CVS/Entries</p>
        <p>But not:</p>
        <p>org/apache/CVS/foo/bar/Entries ('foo/bar/' part does not match)</td>
    </tr>
    <tr>
      <td valign="top">org/apache/jakarta/**</td>
      <td valign="top">Matches all files in the org/apache/jakarta directory tree.
        <p>Matches:</p>
        <p>org/apache/jakarta/tools/ant/docs/index.html<br>
        org/apache/jakarta/test.xml</p>
        <p>But not:</p>
        <p>org/apache/xyz.java ('jakarta'/' part is missing)</td>
    </tr>
    <tr>
      <td valign="top">org/apache/**/CVS/*</td>
      <td valign="top">Matches all files in CVS directories, that are located
        anywhere in the directory tree under org/apache.
        <p>Matches:</p>
        <p>org/apache/CVS/Entries<br>
        org/apache/jakarta/tools/ant/CVS/Entries</p>
        <p>But not:</p>
        <p>org/apache/CVS/foo/bar/Entries ('foo/bar/' part does not match)</td>
    </tr>
    <tr>
      <td valign="top">**/test/**</td>
      <td valign="top">Matches all files which have a directory 'test' in their
        path, including 'test' as a filename.</td>
    </tr>
  </table>
  <p>When these patterns are used in inclusion and exclusion, you have a powerful
  way to select just the files you want.</p>
  <h3>Examples</h3>
  <pre>  
  &lt;copy todir=&quot;${dist}&quot; >
    &lt;fileset dir=&quot;${src}&quot; 
             includes=&quot;**/images/*&quot; 
             excludes=&quot;**/*.gif&quot; 
    /&gt;
  &lt;/copy&gt;</pre>
  <p>This copies all files in directories called &quot;images&quot;, that are
  located in the directory tree &quot;${src}&quot; to the destination &quot;${dist}&quot;,
  but excludes all &quot;*.gif&quot; files from the copy.</p>
  <p> This example can also be expressed using nested elements as
  <pre>
  &lt;copy todir=&quot;${dist}&quot; >
    &lt;fileset dir=&quot;${src}&quot; /&gt;
      &lt;include name=&quot;**/images/*&quot;/&gt;
      &lt;exclude name=&quot;**/*.gif&quot; /&gt;
    &lt;/fileset&gt;
  &lt;/copy&gt;
  </pre>
  
  <h3>Default Excludes</h3>
  <p>There are a set of definitions which are excluded by default from all directory based tasks.
  They are:
  <pre>        &quot;**/*~&quot;,
          &quot;**/#*#&quot;,
          &quot;**/%*%&quot;,
          &quot;**/CVS&quot;,
          &quot;**/CVS/*&quot;,
          &quot;**/.cvsignore&quot;
  </pre>
  If you do not want these default excludes applied, you may disable them with the 
  <code>defaultexcludes=&quot;no&quot;</code> attribute.</p>
  <h3><a name="patternset">PatternSets</a></h3>
  <p>Patterns can be grouped to sets and later be referenced by their id
  attribute. They are defined via a <code>patternset</code> element -
  which can appear nested into a <a href="#fileset">FileSet</a> or a
  directory based task that constitutes an implicit FileSet. In addition
  <code>patternset</code>s can be defined at the same level as
  <code>target</code> - i.e. as children of <code>project</code></p>
  <p>Patterns can be specified by nested <code>&lt;include&gt;</code> or
  <code>&lt;exclude&gt;</code> elements or the following attributes.</p>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top">comma separated list of patterns of files that must be
        included. All files are included when omitted.</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an include pattern</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top">comma separated list of patterns of files that must be
        excluded. No files (except default excludes) are excluded when omitted.</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an exclude pattern</td>
    </tr>
  </table>
  <h4>Examples</h4>
  <blockquote><pre>
  &lt;patternset id=&quot;non.test.sources&quot; &gt;
    &lt;include name=&quot;**/*.java&quot; /&gt;
    &lt;exclude name=&quot;**/*Test*&quot; /&gt;
  &lt;/patternset&gt;
  </pre></blockquote>
  <p>Builds a set of patterns, that matches all <code>.java</code> files
  that do not contain the text <code>Test</code> in their name. This set
  can be <a href="#references">referred</a> to via
  <code>&lt;patternset refid=&quot;non.test.sources&quot;
  /&gt;</code> by tasks that support this feature or by FileSets.</p>
  <h3><a name="fileset">FileSets</a></h3>
  <p>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 <a
  href="#patternset">PatternSets</a>. FileSets can appear inside task
  that support this feature or at the same level as <code>target</code>
  - i.e. as children of <code>project</code>.</p>
  <p>PatternSets can be specified as nested
  <code>&lt;patternset&gt;</code> 
  elements. In addition FileSet holds an implicit PatternSet and
  supports the nested <code>&lt;include&gt;</code> and
  <code>&lt;exclude&gt;</code> elements of PatternSet directly as well
  as PatternSet's attributes.</p>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">dir</td>
      <td valign="top">The root of the directory tree of this FileSet.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">defaultexcludes</td>
      <td valign="top">indicates whether default excludes should be used or not
        (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top">comma separated list of patterns of files that must be
        included. All files are included when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an include pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top">comma separated list of patterns of files that must be
        excluded. No files (except default excludes) are excluded when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an exclude pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h4>Examples</h4>
  <blockquote><pre>
  &lt;fileset dir=&quot;${server.src}&quot; &gt;
    &lt;patternset id=&quot;non.test.sources&quot; &gt;
      &lt;include name=&quot;**/*.java&quot; /&gt;
      &lt;exclude name=&quot;**/*Test*&quot; /&gt;
    &lt;/patternset&gt;
  &lt;/fileset&gt;
  </pre></blockquote>
  <p>Groups all files in directory <code>${server.src}</code> that are Java
  source files and don't have the text <code>Test</code> in their
  name.</p>
  <blockquote><pre>
  &lt;fileset dir=&quot;${client.src}&quot; &gt;
    &lt;patternset refid=&quot;non.test.sources&quot; /&gt;
  &lt;/fileset&gt;
  </pre></blockquote>
  <p>Groups all files in directory <code>${client.src}</code> using the
  same patterns as the example before.</p>
  <hr>
  <h2><a name="tasks">Built in tasks</a></h2>
  <ul>
    <li><a href="#ant">Ant</a></li>
    <li><a href="#antcall">AntCall</a></li>
    <li><a href="#antstructure">AntStructure</a></li>
    <li><a href="#available">Available</a></li>
    <li><a href="#chmod">Chmod</a></li>
    <li><a href="#copy">Copy</a></li>
    <li><a href="#copydir">Copydir</a></li>
    <li><a href="#copyfile">Copyfile</a></li>
    <li><a href="#cvs">Cvs</a></li>
    <li><a href="#delete">Delete</a></li>
    <li><a href="#deltree">Deltree</a></li>
    <li><a href="#echo">Echo</a></li>
    <li><a href="#exec">Exec</a></li>
    <li><a href="#execon">ExecOn</a></li>
    <li><a href="#fail">Fail</a></li>
    <li><a href="#filter">Filter</a></li>
    <li><a href="#fixcrlf">FixCRLF</a></li>
    <li><a href="#genkey">GenKey</a></li>
    <li><a href="#get">Get</a></li>
    <li><a href="#gunzip">GUnzip</a></li>
    <li><a href="#gzip">GZip</a></li>
    <li><a href="#jar">Jar</a></li>
    <li><a href="#java">Java</a></li>
    <li><a href="#javac">Javac</a></li>
    <li><a href="#javadoc">Javadoc/Javadoc2</a></li>
    <li><a href="#mail">Mail</a></li>
    <li><a href="#mkdir">Mkdir</a></li>
    <li><a href="#move">Move</a></li>
    <li><a href="#patch">Patch</a></li>
    <li><a href="#property">Property</a></li>
    <li><a href="#rename">Rename</a></li>
    <li><a href="#replace">Replace</a></li>
    <li><a href="#rmic">Rmic</a></li>
    <li><a href="#signjar">SignJar</a></li>
    <li><a href="sql.html">Sql</a></li>
    <li><a href="#style">Style</a></li>
    <li><a href="#tar">Tar</a></li>
    <li><a href="#taskdef">Taskdef</a></li>
    <li><a href="#touch">Touch</a></li>
    <li><a href="#tstamp">Tstamp</a></li>
    <li><a href="#unzip">Unjar</a></li>
    <li><a href="#untar">Untar</a></li>
    <li><a href="#unzip">Unwar</a></li>
    <li><a href="#unzip">Unzip</a></li>
    <li><a href="#uptodate">Uptodate</a></li>
    <li><a href="#war">War</a></li>
    <li><a href="#zip">Zip</a></li>
  </ul>
  <hr>
  <h2><a name="ant">Ant</a></h2>
  <h3>Description</h3>
  <p>Runs Ant on a supplied buildfile. This can be used to build subprojects.</p>
  <p>When the <i>antfile</i> attribute is omitted, the file &quot;build.xml&quot;
  in the supplied directory (<i>dir</i> attribute) is used.</p>
  <p>If no target attribute is supplied, the default target of the new project is
  used.</p>
  <p>The properties of the current project will be available in the new project.
  These properties will override the properties that are set in the new project.
  (See also the <a href="#property">properties task</a>). You can set properties
  in the new project from the old project by using nested property tags. This
  allows you to parameterize your subprojects.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">antfile</td>
      <td valign="top">the buildfile to use. Defaults to &quot;build.xml&quot;.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">dir</td>
   	<td valign="top">the directory to use as a basedir for the new Ant project. 
  					 Defaults to the current directory.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">target</td>
      <td valign="top">the target of the new Ant project that should be executed.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">output</td>
      <td valign="top">Filename to write the ant output to.
      </td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>
    &lt;ant antfile=&quot;subproject/subbuild.xml&quot; dir=&quot;subproject&quot; target=&quot;compile&quot; /&gt;
  
    &lt;ant dir=&quot;subproject&quot; /&gt;
  
    &lt;ant antfile=&quot;subproject/property_based_subbuild.xml&quot;&gt;
      &lt;property name=&quot;param1&quot; value=&quot;version 1.x&quot; /&gt;
      &lt;property file=&quot;config/subproject/default.properties&quot; /&gt;
    &lt;/ant&gt;
  </pre>
  <hr>
  <h2><a name="antcall">AntCall</a></h2>
  <h3>Description</h3>
  <p>Call another target within the same build-file optionally specifying some
  properties (param's in this context)</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">target</td>
      <td valign="top">The target to execute.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
  </table>
  <h3>Parameters specified as nested elements</h3>
  <h4>param</h4>
  <p>Specifies the properties to set before running the specified target. See <a
  href="#property">property</a> for usage guidelines.</p>
  <h3>Examples</h3>
  <pre>
    &lt;target name=&quot;default&quot;&gt;
      &lt;antcall target=&quot;doSomethingElse&quot;&gt;
        &lt;param name=&quot;param1&quot; value=&quot;value&quot;/&gt;
      &lt;/antcall&gt;
    &lt;/target&gt;
  
    &lt;target name=&quot;doSomethingElse&quot;&gt;
      &lt;echo message=&quot;param1=${param1}&quot;/&gt;
    &lt;/target&gt;
  </pre>
  <p>Will run the target 'doSomethingElse' and echo 'param1=value'.</p>
  <hr>
  <h2><a name="antstructure">AntStructure</a></h2>
  <h3>Description</h3> 
  <p>Generates a DTD for Ant build files which contains information
  about all tasks currently known to Ant.</p> 
  <p>Note that the DTD generated by this task is incomplete, you can
  always add XML entities using <a
  href="#taskdef"><code>&lt;taskdef&gt;</code></a>. See <a
  href="http://www.sdv.fr/pages/casa/html/ant-dtd.en.html">here</a> for
  a way to get around this problem.</p>
  <p>This task doesn't know about required attributes, all will be
  listed as <code>#IMPLIED</code>.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">output</td>
      <td valign="top">file to write the DTD to.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <blockquote><pre>
  &lt;antstructure output=&quot;project.dtd&quot; /&gt;
  </pre></blockquote>
  <hr>
  <h2><a name="available">Available</a></h2>
  <h3>Description</h3>
  <p>Sets a property if a resource is available at runtime. This resource can be a
  file resource, a class in classpath or a JVM system resource.</p>
  <p>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 specific by using the value attribute.</p>
  <p>Normally, this task is used to set properties that are useful to avoid target
  execution depending on system parameters.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">property</td>
      <td valign="top">the name of the property to set.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">value</td>
      <td valign="top">the value to set the property to. Defaults to &quot;true&quot;.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">classname</td>
      <td valign="top">the class to look for in classpath.</td>
      <td valign="middle" align="center" rowspan="3">Yes</td>
    </tr>
    <tr>
      <td valign="top">resource</td>
      <td valign="top">the resource to look for in the JVM</td>
    </tr>
    <tr>
      <td valign="top">file</td>
      <td valign="top">the file to look for.</td>
    </tr>
    <tr>
      <td valign="top">classpath</td> <td valign="top">the classpath to
        use when looking up <code>classname</code>.</td> <td
      align="center" valign="top">No</td>
    </tr>
  </table>
  <h3>Parameters specified as nested elements</h3>
  <h4>classpath</h4>
  <p><code>Available</code>'s <em>classpath</em> attribute is a <a
  href="#path">PATH like structure</a> and can also be set via a nested
  <em>classpath</em> element.</p>
  <h3>Examples</h3>
  <pre>  &lt;available classname=&quot;org.whatever.Myclass&quot; property=&quot;Myclass.present&quot; /&gt;</pre>
  <p>sets the property <code><i>Myclass.present</i></code> to the value &quot;true&quot;
  if the <i>org.whatever.Myclass</i> is found in Ant's classpath.</p>
  <hr>
  <h2><a name="chmod">Chmod</a></h2>
  <h3>Description</h3>
  <p>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.</p>
  <p>See the section on <a href="#directorybasedtasks">directory based
  tasks</a>, on how the inclusion/exclusion of files works, and how to
  write patterns.</p>
  <p>This task holds an implicit <a href="#fileset">FileSet</a> and
  supports all of FileSet's attributes and nested elements
  directly. More FileSets can be specified using nested
  <code>&lt;fileset&gt;</code> elements.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">file</td>
      <td valign="top">the file or single directory of which the permissions 
        must be changed.</td>
      <td valign="top" valign="middle" rowspan="2">exactly one of the two or nested <code>&lt;fileset&gt;</code> elements.</td>
    </tr>
    <tr>
      <td valign="top">dir</td>
      <td valign="top">the directory which holds the files whose permissions 
        must be changed.</td>
    </tr>
    <tr>
      <td valign="top">perm</td>
      <td valign="top">the new permissions.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top">comma separated list of patterns of files that must be
        included. All files are included when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an include pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top">comma separated list of patterns of files that must be
        excluded. No files (except default excludes) are excluded when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an exclude pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">defaultexcludes</td>
      <td valign="top">indicates whether default excludes should be used or not
        (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">parallel</td>
      <td valign="top">process all specified files using a single
        <code>chmod</code> command. Defaults to true.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">type</td>
      <td valign="top">One of <em>file</em>, <em>dir</em> or
        <em>both</em>. If set to <em>file</em>, only the permissions of
        plain files are going to be changed. If set to <em>dir</em>, only
        the directories are considered.</td>
      <td align="center" valign="top">No, default is <em>file</em></td>
    </tr>
  </table>
  <h3>Examples</h3>
  <blockquote>
    <p><code>&lt;chmod file=&quot;${dist}/start.sh&quot; perm=&quot;ugo+rx&quot;
    /&gt;</code></p>
  </blockquote>
  <p>makes the &quot;start.sh&quot; file readable and executable for anyone on a
  UNIX system.</p>
  <blockquote>
  <pre>
      &lt;chmod dir=&quot;${dist}/bin&quot; perm=&quot;ugo+rx&quot; includes=&quot;**/*.sh&quot; /&gt;
  </pre>
  </blockquote>
  <p>makes all &quot;.sh&quot; files below <code>${dist}/bin</code>
  readable and executable for anyone on a UNIX system.</p>
  <blockquote>
  <pre>
  &lt;chmod perm=&quot;g+w&quot; /&gt;
    &lt;fileset dir=&quot;shared/sources1&quot; &gt;
      &lt;exclude name=&quot;**/trial/**&quot; /&gt;
    &lt;/fileset&gt;
    &lt;fileset refid=&quot;other.shared.sources&quot; /&gt;
  &lt;/chmod&gt;
  </pre>
  </blockquote>
  <p>makes all files below <code>shared/sources1</code> (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 <code>id</code> <code>other.shared.sources</code> get the same
  permissions.</p>
  <hr>
  <h2><a name="copy">Copy</a></h2>
  <h3>Description</h3>
  <p>Copies a file or Fileset to a new file or directory.  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 <var>overwrite</var> attribute.</p>
  <p><a href="#fileset">FileSet</a>s are used to select files to copy.  
  To use a fileset, the <var>todir</var> attribute must be set.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">file</td>
      <td valign="top">The file to copy.</td>
      <td valign="top" align="center">One of either <var>file</var> or 
      at least one nested fileset element.</td>
    </tr>
    <tr>
      <td valign="top">tofile</td>
      <td valign="top">The file to copy to.</td>
      <td valign="top" align="center" rowspan="2">With the <var>file</var> attribute, 
      either <var>tofile</var> or <var>todir</var> can be used.  With nested filesets, 
      only <var>todir</var> is allowed.</td>
    </tr>
    <tr>
      <td valign="top">todir</td>
      <td valign="top">The directory to copy to.</td>
    </tr>
    <tr>
      <td valign="top">overwrite</td>
      <td valign="top">Overwrite existing files even if the destination
        files are newer. Defaults to &quot;no&quot;.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">filtering</td>
      <td valign="top">Indicates whether token filtering should take place during
        the copy. Defaults to &quot;no&quot;.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">flatten</td>
      <td valign="top">Ignore directory structure of source directory,
        copy all files into a single directory, specified by the <var>todir</var>
        attribute. Defaults to &quot;no&quot;.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includeEmptyDirs</td>
  	 <td valign="top">Copy empty directories included with the nested FileSet(s).
  	   Defaults to &quot;yes&quot;.</td>
  	 <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <p><b>Copy a single file</b></p>
  <pre>
    &lt;copy file=&quot;myfile.txt&quot; tofile=&quot;mycopy.txt&quot; /&gt;
  </pre>
  <p><b>Copy a file to a directory</b></p>
  <pre>
    &lt;copy file=&quot;myfile.txt&quot; todir=&quot;../some/dir/tree&quot; /&gt;
  </pre>
  <p><b>Copy a directory to another directory</b></p>
  <pre>
    &lt;copy todir=&quot;../new/dir&quot;&gt;
      &lt;fileset dir=&quot;src_dir&quot;/&gt;
    &lt;/copy&gt;
  </pre>
  <p><b>Copy a set of files to a directory</b></p>
  <pre>
    &lt;copy todir=&quot;../dest/dir&quot; &gt;
      &lt;fileset dir=&quot;src_dir&quot &gt;
        &lt;exclude name=&quot;**/*.java&quot; /&gt;
      &lt;/fileset&gt;
    &lt;/copy&gt;
  
    &lt;copy todir=&quot;../dest/dir&quot; &gt;
      &lt;fileset dir=&quot;src_dir&quot excludes=&quot;**/*.java&quot; /&gt;
    &lt;/copy&gt;
  </pre>
  <hr>
  <h2><a name="copydir">Copydir</a></h2>
  <h3><i>Deprecated</i></h3>
  <p><i>This task has been deprecated.  Use the Copy task instead.</i></p>
  <h3>Description</h3>
  <p>Copies a directory tree from the source to the destination.</p>
  <p>It is possible to refine the set of files that are being copied. This can be
  done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
  attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
  have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
  the files you want to have excluded. This is also done with patterns. And
  finally with the <i>defaultexcludes</i> attribute, you can specify whether you
  want to use default exclusions or not. See the section on <a
  href="#directorybasedtasks">directory based tasks</a>, on how the
  inclusion/exclusion of files works, and how to write patterns.</p>
  <p>This task forms an implicit <a href="#fileset">FileSet</a> and
  supports all attributes of <code>&lt;fileset&gt;</code>
  (<code>dir</code> becomes <code>src</code>) as well as the nested
  <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
  <code>&lt;patternset&gt;</code> elements.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">src</td>
      <td valign="top">the directory to copy.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">dest</td>
      <td valign="top">the directory to copy to.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top">comma separated list of patterns of files that must be
        included. All files are included when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an include pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top">comma separated list of patterns of files that must be
        excluded. No files (except default excludes) are excluded when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an exclude pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">defaultexcludes</td>
      <td valign="top">indicates whether default excludes should be used or not
        (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">filtering</td>
      <td valign="top">indicates whether token filtering should take place during
        the copy</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">flatten</td>
      <td valign="top">ignore directory structure of source directory,
        copy all files into a single directory - specified by the dest
        attribute (default is false).</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">forceoverwrite</td>
      <td valign="top">overwrite existing files even if the destination
        files are newer (default is false).</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;copydir src=&quot;${src}/resources&quot;
             dest=&quot;${dist}&quot;
    /&gt;</pre>
  <p>copies the directory <code>${src}/resources</code> to <code>${dist}</code>.</p>
  <pre>  &lt;copydir src=&quot;${src}/resources&quot;
             dest=&quot;${dist}&quot;
             includes=&quot;**/*.java&quot;
             excludes=&quot;**/Test.java&quot;
    /&gt;</pre>
  <p>copies the directory <code>${src}/resources</code> to <code>${dist}</code>
  recursively. All java files are copied, except for files with the name <code>Test.java</code>.</p>
  <pre>  &lt;copydir src=&quot;${src}/resources&quot;
             dest=&quot;${dist}&quot;
             includes=&quot;**/*.java&quot;
             excludes=&quot;mypackage/test/**&quot; /&gt;</pre>
  <p>copies the directory <code>${src}/resources</code> to <code>${dist}</code>
  recursively. All java files are copied, except for the files under the <code>mypackage/test</code>
  directory.</p>
  <hr>
  <h2><a name="copyfile">Copyfile</a></h2>
  <h3><i>Deprecated</i></h3>
  <p><i>This task has been deprecated.  Use the Copy task instead.</i></p>
  <h3>Description</h3>
  <p>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.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">src</td>
      <td valign="top">the filename of the file to copy.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">dest</td>
      <td valign="top">the filename of the file where to copy to.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">filtering</td>
      <td valign="top">indicates whether token filtering should take place during
        the copy</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">forceoverwrite</td>
      <td valign="top">overwrite existing files even if the destination
        files are newer (default is false).</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <blockquote>
    <p><code>&lt;copyfile src=&quot;test.java&quot; dest=&quot;subdir/test.java&quot;
    /&gt;</code></p>
    <p><code>&lt;copyfile src=&quot;${src}/index.html&quot; dest=&quot;${dist}/help/index.html&quot;
    /&gt;</code></p>
  </blockquote>
  <hr>
  <h2><a name="cvs">Cvs</a></h2>
  <h3>Description</h3>
  <p>Handles packages/modules retrieved from a 
  <a href="http://www.cyclic.com/">CVS</a> repository.</p>
  <p>When doing automated builds, the <a href="#get">get task</a> should be
  preferred over the <i>checkout</i> command, because of speed.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">command</td>
      <td valign="top">the CVS command to execute.</td>
      <td align="center" valign="top">No, default &quot;checkout&quot;</td>
    </tr>
    <tr>
      <td valign="top">cvsRoot</td>
      <td valign="top">the CVSROOT variable.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">dest</td>
      <td valign="top">the directory where the checked out files should be placed.</td>
      <td align="center" valign="top">No, default is project's basedir.</td>
    </tr>
    <tr>
      <td valign="top">package</td>
      <td valign="top">the package/module to check out.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">tag</td>
      <td valign="top">the tag of the package/module to check out.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">date</td>
      <td valign="top">Use the most recent revision no later than the given date</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">quiet</td>
      <td valign="top">suppress informational messages.</td>
      <td align="center" valign="top">No, default &quot;false&quot;</td>
    </tr>
    <tr>
      <td valign="top">noexec</td>
      <td valign="top">report only, don't change any files.</td>
      <td align="center" valign="top">No, default &quot;false&quot;</td>
    </tr>
    <tr>
      <td valign="top">output</td>
      <td valign="top">the file to direct standard output from the command.</td>
      <td align="center" valign="top">No, default output to ANT Log as MSG_INFO.</td>
    </tr>
    <tr>
      <td valign="top">error</td>
      <td valign="top">the file to direct standard error from the command.</td>
      <td align="center" valign="top">No, default error to ANT Log as MSG_WARN.</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;cvs cvsRoot=&quot;:pserver:anoncvs@jakarta.apache.org:/home/cvspublic&quot;
         package=&quot;jakarta-tools&quot;
         dest=&quot;${ws.dir}&quot;
    /&gt;</pre>
  <p>checks out the package/module &quot;jakarta-tools&quot; from the CVS
  repository pointed to by the cvsRoot attribute, and stores the files in &quot;${ws.dir}&quot;.</p>
  <pre>  &lt;cvs dest=&quot;${ws.dir}&quot; command=&quot;update&quot; /&gt;</pre>
  <p>updates the package/module that has previously been checked out into
  &quot;${ws.dir}&quot;.</p>
  <hr>
  <h2><a name="delete">Delete</a></h2>
  <h3>Description</h3>
  <p>Deletes either a single file, all files in a specified directory and its 
  sub-directories, or a set of files specified by one or more <a href="#fileset">FileSet</a>s.
  When specifying a set of files, empty directories are <em>not</em> removed.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">file</td>
      <td valign="top">The file to delete.</td>
      <td align="center" valign="middle" rowspan="2">at least one of the two</td>
    </tr>
    <tr>
      <td valign="top">dir</td>
      <td valign="top">The directory to delete files from.</td>
    </tr>
    <tr>
      <td valign="top">verbose</td>
      <td valign="top">Show name of each deleted file (&quot;true&quot;/&quot;false&quot;).
  	 Default is &quot;false&quot; when omitted.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top"><i>Deprecated.</i>  Comma separated list of patterns of files that must be
        deleted. All files are in the current directory 
        and any sub-directories are deleted when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top"><i>Deprecated.</i>  The name of a file. Each line of this file is
        taken to be an include pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top"><i>Deprecated.</i>  Comma separated list of patterns of files that must be
        excluded from the deletion list. No files (except default excludes) are excluded when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top"><i>Deprecated.</i>  The name of a file. Each line of this file is
        taken to be an exclude pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">defaultexcludes</td>
      <td valign="top"><i>Deprecated.</i>  Indicates whether default excludes should be used or not
        (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;delete file=&quot;/lib/ant.jar&quot; /&gt;</pre>
  <p>deletes the file <code>/lib/ant.jar</code>.</p>
  <pre>  &lt;delete dir=&quot;lib&quot; /&gt;</pre>
  <p>deletes all files in the <code>/lib</code> directory.</p>
  <pre>  &lt;delete&gt;
      &lt;fileset dir=&quot;.&quot; includes=&quot;**/*.bak&quot; /&gt;
    &lt;/delete&gt;
  </pre>
  <p>deletes all files with the extension &quot;<code>.bak</code>&quot from the current directory 
  and any sub-directories.</p>
  <hr>
  <h2><a name="deltree">Deltree</a></h2>
  <h3><i>Deprecated</i></h3>
  <p><i>This task has been deprecated.  Use the Delete task instead.</i></p>
  <h3>Description</h3>
  <p>Deletes a directory with all its files and subdirectories.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">dir</td>
      <td valign="top">the directory to delete.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;deltree dir=&quot;dist&quot; /&gt;</pre>
  <p>deletes the directory <code>dist</code>, including its files and
  subdirectories.</p>
  <pre>  &lt;deltree dir=&quot;${dist}&quot; /&gt;</pre>
  <p>deletes the directory <code>${dist}</code>, including its files and
  subdirectories.</p>
  <hr>
  <h2><a name="echo">Echo</a></h2>
  <h3>Description</h3>
  <p>Echoes a message to System.out or a file.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">message</td>
      <td valign="top">the message to echo.</td>
      <td valign="top" align="center">Yes, unless data is included in a
        character section within this element.</td>
    </tr>
    <tr>
      <td valign="top">file</td>
      <td valign="top">the file to write the message to.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">append</td>
      <td valign="top">Append to an existing file?</td>
      <td valign="top" align="center">No - default is false.</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;echo message=&quot;Hello world&quot; /&gt;</pre>
  <pre>  
  &lt;echo&gt;
  This is a longer message stretching over
  two lines.
  &lt;/echo&gt;
  </pre>
  <hr>
  <h2><a name="exec">Exec</a></h2>
  <h3>Description</h3>
  <p>Executes a system command. When the <i>os</i> attribute is specified, then
  the command is only executed when Ant is run on one of the specified operating
  systems.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">command</td>
      <td valign="top">the command to execute with all command line
        arguments. <b>deprecated, use executable and nested
        <code>&lt;arg&gt;</code> elements instead</b>.</td>
      <td align="center" rowspan="2">Exactly one of the two.</td>
    </tr>
    <tr>
      <td valign="top">executable</td>
      <td valign="top">the command to execute without any command line
        arguments.</td>
    </tr>
    <tr>
      <td valign="top">dir</td>
      <td valign="top">the directory in which the command should be executed.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">os</td>
      <td valign="top">list of Operating Systems on which the command may be
        executed.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">output</td>
      <td valign="top">the file to which the output of the command should be
        redirected.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">timeout</td>
      <td valign="top">Stop the command if it doesn't finish within the
        specified time (given in milliseconds).</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">failonerror</td>
      <td valign="top">Stop the buildprocess if the command exits with a
        returncode other than 0.</td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <blockquote>
    <p><code>&lt;exec dir=&quot;${src}&quot; executable=&quot;dir&quot; os=&quot;windows&quot;
    output=&quot;dir.txt&quot; /&gt;</code></p>
  </blockquote>
  <h3>Parameters specified as nested elements</h3>
  <h4>arg</h4>
  <p>Command line arguments should be specified as nested
  <code>&lt;arg&gt;</code> elements. See <a
  href="index.html#arg">Command line arguments</a>.</p>
  <h4><a name="env">env</a></h4>
  <p>It is possible to specify environment variables to pass to the
  system command via nested <code>&lt;env&gt;</code> elements.</p>
  <p>Please note that the environment of the current Ant process is
  <b>not</b> passed to the system command if you specify variables using
  <code>&lt;env&gt;</code>.</p>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">key</td>
      <td valign="top">The name of the environment variable.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">value</td>
      <td valign="top">The literal value for the environment variable.</td>
      <td align="center" rowspan="3">Exactly one of these.</td>
    </tr>
    <tr>
      <td valign="top">path</td>
      <td valign="top">The value for a PATH like environment
        variable. You can use ; or : as path separators and Ant will
        convert it to the platform's local conventions.</td>
    </tr>
    <tr>
      <td valign="top">file</td>
      <td valign="top">The value for the environment variable. Will be
        replaced by the absolute filename of the file by Ant.</td>
    </tr>
  </table>
  <h5>Examples</h5>
  <blockquote><pre>
  &lt;exec executable=&quot;emacs&quot; &gt;
    &lt;env key=&quot;DISPLAY&quot; value=&quot;:1.0&quot; /&gt;
  &lt;/exec&gt;
  </pre></blockquote>
  <p>starts <code>emacs</code> on display 1 of the X Window System.</p>
  <blockquote><pre>
  &lt;exec ... &gt;
    &lt;env key=&quot;PATH&quot; path=&quot;${java.library.path}:${basedir}/bin&quot; /&gt;
  &lt;/exec&gt;
  </pre></blockquote>
  <p>adds <code>${basedir}/bin</code> to the <code>PATH</code> of the
  system command.</p>
  <p><b>Note:</b> Although it may work for you to specify arguments using 
  a simple arg-element and seperate them by spaces it may fail if you switch to
  a newer version of the JDK. JDK &lt; 1.2 will pass these as separate arguments
  to the program you are calling, JDK &gt;= 1.2 will pass them as a single 
  argument and cause most calls to fail.</p>
  <p><b>Note2:</b> If you are using Ant on Windows and a new DOS-Window pops up
  for every command which is excuted this may be a problem of the JDK you are using.
  This problem may occur with all JDK's &lt; 1.2.</p>
  <hr>
  <h2><a name="execon">ExecOn</a></h2>
  <h3>Description</h3>
  <p>Executes a system command. When the <i>os</i> attribute is specified, then
  the command is only executed when Ant is run on one of the specified operating
  systems.</p>
  <p>The files and/or directories of a number of <a
  href="#fileset">FileSet</a>s are passed as arguments to the system
  command. At least one nested <code>&lt;fileset&gt;</code> is required.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">executable</td>
      <td valign="top">the command to execute without any command line
        arguments.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">dir</td>
      <td valign="top">the directory in which the command should be executed.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">os</td>
      <td valign="top">list of Operating Systems on which the command may be
        executed.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">output</td>
      <td valign="top">the file to which the output of the command should be
        redirected.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">timeout</td>
      <td valign="top">Stop the command if it doesn't finish within the
        specified time (given in milliseconds).</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">failonerror</td>
      <td valign="top">Stop the buildprocess if the command exits with a
        returncode other than 0.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">parallel</td>
      <td valign="top">Run the command only once, appending all files as
        arguments. Defaults to true. If false, command will be executed
        once for every file.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">type</td>
      <td valign="top">One of <em>file</em>, <em>dir</em> or
        <em>both</em>. If set to <em>file</em>, only the names of plain
        files will be sent to the command. If set to <em>dir</em>, only
        the names of directories are considered.</td>
      <td align="center" valign="top">No, default is <em>file</em></td>
    </tr>
  </table>
  <h3>Parameters specified as nested elements</h3>
  <h4>fileset</h4>
  <p>You can use any number of nested <code>&lt;fileset&gt;</code>
  elements to define the files for this task and refer to
  <code>&lt;fileset&gt;</code>s defined elsewhere.</p>
  <h4>arg</h4>
  <p>Command line arguments should be specified as nested
  <code>&lt;arg&gt;</code> elements. See <a
  href="index.html#arg">Command line arguments</a>.</p>
  <h4>env</h4>
  <p>It is possible to specify environment variables to pass to the
  system command via nested <code>&lt;env&gt;</code> elements. See the
  description in the section about <a href="#env">exec</a></p>
  <p>Please note that the environment of the current Ant process is
  <b>not</b> passed to the system command if you specify variables using
  <code>&lt;env&gt;</code>.</p>
  <h3>Examples</h3>
  <blockquote><pre>
  &lt;execon executable=&quot;ls&quot; &gt;
    &lt;arg value=&quot;-l&quot; /&gt;
    &lt;fileset dir=&quot;/tmp&quot;&gt;
      &lt;patternset&gt;
        &lt;exclude name=&quot;**/*.txt&quot; /&gt;
      &lt;/patternset&gt;
    &lt;/fileset&gt;
    &lt;fileset refid=&quot;other.files&quot; /&gt;
  &lt;/execon&gt;
  </pre></blockquote>
  <p>invokes <code>ls -l</code>, adding the absolute filenames of all
  files below <code>/tmp</code> not ending in <code>.txt</code> and all
  files of the FileSet with <code>id</code> <code>other.files</code> to
  the command line.</p>
  <hr>
  <h2><a name="fail">Fail</a></h2>
  <h3>Description</h3>
  <p>Exits the current build (just throwing a BuildException), optionally printing additional information.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">message</td>
      <td valign="top">A message giving further information on why the build exited</td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;fail/&gt;</pre>
  <p>will exit the current build with no further information given.
  <pre>
  BUILD FAILED
  
  build.xml:4: No message
  </pre>
  </p>
  <pre>  &lt;fail message=&quot;Something wrong here.&quot;/&gt;</pre>
  <p>will exit the current build and print something like the following to whereever
  your output goes:
  <pre>
  BUILD FAILED
  
  build.xml:4: Something wrong here.
  </pre>
  </p>
  <hr>
  <h2><a name="filter">Filter</a></h2>
  <h3>Description</h3>
  <p>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.</p>
  <p>Note 1: the token string must not contain the separators chars (@).<br>
  Note 2: Either token and value attributes must be provided, or only the
  filterfile attribute.</p>
  
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">token</td>
      <td valign="top">the token string without @</td>
      <td align="center" valign="top">Yes*</td>
    </tr>
    <tr>
      <td valign="top">value</td>
      <td valign="top">the string that should be put to replace the token when the 
        file is copied</td>
      <td align="center" valign="top">Yes*</td>
    </tr>
    <tr>
      <td valign="top">filtersfile</td>
      <td valign="top">The file from which the filters must be read. This file must be a formatted as a property file. </td>
      <td align="center" valign="top">Yes*</td>
    </tr>
  </table>
  <p>* see notes 1 and 2 above parameters table.</p>
  <h3>Examples</h3>
  <pre>  &lt;filter token=&quot;year&quot; value=&quot;2000&quot; /&gt;
    &lt;copy todir=&quot;${dest.dir}&quot;&gt;
      &lt;fileset dir=&quot;${src.dir}&quot; /&gt;
    &lt;/copy&gt;</pre> 
  <p>will copy recursively all the files from the <i>src.dir</i> directory into
  the <i>dest.dir</i> directory replacing all the occurencies of the string <i>@year@</i>
  with <i>2000.</i></p>
  <pre>  &lt;filter filterfile=&quot;deploy_env.properties&quot; /&gt;</pre>
  will read all property entries from the <i>deploy_env.properties</i> file
  and set these as filters.
  
  <hr>
  <h2><a name="fixcrlf">FixCRLF</a></h2>
  <h3>Description</h3>
  <p>Adjusts a text file to local.</p>
  <p>It is possible to refine the set of files that are being adjusted. This can be
  done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
  attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
  have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
  the files you want to have excluded. This is also done with patterns. And
  finally with the <i>defaultexcludes</i> attribute, you can specify whether you
  want to use default exclusions or not. See the section on <a
  href="#directorybasedtasks">directory based tasks</a>, on how the
  inclusion/exclusion of files works, and how to write patterns.</p>
  <p>This task forms an implicit <a href="#fileset">FileSet</a> and
  supports all attributes of <code>&lt;fileset&gt;</code>
  (<code>dir</code> becomes <code>srcdir</code>) as well as the nested
  <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
  <code>&lt;patternset&gt;</code> elements.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">srcDir</td>
      <td valign="top">Where to find the files to be fixed up.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">destDir</td>
      <td valign="top">Where to place the corrected files.  Defaults to
        srcDir (replacing the original file)</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top">comma separated list of patterns of files that must be
        included. All files are included when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an include pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top">comma separated list of patterns of files that must be
        excluded. No files (except default excludes) are excluded when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an exclude pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">defaultexcludes</td>
      <td valign="top">indicates whether default excludes should be used or not
        (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">cr</td>
      <td valign="top">Specifies how carriage return (CR) characters are to
        be handled.  Valid values for this property are:
        <ul>
        <li>add: ensure that there is a CR before every LF
        <li>asis: leave CR characters alone
        <li>remove: remove all CR characters
        </ul>
        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.
        <p>
        Note: Unless this property is specified as &quot;asis&quot;, extra CR characters
        which do not precede a LF will be removed.
        </td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">tab</td>
      <td valign="top">Specifies how tab characters are to be handled.  Valid
        values for this property are:
        <ul>
        <li>add: convert sequences of spaces which span a tab stop to tabs
        <li>asis: leave tab and space characters alone
        <li>remove: convert tabs to spaces
        </ul>
        Default for this parameter is &quot;asis&quot;.
        <p>
        Note: Unless this property is specified as &quot;asis&quot;, extra spaces and
        tabs after the last non-whitespace character on the line will be removed.
        </td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">tablength</td>
      <td valign="top">The number of characters a TAB stop corresponds to. 
        Must be a positive power of 2, default for this parameter is 8.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">eof</td>
      <td valign="top">Specifies how DOS end of file (control-Z) characters are
        to be handled.  Valid values for this property are:
        <ul>
        <li>add: ensure that there is an EOF character at the end of the file
        <li>asis: leave EOF characters alone
        <li>remove: remove any EOF character found at the end
        </ul>
        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.
        </td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;fixcrlf srcdir=&quot;${src}&quot;
         cr=&quot;remove&quot; eof=&quot;remove&quot;
         includes=&quot;**/*.sh&quot;
    /&gt;</pre>
  <p>Removes carriage return and eof characters from the shell scripts.  Tabs and
  spaces are left as is.
  <pre>  &lt;fixcrlf srcdir=&quot;${src}&quot;
         cr=&quot;add&quot;
         includes=&quot;**/*.bat&quot;
    /&gt;</pre>
  <p>Ensures that there are carriage return characters prior to evey line feed.
  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.</p>
  <pre>  &lt;fixcrlf srcdir=&quot;${src}&quot;
         tabs=&quot;add&quot;
         includes=&quot;**/Makefile&quot;
    /&gt;</pre>
  <p>Adds or removes CR characters to match local OS conventions, and
  converts spaces to tabs when appropriate.  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.</p>
  <pre>  &lt;fixcrlf srcdir=&quot;${src}&quot;
         tabs=&quot;remove&quot;
         includes=&quot;**/README*&quot;
    /&gt;</pre>
  <p>Adds or removes CR characters to match local OS conventions, and
  converts all tabs to spaces.  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.</p>
  <hr>
  <h2><a name="genkey">GenKey</a></h2>
  <h3>Description</h3>
  <p>Generates a key in keystore.</p>
  
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">alias</td>
      <td valign="top">the alias to add under</td>
      <td valign="top" align="center">Yes.</td>
    </tr>
    <tr>
      <td valign="top">storepass</td>
      <td valign="top">password for keystore integrity.</td>
      <td valign="top" align="center">Yes.</td>
    </tr>
    <tr>
      <td valign="top">keystore</td>
      <td valign="top">keystore location</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">storetype</td>
      <td valign="top">keystore type</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">keypass</td>
      <td valign="top">password for private key (if different)</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">sigalg</td>
      <td valign="top">the algorithm to use in signing</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">keyalg</td>
      <td valign="top">the method to use when generating name-value pair</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">verbose</td>
      <td valign="top">(true | false) verbose output when signing</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">dname</td>
      <td valign="top">The distinguished name for entity</td>
      <td valign="top" align="center">Yes if dname element unspecified</td>
    </tr>
    <tr>
      <td valign="top">validity</td>
      <td valign="top">(integer) indicates how many days certificate is valid</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">keysize</td>
      <td valign="top">(integer) indicates the size of key generated</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  
  <p>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 , are replace
  <p>The following two examples are identical: </p>
  
  <h3>Examples</h3>
  <blockquote>
    <p><code>&lt;genkey alias=&quot;apache-group&quot; storepass=&quot;secret&quot; 
    dname=&quot;CN=Ant Group, OU=Jakarta Division, O=Apache.org, C=US&quot; /&gt;</code></p>
  </blockquote>
  
  <blockquote>
    <pre><code>&lt;genkey alias=&quot;apache-group&quot; storepass=&quot;secret&quot; &gt;
    &lt;dname&gt;
      &lt;param name=&quot;CN&quot; value=&quot;Ant Group&quot;/&gt;
      &lt;param name=&quot;OU&quot; value=&quot;Jakarta Division&quot;/&gt;
      &lt;param name=&quot;O&quot;  value=&quot;Apache.Org&quot;/&gt;
      &lt;param name=&quot;C&quot;  value=&quot;US&quot;/&gt;
    &lt;/dname&gt;
  &lt;/genkey&gt;</code></pre>
  </blockquote>
  <hr>
  <h2><a name="get">Get</a></h2>
  <h3>Description</h3>
  <p>Gets a file from a URL. When the verbose option is &quot;on&quot;, this task
  displays a '.' for every 100 Kb retrieved.</p>
  <p>This task should be preferred above the <a href="#cvs">CVS task</a> when
  doing automated builds. CVS is significantly slower than loading a compressed
  archive with http/ftp.</p>
  
  The <i>usetimestamps</i> 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. 
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">src</td>
      <td valign="top">the URL from which to retrieve a file.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">dest</td>
      <td valign="top">the file where to store the retrieved file.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">verbose</td>
      <td valign="top">show verbose progress information (&quot;on&quot;/&quot;off&quot;).</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">ignoreerrors</td>
      <td valign="top">Log errors but don't treat as fatal.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">usetimestamps</td>
      <td valign="top">conditionally download a file based on the timestamp of the local copy.
  	HTTP only</td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;get src=&quot;http://jakarta.apache.org/&quot; dest=&quot;help/index.html&quot; /&gt;</pre>
  <p>Gets the index page of http://jakarta.apache.org/, and stores it in the file <code>help/index.html</code>.</p>
  
  <pre>  &lt;get src=&quot;http://jakarta.apache.org/builds/tomcat/nightly/ant.zip&quot; 
  	dest=&quot;optional.jar&quot; 
  	verbose=&quot;true&quot;
  	usetimestamps=&quot;true&quot;/&gt;</pre>
  <p>
  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.
  </p>
  
  <hr>
  <h2><a name="gunzip">GUnzip</a></h2>
  <h3>Description</h3>
  <p>Expands a GZip file.</p>
  
  <p>If <i>dest</i> is a directory the name of the destination file is
  the same as <i>src</i> (with the &quot;.gz&quot; extension removed if
  present). If <i>dest</i> is omitted, the parent dir of <i>src</i> 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.</p>
  
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">src</td>
      <td valign="top">the file to expand.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">dest</td>
      <td valign="top">the destination file or directory.</td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <blockquote>
    <p><code>&lt;gunzip src=&quot;test.tar.gz&quot;/&gt;</code></p>
  </blockquote>
  <p>expands <i>test.tar.gz</i> to <i>test.tar</i></p>
  <blockquote>
    <p><code>&lt;gunzip src=&quot;test.tar.gz&quot; dest=&quot;test2.tar&quot;/&gt;</code></p>
  </blockquote>
  <p>expands <i>test.tar.gz</i> to <i>test2.tar</i></p>
  <blockquote>
    <p><code>&lt;gunzip src=&quot;test.tar.gz&quot; dest=&quot;subdir&quot;/&gt;</code></p>
  </blockquote>
  <p>expands <i>test.tar.gz</i> to <i>subdir/test.tar</i> (assuming
  subdir is a directory).</p>
  
  <hr>
  <h2><a name="gzip">GZip</a></h2>
  <h3>Description</h3>
  <p>GZips a file.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">src</td>
      <td valign="top">the file to gzip.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">zipfile</td>
      <td valign="top">the destination file.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <blockquote>
    <p><code>&lt;gzip src=&quot;test.tar&quot; zipfile=&quot;test.tar.gz&quot;
    /&gt;</code></p>
  </blockquote>
  <hr>
  <h2><a name="jar">Jar</a></h2>
  <h3>Description</h3>
  <p>Jars a set of files.</p>
  <p>The <i>basedir</i> attribute is the reference directory from where to jar.</p>
  <p>Note that file permissions will not be stored in the resulting jarfile.</p>
  <p>It is possible to refine the set of files that are being jarred. This can be
  done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
  attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
  have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
  the files you want to have excluded. This is also done with patterns. And
  finally with the <i>defaultexcludes</i> attribute, you can specify whether you
  want to use default exclusions or not. See the section on <a
  href="#directorybasedtasks">directory based tasks</a>, on how the
  inclusion/exclusion of files works, and how to write patterns.</p>
  <p>This task forms an implicit <a href="#fileset">FileSet</a> and
  supports all attributes of <code>&lt;fileset&gt;</code>
  (<code>dir</code> becomes <code>basedir</code>) as well as the nested
  <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
  <code>&lt;patternset&gt;</code> elements.</p>
  <p>You can also use nested file sets for more flexibility, and specify
  multiple ones to merge together different trees of files into one JAR.
  See the <a href="#zip">Zip</a> task for more details and examples.</p>
  <p>If the manifest is omitted, a simple one will be supplied by Ant.
  You should not include <samp>META-INF/MANIFEST.MF</samp> in your set of files.
  <p>The <code>whenempty</code> parameter controls what happens when no files match.
  If <code>create</code> (the default), the JAR is created anyway with only a manifest.
  If <code>skip</code>, the JAR is not created and a warning is issued.
  If <code>fail</code>, the JAR is not created and the build is halted with an error.
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">jarfile</td>
      <td valign="top">the jar-file to create.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">basedir</td>
      <td valign="top">the directory from which to jar the files.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">compress</td>
      <td valign="top">Not only store data but also compress them, defaults to true</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top">comma separated list of patterns of files that must be
        included. All files are included when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an include pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top">comma separated list of patterns of files that must be
        excluded. No files (except default excludes) are excluded when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an exclude pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">defaultexcludes</td>
      <td valign="top">indicates whether default excludes should be used or not
        (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">manifest</td>
      <td valign="top">the manifest file to use.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">whenempty</td>
      <td valign="top">Behavior to use if no files match.</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot; basedir=&quot;${build}/classes&quot; /&gt;</pre>
  <p>jars all files in the <code>${build}/classes</code> directory in a file
  called <code>app.jar</code> in the <code>${dist}/lib</code> directory.</p>
  <pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot;
         basedir=&quot;${build}/classes&quot;
         excludes=&quot;**/Test.class&quot;
    /&gt;</pre>
  <p>jars all files in the <code>${build}/classes</code> directory in a file
  called <code>app.jar</code> in the <code>${dist}/lib</code> directory. Files
  with the name <code>Test.class</code> are excluded.</p>
  <pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot;
         basedir=&quot;${build}/classes&quot;
         includes=&quot;mypackage/test/**&quot;
         excludes=&quot;**/Test.class&quot;
    /&gt;</pre>
  <p>jars all files in the <code>${build}/classes</code> directory in a file
  called <code>app.jar</code> in the <code>${dist}/lib</code> directory. Only
  files under the directory <code>mypackage/test</code> are used, and files with
  the name <code>Test.class</code> are excluded.</p>
  <pre>  &lt;jar jarfile=&quot;${dist}/lib/app.jar&quot;&gt;
      &lt;fileset dir=&quot;${build}/classes&quot;
               excludes=&quot;**/Test.class&quot;
      /&gt;
      &lt;fileset dir=&quot;${src}/resources&quot;/&gt;
    &lt;/jar&gt;</pre>
  <p>jars all files in the <code>${build}/classes</code> directory and also
  in the <code>${src}/resources</code> directory together in a file
  called <code>app.jar</code> in the <code>${dist}/lib</code> directory.
  Files with the name <code>Test.class</code> are excluded.
  If there are files such as <code>${build}/classes/mypackage/MyClass.class</code>
  and <code>${src}/resources/mypackage/image.gif</code>, they will appear
  in the same directory in the JAR (and thus be considered in the same package
  by Java).</p>
  
  <hr>
  <h2><a name="java">Java</a></h2>
  <h3>Description</h3>
  <p>Executes a Java class within the running (Ant) VM or forks another VM if
  specified.</p>
  <p>Be careful that the executed class doesn't call System.exit(), because it
  will terminate the VM and thus Ant. In case this happens, it's highly suggested
  that you set the fork attribute so that System.exit() stops the other VM and not
  the one that is currently running Ant.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">classname</td>
      <td valign="top">the Java class to execute.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">args</td>
      <td valign="top">the arguments for the class that is
        executed. <b>deprecated, use nested <code>&lt;arg&gt;</code>
        elements instead.</b></td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">classpath</td>
      <td valign="top">the classpath to use.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">classpathref</td>
      <td valign="top">the classpath to use, given as <a
        href="#references">reference</a> to a PATH defined elsewhere.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">fork</td>
      <td valign="top">if enabled triggers the class execution in another VM
        (disabled by default)</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">jvm</td>
      <td valign="top">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.
      </td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">jvmargs</td>
      <td valign="top">the arguments to pass to the forked VM (ignored
        if fork is disabled). <b>deprecated, use nested
        <code>&lt;jvmarg&gt;</code> elements instead.</b></td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">maxmemory</td>
      <td valign="top">Max amount of memory to allocate to the forked VM
        (ignored if fork is disabled)</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">failonerror</td>
      <td valign="top">Stop the buildprocess if the command exits with a
        returncode other than 0. Only available if fork is true.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">dir</td>
      <td valign="top">The directory to invoke the VM in.  (ignored if
        fork is disabled)</td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>
  <h3>Parameters specified as nested elements</h3>
  <h4>arg and jvmarg</h4>
  <p>Use nested <code>&lt;arg&gt;</code> and <code>&lt;jvmarg&gt;</code>
  elements to specify arguments for the or the forked VM. See <a
  href="index.html#arg">Command line arguments</a>.</p>
  <h4>sysproperty</h4>
  <p>Use nested <code>&lt;sysproperty&gt;</code>
  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 <a href="index.html#env">environment
  variables</a>.</p>
  <h4>classpath</h4>
  <p><code>Java</code>'s <em>classpath</em> attribute is a <a
  href="#path">PATH like structure</a> and can also be set via a nested
  <em>classpath</em> element.</p>
  <h5>Example</h5>
  <pre>  
         &lt;java classname=&quot;test.Main&quot; &gt;
           &lt;arg value=&quot;-h&quot; /&gt; 
           &lt;classpath&gt;
             &lt;pathelement location=&quot;\test.jar&quot; /&gt;
             &lt;pathelement path=&quot;${java.class.path}&quot; /&gt;
           &lt;/classpath&gt;
         &lt;/java&gt;
  </pre>
  <h3>Examples</h3>
  <pre>  &lt;java classname=&quot;test.Main&quot; /&gt;</pre>
  <pre>  &lt;java classname=&quot;test.Main&quot;
          fork=&quot;yes&quot; &gt;
      &lt;sysproperty key=&quot;DEBUG&quot; value=&quot;true&quot; /&gt; 
      &lt;arg value=&quot;-h&quot; /&gt; 
      &lt;jvmarg value=&quot;-Xrunhprof:cpu=samples,file=log.txt,depth=3&quot; /&gt; 
    &lt;/java&gt;
  </pre>
  
  <hr>
  <h2><a name="javac">Javac</a></h2>
  <h3>Description</h3>
  <p>Compiles a source tree within the running (Ant) VM.</p>
  <p>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.</p>
  <p>The directory structure of the source tree should follow the package
  hierarchy.</p>
  <p>It is possible to refine the set of files that are being compiled/copied.
  This can be done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
  attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
  have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
  the files you want to have excluded. This is also done with patterns. And
  finally with the <i>defaultexcludes</i> attribute, you can specify whether you
  want to use default exclusions or not. See the section on <a
  href="#directorybasedtasks">directory based tasks</a>, on how the
  inclusion/exclusion of files works, and how to write patterns.</p>
  <p>It is possible to use different compilers. This can be selected with the
  &quot;build.compiler&quot; property. There are three choices:</p>
  <ul>
    <li>classic (the standard compiler of JDK 1.1/1.2)</li>
    <li>modern (the new compiler of JDK 1.3)</li>
    <li>jikes (the <a
      href="http://oss.software.ibm.com/developerworks/opensource/jikes/project">Jikes</a>
      compiler)</li>
    <li>jvc (the Command-Line Compiler from Microsoft's SDK for Java /
      Visual J++)</li>
  </ul>
  <p>For JDK 1.1/1.2 is classic the default. For JDK 1.3 is modern the default.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">srcdir</td>
      <td valign="top">location of the java files.</td>
      <td align="center" valign="top">Yes, unless nested <code>&lt;src&gt;</code> elements are present.</td>
    </tr>
    <tr>
      <td valign="top">destdir</td>
      <td valign="top">location where to store the class files.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top">comma separated list of patterns of files that must be
        included. All files are included when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an include pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top">comma separated list of patterns of files that must be
        excluded. No files (except default excludes) are excluded when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an exclude pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">defaultexcludes</td>
      <td valign="top">indicates whether default excludes should be used or not
        (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">classpath</td>
      <td valign="top">the classpath to use.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">bootclasspath</td>
      <td valign="top">location of bootstrap class files.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">classpathref</td>
      <td valign="top">the classpath to use, given as <a
        href="#references">reference</a> to a PATH defined elsewhere.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">bootclasspathref</td>
      <td valign="top">location of bootstrap class files, given as by <a
        href="#references">reference</a> to a PATH defined elsewhere.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">extdirs</td>
      <td valign="top">location of installed extensions.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">encoding</td>
      <td valign="top">encoding of source files.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">debug</td>
      <td valign="top">indicates whether there should be compiled with debug
        information (&quot;off&quot;).</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">optimize</td>
      <td valign="top">indicates whether there should be compiled with
        optimization (&quot;off&quot;).</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">deprecation</td>
      <td valign="top">indicates whether there should be compiled with deprecation
        information (&quot;off&quot;).</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">target</td>
      <td valign="top">Generate class files for specific VM version, e.g.
  	 &quot;1.1&quot; or &quot;1.2&quot;.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">verbose</td>
      <td valign="top">asks the compiler for verbose output.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">depend</td> <td valign="top">enables dependency
        tracking for compilers that support this (jikes and classic)</td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>
  
  <h3>Parameters specified as nested elements</h3>
  <p>This task forms an implicit <a href="#fileset">FileSet</a> and
  supports all attributes of <code>&lt;fileset&gt;</code>
  (<code>dir</code> becomes <code>srcdir</code>) as well as the nested
  <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
  <code>&lt;patternset&gt;</code> elements.</p>
  <h4>src, classpath, bootclasspath and extdirs</h4>
  <p><code>Javac</code>'s <em>srcdir</em>, <em>classpath</em>,
  <em>bootclasspath</em> and <em>extdirs</em> attributes are <a
  href="#path">PATH like structure</a> and can also be set via nested
  <em>src</em>, <em>classpath</em>, <em>bootclasspath</em> and
  <em>extdirs</em> elements respectively.</p>
  
  <h3>Examples</h3>
  <pre>  &lt;javac srcdir=&quot;${src}&quot;
           destdir=&quot;${build}&quot;
           classpath=&quot;xyz.jar&quot;
           debug=&quot;on&quot;
    /&gt;</pre>
  <p>compiles all .java files under the directory <code>${src}</code>, and stores
  the .class files in the directory <code>${build}</code>. 
  The classpath used contains <code>xyz.jar</code>, and debug information is on.</p>
  <pre>  &lt;javac srcdir=&quot;${src}&quot;
           destdir=&quot;${build}&quot;
           includes=&quot;mypackage/p1/**,mypackage/p2/**&quot;
           excludes=&quot;mypackage/p1/testpackage/**&quot;
           classpath=&quot;xyz.jar&quot;
           debug=&quot;on&quot;
    /&gt;</pre>
  <p>compiles .java files under the directory <code>${src}</code>, and stores the
  .class files in the directory <code>${build}</code>. 
  The classpath used contains <code>xyz.jar</code>, and debug information is on.
  Only files under <code>mypackage/p1</code> and <code>mypackage/p2</code> are
  used. Files in the <code>mypackage/p1/testpackage</code> directory are excluded
  form compilation and copy.</p>
  
  <pre>  &lt;javac srcdir=&quot;${src}:${src2}&quot;
           destdir=&quot;${build}&quot;
           includes=&quot;mypackage/p1/**,mypackage/p2/**&quot;
           excludes=&quot;mypackage/p1/testpackage/**&quot;
           classpath=&quot;xyz.jar&quot;
           debug=&quot;on&quot;
    /&gt;</pre>
  
  <p>is the same as the previous example with the addition of a second source path, defined by
  the propery <code>src2</code>. This can also be represented using nested elements as follows
  
  <pre>  &lt;javac destdir=&quot;${build}&quot;
           classpath=&quot;xyz.jar&quot;
           debug=&quot;on&quot;&gt;
      &lt;src path=&quot;${src}&quot; /&gt;
      &lt;src path=&quot;${src2}&quot; /&gt;
      &lt;include name=&quot;mypackage/p1/**,mypackage/p2/**&quot; /&gt;
      &lt;exclude name=&quot;mypackage/p1/testpackage/**&quot; /&gt;
    &lt;/javac&gt;</pre>
  
  <p><b>Note:</b> 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 JDK's &lt; 1.2.</p>
  
  <hr>
  <h2><a name="javadoc">Javadoc/Javadoc2</a></h2>
  <h3>Description</h3>
  <p>Generates code documentation using the javadoc tool.</p>
  <p>The source directory will be recursively scanned for Java source files to process
  but only those matching the inclusion 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
  &quot;changed&quot; files, unlike the <a href="#javac">javac</a> task. This means
  all packages will be processed each time this task is run. In general, however,
  this task is used much less frequently.</p>
  <p>This task works seamlessly between different javadoc versions (1.1 and 1.2),
  with the obvious restriction that the 1.2 attributes will be ignored if run in a
  1.1 VM.</p>
  <p>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.</p>
  <p>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. 
  
  <p>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 <a href="#javadoc">javadoc</a>
  instead.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Availability</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">sourcepath</td>
      <td valign="top">Specify where to find source files</td>
      <td align="center" valign="top">all</td>
      <td align="center" rowspan="2">At least one of the two or nested
        <code>&lt;sourcepath&gt;</code></td>
    </tr>
    <tr>
      <td valign="top">sourcepathref</td>
      <td valign="top">Specify where to find source files by <a
        href="#references">reference</a> to a PATH defined elsewhere.</td>
      <td align="center" valign="top">all</td>
    </tr>
    <tr>
      <td valign="top">destdir</td>
      <td valign="top">Destination directory for output files</td>
      <td align="center" valign="top">all</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">maxmemory</td>
      <td valign="top">Max amount of memory to allocate to the javadoc VM</td>
      <td align="center" valign="top">all</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">sourcefiles</td>
      <td valign="top">Space separated list of source files</td>
      <td align="center" valign="top">all</td>
      <td align="center" valign="middle" rowspan="2">at least one of the two</td>
    </tr>
    <tr>
      <td valign="top">packagenames</td>
      <td valign="top">Comma separated list of package files (with terminating
        wildcard)</td>
      <td align="center" valign="top">all</td>
    </tr>
    <tr>
      <td valign="top">packageList</td>
      <td valign="top">The name of a file containing the packages to process</td>
      <td align="center" valign="top">all</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">classpath</td>
      <td valign="top">Specify where to find user class files</td>
      <td align="center" valign="top">all</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Bootclasspath</td>
      <td valign="top">Override location of class files loaded by the bootstrap
        class loader</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">classpathref</td>
      <td valign="top">Specify where to find user class files by <a
        href="#references">reference</a> to a PATH defined elsewhere.</td>
      <td align="center" valign="top">all</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">bootclasspathref</td>
      <td valign="top">Override location of class files loaded by the
        bootstrap class loader by <a href="#references">reference</a> to a
        PATH defined elsewhere.</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Extdirs</td>
      <td valign="top">Override location of installed extensions</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Overview</td>
      <td valign="top">Read overview documentation from HTML file</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Public</td>
      <td valign="top">Show only public classes and members</td>
      <td align="center" valign="top">all</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Protected</td>
      <td valign="top">Show protected/public classes and members (default)</td>
      <td align="center" valign="top">all</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Package</td>
      <td valign="top">Show package/protected/public classes and members</td>
      <td align="center" valign="top">all</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Private</td>
      <td valign="top">Show all classes and members</td>
      <td align="center" valign="top">all</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Old</td>
      <td valign="top">Generate output using JDK 1.1 emulating doclet</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Verbose</td>
      <td valign="top">Output messages about what Javadoc is doing</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Locale</td>
      <td valign="top">Locale to be used, e.g. en_US or en_US_WIN</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Encoding</td>
      <td valign="top">Source file encoding name</td>
      <td align="center" valign="top">all</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Version</td>
      <td valign="top">Include @version paragraphs</td>
      <td align="center" valign="top">all</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Use</td>
      <td valign="top">Create class and package usage pages</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Author</td>
      <td valign="top">Include @author paragraphs</td>
      <td align="center" valign="top">all</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Splitindex</td>
      <td valign="top">Split index into one file per letter</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Windowtitle</td>
      <td valign="top">Browser window title for the documentation (text)</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Doctitle</td>
      <td valign="top">Include title for the package index(first) page (html-code)</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Header</td>
      <td valign="top">Include header text for each page (html-code)</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">Footer</td>
      <td valign="top">Include footer text for each page (html-code)</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">bottom</td>
      <td valign="top">Include bottom text for each page (html-code)</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">link</td>
      <td valign="top">Create links to javadoc output at the given URL</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">linkoffline</td>
      <td valign="top">Link to docs at &lt;url&gt; using package list at
        &lt;url2&gt;</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">group</td>
      <td valign="top">Group specified packages together in overview page</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">nodeprecated</td>
      <td valign="top">Do not include @deprecated information</td>
      <td align="center" valign="top">all</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">nodeprecatedlist</td>
      <td valign="top">Do not generate deprecated list</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">notree</td>
      <td valign="top">Do not generate class hierarchy</td>
      <td align="center" valign="top">all</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">noindex</td>
      <td valign="top">Do not generate index</td>
      <td align="center" valign="top">all</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">nohelp</td>
      <td valign="top">Do not generate help link</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">nonavbar</td>
      <td valign="top">Do not generate navigation bar</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">serialwarn</td>
      <td valign="top">FUTURE: Generate warning about @serial tag</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">helpfile</td>
      <td valign="top">FUTURE: Specifies the HTML help file to use</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">stylesheetfile</td>
      <td valign="top">Specifies the CSS stylesheet to use</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">charset</td>
      <td valign="top">FUTURE: Charset for cross-platform viewing of generated
        documentation</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">docencoding</td>
      <td valign="top">Output file encoding name</td>
      <td align="center" valign="top">1.1</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">doclet</td>
      <td valign="top">Specifies the class file that starts the doclet used in generating the documentation.</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">docletpath</td>
      <td valign="top">Specifies the path to the doclet class file that is specified with the -doclet option.</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">docletpathref</td>
      <td valign="top">Specifies the path to the doclet class file that
        is specified with the -doclet option by <a
        href="#references">reference</a> to a PATH defined elsewhere.</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">additionalparam</td>
      <td valign="top">Lets you add additional parameters to the javadoc command line. Useful for doclets</td>
      <td align="center" valign="top">1.2</td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>
  
  <h3>Parameters specified as nested elements</h3>
  <h4>link</h4>
  <p>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.</p>
  <h4>Parameters</h4>
  
  <table width="60%" border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">href</td>
      <td valign="top">The URL for the external documentation you wish to link to</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">offline</td>
      <td valign="top">True if this link is not available online at the time of 
                       generating the documentation</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">packagelistLoc</td>
      <td valign="top">The location to the directory containing the package-list file for
                       the external documentation</td>
      <td align="center" valign="top">Only if the offline attribute is true</td>
    </tr>
  </table>
    
  <h4>groups</h4> 
  <p>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.</p>
  
  <table width="60%" border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">title</td>
      <td valign="top">Title of the group</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">packages</td>
      <td valign="top">List of packages to include in that group</td>
      <td align="center" valign="top">Yes</td>
    </tr>
  </table>
  
  <h4>doclet</h4>
  <p>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 
  <code>&lt;doclet&gt;</code> nested element. Such attributes should only be specified, 
  therefore, if they can be interpreted by the doclet in use.
  
  <p>If the doclet requires additional parameters, these can be specified with
  <code>&lt;param&gt;</code> elements within the <code>&lt;doclet&gt;</code> 
  element. These paramaters are restricted to simple strings. An example usage
  of the doclet element is shown below:
  
  <pre>  &lt;javadoc ...&gt;
       &lt;doclet name="theDoclet"
               path="path/to/theDoclet"&gt;
          &lt;param name="-foo" value="foovalue"/&gt;
          &lt;param name="-bar" value="barvalue"/&gt;
       &lt;/doclet&gt;
    &lt;/javadoc&gt;
  </pre>
  
  <h4>sourcepath, classpath and bootclasspath</h4>
  <p><code>Javadoc</code>'s <em>sourcepath</em>, <em>classpath</em> and
  <em>bootclasspath</em> attributes are <a href="#path">PATH like
  structure</a> and can also be set via nested <em>sourcepath</em>,
  <em>classpath</em> and <em>bootclasspath</em> elements
  respectively.</p>
  
  <h3>Example</h3>
  <pre>  &lt;javadoc packagenames=&quot;com.dummy.test.*&quot;
             sourcepath=&quot;src&quot;
             destdir=&quot;docs/api&quot;
             author=&quot;true&quot;
             version=&quot;true&quot;
             use=&quot;true&quot;
             windowtitle=&quot;Test API&quot;
             doctitle=&quot;&lt;h1&gt;Test&lt;/h1&gt;&quot;
             bottom=&quot;&lt;i&gt;Copyright &amp;#169; 2000 Dummy Corp. All Rights Reserved.&lt;/i&gt;&quot;&gt;
      &lt;group title=&quot;Group 1 Packages&quot; packages=&quot;com.dummy.test.a*&quot;/&gt;
      &lt;group title=&quot;Group 2 Packages&quot; packages=&quot;com.dummy.test.b*&quot;/&gt;
      &lt;link offline=&quot;true&quot; href=&quot;http://java.sun.com/products/jdk/1.2/docs/api/&quot; packagelistLoc=&quot;C:\tmp&quot;/&gt;
      &lt;link href=&quot;http://developer.java.sun.com/developer/products/xml/docs/api/&quot;/&gt;
    &lt/javadoc&gt;</pre>
    
  <hr>
  <h2><a name="mail">Mail</a></h2>
  <h3>Description</h3>
  <p>A task to send SMTP email.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">from</td>
      <td valign="top">Email address of sender.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">tolist</td>
      <td valign="top">Comma-separated list of recipients.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">message</td>
      <td valign="top">Message to send in the body of the email.</td>
      <td align="center" valign="middle" rowspan="2">Yes</td>
    </tr>
    <tr>
      <td valign="top">files</td>
      <td valign="top">Filename(s) of text to send in the body of the email. 
  	Multiple files are comma-separated.</td>
    </tr>
    <tr>
      <td valign="top">mailhost</td>
      <td valign="top">Host name of the mail server.</td>
      <td align="center" valign="top">No, default to &quot;localhost&quot;</td>
    </tr>
    <tr>
      <td valign="top">subject</td>
      <td valign="top">Email subject line.</td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>
    &lt;mail from=&quot;me&quot; tolist=&quot;you&quot; subject=&quot;Results of nightly build&quot;
          files=&quot;build.log&quot;/&gt;</pre>
  <p>Sends an eMail from <i>me</i> to <i>you</i> with a subject of 
  <i>Results of nightly build</i> and includes the contents of <i>build.log</i>
  in the body of the message.</p>
  <hr>
  
  <h2><a name="mkdir">Mkdir</a></h2>
  <h3>Description</h3>
  <p>Creates a directory. Also non-existent parent directories are created, when
  necessary.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">dir</td>
      <td valign="top">the directory to create.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>&lt;mkdir dir=&quot;${dist}&quot; /&gt;</pre>
  <p>creates a directory <code>${dist}</code>.</p>
  <pre>&lt;mkdir dir=&quot;${dist}/lib&quot; /&gt;</pre>
  <p>creates a directory <code>${dist}/lib</code>.</p>
  <hr>
  <h2><a name="move">Move</a></h2>
  <h3>Description</h3>
  <p>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 <var>overwrite</var> 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.</p>
  <p><a href="#fileset">FileSet</a>s are used to select sets of files
  to move to the <var>todir</var> directory.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">file</td>
      <td valign="top">the file to move</td>
      <td valign="top" align="center">One of <var>file</var> or 
       at least one nested fileset element</td>
    </tr>
    <tr>
      <td valign="top">tofile</td>
      <td valign="top">the file to move to</td>
      <td valign="top" align="center" rowspan="2">With the <var>file</var> attribute, 
      either <var>tofile</var> or <var>todir</var> can be used.  With a nested fileset, 
  	 only <var>todir</var> is allowed.</td>
    </tr>
    <tr>
      <td valign="top">todir</td>
      <td valign="top">the directory to move to</td>
    </tr>
    <tr>
      <td valign="top">overwrite</td>
      <td valign="top">overwrite existing files even if the destination
        files are newer (default is &quot;true&quot;)</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">filtering</td>
      <td valign="top">indicates whether token filtering should take place during
        the move.  See the <a href="#filter">filter</a> task for a description of
        how filters work.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">flatten</td>
      <td valign="top">ignore directory structure of source directory,
        copy all files into a single directory, specified by the <var>todir</var>
        attribute (default is &quot;false&quot;).</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includeEmptyDirs</td>
  	 <td valign="top">Copy empty directories included with the nested FileSet(s).
  	   Defaults to &quot;yes&quot;.</td>
  	 <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <p><b>Move a single file (rename a file)</b></p>
  <pre>
    &lt;move file=&quot;file.orig&quot; tofile=&quot;file.moved&quot; /&gt;
  </pre>
  <p><b>Move a single file to a directory</b></p>
  <pre>
    &lt;move file=&quot;file.orig&quot; todir=&quot;dir/to/move/to&quot; /&gt;
  </pre>
  <p><b>Move a directory to a new directory</b></p>
  <pre>
    &lt;move todir=&quot;new/dir/to/move/to&quot;&gt;
      &lt;fileset dir=&quot;src/dir&quot;/&gt;
    &lt;/move&gt;
  </pre>
  <p><b>Move a set of files to a new directory</b></p>
  <pre>
    &lt;move todir=&quot;some/new/dir&quot; &gt;
      &lt;fileset dir=&quot;my/src/dir&quot; &gt;
        &lt;include name=&quot;**/*.jar&quot; /&gt;
        &lt;exclude name=&quot;**/ant.jar&quot; /&gt;
      &lt;/fileset&gt;
    &lt;/move&gt;
  </pre>
  <hr>
  <h2><a name="patch">Patch</a></h2>
  <h3>Description</h3>
  <p>Applies a diff file to originals.
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">patchfile</td> 
      <td valign="top">the file that includes the diff output</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">originalfile</td> 
      <td valign="top">the file to patch</td>
      <td align="center" valign="top">No, tries to guess it from the diff 
        file</td>
    </tr>
    <tr>
      <td valign="top">backups</td> 
      <td valign="top">Keep backups of the unpatched files</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">quiet</td> 
      <td valign="top">Work silently unless an error occurs</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">reverse</td> 
      <td valign="top">Assume patch was created with old and new files 
        swapped.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">ignorewhitespace</td> 
      <td valign="top">Ignore whitespace differences.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">strip</td> 
      <td valign="top">Strip the smallest prefix containing <i>num</i> leading 
        slashes from filenames.</td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;patch patchfile=&quot;module.1.0-1.1.patch&quot; /&gt;</pre>
  <p>applies the diff included in <i>module.1.0-1.1.patch</i> to the
  files in base directory guessing the filename(s) from the diff output.
  <pre>  &lt;patch patchfile=&quot;module.1.0-1.1.patch&quot; strip=&quot;1&quot; /&gt;</pre>
  <p>like above but one leading directory part will be removed. i.e. if
  the diff output looked like
  <pre>
  --- a/mod1.0/A	Mon Jun  5 17:28:41 2000
  +++ a/mod1.1/A	Mon Jun  5 17:28:49 2000
  </pre> 
  the leading <i>a/</i> will be stripped.
  <hr>
  <h2><a name="property">Property</a></h2>
  <h3>Description</h3>
  <p>Sets a property (by name and value), or set of properties (from file or
  resource) in the project.</p>
  <p>When a property was set by the user, or was a property in a parent project
  (that started this project with the <a href="#ant">ant task</a>), then this
  property cannot be set, and will be ignored. This means that properties set
  outside the current project always override the properties of the current
  project.</p>
  <p>There are four ways to set properties:</p>
  <ul>
    <li>By supplying both the <i>name</i> and <i>value</i> attribute.</li>
    <li>By supplying both the <i>name</i> and <i>refid</i> attribute.</li>
    <li>By setting the <i>file</i> 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.</li>
    <li>By setting the <i>resource</i> 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.</li>
  </ul>
  <p>Although combinations of the three ways are possible, only one should be used
  at a time. Problems might occur with the order in which properties are set, for
  instance.</p>
  <p>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.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">name</td>
      <td valign="top">the name of the property to set.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">value</td>
      <td valign="top">the value of the property.</td>
      <td valign="middle" align="center" rowspan="5">Yes</td>
    </tr>
    <tr>
      <td valign="top">refid</td>
      <td valign="top"><a href="#references">Reference</a> to an object
        defined elsewhere. Only yields reasonable results for references
        to <a href="#path">PATH like structures</a> or properties.</td>
    </tr>
    <tr>
      <td valign="top">resource</td>
      <td valign="top">the resource name of the property file.</td>
    </tr>
    <tr>
      <td valign="top">file</td>
      <td valign="top">the filename of the property file .</td>
    </tr>
    <tr>
      <td valign="top">location</td>
      <td valign="top">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.</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;property name=&quot;foo.dist&quot; value=&quot;dist&quot; /&gt;</pre>
  <p>sets the property <code>foo.dist</code> to the value &quot;dist&quot;.</p>
  <pre>  &lt;property file=&quot;foo.properties&quot; /&gt;</pre>
  <p>reads a set of properties from a file called &quot;foo.properties&quot;.</p>
  <pre>  &lt;property resource=&quot;foo.properties&quot; /&gt;</pre>
  <p>reads a set of properties from a resource called &quot;foo.properties&quot;.</p>
  <p>Note that you can reference a global properties file for all of your Ant
  builds using the following:
  <pre>  &lt;property file=&quot;${user.home}/.ant-global.properties&quot; /&gt;</pre>
  <p>since the &quot;user.home&quot; 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 &quot;C:\&quot;.  Different JVM
  implementations may use other values for the home directory on Windows.
  <hr>
  <h2><a name="rename">Rename</a></h2>
  <h3><i>Deprecated</i></h3>
  <p><i>This task has been deprecated.  Use the Move task instead.</i></p>
  <h3>Description</h3>
  <p>Renames a given file.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">src</td>
      <td valign="top">file to rename.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">dest</td>
      <td valign="top">new name of the file.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">replace</td>
      <td valign="top">Enable replacing of existing file (default: on).</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;rename src=&quot;foo.jar&quot; dest=&quot;${name}-${version}.jar&quot; /&gt;</pre> 
  <p>Renames the file <code>foo.jar</code> to <code>${name}-${version}.jar</code> (assuming <code>name</code>
   and <code>version</code> being predefined properties). If a file named <code>${name}-${version}.jar</code>
   already exists, it will be removed prior to renaming <code>foo.jar</code>.</p>
  <hr>
  <h2><a name="replace">Replace</a></h2>
  <h3>Description</h3>
  <p>Replace is a directory based task for replacing the occurrence of a given string with another string 
  in selected file.</p>
  <p>If you want to replace a text that crosses line boundaries, you
  must use a nested <code>&lt;replacetoken&gt;</code> element.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">file</td>
      <td valign="top">file for which the token should be replaced.</td>
      <td align="center" rowspan="2">Exactly one of the two.</td>
    </tr>
    <tr>
      <td valign="top">dir</td>
      <td valign="top">The base directory to use when replacing a token in 
        multiple files.</td>
    </tr>
    <tr>
      <td valign="top">token</td>
      <td valign="top">the token which must be replaced.</td>
      <td valign="top" align="center">Yes, unless a nested <code>replacetoken</code>
        element is used.</td>
    </tr>
    <tr>
      <td valign="top">value</td>
      <td valign="top">the new value for the token. When omitted, an empty string
        (&quot;&quot;) is used.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top">comma separated list of patterns of files that must be
        included. All files are included when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an include pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top">comma separated list of patterns of files that must be
        excluded. No files (except default excludes) are excluded when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an exclude pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">defaultexcludes</td>
      <td valign="top">indicates whether default excludes should be used or not
        (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;replace file=&quot;${src}/index.html&quot; token=&quot;@@@&quot; value=&quot;wombat&quot; /&gt;</pre>
  <p>replaces occurrences of the string &quot;@@@&quot; with the string
  &quot;wombat&quot;, in the file <code>${src}/index.html</code>.</p>
  <h3>Parameters specified as nested elements</h3>
  <p>This task forms an implicit <a href="#fileset">FileSet</a> and
  supports all attributes of <code>&lt;fileset&gt;</code> as well as the
  nested <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
  <code>&lt;patternset&gt;</code> elements.</p>
  <p>If either the text you want to replace or the replacement text
  cross line boundaries, you can use nested elements to specify
  them.</p>
  <h3>Examples</h3>
  <blockquote><pre>  
  &lt;replace dir=&quot;${src}&quot; value=&quot;wombat&quot;&gt;
    &lt;include name=&quot;**/*.html&quot; /&gt;
    &lt;replacetoken&gt;&lt;[CDATA[multi line
  token]]>&lt;/replacetoken&gt;
  &lt;/replace&gt;
  </pre></blockquote>
  <p>replaces occurrences of the string &quot;multi
  line<em>\n</em>token&quot; with the string &quot;wombat&quot;, in all
  HTML files in the directory <code>${src}</code>.Where <em>\n</em> is
  the platform specific line separator.</p>
  <blockquote><pre>  
  &lt;replace file=&quot;${src}/index.html&quot;&gt;
    &lt;replacetoken&gt;&lt;[CDATA[two line
  token]]>&lt;/replacetoken&gt;
    &lt;replacevalue&gt;&lt;[CDATA[two line
  token]]>&lt;/replacevalue&gt;
  &lt;/replace&gt;
  </pre></blockquote>
  <hr>
  <h2><a name="rmic">Rmic</a></h2>
  <h3>Description</h3>
  <p>Runs the rmic compiler for a certain class.</p>
  <p>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).</p>
  <p>It is possible to refine the set of files that are being rmiced. This can be
  done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
  attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
  have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
  the files you want to have excluded. This is also done with patterns. And
  finally with the <i>defaultexcludes</i> attribute, you can specify whether you
  want to use default exclusions or not. See the section on <a
  href="#directorybasedtasks">directory based tasks</a>, on how the
  inclusion/exclusion of files works, and how to write patterns.</p>
  <p>This task forms an implicit <a href="#fileset">FileSet</a> and
  supports all attributes of <code>&lt;fileset&gt;</code>
  (<code>dir</code> becomes <code>base</code>) as well as the nested
  <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
  <code>&lt;patternset&gt;</code> elements.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">base</td>
      <td valign="top">the location to store the compiled files.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">classname</td>
      <td valign="top">the class for which to run <code>rmic</code>.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">filtering</td>
      <td valign="top">indicates whether token filtering should take place</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">sourcebase</td>
      <td valign="top">Pass the &quot;-keepgenerated&quot; flag to rmic and
   move the generated source file to the base directory.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">stubversion</td>
      <td valign="top">Specify the JDK version for the generated stub code.
   Specify &quot;1.1&quot; to pass the &quot;-v1.1&quot; option to rmic.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">classpath</td>
      <td valign="top">The classpath to use during compilation</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">classpathref</td>
      <td valign="top">The classpath to use during compilation, given as <a
        href="#references">reference</a> to a PATH defined elsewhere</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top">comma separated list of patterns of files that must be
        included. All files are included when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an include pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top">comma separated list of patterns of files that must be
        excluded. No files (except default excludes) are excluded when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an exclude pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">defaultexcludes</td>
      <td valign="top">indicates whether default excludes should be used or not
        (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">verify</td>
      <td valign="top">check that classes implement Remote before handing them 
          to rmic (default is false)</td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>
  <h3>Parameters specified as nested elements</h3>
  <h4>classpath</h4>
  <p><code>Rmic</code>'s <em>classpath</em> attribute is a <a
  href="#path">PATH like structure</a> and can also be set via a nested
  <em>classpath</em> elements.</p>
  <h3>Examples</h3>
  <pre>  &lt;rmic classname=&quot;com.xyz.FooBar&quot; base=&quot;${build}/classes&quot; /&gt;</pre>
  <p>runs the rmic compiler for the class <code>com.xyz.FooBar</code>. The
  compiled files will be stored in the directory <code>${build}/classes</code>.</p>
  <pre>  &lt;rmic base=&quot;${build}/classes&quot; includes=&quot;**/Remote*.class&quot; /&gt;</pre>
  <p>runs the rmic compiler for all classes with <code>.class</code>
  files below <code>${build}/classes</code> whose classname starts with
  <i>Remote</i>. The compiled files will be stored in the directory
  <code>${build}/classes</code>.</p>
  
  <hr>
  <h2><a name="signjar">SignJar</a></h2>
  <h3>Description</h3>
  <p>Signs a jar or zip file with the javasign command line tool.</p>
  
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">jar</td>
      <td valign="top">the jar file to sign</td>
      <td valign="top" align="center">Yes.</td>
    </tr>
    <tr>
      <td valign="top">alias</td>
      <td valign="top">the alias to sign under</td>
      <td valign="top" align="center">Yes.</td>
    </tr>
    <tr>
      <td valign="top">storepass</td>
      <td valign="top">password for keystore integrity.</td>
      <td valign="top" align="center">Yes.</td>
    </tr>
    <tr>
      <td valign="top">keystore</td>
      <td valign="top">keystore location</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">storetype</td>
      <td valign="top">keystore type</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">keypass</td>
      <td valign="top">password for private key (if different)</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">sigfile</td>
      <td valign="top">name of .SF/.DSA file</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">signedjar</td>
      <td valign="top">name of signed JAR file</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">verbose</td>
      <td valign="top">(true | false) verbose output when signing</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">internalsf</td>
      <td valign="top">(true | false) include the .SF file inside the signature
  block</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">sectionsonly</td>
      <td valign="top">(true | false) don't compute hash of entire manifest</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <blockquote>
    <p><code>&lt;signjar jar=&quot;${dist}/lib/ant.jar&quot;
  alias=&quot;apache-group&quot; storepass=&quot;secret&quot; /&gt;</code></p>
  </blockquote>
  <p>signs the ant.jar with alias &quot;apache-group&quot; accessing the
  keystore and private key via &quot;secret&quot; password.</p>
  <hr>
  <h2><a name="style">Style</a></h2>
  <h3>Description</h3>
  <p>Process a set of documents via XSLT.</p>
  <p>This is useful for building views of XML based documentation,
  or in generating code.</p>
  <p>It is possible to refine the set of files that are being copied. This can be
  done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
  attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
  have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
  the files you want to have excluded. This is also done with patterns. And
  finally with the <i>defaultexcludes</i> attribute, you can specify whether you
  want to use default exclusions or not. See the section on <a
  href="#directorybasedtasks">directory based tasks</a>, on how the
  inclusion/exclusion of files works, and how to write patterns.</p>
  <p>This task forms an implicit <a href="#fileset">FileSet</a> and
  supports all attributes of <code>&lt;fileset&gt;</code>
  (<code>dir</code> becomes <code>basedir</code>) as well as the nested
  <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
  <code>&lt;patternset&gt;</code> elements.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">basedir</td>
      <td valign="top">where to find the source xml file.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">destdir</td>
      <td valign="top">directory where to store the results.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">extension</td>
      <td valign="top">desired file extension to be used for the targets.
          If not specified, the default is &quot;html&quot;.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">style</td>
      <td valign="top">name of the stylesheet to use.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">processor</td>
      <td valign="top">name of the XSLT processor to use.  Permissible
  values are &quot;xslp&quot; for the XSL:P processor, &quot;xalan&quot; 
  for the Apache XML Xalan processor, or the name of an arbitrary XSLTLiaison class.
  Defaults to xslp or xalan (in that order), if one is found in your
  class path</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top">comma separated list of patterns of files that must be
        included. All files are included when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an include pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top">comma separated list of patterns of files that must be
        excluded. No files (except default excludes) are excluded when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an exclude pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">defaultexcludes</td>
      <td valign="top">indicates whether default excludes should be used or not
        (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <blockquote>
    <p><pre>
  &lt;style basedir=&quot;doc&quot; destdir=&quot;build/doc&quot;
         extension=&quot;html&quot; style=&quot;style/apache.xml&quot;/&gt;
  </pre></p>
  </blockquote>
  <hr>
  <h2><a name="tar">Tar</a></h2>
  <h3>Description</h3>
  <p>Creates a tar archive.</p>
  <p>The <i>basedir</i> attribute is the reference directory from where to tar.</p>
  <p>It is possible to refine the set of files that are being tarred. This can be
  done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
  attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
  have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
  the files you want to have excluded. This is also done with patterns. And
  finally with the <i>defaultexcludes</i> attribute, you can specify whether you
  want to use default exclusions or not. See the section on <a
  href="#directorybasedtasks">directory based tasks</a>, on how the
  inclusion/exclusion of files works, and how to write patterns.</p>
  <p>This task forms an implicit <a href="#fileset">FileSet</a> and
  supports all attributes of <code>&lt;fileset&gt;</code>
  (<code>dir</code> becomes <code>basedir</code>) as well as the nested
  <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
  <code>&lt;patternset&gt;</code> elements.</p>
  <p>Note that this task does not perform compression. You might want to use the <a href="#gzip">GZip</a>
  task to come up with a .tar.gz package.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td valign="top" align="center"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">tarfile</td>
      <td valign="top">the tar-file to create.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">basedir</td>
      <td valign="top">the directory from which to zip the files.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top">comma separated list of patterns of files that must be
        included. All files are included when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an include pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top">comma separated list of patterns of files that must be
        excluded. No files (except default excludes) are excluded when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an exclude pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">defaultexcludes</td>
      <td valign="top">indicates whether default excludes should be used or not
        (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;tar tarfile=&quot;${dist}/manual.tar&quot; basedir=&quot;htdocs/manual&quot; /&gt;
    &lt;gzip zipfile=&quot;${dist}/manual.tar.gz&quot; src=&quot;${dist}/manual.tar&quot; /&gt;</pre>
  <p>tars all files in the <code>htdocs/manual</code> directory in a file called <code>manual.tar</code>
  in the <code>${dist}</code>  directory, then applies the gzip task to compress
  it.</p>
  <pre>  &lt;tar tarfile=&quot;${dist}/manual.tar&quot;
         basedir=&quot;htdocs/manual&quot;
         excludes=&quot;mydocs/**, **/todo.html&quot;
    /&gt;</pre>
  <p>tars all files in the <code>htdocs/manual</code> directory in a file called <code>manual.tar</code>
  in the <code>${dist}</code> directory. Files in the directory <code>mydocs</code>,
  or files with the name <code>todo.html</code> are excluded.</p>
  <hr>
  <h2><a name="taskdef">Taskdef</a></h2>
  <h3>Description</h3>
  <p>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.</p>
  <p>Taskdef should be used to add your own tasks to the system. See also &quot;<a
  href="#writingowntask">Writing your own task</a>&quot;.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">name</td>
      <td valign="top">the name of the task</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">classname</td>
      <td valign="top">the full class name implementing the task</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">classpath</td> <td valign="top">the classpath to
        use when looking up <code>classname</code>.</td> <td
      align="center" valign="top">No</td>
    </tr>
  </table>
  <h3>Parameters specified as nested elements</h3>
  <h4>classpath</h4>
  <p><code>Taskdef</code>'s <em>classpath</em> attribute is a <a
  href="#path">PATH like structure</a> and can also be set via a nested
  <em>classpath</em> element.</p>
  <h3>Examples</h3>
  <pre>  &lt;taskdef name=&quot;myjavadoc&quot; classname=&quot;com.mydomain.JavadocTask&quot; /&gt;</pre>
  <p>makes a task called <code>myjavadoc</code> available to Ant. The class <code>com.mydomain.JavadocTask</code>
  implements the task.</p>
  <hr>
  <h2><a name="touch">Touch</a></h2>
  <h3>Description</h3>
  <p>Changes the modification time of a file and possibly creates it at
  the same time.</p>
  <p>For JDK 1.1 only the creation of new files with a modification time
  of now works, all other cases will emit a warning.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">file</td>
      <td valign="top">the name of the file</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">millis</td>
      <td valign="top">specifies the new modification time of the file
         in milliseconds since midnight Jan 1 1970</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">datetime</td>
      <td valign="top">specifies the new modification time of the file
         in the format MM/DD/YYYY HH:MM AM_or_PM.</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <p>If both <code>millis</code> and <code>datetime</code> are omitted
  the current time is assumed.</p>
  <h3>Examples</h3>
  <pre>  &lt;touch file=&quot;myfile&quot; /&gt;</pre>
  <p>creates <code>myfile</code> if it doesn't exist and changes the
  modification time to the current time.</p>
  <pre>  &lt;touch file=&quot;myfile&quot; datetime=&quot;06/28/2000 2:02 pm&quot; /&gt;</pre>
  <p>creates <code>myfile</code> 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).</p>
  <hr>
  <h2><a name="tstamp">Tstamp</a></h2>
  <h3>Description</h3>
  <p>Sets the DSTAMP, TSTAMP and TODAY properties in the current project. The
  DSTAMP is in the &quot;yyyymmdd&quot; format, the TSTAMP is in the &quot;hhmm&quot;
  format and TODAY is &quot;month day year&quot;.</p>
  <p>These properties can be used in the buildfile, for instance, to create
  timestamped filenames or used to replace placeholder tags inside documents to
  indicate, for example, the release date. The best place for this task is in your
  initialization target.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;tstamp/&gt;</pre>
  <hr>
  <h2><a name="uptodate">Uptodate</a></h2>
  <h3>Description</h3>
  <p>Sets a property if a Target file is more up to date than a set of
  Source files. Source files are specified by nested &lt;srcfiles&gt;
  elements, these are <a href="#fileset">FileSet</a>s.</p>
  <p>The value part of the property being set is <i>true</i> if the timestamp of the 
  Target file is more recent than the timestamp of every Source file.</p>
  <p>Normally, this task is used to set properties that are useful to avoid target
  execution depending on the relative age of the specified files.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">property</td>
      <td valign="top">the name of the property to set.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">targetfile</td>
      <td valign="top">the file for which we want to determine the status.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;uptodate property=&quot;xmlBuild.notRequired&quot; targetfile=&quot;${deploy}\xmlClasses.jar&quot; &gt;
      &lt;srcfiles dir= &quot;${src}/xml&quot; includes=&quot;**/*.dtd&quot; /&gt;
    &lt;/uptodate&gt;</pre>
  <p>sets the property <code><i>xmlBuild.notRequired</i></code> to the value &quot;true&quot;
  if the <i>${deploy}/xmlClasses.jar</i> is more up to date than any of the DTD files in the <i>${src}/xml</i> directory.</p>
  <hr>
  <h2><a name="unzip">Unjar/Unwar/Unzip</a></h2>
  <h3>Description</h3>
  <p>Unzips a zip-, war- or jarfile.</p>
  <p>For JDK 1.1 &quot;last modified time&quot; field is set to current time instead of being 
  carried from zipfile.</p>
  <p>File permissions will not be restored on extracted files.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">src</td>
      <td valign="top">zipfile to expand.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">dest</td>
      <td valign="top">directory where to store the expanded files.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <blockquote>
    <p><code>&lt;unzip src=&quot;${tomcat_src}/tools-src.zip&quot; dest=&quot;${tools.home}&quot;
    /&gt;</code></p>
  </blockquote>
  <hr>
  <h2><a name="untar">Untar</a></h2>
  <h3>Description</h3>
  <p>Untars a tarfile.</p>
  <p>File permissions will not be restored on extracted files.</p>
  <p>For JDK 1.1 &quot;last modified time&quot; field is set to current time instead of being 
  carried from tarfile.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">src</td>
      <td valign="top">tarfile to expand.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">dest</td>
      <td valign="top">directory where to store the expanded files.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <blockquote>
    <p><code>
  &lt;gunzip src=&quot;tools.tar.gz&quot;/&gt;<br>
  &lt;untar src=&quot;tools.tar&quot; dest=&quot;${tools.home}&quot;/&gt;
  </code></p>
  </blockquote>
  <hr>
  <h2><a name="war">War</a></h2>
  <h3>Description</h3>
  <p>An extension of the <a href="#jar">Jar</a> task with special
  treatment for files that should end up in the <code>WEB-INF/lib</code>,
  <code>WEB-INF/classes</code> or <code>WEB-INF</code> directories of the Web
  Application Archive.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">warfile</td>
      <td valign="top">the war-file to create.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">webxml</td>
      <td valign="top">The deployment descriptor to use (WEB-INF/web.xml).</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">basedir</td>
      <td valign="top">the directory from which to jar the files.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">compress</td>
      <td valign="top">Not only store data but also compress them, defaults to true</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top">comma separated list of patterns of files that must be
        included. All files are included when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an include pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top">comma separated list of patterns of files that must be
        excluded. No files (except default excludes) are excluded when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an exclude pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">defaultexcludes</td>
      <td valign="top">indicates whether default excludes should be used or not
        (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">manifest</td>
      <td valign="top">the manifest file to use.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">whenempty</td>
      <td valign="top">Behavior to use if no files match.</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Nested elements</h3>
  <h4>lib</h4>
  <p>The nested <code>lib</code> element specifies a <a
  href="#fileset">FileSet</a>. All files included in this fileset will
  end up in the <code>WEB-INF/lib</code> directory of the war file.</p>
  <h4>classes</h4>
  <p>The nested <code>classes</code> element specifies a <a
  href="#fileset">FileSet</a>. All files included in this fileset will
  end up in the <code>WEB-INF/classes</code> directory of the war file.</p>
  <h4>webinf</h4>
  <p>The nested <code>webinf</code> element specifies a <a
  href="#fileset">FileSet</a>. All files included in this fileset will
  end up in the <code>WEB-INF</code> directory of the war file. If this
  fileset includes a file named <code>web.xml</code>, the file is
  ignored and you will get a warning.</p>
  <h3>Examples</h3>
  <p>Assume the following structure in the project's base directory:
  <pre>
  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
  </pre>
  then the war file <code>myapp.war</code> created with
  <pre>
  &lt;war warfile=&quot;myapp.war&quot; webxml=&quot;src/metadata/myapp.xml&quot;&gt;
    &lt;fileset dir=&quot;src/html/myapp&quot; /&gt;
    &lt;fileset dir=&quot;src/jsp/myapp&quot; /&gt;
    &lt;lib dir=&quot;thirdparty/libs&quot;&gt;
      &lt;exclude name=&quot;jdbc1.jar&quot; /&gt;
    &lt;/lib&gt;
    &lt;classes dir=&quot;build/main&quot; /&gt;
  &lt;/war&gt;
  </pre>
  will consist of
  <pre>
  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
  </pre>
  using Ant's default manifest file. The content of
  <code>WEB-INF/web.xml</code> is identical to
  <code>src/metadata/myapp.xml</code>.</p>
  <hr>
  <h2><a name="zip">Zip</a></h2>
  <h3>Description</h3>
  <p>Creates a zipfile.</p>
  <p>The <i>basedir</i> attribute is the reference directory from where to zip.</p>
  <p>Note that file permissions will not be stored in the resulting zipfile.</p>
  <p>It is possible to refine the set of files that are being zipped. This can be
  done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
  attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
  have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
  the files you want to have excluded. This is also done with patterns. And
  finally with the <i>defaultexcludes</i> attribute, you can specify whether you
  want to use default exclusions or not. See the section on <a
  href="#directorybasedtasks">directory based tasks</a>, on how the
  inclusion/exclusion of files works, and how to write patterns. 
  <p>This task forms an implicit <a href="#fileset">FileSet</a> and
  supports all attributes of <code>&lt;fileset&gt;</code>
  (<code>dir</code> becomes <code>basedir</code>) as well as the nested
  <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
  <code>&lt;patternset&gt;</code> elements.</p>
  <p>Or, you may place within it nested file sets, or references to file sets.
  In this case <code>basedir</code> is optional; the implicit file set is <em>only used</em>
  if <code>basedir</code> is set. You may use any mixture of the implicit file set
  (with <code>basedir</code> set, and optional attributes like <code>includes</code>
  and optional subelements like <code>&lt;include&gt;</code>); explicit nested
  <code>&lt;fileset&gt;</code> elements so long as at least one fileset total is specified. The ZIP file will
  only reflect the relative paths of files <em>within</em> each fileset.</p>
  <p>The <code>whenempty</code> parameter controls what happens when no files match.
  If <code>skip</code> (the default), the ZIP is not created and a warning is issued.
  If <code>fail</code>, the ZIP is not created and the build is halted with an error.
  If <code>create</code>, an empty ZIP file (explicitly zero entries) is created,
  which should be recognized as such by compliant ZIP manipulation tools.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td valign="top" align="center"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">zipfile</td>
      <td valign="top">the zip-file to create.</td>
      <td align="center" valign="top">Yes</td>
    </tr>
    <tr>
      <td valign="top">basedir</td>
      <td valign="top">the directory from which to zip the files.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">compress</td>
      <td valign="top">Not only store data but also compress them, defaults to true</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top">comma separated list of patterns of files that must be
        included. All files are included when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an include pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top">comma separated list of patterns of files that must be
        excluded. No files (except default excludes) are excluded when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an exclude pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">defaultexcludes</td>
      <td valign="top">indicates whether default excludes should be used or not
        (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">whenempty</td>
      <td valign="top">Behavior when no files match.</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;
         basedir=&quot;htdocs/manual&quot;
    /&gt;</pre>
  <p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>
  in the <code>${dist}</code> directory.</p>
  <pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;
         basedir=&quot;htdocs/manual&quot;
         excludes=&quot;mydocs/**, **/todo.html&quot;
    /&gt;</pre>
  <p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>
  in the <code>${dist}</code> directory. Files in the directory <code>mydocs</code>,
  or files with the name <code>todo.html</code> are excluded.</p>
  <pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;
         basedir=&quot;htdocs/manual&quot;
         includes=&quot;api/**/*.html&quot;
         excludes=&quot;**/todo.html&quot;
    /&gt;</pre>
  <p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>
  in the <code>${dist}</code> directory. Only html files under the directory <code>api</code>
  are zipped, and files with the name <code>todo.html</code> are excluded.</p>
  <pre>  &lt;zip zipfile=&quot;${dist}/manual.zip&quot;&gt;
      &lt;fileset dir=&quot;htdocs/manual&quot;/&gt;
      &lt;fileset dir=&quot;.&quot; includes=&quot;ChangeLog.txt&quot;/&gt;
    &lt;/zip&gt;</pre>
  <p>zips all files in the <code>htdocs/manual</code> directory in a file called <code>manual.zip</code>
  in the <code>${dist}</code> directory, and also adds the file <code>ChangeLog.txt</code> in the
  current directory. <code>ChangeLog.txt</code> will be added to the top of the ZIP file, just as if
  it had been located at <code>htdocs/manual/ChangeLog.txt</code>.</p>
  
  <hr>
  <h2><a name="optionaltasks">Optional tasks</a></h2>
  <ul>
    <li><a href="#cab">Cab</a></li>
    <li><a href="#ftp">FTP</a></li>
    <li><a href="javacc.html">JavaCC</a></li>
    <li><a href="jlink.html">Jlink</a></li>
    <li><a href="junit.html">JUnit</a></li>
    <li><a href="native2ascii.html">Native2Ascii</a></li>
    <li><a href="#netrexxc">NetRexxC</a></li>
    <li><a href="P4desc.html">Perforce</a></li>
    <li><a href="#renameexts">RenameExtensions</a></li>
    <li><a href="#script">Script</a></li>
    <li><a href="#vssget">VssGet</a></li>
    <li><a href="ejb.html">EJB Tasks</a></li>
  </ul>
  <hr>
  <h2><a name="cab">Cab</a></h2>
  <h3>Description</h3>
  <p>The cab task creates Microsoft cab archive files.  It is invoked
  similar to the <a href="#jar">jar</a> or <a href="#zip">zip</a> tasks.
  This task will only work on Windows, and will be silently ignored on
  other platforms.  You must have the Microsoft cabarc tool available in
  your executable path.</p>
  <p>See the section on <a href="#directorybasedtasks">directory based
  tasks</a>, on how the inclusion/exclusion of files works, and how to
  write patterns.</p>
  <p>This task forms an implicit <a href="#fileset">FileSet</a> and
  supports all attributes of <code>&lt;fileset&gt;</code>
  (<code>dir</code> becomes <code>basedir</code>) as well as the nested
  <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
  <code>&lt;patternset&gt;</code> elements.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">cabfile</td>
      <td valign="top">the name of the cab file to create.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">basedir</td>
      <td valign="top">the directory to start archiving files from.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">verbose</td>
      <td valign="top">set to &quot;yes&quot; if you want to see the output from
        the cabarc tool.  defaults to &quot;no&quot;.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">compress</td>
      <td valign="top">set to &quot;no&quot; to store files without compressing.
        defaults to &quot;yes&quot;.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">options</td>
      <td valign="top">use to set additional command-line options for
        the cabarc tool.  should not normally be necessary.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top">comma separated list of patterns of files that
        must be included. All files are included when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an include pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top">comma separated list of patterns of files that
        must be excluded. No files (except default excludes) are excluded
        when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an exclude pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">defaultexcludes</td>
      <td valign="top">indicates whether default excludes should be used
        or not (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <blockquote><pre>
  &lt;cab cabfile=&quot;${dist}/manual.cab&quot;
       basedir=&quot;htdocs/manual&quot; 
    /&gt;
  </pre></blockquote>
  <p>cabs all files in the htdocs/manual directory in a file called
  manual.cab in the ${dist} directory.</p>
  <blockquote><pre>
  &lt;cab cabfile=&quot;${dist}/manual.cab&quot;
       basedir=&quot;htdocs/manual&quot;
       excludes=&quot;mydocs/**, **/todo.html&quot;
    /&gt;
  </pre></blockquote>
  <p>cabs all files in the htdocs/manual directory in a file called
  manual.cab in the ${dist} directory. Files in the directory mydocs,
  or files with the name todo.html are excluded.</p>
  <blockquote><pre>
  &lt;cab cabfile=&quot;${dist}/manual.cab&quot;
       basedir=&quot;htdocs/manual&quot;
       includes=&quot;api/**/*.html&quot;
       excludes=&quot;**/todo.html&quot;
       verbose=&quot;yes&quot;
    /&gt;
  </pre></blockquote>
  <p>cab all files in the htdocs/manual directory in 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.</p>
  <hr>
  <h2><a name="ftp">FTP</a></h2>
  <h3>Description</h3>
  <p>The ftp task implements a basic FTP client that can send, receive,
  list, and delete files.  See below for descriptions and examples of how
  to perform each task.</p>
  <p>The ftp task makes no attempt to determine what file system syntax is
  required by the remote server, and defaults to Unix standards.
  <i>remotedir</i> must be specified in the exact syntax required by the ftp
  server. If the usual Unix conventions are not supported by the server,
  <i>separator</i> can be used to set the file separator that should be used
  instead.</p>
  <p>See the section on <a href="#directorybasedtasks">directory based
  tasks</a>, on how the inclusion/exclusion of files works, and how to
  write patterns.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">server</td>
      <td valign="top">the address of the remote ftp server.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">port</td>
      <td valign="top">the port number of the remote ftp server.
                       Defaults to port 21.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">userid</td>
      <td valign="top">the login id to use on the ftp server.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">password</td>
      <td valign="top">the login password to use on the ftp server.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">remotedir</td>
      <td valign="top">the directory to which to upload files on the 
                       ftp server.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">action</td>
      <td valign="top">the ftp action to perform, defaulting to &quot;send&quot;.  
                       Currently supports&quot;put&quot;, &quot;get&quot;,
                       &quot;del&quot;, and &quot;list&quot;.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">binary</td>
      <td valign="top">selects binary-mode (&quot;yes&quot;) or text-mode 
                       (&quot;no&quot;) transfers.  
                       Defaults to &quot;yes&quot;</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">verbose</td>
      <td valign="top">displays information on each file transferred if set 
                       to &quot;yes&quot;. Defaults to &quot;no&quot;.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">depends</td>
      <td valign="top">transfers only new or changed files if set to 
                       &quot;yes&quot;. Defaults to &quot;no&quot;.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">newer</td>
      <td valign="top">a synonym for <i>depends</i>.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">separator</td>
      <td valign="top">sets the file separator used on the ftp server.
                       Defaults to &quot;/&quot;.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">listing</td>
      <td valign="top">the file to write results of the &quot;list&quot; action.
                       Required for the &quot;list&quot; action, ignored otherwise.</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Sending Files</h3>
  <p>The easiest way to describe how to send files is with a couple of examples:</p>
  <pre>
    &lt;ftp server=&quot;ftp.apache.org&quot;
         userid=&quot;anonymous&quot;
         password=&quot;me@myorg.com&quot;&gt;
      &lt;fileset dir=&quot;htdocs/manual&quot; /&gt;
    &lt;/ftp&gt;
  </pre>
  <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and 
  uploads all files in the <code>htdocs/manual</code> directory 
  to the default directory for that user.</p>
  <pre>  &lt;ftp server=&quot;ftp.apache.org&quot;
         remotedir=&quot;incoming&quot;
         userid=&quot;anonymous&quot;
         password=&quot;me@myorg.com&quot;
         depends=&quot;yes&quot;
    &gt;
      &lt;fileset dir=&quot;htdocs/manual&quot; /&gt;
    &lt;/ftp&gt;</pre>
  <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and 
  uploads all new or changed files in the <code>htdocs/manual</code> directory 
  to the <code>incoming</code> directory relative to the default directory
  for <code>anonymous</code>.</p>
  <pre>  &lt;ftp server=&quot;ftp.apache.org&quot;
         port=&quot;2121&quot;
         remotedir=&quot;/pub/incoming&quot;
         userid=&quot;coder&quot;
         password=&quot;java1&quot;
         depends=&quot;yes&quot;
         binary=&quot;no&quot;
    &gt;
      &lt;fileset dir=&quot;htdocs/manual&quot;&gt;
        &lt;include name=&quot;**/*.html&quot; /&gt;
      &lt;/fileset&gt;
    &lt;/ftp&gt;</pre>
  <p>Logs in to <code>ftp.apache.org</code> at port <code>2121</code> as 
  <code>coder</code> with password <code>java1</code> and uploads all new or 
  changed HTML files in the <code>htdocs/manual</code> directory to the 
  <code>/pub/incoming</code> directory.  The files are transferred in text
  mode.</p>
  <pre>  &lt;ftp server=&quot;ftp.nt.org&quot;
         remotedir=&quot;c:\uploads&quot;
         userid=&quot;coder&quot;
         password=&quot;java1&quot;
         separator=&quot;\&quot;
         verbose=&quot;yes&quot;
    &gt;
      &lt;fileset dir=&quot;htdocs/manual&quot;&gt;
        &lt;include name=&quot;**/*.html&quot; /&gt;
      &lt;/fileset&gt;
    &lt;/ftp&gt;</pre>
  <p>Logs in to the Windows-based <code>ftp.nt.org</code> as 
  <code>coder</code> with password <code>java1</code> and uploads all 
  HTML files in the <code>htdocs/manual</code> directory to the 
  <code>c:\uploads</code> directory.  Progress messages are displayed as each
  file is uploaded.</p>
  <h3>Getting Files</h3>
  <p>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.</p>
  <pre>
    &lt;ftp action=&quot;get&quot;
         server=&quot;ftp.apache.org&quot;
         userid=&quot;anonymous&quot;
         password=&quot;me@myorg.com&quot;&gt;
      &lt;fileset dir=&quot;htdocs/manual&quot; &gt;
        &lt;include name=&quot;**/*.html&quot; /&gt;
      &lt;/fileset&gt;
    &lt;/ftp&gt;
  </pre>
  <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and 
  recursively downloads all .html files from default directory for that user 
  into the <code>htdocs/manual</code> directory on the local machine.</p>
  <h3>Deleting Files</h3>
  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.
  <pre>
    &lt;ftp action=&quot;del&quot;
         server=&quot;ftp.apache.org&quot;
         userid=&quot;anonymous&quot;
         password=&quot;me@myorg.com&quot; &gt;
      &lt;fileset&gt;
        &lt;include name=&quot;**/*.tmp&quot; /&gt;
      &lt;/fileset&gt;
    &lt;/ftp&gt;
  </pre>
  <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> 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.</p>
  <h3>Listing Files</h3>
  <pre>
    &lt;ftp action=&quot;list&quot;
         server=&quot;ftp.apache.org&quot;
         userid=quot;anonymous&quot;
         password=&quot;me@myorg.com&quot; 
         listing=&quot;data/ftp.listing&quot; &gt;
      &lt;fileset&gt;
        &lt;include name=&quot;**&quot; /&gt;
      &lt;/fileset&gt;
    &lt;/ftp&gt;
  </pre>
  <p>This provides a file listing in <code>data/ftp.listing</code> of all the files on
  the FTP server relative to the default directory of the <code>anonymous</code>
  user. The listing is in whatever format the FTP server normally lists files.</p>
  <hr>
  <h2><a name="netrexxc">NetRexxC</a></h2>
  <h3>Description</h3>
  <p>Compiles a <a href="http://www2.hursley.ibm.com/netrexx">NetRexx</a>
  source tree within the running (Ant) VM.</p>
  <p>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.</p>
  <p>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</p>
  <p>The directory structure of the source tree should follow the package
  hierarchy.</p>
  <p>It is possible to refine the set of files that are being compiled/copied.
  This can be done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and
  <i>defaultexcludes</i> attributes. With the <i>includes</i> or <i>includesfile</i> attribute you 
  specify the files you want to have included by using patterns. The 
  <i>exclude</i> or <i>excludesfile</i> attribute is used to specify the files you want to have 
  excluded.  This is also done with patterns.  And finally with the 
  <i>defaultexcludes</i> attribute, you can specify whether you
  want to use default exclusions or not. See the section on <a
  href="#directorybasedtasks">directory based tasks</a>, on how the
  inclusion/exclusion of files works, and how to write patterns.</p>
  <p>This task forms an implicit <a href="#fileset">FileSet</a> and
  supports all attributes of <code>&lt;fileset&gt;</code>
  (<code>dir</code> becomes <code>srcdir</code>) as well as the nested
  <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
  <code>&lt;patternset&gt;</code> elements.</p>
  
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">binary</td>
      <td valign="top">Whether literals are treated as the java binary
        type rather than the NetRexx types</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">classpath</td>
      <td valign="top">The classpath to use during compilation</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">comments</td>
      <td valign="top">Whether comments are passed through to the
        generated java source</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">compact</td>
      <td valign="top">Whether error messages come out in compact or
        verbose format</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">compile</td>
      <td valign="top">Whether the NetRexx compiler should compile the
        generated java code</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">console</td>
      <td valign="top">Whether or not messages should be displayed on the
        'console'</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">crossref</td>
      <td valign="top">Whether variable cross references are generated</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">decimal</td>
      <td valign="top">Whether decimal arithmetic should be used for the
        NetRexx code</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">defaultexcludes</td>
      <td valign="top">indicates whether default excludes should be used or not
        (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when
        omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">destDir</td>
      <td valign="top">the destination directory into which the NetRexx
        source files should be copied and then compiled</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">diag</td>
      <td valign="top">Whether diagnostic information about the compile is
        generated</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top">comma separated list of patterns of files that must be
        excluded. No files (except default excludes) are excluded when
        omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an exclude pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">explicit</td>
      <td valign="top">Whether variables must be declared explicitly
        before use</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">format</td>
      <td valign="top">Whether the generated java code is formatted nicely
        or left to match NetRexx line numbers for call stack debugging</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top">comma separated list of patterns of files that must be
        included. All files are included when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an include pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">java</td>
      <td valign="top">Whether the generated java code is produced</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">keep</td>
      <td valign="top">Sets whether the generated java source file should be kept
        after compilation. The generated files will have an extension of
        .java.keep, <b>not</b> .java</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">logo</td>
      <td valign="top">Whether the compiler text logo is displayed when
        compiling</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">replace</td>
      <td valign="top">Whether the generated .java file should be replaced
        when compiling</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">savelog</td>
      <td valign="top">Whether the compiler messages will be written to
        NetRexxC.log as well as to the console</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">sourcedir</td>
      <td valign="top">Tells the NetRexx compiler to store the class files in the
        same directory as the source files. The alternative is the working
        directory</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">srcDir</td>
      <td valign="top">Set the source dir to find the source Netrexx
        files</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">strictargs</td>
      <td valign="top">Tells the NetRexx compiler that method calls always
        need parentheses, even if no arguments are needed, e.g. 
        <code>aStringVar.getBytes</code> vs. 
        <code>aStringVar.getBytes()</code></td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">strictassign</td>
      <td valign="top">Tells the NetRexx compile that assignments must
        match exactly on type</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">strictcase</td>
      <td valign="top">Specifies whether the NetRexx compiler should be
        case sensitive or not</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">strictimport</td>
      <td valign="top">Whether classes need to be imported explicitly using an 
        <code>import</code> statement.  By default the NetRexx compiler will 
        import certain packages automatically</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">strictprops</td>
      <td valign="top">Whether local properties need to be qualified
        explicitly using <code>this</code></td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">strictsignal</td>
      <td valign="top">Whether the compiler should force catching of
        exceptions by explicitly named types</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">symbols</td>
      <td valign="top">Whether debug symbols should be generated into the
        class file</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">time</td>
      <td valign="top">Asks the NetRexx compiler to print compilation
        times to the console</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">trace</td>
      <td valign="top">Turns on or off tracing and directs the resultant
        trace output</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">utf8</td>
      <td valign="top">Tells the NetRexx compiler that the source is in UTF8</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">verbose</td>
      <td valign="top">Whether lots of warnings and error messages should
        be generated</td>
      <td valign="top" align="center">Yes</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <blockquote>
    <p><code>&lt;netrexxc srcDir=&quot;/source/project&quot;
             includes=&quot;vnr/util/*&quot;
             destDir=&quot;/source/project/build&quot;
             classpath=&quot;/source/project2/proj.jar&quot;
             comments=&quot;true&quot;
             crossref=&quot;false&quot; replace=&quot;true&quot;
             keep=&quot;true&quot; /&gt;</code>
    </p>
  </blockquote>
  <hr>
  <h2><a name="renameexts">RenameExtensions</a></h2>
  <h3>Description</h3>
  <p>Renames files in the <code>srcDir</code> directory ending with the
  <code>fromExtension</code> string so that they end with the 
  <code>toExtension</code> string. Files are only replaced if 
  <code>replace</code> is true
  </p>
  <p>See the section on 
  <a href="#directorybasedtasks">directory based tasks</a>, on how the
  inclusion/exclusion of files works, and how to write patterns. 
  This task forms an implicit <a href="#fileset">FileSet</a> and
  supports all attributes of <code>&lt;fileset&gt;</code>
  (<code>dir</code> becomes <code>srcDir</code>) as well as the nested
  <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
  <code>&lt;patternset&gt;</code> elements.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">defaultexcludes</td>
      <td valign="top">indicates whether default excludes should be used or not
        (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when
        omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludes</td>
      <td valign="top">comma separated list of patterns of files that must be
        excluded. No files (except default excludes) are excluded when
        omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">excludesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an exclude pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">fromExtention</td>
      <td valign="top">The string that files must end in to be renamed</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">includes</td>
      <td valign="top">comma separated list of patterns of files that must be
        included. All files are included when omitted.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">includesfile</td>
      <td valign="top">the name of a file. Each line of this file is
        taken to be an include pattern</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">replace</td>
      <td valign="top">Whether the file being renamed to should be
        replaced if it already exists</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">srcDir</td>
      <td valign="top">The starting directory for files to search in</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">toExtension</td>
      <td valign="top">The string that renamed files will end with on
        completion</td>
      <td valign="top" align="center">Yes</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <blockquote>
    <p><code>&lt;renameext srcDir=&quot;/source/project1&quot;
                includes=&quot;**&quot;
                excludes=&quot;**/samples/*&quot;
                fromExtension=&quot;.java.keep&quot;
                toExtension=&quot;.java&quot;
                replace=&quot;true&quot; /&gt;
  </code>
    </p>
  </blockquote>
  
  <hr>
  <h2><a name="script">Script</a></h2>
  <h3>Description</h3>
  <p>Execute a script in a 
    <a href="http://oss.software.ibm.com/developerworks/opensource/bsf/">BSF</a> supported language.
  <p>All items (tasks, targets, etc) of the running project are
  accessible from the script, using either their <code>name</code> or
  <code>id</code> attributes.</p>
  <p>Scripts can do almost anything a task written in Java could do.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">language</td>
      <td valign="top">The programming language the script is written in.
        Must be a supported BSF language</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">src</td>
      <td valign="top">The location of the script as a file, if not inline</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Examples</h3>
  <blockquote><pre>
  &lt;project name=&quot;squares&quot; default=&quot;main&quot; basedir=&quot;.&quot;&gt;
  
    &lt;target name=&quot;setup&quot;&gt;
  
      &lt;script language=&quot;javascript&quot;&gt; &lt;![CDATA[
  
        for (i=1; i&lt;=10; i++) {
          echo = squares.createTask(&quot;echo&quot;);
          main.addTask(echo);
          echo.setMessage(i*i);
        }
  
      ]]&gt; &lt;/script&gt;
  
    &lt;/target&gt;
  
    &lt;target name=&quot;main&quot; depends=&quot;setup&quot; /&gt;
  
  &lt;/project&gt;
  </pre></blockquote>
  <p>generates</p>
  <blockquote><pre>
  setup:
  
  main:
  1
  4
  9
  16
  25
  36
  49
  64
  81
  100
  
  BUILD SUCCESSFUL
  </pre></blockquote>
  <p>Another example, using <a href="#references">references by id</a>
  and two different scripting languages:</p>
  <blockquote><pre>
  &lt;project name=&quot;testscript&quot; default=&quot;main&quot;&gt;
    &lt;target name=&quot;sub&quot;&gt;
      &lt;echo id=&quot;theEcho&quot; /&gt;
    &lt;/target&gt;
  
    &lt;target name=&quot;sub1&quot;&gt;
      &lt;script language=&quot;netrexx&quot;&gt;&lt;![CDATA[
        theEcho.setMessage(&quot;In sub1&quot;)
        sub.execute
      ]]&gt;&lt;/script&gt;
    &lt;/target&gt;
  
    &lt;target name=&quot;sub2&quot;&gt;
      &lt;script language=&quot;javascript&quot;&gt;&lt;![CDATA[
        theEcho.setMessage(&quot;In sub2&quot;);
        sub.execute();
      ]]&gt;&lt;/script&gt;
    &lt;/target&gt;
  
    &lt;target name=&quot;main&quot; depends=&quot;sub1,sub2&quot; /&gt;
  &lt;/project&gt;
  </pre></blockquote>
  <p>generates</p>
  <blockquote><pre>
  sub1:
  In sub1
  
  sub2:
  In sub2
  
  main:
  
  BUILD SUCCESSFUL
  </pre></blockquote>
  <hr>
  <h2><a name="vssget">VssGet</a></h2>
  <h3>Description</h3>
  Task to perform GET commands to Microsoft Visual Source Safe.
  <p>If you specify two or more attributes from version, date and 
  label only one will be used in the order version, date, label.</p>
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <th>Attribute</th>
      <th>Values</th>
      <th>Required</th>
    </tr>
    <tr>
       <td>login</td>
       <td>username,password</td>
       <td>No</td>
    </tr>
    <tr>
       <td>vsspath</td>
       <td>SourceSafe path</td>
       <td>Yes</td>
    </tr>
    <tr>
       <td>localpath</td>
       <td>Override the working directory and get to the specified path</td>
       <td>No</td>
    </tr>
    <tr>
       <td>writable</td>
       <td>true or false</td>
       <td>No</td>
    </tr>
    <tr>
       <td>recursive</td>
       <td>true or false</td>
       <td>No</td>
    </tr>
    <tr>
       <td>version</td>
       <td>a version number to get</td>
       <td>No</td>
    </tr>
    <tr>
       <td>date</td>
       <td>a date stamp to get at</td>
       <td>No</td>
    </tr>
    <tr>
       <td>label</td>
       <td>a label to get for</td>
       <td>No</td>
    </tr>
    <tr>
       <td>ssdir</td>
       <td>directory where <code>ss.exe</code> resides. By default the
       task expects it to be in the PATH.</td>
       <td>No</td>
    </tr>
  </table>
  <p>Note that only one of version, date or label should be specified</p>
  <h3>Examples</h3>
  <blockquote>
  <pre>
  &lt;vssget localPath=&quot;C:\mysrc\myproject&quot;
          recursive=&quot;true&quot; 
          label=&quot;Release1&quot;
          login=&quot;me,mypassword&quot;
          vsspath=&quot;/source/aProject&quot;
          writable=&quot;true&quot;/&gt;
  </pre>
  </blockquote>
  <p>Does a get on the VSS-Project <i>$/source/aproject</i> using the username
  <i>me</i> and the password <i>mypassword</i>. It will recursively get the files 
  which are labeled <i>Release1</i> and write them to the local directory
  <i>C:\mysrc\myproject</i>. The local files will be writable.</p>
  <hr>
  <h2><a name="buildevents">Build Events</a></h2>
  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. 
  
  <p>To use build events you need to create an ant <code>Project</code> object. You can then call the 
  <code>addBuildListener</code> method to add your listener to the project. Your listener must implement
  the <code>org.apache.tools.antBuildListener</code> interface. The listener will receive BuildEvents 
  for the following events
  <ul>
  <li>Build started
  <li>Build finished
  <li>Target started
  <li>Target finished
  <li>Task started
  <li>Task finished
  <li>Message logged
  </ul>
  
  If you wish to attach a listener from the command line you may use the -listener option. For example
  <blockquote>
    <pre>ant -listener org.apache.tools.ant.XmlLogger</pre>
  </blockquote>
  will run ant with a listener which 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.
  
  
  <hr>
  <h2><a name="writingowntask">Writing your own task</a></h2>
  <p>It is very easy to write your own task:</p>
  <ol>
    <li>Create a Java class that extends <code>org.apache.tools.ant.Task</code>.</li>
    <li>For each attribute, write a setter method. The setter method must be a 
      <code>public void</code> method that takes a single argument. The
      name of the method must begin with &quot;set&quot;, followed by the
      attribute name, with the first character in uppercase, and the rest in
      lowercase. The type of the attribute can be <code>String</code>, any 
      primitive type (they are converted for you from their String-representation
  	in the build-file. If you specify a boolean your method will be passed the value 
  	<i>true</i> if the value specified in the build-file is one of &quot;true&quot;,
  	&quot;yes&quot; or &quot;on&quot;), <code>Class</code>, <code>File</code>
  	(in which case the value of the attribute is interpreted relative to the 
  	project's basedir) or any other type that has a constructor with a single 
  	<code>String</code> argument</li>
    <li>If your task has enumerated attributes, you should consider using
      a subclass of org.apache.tools.ant.types.EnumeratedAttribute as argument
      to your setter method. See org.apache.tools.ant.taskdefs.FixCRLF for
      an example.</li>
    <li>If the task should support character data, write a <code>public void 
      addText(String)</code> method.</li>
    <li>For each nested element, write a create or add method. A create method 
      must be a <code>public</code> method that takes no arguments and returns 
      an Object type. The name of the create method must begin with 
      &quot;create&quot;, followed by the element name. An add method must be 
      a <code>public void</code> method that takes a single argument of an 
      Object type with a no argument constructor. The name of the add method 
      must begin with &quot;add&quot;, followed by the element name.
    <li>Write a <code>public void execute</code> method, with no arguments, that
      throws a <code>BuildException</code>. This method implements the task
      itself.</li>
  </ol>
  <h3>The life cycle of a task</h3>
  <ol>
    <li>The task gets instantiated using a no-arg constructor at parser
      time. This means even tasks that are never executed get
      instantiated.</li>
  
    <li>The tasks gets references to its project and location inside the
      build file via their inherited <code>project</code> and
      <code>location</code> variables.</li>
  
    <li>If the user specified an id attribute to this task, the project
      registers a reference to this newly created task - at parser
      time.</li>
  
    <li>The task gets a reference to the target it belongs to via its
      inherited <code>target</code> variable.</li>
  
    <li><code>init()</code> is called at parser time.</li>
  
    <li>All child elements of the XML element corresponding to this task
      are created via this task's <code>createXXX()</code> methods or
      instantiated and added to this task via its <code>addXXX()</code>
      methods - at parser time.</li>
  
    <li>All attributes of this task get set via their corresponding
      <code>setXXX</code> methods - at runtime.</li>
  
    <li>The content character data sections inside the XML element
      corresponding to this task is added to the task via its
      <code>addText</code> method - at runtime.</li>
  
    <li>All attributes of all child elements get set via their corresponding
      <code>setXXX</code> methods - at runtime.</li>
  
    <li><code>execute()</code> is called at runtime.</li>
  
  </ol>
  <h3>Example</h3>
  <p>Let's write our own task, that prints a message on the System.out stream. The
  task has one attribute called &quot;message&quot;.</p>
  <blockquote>
    <pre>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 &quot;message&quot; attribute
    public void setMessage(String msg) {
      this.msg = msg;
    }
  }</pre>
  </blockquote>
  <p>It's really this simple;-)</p>
  <p>Adding your task to the system is rather simple too:</p>
  <ol>
    <li>Make sure the class that implements your task is in the classpath when
      starting Ant.</li>
    <li>Add a <i>taskdef</i> element to your project. This actually adds
      your task to the system.</li>
    <li>Use your task in the rest of the buildfile.</li>
  </ol>
  <h3>Example</h3>
  <blockquote>
    <pre>&lt;?xml version=&quot;1.0&quot;?&gt;
  
  &lt;project name=&quot;OwnTaskExample&quot; default=&quot;main&quot; basedir=&quot;.&quot;&gt;
    &lt;taskdef name=&quot;mytask&quot; classname=&quot;com.mydomain.MyVeryOwnTask&quot;/&gt;
  
    &lt;target name=&quot;main&quot;&gt;
      &lt;mytask message=&quot;Hello World! MyVeryOwnTask works!&quot; /&gt;
    &lt;/target&gt;
  &lt;/project&gt;
  </pre>
  </blockquote>
  <p>Another way to add a task (more permanently), is to add the task name and
  implementing class name to the <code>default.properties</code> file in the <code>org.apache.tools.ant.taskdefs</code>
  package. Then you can use it as if it were a built in task.</p>
  <hr>
  <h2><a name="faq">FAQ, DTD, external resources</a></h2>
  <p>There is an online FAQ for Ant at <a
  href="http://jakarta.apache.org/jyve-faq/Turbine/screen/DisplayTopics/action/SetAll/project_id/2/faq_id/16">jakarta.apache.org</a>. This
  FAQ is interactive, which means you can ask and answer questions
  online.</p>
  <p>One of the questions poping up quite often is &quot;Is there a DTD for
  buildfiles?&quot;. Please refer to the FAQ for an answer.</p>
  <hr>
  <h2><a name="feedback">Feedback</a></h2>
  <p>To provide feedback on this software, please subscribe to the Ant User
  Mail List (<a href="mailto:ant-user-subscribe@jakarta.apache.org">ant-user-subscribe@jakarta.apache.org</a>)</p>
  <p>If you want to contribute to Ant or stay current with the latest
  development, join the Ant Development Mail List (<a
  href="mailto:ant-dev-subscribe@jakarta.apache.org">ant-dev-subscribe@jakarta.apache.org</a>)</p>
  <p>Archives of both lists can be found at <a
  href="http://archive.covalent.net/">http://archive.covalent.net/</a>. Many
  thanks to Covalent Technologies.</p>
  <hr>
  <p align="center">Copyright &copy; 2000 Apache Software Foundation. All rights
  Reserved.</p>
  
  </body>
  
  </html>
  
  
  
  
  1.1                  jakarta-site/ant/jakarta-ant/docs/javacc.html
  
  Index: javacc.html
  ===================================================================
  <html>
  
  <head>
  <meta http-equiv="Content-Language" content="en-us">
  <title>JavaCC Task</title>
  </head>
  
  <body>
  
  <h2><a name="javacc">JavaCC</a></h2>
  <h3>Description</h3> 
  <p>
    Invokes the <a HREF="http://www.metamata.com/javacc/">JavaCC</a> compiler 
    compiler on a grammar file.
  </p>
  <p>
    To use the javacc task, set the <i>target</i> attribute to the name of the 
    grammar file to process.  You also need to specify the directory containing 
    the JavaCC installation using the <i>javacchome</i> attribute, so that ant 
    can find the JavaCC classes.  Optionally, you can also set the 
    <i>outputdirectory</i> to write the generated file to a specific directory.
    Otherwise javacc writes the generated files to the directory containing
    the grammar file.
  </p>
  <p>
    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.
  </p>
  
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">target</td>
      <td valign="top">The grammar file to process.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">javacchome</td>
      <td valign="top">The directory containing the JavaCC distribution.</td>
      <td valign="top" align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">outputdirectory</td>
      <td valign="top">
        The directory to write the generated files to.  If not set, the files
        are written to the directory containing the grammar file.
      </td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">buildparser</td>
      <td valign="top">Sets the BUILD_PARSER grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">buildtokenmanager</td>
      <td valign="top">Sets the BUILD_TOKEN_MANAGER grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">cachetokens</td>
      <td valign="top">Sets the CACHE_TOKENS grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">choiceambiguitycheck</td>
      <td valign="top">Sets the CHOICE_AMBIGUITY_CHECK grammar option.  This is an integer option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">commontokenaction</td>
      <td valign="top">Sets the COMMON_TOKEN_ACTION grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">debuglookahead</td>
      <td valign="top">Sets the DEBUG_LOOKAHEAD grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">debugparser</td>
      <td valign="top">Sets the DEBUG_PARSER grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">debugtokenmanager</td>
      <td valign="top">Sets the DEBUG_TOKEN_MANAGER grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">errorreporting</td>
      <td valign="top">Sets the ERROR_REPORTING grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">forcelacheck</td>
      <td valign="top">Sets the FORCE_LA_CHECK grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">ignorecase</td>
      <td valign="top">Sets the IGNORE_CASE grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">javaunicodeescape</td>
      <td valign="top">Sets the JAVA_UNICODE_ESCAPE grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">lookahead</td>
      <td valign="top">Sets the LOOKAHEAD grammar option.  This is an integer option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">optimizetokenmanager</td>
      <td valign="top">Sets the OPTIMIZE_TOKEN_MANAGER grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">otherambiguitycheck</td>
      <td valign="top">Sets the OTHER_AMBIGUITY_CHECK grammar option.  This is an integer option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">sanitycheck</td>
      <td valign="top">Sets the SANITY_CHECK grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">static</td>
      <td valign="top">Sets the STATIC grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">unicodeinput</td>
      <td valign="top">Sets the UNICODE_INPUT grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">usercharstream</td>
      <td valign="top">Sets the USER_CHAR_STREAM grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">usertokenmanager</td>
      <td valign="top">Sets the USER_TOKEN_MANAGER grammar option.  This is a boolean option.</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>
  <h3>Example</h3>
  <blockquote><pre>
  &lt;javacc 
      target=&quot;src/Parser.jj&quot; 
      outputdirectory&quot;build/src&quot;
      javacchome=&quot;c:/program files/JavaCC&quot; 
      static=&quot;true&quot;
  /&gt;
  </pre></blockquote>
  <p>
    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.
  </p>
  <hr>
  
  
  
  
  1.1                  jakarta-site/ant/jakarta-ant/docs/jlink.html
  
  Index: jlink.html
  ===================================================================
  <html>
  <head>
  </head>
  <body>
  
  <h2><a name="jlink">Jlink</a></h2>
  <h3><b>Description:</b></h3>
  <p>Links entries from sub-builds and libraries.</p>
  
  <p>The jlink task can be used to build jar and zip files, similar to 
  the <i>jar</i> 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.</p>
  
  <p>If a mergefile is specified directly (eg. at the top level of a 
  <i>mergefiles</i>
  pathelement) <i>and</i> the mergefile ends in &quot;.zip&quot; or 
  &quot;.jar&quot;,
  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).
  </p>
  
  <p>
  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.
  </p>
  
  <p>
  jlink ignores META-INF directories in mergefiles. Users should supply their
  own manifest information for the output file.
  </p>
  
  <p>It is possible to refine the set of files that are being jlinked. 
  This can be
  done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, 
  <i>excludesfile</i>,
  and <i>defaultexcludes</i> attributes on the <i>addfiles</i> and 
  <i>mergefiles</i>
  nested elements. With the <i>includes</i> or <i>includesfile</i>
  attribute you specify the files you want to have included by using patterns.
  The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
  the files you want to have excluded. This is also done with patterns. And
  finally with the <i>defaultexcludes</i> attribute, you can specify whether you
  want to use default exclusions or not. See the section on <a
  href="#directorybasedtasks">directory based tasks</a>, on how the
  inclusion/exclusion of files works, and how to write patterns. The patterns are
  relative to the <i>base</i> directory.</p>
  
  
  
  <h3>Parameters:</h3>
  <table border="1" cellpadding="2" cellspacing="0">
     <tr>
       <td valign="top"><b>Attribute</b></td>
       <td valign="top"><b>Description</b></td>
       <td align="center" valign="top"><b>Required</b></td>
     </tr>
     <tr>
       <td valign="top">outfile</td>
       <td valign="top">the path of the output file.</td>
       <td valign="top" align="center">Yes</td>
     </tr>
     <tr>
       <td valign="top">compress</td>
       <td valign="top">whether or not the output should be compressed. 
  <i>true</i>,
                        <i>yes</i>, or <i>on</i> result in compressed output.
                        If omitted, output will be uncompressed (inflated).</td>
       <td valign="top" align="center">No</td>
     </tr>
     <tr>
       <td valign="top">mergefiles</td>
       <td valign="top">files to be merged into the output, if possible.</td>
       <td valign="middle" align="middle" rowspan="2">At least one of 
  mergefiles or addfiles</td>
     </tr>
     <tr>
       <td valign="top">addfiles</td>
       <td valign="top">files to be added to the output.</td>
     </tr>
  </table>
  
  <h3>Examples</h3>
  
  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.
  <pre>
  &lt;jlink compress=&quot;false&quot; outfile=&quot;out.jar&quot;&gt;
     &lt;mergefiles&gt;
       &lt;pathelement path=&quot;${build.dir}/mergefoo.jar&quot;/&gt;
       &lt;pathelement path=&quot;${build.dir}/mergebar.jar&quot;/&gt;
     &lt;/mergefiles&gt;
     &lt;addfiles&gt;
       &lt;pathelement path=&quot;${build.dir}/mac.jar&quot;/&gt;
       &lt;pathelement path=&quot;${build.dir}/pc.zip&quot;/&gt;
     &lt;/addfiles&gt;
  &lt;/jlink&gt;
  </pre>
  
  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.
  <pre>
  &lt;jlink compress=&quot;false&quot; outfile=&quot;out.jar&quot;&gt;
     &lt;mergefiles&gt;
       &lt;pathelement path=&quot;build/tempbuild&quot;/&gt;
     &lt;/mergefiles&gt;
  &lt;/jlink&gt;
  </pre>
  
  However, the next example would result in two top-level entries in out.jar,
  namely bar.class and barnone/myClass.zip
  <pre>
  &lt;jlink compress=&quot;false&quot; outfile=&quot;out.jar&quot;&gt;
     &lt;mergefiles&gt;
       &lt;pathelement path=&quot;build/tempbuild/foo.jar&quot;/&gt;
     &lt;/mergefiles&gt;
  &lt;/jlink&gt;
  </pre>
  
  </body>
  
  </html>
  
  
  
  1.1                  jakarta-site/ant/jakarta-ant/docs/junit.html
  
  Index: junit.html
  ===================================================================
  <html>
  <head>
  </head>
  <body>
  
  <h2><a name="junit">JUnit</a></h2>
  <h3>Description</h3>
  
  <p>This task runs tests from the JUnit testing framework. The latest
  version of the framework can be found at 
  <a href="http://www.junit.org">http://www.junit.org</a>.
  This task requires JUnit 3.0 or above.</p>
  
  <p>Tests are defined by nested <code>test</code> or
  <code>batchtest</code> tags, see <a href="#nested">nested
  elements</a>.</p>
  
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td width="12%" valign="top"><b>Attribute</b></td>
    <td width="78%" valign="top"><b>Description</b></td>
    <td width="10%" valign="top"><b>Required</b></td>
  </tr>
    <tr>
      <td valign="top">printsummary</td> 
      <td valign="top">Print one line statistics for each testcase.</td>
      <td align="center" valign="top">No, default is "off"</td>
    </tr>
    <tr>
      <td valign="top">fork</td> 
      <td valign="top">Run the tests in a separate VM.</td>
      <td align="center" valign="top">No, default is "off"</td>
    </tr>
    <tr>
      <td valign="top">haltonerror</td> 
      <td valign="top">Stop the build process if an error occurs during the test
         run.</td>
      <td align="center" valign="top">No, default is "off"</td>
    </tr>
    <tr>
      <td valign="top">haltonfailure</td> 
      <td valign="top">Stop the build process if a test fails (errors are 
        considered failures as well).</td>
      <td align="center" valign="top">No, default is "off"</td>
    </tr>
    <tr>
      <td valign="top">timeout</td> 
      <td valign="top">Cancel the individual tests if the don't finish
        in the given time (measured in milliseconds).  Ignored if fork is
        disabled.</td> 
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">maxmemory</td>
      <td valign="top">Max amount of memory to allocate to the forked VM
        (ignored if fork is disabled)</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">jvm</td>
      <td valign="top">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.</td>
      <td align="center" valign="top">No, default &quot;java&quot;</td>
    </tr>
    <tr>
      <td valign="top">dir</td>
      <td valign="top">The directory to invoke the VM in. (ignored if
        fork is disabled)</td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>
  
  <h3><a name="nested">Nested Elements</a></h3>
  
  <p><code>junit</code> supports a nested <code>&lt;classpath&gt;</code>
  element, that represents a <a href="index.html#path">PATH like
  structure</a>.</p>
  
  <h4>jvmarg</h4>
  
  <p>If fork is enabled, additional parameters may be passed to the new
  VM via nested <code>&lt;jvmarg&gt;</code> attributes, for example:</p>
  
  <pre><blockquote>
  &lt;junit fork=&quot;yes&quot;&gt;
    &lt;jvmarg value=&quot;-Djava.compiler=NONE&quot;/&gt;
  &lt;/junit&gt;
  </blockquote></pre>
  would run the test in a VM without JIT.</p>
  
  <p><code>&lt;jvmarg&gt;</code> allows all attributes described in <a
  href="index.html#arg">Command line arguments</a>.</p>
  
  <h4>formatter</h4>
  
  <p>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 <code>outfile</code> attribute
  of <code>&lt;test&gt;</code>.
  
  <p>There are two predefined formatters, one prints the test results in
  XML format, the other emits plain text. Custom formatters that need to
  implement
  <code>org.apache.tools.ant.taskdefs.optional.junit.JUnitResultFormatter</code>
  can be specified.</p>
  
  <table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td width="12%" valign="top"><b>Attribute</b></td>
    <td width="78%" valign="top"><b>Description</b></td>
    <td width="10%" valign="top"><b>Required</b></td>
  </tr>
    <tr>
      <td valign="top">type</td> 
      <td valign="top">Use a predefined formatter (either "xml" or "plain").</td>
      <td align="center" rowspan="2">Exactly one of these.</td>
    </tr>
    <tr>
      <td valign="top">classname</td> 
      <td valign="top">Name of a custom formatter class.</td>
    </tr>
    <tr>
      <td valign="top">extension</td> 
      <td valign="top">Extension to append to the output filename.</td>
      <td align="center">Yes, if classname has been used.</td>
    </tr>
    <tr>
      <td valign="top">usefile</td> 
      <td valign="top">Boolean that determines whether output should be
        sent to a file.</td>
      <td align="center">No, default true.</td>
    </tr>
  </table>
  
  <h4>test</h4>
  
  <p>Defines a single test class.</p>
  
  <table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td width="12%" valign="top"><b>Attribute</b></td>
    <td width="78%" valign="top"><b>Description</b></td>
    <td width="10%" valign="top"><b>Required</b></td>
  </tr>
    <tr>
      <td valign="top">name</td> 
      <td valign="top">Name of the test class</td>
      <td align="center">Yes</td>
    </tr>
    <tr>
      <td valign="top">fork</td> 
      <td valign="top">Run the tests in a separate VM. 
        Overrides value set in <code>&lt;junit&gt;</code>.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">haltonerror</td> 
      <td valign="top">Stop the build process if an error occurs during the test
         run. Overrides value set in <code>&lt;junit&gt;</code>.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">haltonfailure</td> 
      <td valign="top">Stop the build process if a test fails (errors are 
        considered failures as well).  Overrides value set in 
        <code>&lt;junit&gt;</code>.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">outfile</td> 
      <td valign="top">Base name of the test result. The full filename is
        determined by this attribute and the extension of
        <code>formatter</code>.</td>
      <td align="center" valign="top">No, default is
        <code>TEST-name</code> using the <code>name</code> attribute.</td>
    </tr>
    <tr>
      <td valign="top">if</td> 
      <td valign="top">Only run test if the named property is set.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">unless</td> 
      <td valign="top">Only run test if the named property is <b>not</b> set.</td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>
  
  <p>Tests can define their own formatters via nested
  <code>&lt;formatter&gt;</code> elements.</p>
  
  <h4>batchtest</h4>
  
  <p>Define a number of tests based on pattern matching.</p>
  
  <p><code>batchtest</code> collects the included files from any number
  of nested <a
  href="index.html#fileset"><code>&lt;fileset&gt;</code></a>s. It then
  generates a test class name for each file that ends in
  <code>.java</code> or <code>.class</code>.</p>
  
  <table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td width="12%" valign="top"><b>Attribute</b></td>
    <td width="78%" valign="top"><b>Description</b></td>
    <td width="10%" valign="top"><b>Required</b></td>
  </tr>
    <tr>
      <td valign="top">fork</td> 
      <td valign="top">Run the tests in a separate VM. 
        Overrides value set in <code>&lt;junit&gt;</code>.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">haltonerror</td> 
      <td valign="top">Stop the build process if an error occurs during the test
         run. Overrides value set in <code>&lt;junit&gt;</code>.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">haltonfailure</td> 
      <td valign="top">Stop the build process if a test fails (errors are 
        considered failures as well).  Overrides value set in 
        <code>&lt;junit&gt;</code>.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">if</td> 
      <td valign="top">Only run tests if the named property is set.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">unless</td> 
      <td valign="top">Only run tests if the named property is <b>not</b> set.</td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>
  
  <p>Batchtests can define their own formatters via nested
  <code>&lt;formatter&gt;</code> elements.</p>
  
  <h3>Examples</h3>
  <pre><blockquote>
  &lt;junit&gt;
    &lt;test name="my.test.TestCase" /&gt;
  &lt;/junit&gt;
  </pre></blockquote>
  
  <p>Runs the test defined in <code>my.test.TestCase</code> in the same
  VM. No output will be generated unless the test fails.</p>
  
  <pre><blockquote>
  &lt;junit printsummary="yes" fork="yes" haltonfailure="yes"&gt;
    &lt;formatter type="plain" /&gt;
    &lt;test name="my.test.TestCase" /&gt;
  &lt;/junit&gt;
  </pre></blockquote>
  
  <p>Runs the test defined in <code>my.test.TestCase</code> in a
  separate VM.  At the end of the test a single line summary will be
  printed. A detailed report of the test can be found in
  <code>TEST-my.test.TestCase.txt</code>. The build process will be
  stopped if the test fails.</p>
  
  <pre><blockquote>
  &lt;junit printsummary="yes" haltonfailure="yes"&gt;
    &lt;classpath&gt;
      &lt;pathelement location="${build.tests}" /&gt;
      &lt;pathelement path="${java.class.path}" /&gt;
    &lt;/classpath&gt;
  
    &lt;formatter type="plain" /&gt;
  
    &lt;test name="my.test.TestCase" haltonfailure="no" outfile="result" &gt;
      &lt;formatter type="xml" /&gt;
    &lt;/test&gt;
  
    &lt;batchtest fork="yes"&gt;
      &lt;fileset dir="${src.tests}"&gt;
        &lt;include name="**/*Test*.java" /&gt;
        &lt;exclude name="**/AllTests.java" /&lt;
      &lt;/fileset&gt;
    &lt;/batchtest&gt;
  &lt;/junit&gt;
  </pre></blockquote>
  
  <p>Runs <code>my.test.TestCase</code> 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 <code>result.xml</code>.</p>
  
  <p>For each matching file in the directory <code>${src.tests}</code> a
  test is run in a separate VM. If a test fails, the build process is
  aborted. Results are collected in files named
  <code>TEST-<em>name</em>.txt</code>.</p>
  
  </body>
  </html>
  
  
  
  1.1                  jakarta-site/ant/jakarta-ant/docs/native2ascii.html
  
  Index: native2ascii.html
  ===================================================================
  <html>
    <head><title>Native2Ascii</title></head>
    <body>
      <h2>Native2Ascii</h2>
      
      <h3>Description:</h3>
      
      <p>
        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.
      </p>
  
      <p>
        Files in the directory <em>src</em>
        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
        <em>includes</em> and <em>excludes</em> attributes.
        For more information on file matching patterns,
        see the section on
        <a href="index.html#directorybasedtasks">directory based tasks</a>.
        If no <em>encoding</em> is specified, 
        the default encoding for the JVM is used.
        If <em>ext</em> is specified, then output files are renamed
        to use it as a new extension.
        If <em>dest</em> and <em>src</em> point to the same directory,
        the <em>ext</em> attribute is required.
      </p>
  
      <p>
        This task forms an implicit <a href="index.html#fileset">File Set</a>,
        and supports all attributes of <code>&lt;fileset&gt;</code>
        (<code>dir</code> becomes <code>src</code>) as well as 
        nested <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code>,
        and <code>&lt;patternset&gt;</code> elements.
      </p>
  
      <table border="1" cellpading="2" cellspacing="0">
        <tr>
          <td><b>Attribute</b></td>
          <td><b>Description</b></td>
          <td><b>Required<b></td>
        </tr>
        <tr>
          <td>reverse</td>
          <td>Reverse the sense of the conversion,
            i.e. convert from ASCII to native</td>
          <td align="center">No</td>
        </tr>
        <tr>
          <td>encoding</td>
          <td>The native encoding the files are in
            (default is the default encoding for the JVM)</td>
          <td align="center">No</td>
        </tr>
        <tr>
          <td>src</td>
          <td>The directory to find files in (default is <em>basedir</em>)</td>
          <td align="center">No</td>
        </tr>
        <tr>
          <td>dest</td>
          <td>The directory to output file to</td>
          <td align="center">Yes</td>
        </tr>
        <tr>
          <td>ext</td>
          <td>File extension to use in renaming output files</td>
          <td align="center">No</td>
        </tr>
        <tr>
          <td>defaultexcludes</td>
          <td>indicates whether default excludes should be used or not
            (&quot;yes&quot;/&quot;no&quot;).
            Default excludes are used when omitted.
          </td>
          <td align="center">No</td>
        </tr>
        <tr>
          <td>includes</td>
          <td>comma separated list of patterns of files that must be
            included. All files are included when omitted.</td>
          <td align="center">No</td>
        </tr>
        <tr>
          <td>includesfile</td>
          <td>the name of a file. Each line of this file is
            taken to be an include pattern</td>
          <td align="center">No</td>
        </tr>
        <tr>
          <td>excludes</td>
          <td>comma separated list of patterns of files that must be excluded.
            No files (except default excludes) are excluded when omitted.</td>
          <td align="center">No</td>
        </tr>
        <tr>
          <td>excludesfile</td>
          <td>the name of a file. Each line of this file is
            taken to be an exclude pattern</td>
          <td align="center">No</td>
        </tr>
      </table>
        
      <h3>Examples</h3>
  
      <pre>
  &lt;native2ascii encoding=&quot;EUCJIS&quot; src=&quot;srcdir&quot; dest=&quot;srcdir&quot;
     includes=&quot;**/*.eucjis&quot; ext=&quot;.java&quot; /&gt;
      </pre>
  
      <p>
        Converts all files in the directory <em>srcdir</em>
        ending in <code>.eucjis</code> from the EUCJIS encoding to ASCII
        and renames them to end in <code>.java</code>.
      </p>
  
  <pre>
  &lt;native2ascii encoding='EUCJIS&quot; src=&quot;native/japanese&quot; dest=&quot;src&quot;
     includes=&quot;**/*.java /&gt;
  </pre>
  
      <p>
        Converts all the files ending in <code>.java</code>
        in the directory <em>native/japanese</em> to ASCII,
        placing the results in the directory <em>src</em>.
        The names of the files remain the same.
      </p>
    </body>
  </html>
  
  
  
  1.1                  jakarta-site/ant/jakarta-ant/docs/sql.html
  
  Index: sql.html
  ===================================================================
  <html>
  <head>
  </head>
  <body>
  
  <h2><a name="sql">Sql</a></h2>
  <h3>Description</h3>
  <p>Executes a series of sql statement 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.</p>
  
  <p>Multiple statements can be set and each statement is delimited from the next use a semi-colon. Individual lines within the statements can be commented using either -- or // at the start of the line.</p>
  
  <p>The auto-commit 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 commited. If it is turned off the statements will all be executed as one transaction.</p>
  
  <p>The <i>onerror</i> attribute specifies how to preceed when an error occurs during the execution of one of the statements. 
  The possible values are: <b>continue</b> execution, only show the error;
  <b>stop</b> execution and commit transaction;
  and <b>abort</b> execution and transaction and fail task.
  
  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td width="12%" valign="top"><b>Attribute</b></td>
    <td width="78%" valign="top"><b>Description</b></td>
    <td width="10%" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td width="12%" valign="top">driver</td>
    <td width="78%" valign="top">Class name of the jdbc driver</td>
    <td width="10%" valign="top">Yes</td>
  </tr>
  <tr>
    <td width="12%" valign="top">url</td>
    <td width="78%" valign="top">Database connection url</td>
    <td width="10%" valign="top">Yes</td>
  </tr>
  <tr>
    <td width="12%" valign="top">userid</td>
    <td width="78%" valign="top">Database user name</td>
    <td width="10%" valign="top">Yes</td>
  </tr>
  <tr>
    <td width="12%" valign="top">password</td>
    <td width="78%" valign="top">Database password</td>
    <td width="10%" valign="top">Yes</td>
  </tr>
  <tr>
    <td width="12%" valign="top">src</td>
    <td width="78%" valign="top">File containing sql statements</td>
    <td width="10%" valign="top">Yes, unless statements enclosed within tags</td>
  </tr>
  <tr>
    <td width="12%" valign="top">autocommit</td>
    <td width="78%" valign="top">Auto commit flag for database connection (default false)</td>
    <td width="10%" valign="top">No, default "false"</td>
  </tr>
  <tr>
    <td width="12%" valign="top">print</td>
    <td width="78%" valign="top">Print result sets from the statements (default false)</td>
    <td width="10%" valign="top">No, default "false"</td>
  </tr>
  <tr>
    <td width="12%" valign="top">showheaders</td>
    <td width="78%" valign="top">Print headers for result sets from the statements (default true)</td>
    <td width="10%" valign="top">No, default "true"</td>
  </tr>
  <tr>
    <td width="12%" valign="top">output</td>
    <td width="78%" valign="top">Output file for result sets (defaults to System.out)</td>
    <td width="10%" valign="top">No (print to System.out by default)</td>
  </tr>
  <tr>
    <td width="12%" valign="top">classpath</td>
    <td width="78%" valign="top">Classpath used to load driver</td>
    <td width="10%" valign="top">No (use system classpath)</td>
  </tr>
  <tr>
    <td width="12%" valign="top">onerror</td>
    <td width="78%" valign="top">Action to perform when statement fails: continue, stop, abort</td>
    <td width="10%" valign="top">No, default "abort"</td>
  </tr>
  <tr>
    <td width="12%" valign="top">rdbms</td>
    <td width="78%" valign="top">Execute task only if this rdbms</td>
    <td width="10%" valign="top">No (no restriction)</td>
  </tr>
  <tr>
    <td width="12%" valign="top">version</td>
    <td width="78%" valign="top">Execute task only if rdbms version match</td>
    <td width="10%" valign="top">No (no restriction)</td>
  </tr>
  </table>
  
  <h3>Parameters specified as nested elements</h3>
  <h4>transaction</h4>
  <p>Use nested <code>&lt;transaction&gt;</code> 
  elements to specify multiple blocks of commands to the executed
  executed in the same connection but different transactions. This
  is particularly usefull when there are multiple files to execute
  on the same schema.</p>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">src</td>
      <td valign="top">File containing sql statements</td>
      <td valign="top" align="center">Yes, unless statements enclosed within tags</td>
    </tr>
  </table>
  <h4>classpath</h4>
  <p><code>Sql</code>'s <em>classpath</em> attribute is a <a
  href="#path">PATH like structure</a> and can also be set via a nested
  <em>classpath</em> element. It is used to load the JDBC classes.</p>
  <p>
  The 
  </p>
  
  <h3>Examples</h3>
  <pre><blockquote>&lt;sql
      driver="org.database.jdbcDriver"
      url="jdbc:database-url"
      userid="sa"
      password="pass"
      src="data.sql"
  /&gt;
  </pre></blockquote>
  
  <p>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</p>
  
  <blockquote><pre>&lt;sql
      driver="org.database.jdbcDriver"
      url="jdbc:database-url"
      userid="sa"
      password="pass"
      &gt;
  insert
  into table some_table
  values(1,2,3,4);
  
  truncate table some_other_table;
  &lt;/sql&gt;
  </pre></blockquote>
  
  <p>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</p>
  
  <p>Note that you may want to enclose your statements in
  <code>&lt;![CDATA[</code> ... <code>]]&gt;</code> sections so you don't
  need to escape <code>&lt;</code>, <code>&gt;</code> <code>&amp;</code>
  or other special characters. For example:</p>
  
  <blockquote><pre>&lt;sql
      driver="org.database.jdbcDriver"
      url="jdbc:database-url"
      userid="sa"
      password="pass"
      &gt;&lt;![CDATA[
  
  update some_table set column1 = column1 + 1 where column2 &lt; 42;
  
  ]]&gt;&lt;/sql&gt;
  </pre></blockquote>
  
  <p>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 <i>some_other_table</i>.</p>
  
  <pre><blockquote>&lt;sql
      driver="org.database.jdbcDriver"
      url="jdbc:database-url"
      userid="sa"
      password="pass" &gt;
    &lt;transaction  src="data1.sql" /&gt;
    &lt;transaction  src="data2.sql" /&gt;
    &lt;transaction  src="data3.sql" /&gt;
    &lt;transaction&gt;
      truncate table some_other_table;
    &lt;/transaction&gt;
  &lt;/sql&gt;
  </pre></blockquote>
  
  <p>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.</p>
  
  <pre><blockquote>&lt;sql
      driver="org.database.jdbcDriver"
      url="jdbc:database-url"
      userid="sa"
      password="pass"
      src="data.sql"
      print="yes"
      output="outputfile.txt"
      &gt;
  &lt;classpath&gt;
  	&lt;pathelement location="/some/jdbc.jar"&gt;
  &lt;/classpath&gt;
  &lt;/sql&gt;
  </pre></blockquote>
  
  <p>The following will only execute if the RDBMS is "oracle" and the version starts with "8.1."</p>
  
  <pre><blockquote>&lt;sql
      driver="org.database.jdbcDriver"
      url="jdbc:database-url"
      userid="sa"
      password="pass"
      src="data.sql"
      rdbms="oracle"
      version="8.1."
      &gt;
  insert
  into table some_table
  values(1,2,3,4);
  
  truncate table some_other_table;
  &lt;/sql&gt;
  </pre></blockquote>
  
  
  
  </body>
  </html>
  
  
  

Mime
View raw message