<?xml version="1.0"?>

<!--
 * ========================================================================
 * 
 * Copyright 2001-2004 The Apache Software Foundation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * 
 * ========================================================================
-->

<document id="integration_ant">

  <properties>
    <title>Ant Integration</title>
  </properties>

  <body>

    <section title="Ant Integration">

      <p>
        Cactus provides strong integration with the popular build tool
        <link href="ext:ant">Ant</link>. This integration consists of a handful
        of tasks that support the running of tests from an Ant build file.
      </p>

      <section title="Background">

        <p>
          A strong principle of <em>eXtreme Programming</em> (XP) is the
          continuous integration aspect (see the
          <link href="http://www.martinfowler.com/articles/continuousIntegration.html">
          Continuous Integration</link> article by Martin Fowler). The
          traditional approach to the development of complex software has been
          to separate the development process into phases of coding, testing and
          integration. The continuous integration principle is to basically code,
          test and integrate at the same time, so that at almost any point in
          time, you have a working product.
        </p>
        <p>
          In order to achieve this, you need to be able to automatically build
          your entire application, including running the unit and acceptance
          tests. Thus, tools such as Ant or <link href="ext:maven">Maven</link>
          are the foundation for continuous integration. You can build on that
          foundation by using a dedicated continuous integration tool like
          <link href="ext:cruisecontrol">CruiseControl</link>,
          <link href="ext:gump">Gump</link> or
          <link href="ext:anthill">AntHill</link>.
        </p>
        <p>
          Ant is written in Java and provides a wide variety of tasks that
          support the development of Java applications (though it is in no way
          restricted to development). In addition, many third-party tasks are
          available, and it is quite easy to extend Ant with custom tasks.
        </p>

      </section>

      <section title="Ant Resources">

        <p>
          This documentation assumes good knowledge of the basic concepts of
          Ant. Here are several resources that can help you get up to speed
          if you haven't been using Ant yet:
          <ul>
            <li>
              The <link href="ext:ant_manual">Ant Manual</link> is the 
              definitive source about Ant.
            </li>
            <li>
              <link href="http://ant.apache.org/ant_in_anger.html">
              Ant in Anger</link> discusses best practices and common pitfalls
              with Ant usage.
            </li>
            <li>
              The book <link href="http://www.manning.com/hatcher/index.html">
              Java Development With Ant</link> by Erik Hatcher and Steve
              Loughran is very much recommended if you plan to use Ant
              intensively.
            </li>
            <li>
              The document
              <link href="http://wiki.apache.org/ant/TheElementsOfAntStyle">
              The Elements of Ant Style</link> in the Apache Wiki lists some
              general rules for using Ant effectively in any kind of project.
            </li>
          </ul>
          <p>
            A full list of resources is maintained by the Ant team at
            <link href="http://ant.apache.org/resources.html">
            http://ant.apache.org/resources.html</link>
          </p>
        </p>

      </section>

      <section title="Installing the Cactus Ant Tasks">

        <p>
          The Ant tasks provided by Cactus are distributed together with the
          main distribution of Cactus, which you can get from the
          <link href="site:downloads">download</link> area. After downloading
          and expanding the archive, you'll find several JAR files in the
          <code>lib</code> directory. See the
          <link href="site:howto_classpath">Classpath Guide</link> for
          information about which of the JARs you need for what.
        </p>
        <p>
          It is recommended that you copy these JARs into the project for which
          you are writing Cactus tests. A common pattern is to have a
          <code>lib</code> directory in the project directory, and put all the
          JARs there. So your project might look something like this:
          <source><![CDATA[
  [your project]
    |- doc
    |  ...
    |- lib
    |   |- cactus.jar
    |   |- cactus-ant.jar
    |   |- commons-httpclient.jar
    |   |- commons-logging.jar
    |   |- junit.jar
    |   |- aspectjrt.jar
    |- src
    |   |- java
    |   |  ...
    |   |- test
    |   |  ...
    |- build.xml
]]></source>
        </p>
        <p>
          Of course, you can put them anywhere you want as long as you
          can correctly locate them from within your build file. Another
          option is to put all the libraries in the <code>lib</code> 
          directory of your Ant installation, so that they get added to
          the classpath automatically. This option is not recommended, however,
          as it quickly leads to pollution of the classpath used by Ant.
        </p>
        <p>
          There's one step left to enable your project to run Cactus tests
          from within Ant: you'll need to introduce the Cactus tasks to Ant.
          This is done with a <code>&lt;taskdef&gt;</code>:
<source><![CDATA[
<!-- Define the Cactus tasks -->
<taskdef resource="cactus.tasks">
  <classpath>
    <pathelement location="lib/cactus.jar"/>
    <pathelement location="lib/cactus-ant.jar"/>
    <pathelement location="lib/commons-httpclient.jar"/>
    <pathelement location="lib/commons-logging.jar"/>
    <pathelement location="lib/aspectjrt.jar"/>
  </classpath>
</taskdef>
]]></source>
        </p>
        <p>
          As you can see, you'll need to add the JARs required by Cactus to the
          <code>&lt;classpath&gt;</code> of the task definition. Note that we 
          don't include the JUnit library, because it usually needs to be
          installed in the <code>lib</code> directory of your Ant installation
          (see the Ant FAQ for details).
        </p>
        <note>
          If you get an error at this point, make absolutely sure that you've
          correctly set up the classpath for the task definition. Run Ant with
          the <code>-verbose</code> or the <code>-debug</code> options to find
          out which libraries or classes could not be found, or what else may
          be going wrong.
        </note>

      </section>

      <section title="Using the Cactus Ant Tasks">

        <p>
          After you have defined the Cactus tasks you'll need to actually use
          them in the build file to run the Cactus tests. Cactus provides a 
          couple of tasks that support you with running the tests from an Ant
          build. Each of the tasks is independant or complementary to the
          others. You'll need to decide on what tasks to used depending on your
          requirements.
          <table>
          	<caption>Ant tasks provided by Cactus</caption>
            <tr>
              <th>CactifyWar</th>
              <td>
                This task can enhance a provided web application archive (WAR),
                and add the elements required to run Cactus tests against it.
                This includes the JARs required by Cactus on the server-side,
                as well as the definitions of the test redirectors in the 
                deployment descriptor.
              </td>
            </tr>
            <tr>
              <th>CactifyEar</th>
              <td>
                This task can enhance a provided Enterprise application archive (EAR),
                and add the elements required to run Cactus tests against it. It can 
                also add EJB references to allow testing of local EJB:s. 
              </td>
            </tr>
            <tr>
              <th>Cactus</th>
              <td>
                This task extends the standard <code>&lt;junit&gt;</code> task
                with the capability of running in-container tests.
              </td>
            </tr>
            <tr>
              <th>RunServerTests</th>
              <td>
                This task is an alternative to the <code>&lt;cactus&gt;</code>
                task that is more generic but harder to use. In contrast to 
                the <code>&lt;cactus&gt;</code> task, it is not an extension of
                the standard <code>&lt;junit&gt;</code> task.
              </td>
            </tr>
            <tr>
              <th>WebXmlMerge</th>
              <td>
                This task can merge the definitions from two web deployment
                descriptors into a new descriptor, and can thus be used to
                add the definition of the Cactus redirectors to an existing
                descriptor. The same functionality is provided by the
                <code>&lt;cactifywar&gt;</code> task, so if you want to cactify
                an entire WAR, you should use that task instead.
              </td>
            </tr>
          </table>
        </p>
        <p>
          Typically, the sequence for executing Cactus tests from an Ant build
          will be the following:
          <ol>
          	<li>
          	  Compile the test classes (using the standard tasks like
          	  <code>&lt;javac&gt;</code>)
          	</li>
          	<li>
          	  Cactify the web-application (using the
          	  <code>&lt;cactifywar&gt;</code> task, or the
          	  <code>&lt;webxmlmerge&gt;</code> task in combination with builtin
          	  Ant tasks like <code>&lt;war&gt;</code> and
          	  <code>&lt;unwar&gt;</code>)
          	</li>
          	<li>
          	  Start the target container, deploy the application, run the tests
          	  and stop the container (using either <code>&lt;cactus&gt;</code> or
          	  <code>&lt;runservertests&gt;</code>)
          	</li>
          </ol>
        </p>

      </section>

    </section>

  </body>

</document>
