<?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_cactifywar">

  <properties>
    <title>CactifyWar Ant Task</title>
  </properties>

  <body>

    <section title="CactifyWar Task">

      <p>
        The task <strong>cactifywar</strong> allows the enhancement of an existing
        web-application archive (WAR) with the elements needed to run Cactus 
        in-container tests. This includes adding the definitions of the test 
        redirectors to the deployment descriptor, as well as adding the libraries
        that Cactus requires on the server side (see the 
        <link href="site:howto_classpath">Classpath Guide</link> for details).
      </p>

      <note>
        If you want to use the
        <link href="site:howto_httpunit">HttpUnit integration</link> in your
        tests, you'll need to explicitly add the <code>httpunit.jar</code> to
        the cactified WAR. You can easily do this by using a nested
        <code>&lt;lib&gt;</code> element.
      </note>

      <p>
        The <strong>cactifywar</strong> task extends the built-in Ant task
        <strong>war</strong>, so it also supports all attributes and nested
        elements that <strong>war</strong> supports.
      </p>

      <section title="Parameters">

        <p>
          As this task is an extension of the <strong>war</strong> task, it
          also supports all the attributes supported by the
          <strong>war</strong> task. The only exception is the
          <em>warfile</em> attribute, which has been renamed to
          <em>destfile</em> for the <strong>cactifywar</strong> task.
        </p>

        <table>
          <tr>
            <th>Name</th>
            <th>Description</th>
            <th>Required</th>
          </tr>
          <tr>
            <td><strong>destfile</strong></td>
            <td>
              The location of the cactified web-application archive to create.
            </td>
            <td>Yes</td>
          </tr>
          <tr>
            <td>srcfile</td>
            <td>
              The original web-application archive that is going to be
              cactified. If this attribute is not specified, a new web-app
              archive will be created. You'll need to specify the
              <em>version</em> attribute in that case.
            </td>
            <td>No</td>
          </tr>
          <tr>
            <td>mergewebxml</td>
            <td>
              Allows the specification of a web deployment descriptor whose 
              content will get merged into the resulting descriptor. This is
              only required for purposes like adding special security
              constraints for testing, as the Cactus test redirectors will be
              added to the cactified deployment descriptor anyway. The merging
              of the descriptors is based on the same principles as used by the
              <link href="site:task_webxmlmerge">webxmlmerge</link> task.
            </td>
            <td>No</td>
          </tr>
          <tr>
            <td>version</td>
            <td>
              The version of the web application archive to create if no source
              archive has been specified with the <em>srcfile</em> attribute.
              Can be either <code>2.2</code> or <code>2.3</code>.
            </td>
            <td>No, unless the <em>srcfile</em> attribute is omitted</td>
          </tr>
        </table>

      </section>

      <section title="Nested Elements">

        <p>
          As this task is an extension of the <strong>war</strong> task, it
          also supports all attributes that the <strong>war</strong> task
          supports. In addition, you can specify the URL-patterns to map the 
          Cactus test redirectors to which the nested elements
          <strong>filterredirector</strong>, <strong>jspredirector</strong> and
          <strong>servletredirector</strong>. If you don't specify those
          elements, the test redirectors will be mapped to the default
          URL-pattern.
        </p>

        <section title="filterredirector">

          <p>
            The <strong>filterredirector</strong> element lets you specify the
            URL pattern to which the Cactus filter test redirector is mapped in
            the web application.
          </p>

          <section title="Parameters">

            <table>
              <tr>
                <th>Name</th>
                <th>Description</th>
                <th>Required</th>
              </tr>
              <tr>
                <td>name</td>
                <td>
                  The name of the filter redirector. Only needed if you want to
                  add multiple filter redirectors to the deployment descriptor.
                </td>
                <td>No, the default is <em>FilterRedirector</em></td>
              </tr>
              <tr>
                <td>mapping</td>
                <td>
                  The URL-pattern to which the redirector should be mapped.
                  Must start with a forward slash (&quot;/&quot;).
                </td>
                <td>No, the default is <em>/FilterRedirector</em></td>
              </tr>
              <tr>
                <td>roles</td>
                <td>
                  A comma-separated list of role names which will be granted
                  access to the redirector. If this attribute is ommitted,
                  access to the redirector will not be constrained. Unless the
                  roles are already defined in the deployment descriptor, they
                  will be added automatically.
                </td>
                <td>No</td>
              </tr>
            </table>

          </section>

          <note>
            This element will be ignored for Servlet 2.2 web applications.
          </note>

        </section>

        <section title="jspredirector">

          <p>
            The <strong>jspredirector</strong> element lets you specify the
            URL pattern to which the Cactus JSP test redirector is mapped in
            the web application.
          </p>

          <section title="Parameters">

            <table>
              <tr>
                <th>Name</th>
                <th>Description</th>
                <th>Required</th>
              </tr>
              <tr>
                <td>name</td>
                <td>
                  The name of the JSP redirector. Only needed if you want to
                  add multiple JSP redirectors to the deployment descriptor.
                </td>
                <td>No, the default is <em>JspRedirector</em></td>
              </tr>
              <tr>
                <td>mapping</td>
                <td>
                  The URL-pattern to which the redirector should be mapped.
                  Must start with a forward slash (&quot;/&quot;).
                </td>
                <td>No, the default is <em>/JspRedirector</em></td>
              </tr>
              <tr>
                <td>roles</td>
                <td>
                  A comma-separated list of role names which will be granted
                  access to the redirector. If this attribute is ommitted,
                  access to the redirector will not be constrained. Unless the
                  roles are already defined in the deployment descriptor, they
                  will be added automatically.
                </td>
                <td>No</td>
              </tr>
            </table>

          </section>

        </section>

        <section title="servletredirector">

          <p>
            The <strong>servletredirector</strong> element lets you specify the
            URL pattern to which the Cactus servlet test redirector is mapped in
            the web application.
          </p>

          <section title="Parameters">

            <table>
              <tr>
                <th>Name</th>
                <th>Description</th>
                <th>Required</th>
              </tr>
              <tr>
                <td>name</td>
                <td>
                  The name of the servlet redirector. Only needed if you want
                  to add multiple servlet redirectors to the deployment
                  descriptor.
                </td>
                <td>No, the default is <em>ServletRedirector</em></td>
              </tr>
              <tr>
                <td>mapping</td>
                <td>
                  The URL-pattern to which the redirector should be mapped.
                  Must start with a forward slash (&quot;/&quot;).
                </td>
                <td>No, the default is <em>/ServletRedirector</em></td>
              </tr>
              <tr>
                <td>roles</td>
                <td>
                  A comma-separated list of role names which will be granted
                  access to the redirector. If this attribute is ommitted,
                  access to the redirector will not be constrained. Unless the
                  roles are already defined in the deployment descriptor, they
                  will be added automatically.
                </td>
                <td>No</td>
              </tr>
            </table>

          </section>

        </section>

        <section title="xmlcatalog">

          <p>
            The <code>xmlcatalog</code> element can be used to perform Entity
            and DTD resolution. This is a built-in Ant type. See the
            <link href="ext:ant_manual">Ant Manual</link> for details.
          </p>

          <note>
            The <strong>cactifywar</strong> task resolves the DTDs of web-app
            descriptors (version 2.2 as well as 2.3) automatically to copies
            stored in the JAR. So normally, you shouldn't need to specify a
            nested <code>xmlcatalog</code> element. Further, actually
            specifying it will disable the default behaviour, and you'll need
            to provide the web-app DTDs yourself.
          </note>

        </section>

      </section>

      <section title="Examples">

        <p>
          The following example demonstrates the simplest-possible use of the
          task. It will add the redirectors with the default mappings to the
          cactified WARs, as well as the Cactus libraries and the JSP page
          needed for the JSP redirector.
        </p>

        <source><![CDATA[
<cactifywar srcfile="${build.dir}/my.war" destfile="${build.dir}/test.war"/>
]]></source>

        <p>
          The next example demonstrates how to modify the mappings of the
          redirectors.
        </p>

        <source><![CDATA[
<cactifywar srcfile="${build.dir}/my.war" destfile="${build.dir}/test.war">
  <filterredirector mapping="/test/filterRedirector"/>
  <jspredirector mapping="/test/jspRedirector"/>
  <servletredirector mapping="/test/servletRedirector"/>
</cactifywar>
]]></source>

        <p>
          In the following example, we add the test classes as well as the
          <link href="site:howto_httpunit">HttpUnit</link> library to the
          cactified WAR.
        </p>

        <source><![CDATA[
<cactifywar srcfile="${build.dir}/my.war" destfile="${build.dir}/test.war">
  <classes dir="${build.dir}/classes/test" includes="**/*.class"/>
  <lib file="${httpunit.jar}"/>
</cactifywar>
]]></source>

        <p>
          In the next example, we add a security-constrained instance of the
          servlet redirector to be able to run tests using authentication
          (see <link href="site:howto_security">Using Authentication</link>
          for details). Note that you need to provide an empty servlet
          redirector element, so that the default redirector is included
          along side the secured redirector (it would just be overridden
          otherwise).
        </p>

        <source><![CDATA[
<cactifywar srcfile="${build.dir}/my.war" destfile="${build.dir}/test.war">
  <servletredirector/>
  <servletredirector name="ServletRedirectorSecure"
      mapping="/ServletRedirectorSecure" roles="test"/>
</cactifywar>
]]></source>

      </section>

    </section>

  </body>

</document>
