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

  <properties>
    <title>Tomcat Quickstart</title>
  </properties>

  <body>

    <section title="Tomcat Quickstart forewords">

      <note>
        This tutorial applies to Cactus 1.4 or greater and Tomcat 4.0 or
        greater.
      </note>

      <p>
        This document is a step by step tutorial that explains how to set up
        Cactus and run Cactus tests in Tomcat in less than 10 minutes !
        (discounting download time of course :-)).
      </p>
      <p>
        There are 2 ways of packaging Cactus so that you can execute Cactus
        tests on your application:
      </p>
      <ul>
        <li>
          By putting all Cactus jars in your <code>WEB-INF/lib</code> directory,
          as described in the <link href="site:howto_classpath">Classpath
          Tutorial</link>,
        </li>
        <li>
          By putting the Cactus jars in your container classpath so that Cactus
          will load them using the container Context class loader. This
          tutorial will describe this strategy as it is the less intrusive one
          and provides reuse of Cactus jars across several webapps.
        </li>
      </ul>
      <p>
        In addition to this, there are several ways to trigger the execution of
        the Cactus tests (see the <link href="site:howto_runner">TestRunner
        Howto</link> tutorial). We will describe the easiest one to set up in
        this tutorial, which is by using a browser.
      </p>
      <note>
        Step 1 to step 3 are a one time install steps that you need to perform
        only once to be able to run Cactus tests within Tomcat.
      </note>

    </section>

    <section title="Step 1: Install Tomcat">
      <p>
        Download <link href="http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/">Tomcat</link>
        4.0 or greater and unzip it in any directory. Let's call this directory
        <code>[tomcat-root]</code>.
      </p>
    </section>

    <section title="Step 2 : Copy the Cactus jars">
      <p>
        Download the Cactus jars from the <link href="site:downloads">Cactus
        download page</link>. They are located in the <code>lib/</code>
        directory in the zip.
      </p>
      <p>
        Copy the following jars to <code>[tomcat-root]/common/lib</code>:
      </p>
      <ul>
        <li>
          <code>cactus.jar</code>
        </li>
        <li>
          <code>commons-httpclient.jar</code>
        </li>
        <li>
          <code>commons-logging.jar</code>
        </li>
        <li>
          <code>junit.jar</code>
        </li>
        <li>
          <code>aspectjrt.jar</code>
        </li>
      </ul>
      <note>
        This is the minium set of jars needed. If later on you wish to use the
        Cactus <link href="site:howto_httpunit">HttpUnit integration</link>
        you'll also need to copy <code>httpunit.jar</code>.
      </note>
    </section>

    <section title="Step 3: Modify Tomcat web.xml">
      <p>
        Edit <code>[tomcat-root]/conf/web.xml</code> and add the following at
        the beginning of the file, after the <code>&lt;webapp&gt;</code> tag:
      </p>
<source><![CDATA[
<servlet>
  <servlet-name>ServletRedirector</servlet-name>
  <servlet-class>org.apache.cactus.server.ServletTestRedirector</servlet-class>
  <init-param>
    <param-name>param1</param-name>
    <param-value>value1 used for testing</param-value>
  </init-param>
</servlet>

<servlet>
  <servlet-name>ServletTestRunner</servlet-name>
  <servlet-class>org.apache.cactus.server.runner.ServletTestRunner</servlet-class>
</servlet>
]]></source>

      <p>
        Then, after the last <code>&lt;servlet&gt;</code> definition (there
        are a few provided by Tomcat in addition to our 2 above), add:
      </p>

<source><![CDATA[
<servlet-mapping>
    <servlet-name>ServletRedirector</servlet-name>
    <url-pattern>/ServletRedirector</url-pattern>
</servlet-mapping>

<servlet-mapping>
    <servlet-name>ServletTestRunner</servlet-name>
    <url-pattern>/ServletTestRunner</url-pattern>
</servlet-mapping>
]]></source>

      <note>
        <strong>Warning</strong>: Be careful when you modify the global 
        Tomcat <code>web.xml</code> file. If later on you wish to use
        the Cactus Ant integration and more specifically if you use the
        <code>&lt;cactifywar&gt;</code> Ant task, you may run into problems.
        The <code>&lt;cactifywar&gt;</code> task automatically adds the
        needed Cactus redirectors (thus they'll be added twice leading to
        an error.
      </note>
      
    </section>

    <section title="Step 4: Creating a sample applicaton to test">
      <p>
        We're now going to create a very very simple application to server
        so that we can unit test it.
      </p>
      <p>
        First, create the following directory structure:
      </p>

<source><![CDATA[
[tomcat-root]/webapps
  |_ test
    |_ WEB-INF
      |_ classes
]]></source>

      <p>
        Then, create the following <code>SampleServlet.java</code> java source
        file, compile it and copy the resulting .class file in
        <code>[tomcat-root]/webapps/test/WEB-INF/classes</code>.
      </p>

<source><![CDATA[
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;

public class SampleServlet extends HttpServlet
{
    public void saveToSession(HttpServletRequest request)
    {
    	String testparam = request.getParameter("testparam");
    	request.getSession().setAttribute("testAttribute", testparam);
    }
}
]]></source>

      <note>
        You'll notice that this isn't even a finished servlet ! However, this
        shows that you can start testing your code with Cactus even before
        you have finished writing it completely. Extreme Programmers should
        like this :-)
      </note>

      <p>
        We're now read to create our first Cactus test case. Create the
        following <code>TestSampleServlet.java</code> java source file, compile
        it and copy the resulting .class file in
        <code>[tomcat-root]/webapps/test/WEB-INF/classes</code>.
      </p>

<source><![CDATA[
import junit.framework.Test;
import junit.framework.TestSuite;

import org.apache.cactus.ServletTestCase;
import org.apache.cactus.WebRequest;

public class TestSampleServlet extends ServletTestCase
{
    public TestSampleServlet(String theName)
    {
        super(theName);
    }

    public static Test suite()
    {
        return new TestSuite(TestSampleServlet.class);
    }

    public void beginSaveToSessionOK(WebRequest webRequest)
    {
        webRequest.addParameter("testparam", "it works!");
    }

    public void testSaveToSessionOK()
    {
        SampleServlet servlet = new SampleServlet();
        servlet.saveToSession(request);
        assertEquals("it works!", session.getAttribute("testAttribute"));
    }
}
]]></source>

    </section>

    <section title="Step 5: Run the test">

      <p>
        Time to enjoy our hard work ! Start Tomcat by running
        <code>[tomcat-root]/bin/startup.bat</code> (for windows) or
        <code>[tomcat-root]/bin/startup.sh</code> (for unix).
      </p>
      <p>
        Open a browser and point it at
        <code>http://localhost:8080/test/ServletTestRunner?suite=TestSampleServlet</code>
      </p>
      <p>
        You should see:
      </p>
      <figure src="images/tomcat_xml.jpg" alt="XML output of ServletTestRunner"/>

    </section>

    <section title="Step 6: Even more fun!">
      <p>
        Ok, that's nice ... But what if I want HTML instead of XML? Don't
        worry there is a solution. Grab the following
        <link href="site:cactus_report_xsl">XSLT stylesheet</link>
        (based on the stylesheet used by the
        <strong>&lt;junitreport&gt;</strong> Ant task) and drop it in
        <code>[tomcat-root]/webapps/test</code>. Then, open a browser and type
        <code>http://localhost:8080/test/ServletTestRunner?suite=TestSampleServlet&amp;xsl=cactus-report.xsl</code>.
        You should now see the following:
      </p>

      <figure src="images/tomcat_html.jpg" alt="HTML output of ServletTestRunner"/>

      <note>
        This will work with any browser that supports client-slide XSLT 
        transformations (both Internet Explorer and Mozilla do, for example).
      </note>

    </section>

  </body>

</document>
