<?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="task_cactus">

  <properties>
    <title>Cactus Ant Task</title>
  </properties>

  <body>

  <section title="Cactus Task">

    <p>
      The task <strong>cactus</strong> is an extension of the
      <strong>junit</strong> task that is included in Ant as an optional task.
      <strong>cactus</strong> extends <strong>junit</strong> to enable
      in-container tests. It features built-in support for a variety of
      containers, but also allows testing in custom containers.
    </p>

    <p>
      Here are the different steps peformed automatically by the 
      <code>cactus</code> task:
    </p>
    <ol>
      <li>
        Deploy the cactified WAR/EAR into the target container,
      </li>
      <li>
        If the container is not already started, start it. Otherwise, leave
        it running,
      </li>
      <li>
        Run the Cactus tests,
      </li>
      <li>
        If the container was started by the <code>cactus</code> task the
        stop it. Otherwise, leave it running.
      </li>
    </ol>

    <p>
      Currently the following containers are supported out of the box:
      <ul>
        <li><jump anchor="tomcat3x">Apache Tomcat 3.x</jump></li>
        <li><jump anchor="tomcat4x">Apache Tomcat 4.x</jump></li>
        <li><jump anchor="tomcat5x">Apache Tomcat 5.x</jump></li>
        <li><jump anchor="jboss3x">JBoss Application Server 3.x</jump></li>
        <li><jump anchor="orion1x">Orion Application Server 1.x</jump></li>
        <li><jump anchor="orion2x">Orion Application Server 2.x</jump></li>
        <li><jump anchor="resin2x">Resin Server 2.x</jump></li>
        <li><jump anchor="resin3x">Resin Server 3.x</jump></li>
        <li><jump anchor="weblogic7x">WebLogic 7.x</jump></li>
      </ul>
    </p>
    <p>
      In addition if your favorite container is not in the above list, you
      can use the <jump anchor="generic">Generic</jump> container.
    </p>

    <section title="Parameters">

      <p>
        As this task is an extension of the <strong>junit</strong> task, it
        also supports all attributes that the <strong>junit</strong> task
        supports. In addition, the following parameters are supported:
      </p>

      <table>
        <tr>
          <th>Name</th>
          <th>Description</th>
          <th>Required</th>
        </tr>
        <tr>
          <td><strong>warfile</strong></td>
          <td>
            The web application archive that should be tested. The archive must
            already contain everything needed for running Cactus tests (it must
            be <em><link href="site:task_cactifywar">cactified</link></em>).
          </td>
          <td>Yes, unless the <em>earfile</em> attribute is specified</td>
        </tr>
        <tr>
          <td><strong>earfile</strong></td>
          <td>
            The enterprise application archive that should be tested. The
            archive must contain a web module that already contains everything
            needed for running Cactus tests (it must be
            <em><link href="site:task_cactifywar">cactified</link></em>).
          </td>
          <td>Yes, unless the <em>warfile</em> attribute is specified</td>
        </tr>
      </table>

    </section>

    <section title="Nested Elements">

      <p>
        As this task is an extension of the <strong>junit</strong> task, it
        also supports all the nested elements supported by the
        <strong>junit</strong> task. In addition, the following nested 
        elements are supported:
      </p>

      <section title="cactusproperty">
      
        <p>
          The <strong>cactusproperty</strong> element lets you specify the
          name of a property file. All the properties specified in this file
          will be read and set as System properties.
        </p>

        <section title="Parameters">

          <note>
            The <strong>cactusproperty</strong> element supports the following
            parameters:
          </note>

          <table>
            <tr>
              <th>Name</th>
              <th>Description</th>
              <th>Required</th>
            </tr>
            <tr>
              <td>server</td>
              <td>
                Specifies whether the properties should be added in the Cactus
                server side JVM ("<code>true</code>") or the Cactus client side 
                JVM ("<code>false</code>").
              </td>
              <td>Yes</td>
            </tr>
          </table>

          <p>
            Example (used for enabling Cactus logging):
          </p>      

<source><![CDATA[
<!-- Configure the cactus task for logging -->
<cactusproperty server="false"
    propertiesFile="${target.dir}/logging_client.properties"/>
<cactusproperty server="true"
    propertiesFile="${target.dir}/logging_server.properties"/>
]]></source>
              
        </section>
        
      </section>

      <section title="containerset">

        <p>
          The <strong>containerset</strong> element lets you specify which
          containers the tests should run against. Every element nested inside
          this element corresponds to a container. See below for a list of 
          container elements supported in this element.
        </p>

        <section title="Parameters">

          <note>
            The <strong>containerset</strong> element supports the following
            parameters:
          </note>

          <table>
            <tr>
              <th>Name</th>
              <th>Description</th>
              <th>Required</th>
            </tr>
            <tr>
              <td>timeout</td>
              <td>
                Specifies the timeout in milliseconds after which starting up
                a container should be given up. If the timeout is reached
                before the container starts responding with a successful HTTP
                status code, the build will fail.
              </td>
              <td>No, default is <em>3 minutes</em></td>
            </tr>
            <tr>
              <td>proxyport</td>
              <td>
                By specifying this attribute it is possible to insert some
                application that acts as a local TCP/IP proxy between the
                test runner and the actual containers. Most importantly, that
                includes applications that record and display the HTTP
                transactions, which can be helpful in tracking down tricky 
                problems.
              </td>
              <td>No</td>
            </tr>
          </table>

        </section>

      </section>

      <section title="containerclasspath">
        <p>
          The optional <strong>containerclasspath</strong> element lets you 
          specify additional jars that will be added to the container 
          classpaths that are used to start/stop the containers. This is in 
          addition to the container jars which are automatically added by the
          <code>&lt;cactus&gt;</code> task. The <code>containerclasspath</code>
          element behaves exactly the same as the Ant <code>classpath</code>
          element. In most cases you will not need to use this element.
        </p>
      </section>

    </section>

    <section title="Supported Containers">

      <p>
        All elements nested in the <strong>containerset</strong> element
        represent specific containers.
      </p>

      <p>
        Specific container elements provide attributes and nested elements
        as appropriate.
      </p>

      <section title="Common Parameters">

        <p>
          Here is a list of parameters that are common to all containers.
        </p>

        <table>
          <tr>
            <th>Name</th>
            <th>Description</th>
            <th>Required</th>
          </tr>
          <tr>
            <td>protocol</td>
            <td>
              Protocol to use for communication, one of http or https. Note that
              https will only work, if a.) JSSE is installed b.) the proper
              certificates are installed.
            </td>
            <td>No, default is http</td>
          </tr>
          <tr>
            <td>server</td>
            <td>
              Host name or ip of the machine running the server. Note, that
              the built in deployment support will not work for remote hosts.
            </td>
            <td>No, default is localhost</td>
          </tr>
          <tr>
            <td>port</td>
            <td>
              The TCP port that the container should listen to
            </td>
            <td>No, default is 8080</td>
          </tr>
        </table>

      </section>

      <anchor id="generic"/>
      <section title="generic">

        <p>
          The <strong>generic</strong> container supports custom containers by
          allowing you to specify targets to be called, or tasks to executed,
          in order to start up and shut down the container.
        </p>
        <p>
          Note that the attributes of the <code>&lt;cactus&gt;</code> and
          <code>&lt;containerset&gt;</code> elements are currently not used 
          by the <code>&lt;generic&gt;</code> element.
        </p>
 
        <section title="Parameters">

          <table>
            <tr>
              <th>Name</th>
              <th>Description</th>
              <th>Required</th>
            </tr>
            <tr>
              <td>name</td>
              <td>
                A name for the container that is displayed when the tests are
                run.
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>port</td>
              <td>
                The TCP port that the container should listen to
              </td>
              <td>No, default is 8080</td>
            </tr>
            <tr>
              <td>startuptarget</td>
              <td>
                The name of a target that should be called to perform the
                starting up of the container.
              </td>
              <td>
                Yes, unless there's a nested <strong>startup</strong> element
              </td>
            </tr>
            <tr>
              <td>shutdowntarget</td>
              <td>
                The name of a target that should be called to perform the
                shutting down of the container.
              </td>
              <td>
                Yes, unless there's a nested <strong>shutdown</strong> element
              </td>
            </tr>
            <tr>
              <td>if</td>
              <td>
                Tests will only be run in the container if a property of the
                given name exists in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>unless</td>
              <td>
                Tests will only be run in the container if a property of the
                given name doesn't exist in the current project
              </td>
              <td>No</td>
            </tr>
          </table>

        </section>

        <section title="Nested Elements">

          <p>
            The <strong>generic</strong> container supports the following nested
            elements:
          </p>

          <section title="exclude">

            <p>
              Multiple <strong>exclude</strong> elements can be used as in
              standard Ant <em>PatternSets</em> or <em>FileSets</em> to
              exclude specific tests from running in the container.
            </p>

          </section>

          <section title="startup">

            <p>
              A single <strong>startup</strong> element can be nested inside a 
              <strong>generic</strong> element. Using this element, you can
              implement the startup of the container, either by specifying a 
              target name in the <strong>target</strong> attribute, or by
              directly embedding the required Ant tasks inside the
              <strong>startup</strong> element.
            </p>

          </section>

          <section title="shutdown">

            <p>
              A single <strong>shutdown</strong> element can be nested inside a 
              <strong>generic</strong> element. Using this element, you can
              implement the shutdown of the container, either by specifying a 
              target name in the <strong>target</strong> attribute, or by
              directly embedding the required Ant tasks inside the
              <strong>shutdown</strong> element.
            </p>

          </section>

        </section>

      </section>

      <anchor id="jboss3x"/>
      <section title="jboss3x">

        <p>
          The nested element <strong>jboss3x</strong> allows running the tests
          against the JBoss 3.x application server.
        </p>

        <section title="Parameters">

          <table>
            <tr>
              <th>Name</th>
              <th>Description</th>
              <th>Required</th>
            </tr>
            <tr>
              <td><strong>dir</strong></td>
              <td>
                The installation directory of the JBoss 3.x server
              </td>
              <td>Yes</td>
            </tr>
            <tr>
              <td>config</td>
              <td>
                The name of the JBoss server configuration to use. The 
                files in this server configuration will be copied to the
                tmp directory used to start the container.
              </td>
              <td>No, the default is <em>default</em></td>
            </tr>
            <tr>
              <td>port</td>
              <td>
                The TCP port that will be used to poll the server to
                verify if it is running. Note that this port value is
                not used to tell JBoss on what port it should listen
                to, as is the case for the other containers (this may 
                be implemented in the future).
              </td>
              <td>No, default is 8080</td>
            </tr>
            <tr>
              <td>jndiport</td>
              <td>
                The JNDI server port on which the JBoss server has been
                started. This attribute is only used for shutting down JBoss
                and should only be used if you are running JBoss on a custom
                JNDI port.
              </td>
              <td>No, default is 1099</td>
            </tr>
            <tr>
              <td>tmpdir</td>
              <td>
                The directory to which the container will be installed for the
                tests.
              </td>
              <td>
                No (by default the <code>[JBOSS_HOME]/server/cactus</code> 
                temporary directory is used)
              </td>
            </tr>
            <tr>
              <td>output</td>
              <td>
                Name of a file to write the output of the container to. If not
                specified, the standard output will be used
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>append</td>
              <td>
                Whether output should be appended to or overwrite an existing
                file.
              </td>
              <td>No, default is <em>false</em></td>
            </tr>
            <tr>
              <td>if</td>
              <td>
                Tests will only be run in the container if a property of the
                given name exists in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>unless</td>
              <td>
                Tests will only be run in the container if a property of the
                given name doesn't exist in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>jvmArgs</td>
              <td>
                Arguments to be passed to the JVM running the container (for
                instance, -Xms256m -Xmx800m)
              </td>
              <td>No</td>
            </tr>
          </table>

        </section>

        <section title="Nested Elements">

          <p>
            The <strong>jboss3x</strong> container supports the following
            nested elements:
          </p>

          <section title="exclude">

            <p>
              Multiple <strong>exclude</strong> elements can be used as in
              standard Ant PatternSets or FileSets to exclude specific tests
              from running in the container.
            </p>

          </section>

        </section>

      </section>

      <anchor id="orion1x"/>
      <section title="orion1x">

        <p>
          The nested element <strong>orion1x</strong> allows running the tests
          against the Orion Application Server 1.x.
        </p>

        <section title="Parameters">

          <table>
            <tr>
              <th>Name</th>
              <th>Description</th>
              <th>Required</th>
            </tr>
            <tr>
              <td><strong>dir</strong></td>
              <td>
                The installation directory of the Orion 1.x server
              </td>
              <td>Yes</td>
            </tr>
            <tr>
              <td>port</td>
              <td>
                The TCP port that the container should listen to
              </td>
              <td>No, default is 8080</td>
            </tr>
            <tr>
              <td>tmpdir</td>
              <td>
                The directory to which the container will be installed for the
                tests.
              </td>
              <td>No (by default the system temporary directory is used)</td>
            </tr>
            <tr>
              <td>output</td>
              <td>
                Name of a file to write the output of the container to. If not
                specified, the standard output will be used
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>append</td>
              <td>
                Whether output should be appended to or overwrite an existing
                file.
              </td>
              <td>No, default is <em>false</em></td>
            </tr>
            <tr>
              <td>if</td>
              <td>
                Tests will only be run in the container if a property of the
                given name exists in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>unless</td>
              <td>
                Tests will only be run in the container if a property of the
                given name doesn't exist in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>jvmArgs</td>
              <td>
                Arguments to be passed to the JVM running the container (for
                instance, -Xms256m -Xmx800m)
              </td>
              <td>No</td>
            </tr>
          </table>

        </section>

        <section title="Nested Elements">

          <p>
            The <strong>orion1x</strong> container supports the following
            nested elements:
          </p>

          <section title="exclude">

            <p>
              Multiple <strong>exclude</strong> elements can be used as in
              standard Ant PatternSets or FileSets to exclude specific tests
              from running in the container.
            </p>

          </section>

        </section>

      </section>

      <anchor id="orion2x"/>
      <section title="orion2x">

        <p>
          The nested element <strong>orion1x</strong> allows running the tests
          against the Orion Application Server 2.x.
        </p>

        <section title="Parameters">

          <table>
            <tr>
              <th>Name</th>
              <th>Description</th>
              <th>Required</th>
            </tr>
            <tr>
              <td><strong>dir</strong></td>
              <td>
                The installation directory of the Orion 2.x server
              </td>
              <td>Yes</td>
            </tr>
            <tr>
              <td>port</td>
              <td>
                The TCP port that the container should listen to
              </td>
              <td>No, default is 8080</td>
            </tr>
            <tr>
              <td>tmpdir</td>
              <td>
                The directory to which the container will be installed for the
                tests.
              </td>
              <td>No (by default the system temporary directory is used)</td>
            </tr>
            <tr>
              <td>output</td>
              <td>
                Name of a file to write the output of the container to. If not
                specified, the standard output will be used
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>append</td>
              <td>
                Whether output should be appended to or overwrite an existing
                file.
              </td>
              <td>No, default is <em>false</em></td>
            </tr>
            <tr>
              <td>if</td>
              <td>
                Tests will only be run in the container if a property of the
                given name exists in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>unless</td>
              <td>
                Tests will only be run in the container if a property of the
                given name doesn't exist in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>jvmArgs</td>
              <td>
                Arguments to be passed to the JVM running the container (for
                instance, -Xms256m -Xmx800m)
              </td>
              <td>No</td>
            </tr>
          </table>

        </section>

        <section title="Nested Elements">

          <p>
            The <strong>orion2x</strong> container supports the following
            nested elements:
          </p>

          <section title="exclude">

            <p>
              Multiple <strong>exclude</strong> elements can be used as in
              standard Ant PatternSets or FileSets to exclude specific tests
              from running in the container.
            </p>

          </section>

        </section>

      </section>

      <anchor id="resin2x"/>
      <section title="resin2x">

        <p>
          The nested element <strong>resin2x</strong> allows running the tests
          against the Resin Server 2.x.
        </p>

        <section title="Parameters">

          <table>
            <tr>
              <th>Name</th>
              <th>Description</th>
              <th>Required</th>
            </tr>
            <tr>
              <td><strong>dir</strong></td>
              <td>
                The installation directory of the Resin 2.x server
              </td>
              <td>Yes</td>
            </tr>
            <tr>
              <td>resinconf</td>
              <td>
                The configuration file to use instead of the default one
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>port</td>
              <td>
                The TCP port that the container should listen to
              </td>
              <td>No, default is 8080</td>
            </tr>
            <tr>
              <td>tmpdir</td>
              <td>
                The directory to which the container will be installed for the
                tests.
              </td>
              <td>No (by default the system temporary directory is used)</td>
            </tr>
            <tr>
              <td>output</td>
              <td>
                Name of a file to write the output of the container to. If not
                specified, the standard output will be used
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>append</td>
              <td>
                Whether output should be appended to or overwrite an existing
                file.
              </td>
              <td>No, default is <em>false</em></td>
            </tr>
            <tr>
              <td>if</td>
              <td>
                Tests will only be run in the container if a property of the
                given name exists in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>unless</td>
              <td>
                Tests will only be run in the container if a property of the
                given name doesn't exist in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>jvmArgs</td>
              <td>
                Arguments to be passed to the JVM running the container (for
                instance, -Xms256m -Xmx800m)
              </td>
              <td>No</td>
            </tr>
          </table>

        </section>

        <section title="Nested Elements">

          <p>
            The <strong>resin2x</strong> container supports the following
            nested elements:
          </p>

          <section title="exclude">

            <p>
              Multiple <strong>exclude</strong> elements can be used as in
              standard Ant PatternSets or FileSets to exclude specific tests
              from running in the container.
            </p>

          </section>

        </section>

      </section>

      <anchor id="resin3x"/>
      <section title="resin3x">

        <p>
          The nested element <strong>resin3x</strong> allows running the tests
          against the Resin Server 3.x.
        </p>

        <section title="Parameters">

          <table>
            <tr>
              <th>Name</th>
              <th>Description</th>
              <th>Required</th>
            </tr>
            <tr>
              <td><strong>dir</strong></td>
              <td>
                The installation directory of the Resin 3.x server
              </td>
              <td>Yes</td>
            </tr>
            <tr>
              <td>resinconf</td>
              <td>
                The configuration file to use instead of the default one
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>port</td>
              <td>
                The TCP port that the container should listen to
              </td>
              <td>No, default is 8080</td>
            </tr>
            <tr>
              <td>tmpdir</td>
              <td>
                The directory to which the container will be installed for the
                tests.
              </td>
              <td>No (by default the system temporary directory is used)</td>
            </tr>
            <tr>
              <td>output</td>
              <td>
                Name of a file to write the output of the container to. If not
                specified, the standard output will be used
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>append</td>
              <td>
                Whether output should be appended to or overwrite an existing
                file.
              </td>
              <td>No, default is <em>false</em></td>
            </tr>
            <tr>
              <td>if</td>
              <td>
                Tests will only be run in the container if a property of the
                given name exists in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>unless</td>
              <td>
                Tests will only be run in the container if a property of the
                given name doesn't exist in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>jvmArgs</td>
              <td>
                Arguments to be passed to the JVM running the container (for
                instance, -Xms256m -Xmx800m)
              </td>
              <td>No</td>
            </tr>
          </table>

        </section>

        <section title="Nested Elements">

          <p>
            The <strong>resin3x</strong> container supports the following
            nested elements:
          </p>

          <section title="exclude">

            <p>
              Multiple <strong>exclude</strong> elements can be used as in
              standard Ant PatternSets or FileSets to exclude specific tests
              from running in the container.
            </p>

          </section>

        </section>

      </section>

      <anchor id="tomcat3x"/>
      <section title="tomcat3x">

        <p>
          The nested element <strong>tomcat3x</strong> allows running the tests
          against the Apache Tomcat 3.x servlet container.
        </p>

        <section title="Parameters">

          <table>
            <tr>
              <th>Name</th>
              <th>Description</th>
              <th>Required</th>
            </tr>
            <tr>
              <td><strong>dir</strong></td>
              <td>
                The installation directory of the Tomcat 3.x server
              </td>
              <td>Yes</td>
            </tr>
            <tr>
              <td>serverxml</td>
              <td>
                The server configuration file to use instead of the default one
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>port</td>
              <td>
                The TCP port that the container should listen to
              </td>
              <td>No, default is 8080</td>
            </tr>
            <tr>
              <td>tmpdir</td>
              <td>
                The directory to which the container will be installed for the
                tests.
              </td>
              <td>No (by default the system temporary directory is used)</td>
            </tr>
            <tr>
              <td>output</td>
              <td>
                Name of a file to write the output of the container to. If not
                specified, the standard output will be used
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>append</td>
              <td>
                Whether output should be appended to or overwrite an existing
                file.
              </td>
              <td>No, default is <em>false</em></td>
            </tr>
            <tr>
              <td>if</td>
              <td>
                Tests will only be run in the container if a property of the
                given name exists in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>unless</td>
              <td>
                Tests will only be run in the container if a property of the
                given name doesn't exist in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>jvmArgs</td>
              <td>
                Arguments to be passed to the JVM running the container (for
                instance, -Xms256m -Xmx800m)
              </td>
              <td>No</td>
            </tr>
          </table>

        </section>

        <section title="Nested Elements">

          <p>
            The <strong>tomcat3x</strong> container supports the following
            nested elements:
          </p>

          <section title="conf">

            <p>
              An Ant Fileset that can be used to specify the set of files that
              should be placed into the <strong>conf</strong> directory of the
              installation directory. This fileset should not include the
              <code>server.xml</code> file (it will be excluded if you add it)
              as you must use the <code>serverxml</code> attribute to specify a
              custom version of it.
            </p>

          </section>

          <section title="exclude">

            <p>
              Multiple <strong>exclude</strong> elements can be used as in
              standard Ant PatternSets or FileSets to exclude specific tests
              from running in the container.
            </p>

          </section>

        </section>

      </section>

      <anchor id="tomcat4x"/>
      <section title="tomcat4x">

        <p>
          The nested element <strong>tomcat4x</strong> allows running the tests
          against the Apache Tomcat 4.x servlet container.
        </p>

        <section title="Parameters">

          <table>
            <tr>
              <th>Name</th>
              <th>Description</th>
              <th>Required</th>
            </tr>
            <tr>
              <td><strong>dir</strong></td>
              <td>
                The installation directory of the Tomcat 4.x server
              </td>
              <td>Yes</td>
            </tr>
            <tr>
              <td>serverxml</td>
              <td>
                The server configuration file to use instead of the default one
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>contextxml</td>
              <td>
                An optional <a href="ext:tomcat4_context_xml">context xml</a> 
                file to use. Any file specified here will be copied into
                the <code>webapps/</code> directory.
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>port</td>
              <td>
                The TCP port that the container should listen to
              </td>
              <td>No, default is 8080</td>
            </tr>
            <tr>
              <td>tmpdir</td>
              <td>
                The directory to which the container will be installed for the
                tests.
              </td>
              <td>No (by default the system temporary directory is used)</td>
            </tr>
            <tr>
              <td>output</td>
              <td>
                Name of a file to write the output of the container to. If not
                specified, the standard output will be used
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>append</td>
              <td>
                Whether output should be appended to or overwrite an existing
                file.
              </td>
              <td>No, default is <em>false</em></td>
            </tr>
            <tr>
              <td>if</td>
              <td>
                Tests will only be run in the container if a property of the
                given name exists in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>unless</td>
              <td>
                Tests will only be run in the container if a property of the
                given name doesn't exist in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>jvmArgs</td>
              <td>
                Arguments to be passed to the JVM running the container (for
                instance, -Xms256m -Xmx800m)
              </td>
              <td>No</td>
            </tr>
          </table>

        </section>

        <section title="Nested Elements">

          <p>
            The <strong>tomcat4x</strong> container supports the following
            nested elements:
          </p>

          <section title="conf">

            <p>
              An Ant Fileset that can be used to specify the set of files that
              should be placed into the <strong>conf</strong> directory of the
              installation directory. This fileset should not include the
              <code>server.xml</code> file (it will be excluded if you add it)
              as you must use the <code>serverxml</code> attribute to specify a
              custom version of it.
            </p>

          </section>

          <section title="exclude">

            <p>
              Multiple <strong>exclude</strong> elements can be used as in
              standard Ant PatternSets or FileSets to exclude specific tests
              from running in the container.
            </p>

          </section>

        </section>

      </section>

      <anchor id="tomcat5x"/>
      <section title="tomcat5x">

        <p>
          The nested element <strong>tomcat5x</strong> allows running the tests
          against the Apache Tomcat 5.x servlet container.
        </p>

        <p>
          Note: For Tomcat 5.x, there is no <code>contextxml</code> attribute as
          it is not required. Tomcat 5.x requires the context file to be put 
          under the <code>conf/</code> directory (see the 
          <a href="ext:tomcat5_context_xml">context documentation page</a>).
          Thus you'll simply need to use the nested <code>&lt;conf&gt;</code>
          element. Alternatively you should be able to also put your context 
          file in <code>META-INF/context.xml</code>.
        </p>

        <section title="Parameters">

          <table>
            <tr>
              <th>Name</th>
              <th>Description</th>
              <th>Required</th>
            </tr>
            <tr>
              <td><strong>dir</strong></td>
              <td>
                The installation directory of the Tomcat 5.x server
              </td>
              <td>Yes</td>
            </tr>
            <tr>
              <td>serverxml</td>
              <td>
                The server configuration file to use instead of the default one
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>port</td>
              <td>
                The TCP port that the container should listen to
              </td>
              <td>No, default is 8080</td>
            </tr>
            <tr>
              <td>tmpdir</td>
              <td>
                The directory to which the container will be installed for the
                tests.
              </td>
              <td>No (by default the system temporary directory is used)</td>
            </tr>
            <tr>
              <td>output</td>
              <td>
                Name of a file to write the output of the container to. If not
                specified, the standard output will be used
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>append</td>
              <td>
                Whether output should be appended to or overwrite an existing
                file.
              </td>
              <td>No, default is <em>false</em></td>
            </tr>
            <tr>
              <td>if</td>
              <td>
                Tests will only be run in the container if a property of the
                given name exists in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>unless</td>
              <td>
                Tests will only be run in the container if a property of the
                given name doesn't exist in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>jvmArgs</td>
              <td>
                Arguments to be passed to the JVM running the container (for
                instance, -Xms256m -Xmx800m)
              </td>
              <td>No</td>
            </tr>
          </table>

        </section>

        <section title="Nested Elements">

          <p>
            The <strong>tomcat5x</strong> container supports the following
            nested elements:
          </p>

          <section title="conf">

            <p>
              An Ant Fileset that can be used to specify the set of files that
              should be placed into the <strong>conf</strong> directory of the
              installation directory. This fileset should not include the
              <code>server.xml</code> file (it will be excluded if you add it)
              as you must use the <code>serverxml</code> attribute to specify a
              custom version of it.
            </p>

          </section>

          <section title="exclude">

            <p>
              Multiple <strong>exclude</strong> elements can be used as in
              standard Ant PatternSets or FileSets to exclude specific tests
              from running in the container.
            </p>

          </section>

        </section>

      </section>

      <anchor id="weblogic7x"/>
      <section title="weblogic7x">

        <p>
          The nested element <strong>weblogic7x</strong> allows running the 
          tests against the WebLogic 7.x J2EE container.
        </p>

        <section title="Parameters">

          <table>
            <tr>
              <th>Name</th>
              <th>Description</th>
              <th>Required</th>
            </tr>
            <tr>
              <td><strong>dir</strong></td>
              <td>
                The installation directory of WebLogic 7.x. Note that this
                should not be the the bea home directory. For example:
                <code>c:\bea\weblogic700</code>.
              </td>
              <td>Yes</td>
            </tr>
            <tr>
              <td><strong>beahome</strong></td>
              <td>
                The bea home directory. By default Cactus tries to guess the
                bea home directory by taking the parent directory of the
                <code>dir</code> directory (i.e. where WebLogic 7.x is
                installed). You only need to use the <code>beahome</code> if
                you have put your bea home directory somewhere else.
              </td>
              <td>No, defaults to the parent directory of dir</td>
            </tr>
            <tr>
              <td>configXml</td>
              <td>
                The Weblogic <code>config.xml</code> configuration file to use 
                instead of the default one.
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>port</td>
              <td>
                The TCP port that the container should listen to
              </td>
              <td>No, default is 8080</td>
            </tr>
            <tr>
              <td>tmpdir</td>
              <td>
                The directory to which the container will be installed for the
                tests.
              </td>
              <td>No (by default the system temporary directory is used)</td>
            </tr>
            <tr>
              <td>output</td>
              <td>
                Name of a file to write the output of the container to. If not
                specified, the standard output will be used
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>append</td>
              <td>
                Whether output should be appended to or overwrite an existing
                file.
              </td>
              <td>No, default is <em>false</em></td>
            </tr>
            <tr>
              <td>if</td>
              <td>
                Tests will only be run in the container if a property of the
                given name exists in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>unless</td>
              <td>
                Tests will only be run in the container if a property of the
                given name doesn't exist in the current project
              </td>
              <td>No</td>
            </tr>
            <tr>
              <td>jvmArgs</td>
              <td>
                Arguments to be passed to the JVM running the container (for
                instance, -Xms256m -Xmx800m)
              </td>
              <td>No</td>
            </tr>
          </table>

        </section>

        <section title="Nested Elements">

          <p>
            The <strong>tomcat4x</strong> container supports the following
            nested elements:
          </p>

          <section title="conf">

            <p>
              A fileset that can be used to specify the set of files that
              should be placed into the <strong>conf</strong> directory of the
              installation directory. This fileset should not include the
              <code>serverxml</code> file.
            </p>

          </section>

          <section title="exclude">

            <p>
              Multiple <strong>exclude</strong> elements can be used as in
              standard Ant PatternSets or FileSets to exclude specific tests
              from running in the container.
            </p>

          </section>

        </section>

      </section>

    </section>

    <section title="Examples">

      <p>
        The following example demonstrates how to run a suite of Cactus tests
        against three contains with builtin support (JBoss 3, Resin 2 and
        Tomcat 4).
      </p>

      <source><![CDATA[
<cactus warfile="${test.dir}/test.war"
    printsummary="yes" failureproperty="tests.failed">
  <classpath>
    <path refid="cactus.classpath"/>
    <pathelement location="${build.classes.dir}"/>
    <pathelement location="${test.classes.dir}"/>
  </classpath>
  <containerset>
    <jboss2x dir="${jboss3x.home}" config="default"
        todir="${test.reports.dir}/jboss3x"/>
    <resin2x dir="${resin2x.home}" port="8080"
        todir="${test.reports.dir}/resin2x"/>
    <tomcat4x dir="${tomcat4x.home}" port="8080"
        todir="${test.reports.dir}/tomcat4x"/>
  </containerset>
  <formatter type="xml"/>
  <batchtest>
    <fileset dir="${src.test.dir}">
      <include name="**/Test*.java"/>
      <exclude name="**/TestAll.java"/>
    </fileset>
  </batchtest>
</cactus>
]]></source>

      <p>
        The next example shows the use of the <strong>generic</strong>
        container element for starting/stopping a custom container. You need
        to define the two targets <em>mycontainer.start</em> and
        <em>mycontainer.stop</em>, so that the container is started up (on 
        port 8080) before the tests are run, and shut down after the tests
        completed. How these targets are implemented is highly dependant on
        the container. Most likely you'll need to copy some files and use
        the <strong>&lt;java&gt;</strong> task to invoke a container-provided
        Java class that can start/stop the container.
      </p>

      <source><![CDATA[
<cactus warfile="${test.dir}/test.war"
    printsummary="yes" failureproperty="tests.failed">
  <classpath>
    <path refid="cactus.runtime.classpath"/>
    <pathelement location="${build.classes.dir}"/>
    <pathelement location="${test.classes.dir}"/>
  </classpath>
  <containerset>
    <generic name="My Container" port="8080">
      <startup target="mycontainer.start"/>
      <shutdown target="mycontainer.stop"/>
    </generic>
  </containerset>
  <formatter type="xml"/>
  <batchtest>
    <fileset dir="${src.test.dir}">
      <include name="**/Test*.java"/>
      <exclude name="**/TestAll.java"/>
    </fileset>
  </batchtest>
</cactus>
]]></source>

    </section>

  </section>

  </body>
</document>
