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

  <properties>
    <title>Jetty Integration</title>
  </properties>

  <body>

    <section title="Forewords and Requirements">

      <p>
        This page explains how to run Cactus tests with the Jetty servlet
        container. You will need the single <link href="ext:jetty">Jetty</link>
        jar, and if you are using JSPs you will also need the Jasper jars.
      </p>

    </section>
    
    <section title="Setting up Jetty">

      <p>
        The idea is to use the 
        <code>org.apache.cactus.extension.jetty.JettyTestSetup</code> JUnit
        TestSetup class provided by Cactus so that Jetty is started before the 
        tests are run.
      </p>
      <p>
        In order to use the TestSetup, you need to wrap your test suite in 
        <code>JettyTestSetup</code>:
      </p>
<source><![CDATA[
public class TestJettyAll extends TestCase
{
    public static Test suite()
    {
        TestSuite suite = new TestSuite();
        suite.addTestSuite(MyTestClass1.class);
        [...]
        suite.addTestSuite(MyTestClassN.class);
        
        return new JettyTestSetup(suite);
    }        
]]></source>
      
      <p>
        You can configure the Jetty TestSetup either programatically or
        with system properties:
      </p>
      <ul>
        <li>
          The method <code>setConfigFile(File)</code> or the system property
          <code>cactus.jetty.config</code> sets the location of an optional
          jetty.xml file (see Jetty's documentation for details).
        </li>
        <li>
          The method <code>setResourceDir(File)</code> or the system property
          <code>cactus.jetty.resourceDir</code> sets the directory containing
          the web-application resources (expanded WAR). If you omit this step,
          you'll only be able to use the Servlet Redirector.
        </li>
      </ul>
      <p>
        In both cases, the value set programatically takes precendence over the
        value of the corresponding system property.
      </p>
      <note>
        If you're using JSPs you'll need to add the Jasper jars to your 
        runtime Classpath (in addition to the Jetty jar).
      </note>      

      <section title="Example 1: Running from Ant">

        <p>
          Let's assume we have a JUnit task that launches the tests.
          We need to add the Jetty jar and optionally the Jasper jars
          (if we use JSPs) to the runtime classpath. Then, all we have 
          to do is add the correct VM arguments to configure
          the <code>JettyTestSetup</code> behavior. For example:
        </p>
<source><![CDATA[
<junit>

    [...]
    
    <jvmarg value="-Dcactus.contextURL=http://localhost:${test.port}/test"/>
    <jvmarg value="-Dcactus.jetty.resourceDir=${src.webapp.dir}"/>
    <jvmarg value="-Dcactus.jetty.config=${src.webapp.dir}/test/jetty.xml"/>

    <classpath>
        [...]
        <!-- Include Jetty jar and optionally Jasper jars in the classpath -->
        <pathelement location="${jetty.jar}"/>
        <pathelement location="${jasper-compiler.jar}"/>
        <pathelement location="${jasper-runtime.jar}"/>    
    </classpath>
    
    <test name="org.apache.cactus.sample.TestJettyAll"/>

</junit>
]]></source>

      </section>

      <section title="Example 2: Running from an IDE">

        <p>
          Again all you have to do is add the correct VM arguments, and the
          Jetty and Jasper jars, to the JUnit launch.
        </p>
        <p>
          For example in Eclipse you would add the jars, and create a JUnit
          launch configuration as below:
        </p>
        <figure src="images/jetty_eclipse.png"
            alt="Eclipse configuration for Jetty"/>

      </section>

    </section>
  </body>
</document>
