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

  <properties>
    <title>Getting Started</title>
  </properties>

  <body>

    <section title="Forewords">
      <p>
        If you want to quickly get a feeling of Cactus, there is a
        <link href="site:howto_tomcat">20 minutes tutorial</link> that take you
        through running your first Cactus test using Tomcat. It doesn't explain
        how Cactus works or any other details but let's you have something
        running quickly.
      </p>
      <p>
        We suggest you take this quicky tutorial and then come back here and
        continue reading below. You would have had a first glimpse of Cactus
        in action and will be ready to understand the concepts behind it and
        its full power.
      </p>
    </section>

    <section title="Installing Cactus">

      <p>
        There is not really an installation of Cactus per see, as Cactus is
        not an application but a framework. However you do need to understand
        how it integrates in your working environment. In order to simplify
        this integration Cactus offers 
        <a href="site:howto_runner">several integration modules</a>. Thus, 
        installing Cactus simply means picking an integration module and 
        learning how to configure and use it.
      </p>

    </section>

    <section title="System Requirements">

      <p>
        In order to run Cactus tests you need to have the following
        software already installed on your system:
      </p>

      <ul>
        <li>
          <strong>Java Virtual Machine</strong>
          A Java 1.2 or greater compatible virtual machine must be present. Note
          that all servlet engines require a JVM to run so if you are already
          using servlets you already have one installed.
        </li>
        <li>
          <strong>Servlet/J2EE Engine</strong>
          A Servlet 2.x/J2EE 1.x compliant servlet engine for running your 
          Cactus tests must be present.
        </li>
      </ul>

      <p>
        You also need to have installed the development tools that you are 
        integrating Cactus with. For example, if you plan to use the Ant
        integration, you must have Ant installed. If you plan to execute
        Cactus tests from an IDE, this IDE software has to be already 
        installed, etc.
      </p>

    </section>

    <section title="The Cactus files">

      <p>
        At this point, you should have
        <link href="site:downloads">downloaded</link> a Cactus distribution
        (for the J2EE API you intend to use) and unzipped it in a
        <code>[cactus root]</code> directory.
      </p>
      <p>
        You'll find the following directories under <code>[cactus root]</code>:
      </p>
      <ul>
        <li>
          <strong><code>doc/</code></strong>: contains Cactus web site and
          API javadocs.
        </li>
        <li>
          <strong><code>lib/</code></strong>: contains Cactus jars and related
          external libraries.
        </li>
        <li>
          <strong><code>samples/</code></strong>: contains 
          <a href="site:howto_sample">sample applications</a>
          showing how to write Cactus tests and how to automate their 
          execution.
        </li>
        <li>
          <strong><code>samples/ejb</code></strong>: contains a sample 
          application showing how to test EJBs with Cactus.
        </li>
        <li>
          <strong><code>samples/jetty</code></strong>: contains a sample 
          application showing how to test Servlet with Cactus and Jetty
          (using the <code>JettyTestSetup</code> extension).
        </li>
        <li>
          <strong><code>samples/servlet</code></strong>: contains a sample 
          application showing how to test Servlet/JSPs/Taglibs with Cactus.
        </li>
        <li>
          <strong><code>web/</code></strong>: contains the JSP redirector file
          which is only required if you're using the 
          <a href="site:integration_manual">manual integration</a>.
        </li>
      </ul>

      <p>
        The jars making up Cactus are:
      </p>
      <ul>
        <li>
          <strong><code>cactus.jar</code></strong>: the main jar,
          contains the framework classes. You can find this jar in
          <code>[cactus root]/lib</code>.
        </li>
        <li>
          <strong><code>cactus-ant.jar</code></strong>: a jar which
          contains some custom Ant tasks to help integrate easily with Ant.
          This is only needed if you wish to use Ant for automating the
          execution of Cactus tests. For more information on how to integrate
          Cactus with Ant, see the
          <link href="site:integration_ant">Ant Howto</link> tutorial. You also
          find this jar in <code>[cactus root]/lib</code>.
        </li>
        <li>
          <strong><code>httpclient.jar</code></strong>: Cactus is relying
          on the Jakarta Commons HttpClient framework for Cookie handling.
        </li>
        <li>
          <strong><code>junit.jar</code></strong>: Cactus extends JUnit and
          thus needs the JUnit jar.
        </li>
        <li>
          <strong><code>aspectjrt.jar</code></strong>: Cactus uses
          <link href="ext:aspectj">AspectJ</link> for performing
          several tasks (logging entries and exit of methods, checking
          configuration, etc).
        </li>
        <li>
          <strong><code>commons-logging.jar</code></strong>: Cactus uses
          the Jakarta Commons Logging facade framework to provide seamless
          Cactus logging using any existing Logging framework (Log4j,
          LogKit, JDK 1.4 Logging, etc). It is also needed for Commons
          HttpClient.
        </li>
        <li>
          <strong><code>servletapi.jar</code></strong>: Required for compiling
          the Servlet sample. Ideally we should be bundling the J2EE jar (which
          is required for compiling the EJB sample). However the Sun license 
          does not allow us to redistribute it so you'll need to download it
          by yourself (see the <a href="site:howto_sample">Sample howto</a> 
          page.
        </li>
        <li>
          <strong><code>httpunit.jar</code></strong>: Cactus uses the
          HttpUnit framework to perform <a href="site:howto_httpunit">complex 
          assertions of returned responses</a>. Cactus also bundles a default 
          web response object but the HttpUnit one should be preffered for 
          complex assertions.
        </li>
        <li>
          <strong><code>nekohtml.jar</code></strong>: Required by HttpUnit.
        </li>
      </ul>

    </section>

    <section title="What's next?">

      <p>
        At this point you should understand what Cactus is and how it works.
      </p>
      <p>
        Pick the <a href="site:howto_runner">Cactus integration module</a> that 
        you wish to use in your development environment. Read up on how it works
        and how to use it.
      </p>
      <p>
        Then, you should read the <link href="site:howto_testcase">TestCase
        Howto</link> to understand how to write Cactus Test Cases.
      </p>
      <p>
        The last step is probably to put in practice what you've learned so far
        by <link href="site:howto_sample">running the Cactus Samples</link>.
      </p>
      <p>
        Enjoy !
      </p>

    </section>

  </body>
</document>
