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

  <properties>
    <title>Eclipse plug-in for Cactus</title>
  </properties>

  <body>
    <section title="Overview">
      <p>
        The
        <link href="ext:eclipse">Eclipse</link>
        plug-in for Cactus is a runner for server-side unit tests. It is
        intended to hide the complexity of setting up an environment for
        running Cactus tests. It supports a variety of commercial and
        open-source application servers (better called containers).
      </p>
      <li>
        <jump anchor="features">Features</jump>
      </li>
      <li>
        <jump anchor="installation">Installation</jump>
      </li>
      <li>
        <jump anchor="using">Using</jump>
      </li>
      <li>
        <jump anchor="next">What's next</jump>
      </li>
      <li>
        <jump anchor="developer">Developer's corner</jump>
      </li>
    </section>

    <anchor id="features" />
    <section title="Features">
      <ul>
        <li>
          Adds a shortcut for Cactus tests launching.
          <figure src="images/eclipse/runner/launchshortcut.png"
            alt="Cactus launch shortcut"/>
        </li>
      </ul>
      <ul>
        <li>
          Uses the 
          <link href="site:integration_eclipse_webapp">Webapp Eclipse 
          plug-in</link> to package a WAR file containing the web application.
        </li>
      </ul>
      <ul>
        <li>
          Relies on the Eclipse Ant integration to :
          <ul>
            <li>
              deploy the application
            </li>
            <li>
              start the container before running the tests
            </li>
            <li>
              stop the container when tests have ended
            </li>
          </ul>
        </li>
      </ul>
      <ul>
        <li>
          Integrated Jetty container support
        </li>
      </ul>      
      <ul>
        <li>
          Cactus preference page
          <figure src="images/eclipse/runner/preferences.png"
            alt="Cactus preference page" />
	        <ul>
		        <li>
		          Port on which the container is started.
		        </li>
		        <li>
		          Working directory where the Cactus plugin will create temporary
		          files (packaged war, container configuration files, etc).
		        </li>
		        <li>
		          Support for several containers
			        <figure src="images/eclipse/runner/preferences_containers.png"
			          alt="Preferences for containers" />
		        </li>
	        </ul>
        </li>
      </ul>
      <ul>
        <li>
          The user can provide its own web.xml file. If this is not the case
          the plug-in will use the one by default.
        </li>
      </ul>
      <ul>
        <li>
          Relies on the JUnit plug-in for test runs and result reports.
          <figure src="images/eclipse/runner/junit.png"
            alt="JUnit plug-in" />
        </li>
      </ul>
      <ul>
        <li>
          Cactify a Java project : adds client-side jars to a project's
          build path.
          <figure src="images/eclipse/runner/cactify.png"
            alt="Cactify popup menu" />
        </li>
      </ul>
      <ul>
        <li>
          Log view a la Ant plugin
        </li>
      </ul>
    </section>

    <anchor id="installation"/>
    <section title="Installation">
      <section title="Requirements">
        <p>
          The Cactus plugin requires a version of the Eclipse platform later
          than 2.1.
        </p>
      </section>
      <section title="Installation">
        <p>
          Uncompress the zip file and copy the
          <code>org.apache.cactus.integration.eclipse_[version]</code> folder 
          to your Eclipse <code>plugins</code> folder and restart Eclipse.
        </p>
      </section>
      <section title="Configuration">
        <p>
          Go to Window -> Preferences -> Cactus and set your preferences.
        </p>
      </section>

    </section>
    
    <anchor id="using" />
    <section title="Using">
      <p>
        Select any Cactus test class and from the toolbar do :
        Run As -> Cactus Test
        <figure src="images/eclipse/runner/launchshortcut.png"
          alt="Cactus launch shortcut" />
      </p>
    </section>

    <anchor id="next" />
    <section title="What's next">
      <p>
        In order to release a production-quality tool some features are needed.
      </p>
      <p>
        See the todo section on the Cactus framework page for a list of
        remaining features
      </p>
    </section>

    <anchor id="developer" />
    <section title="Developer's corner">
      <section title="Overview of the plug-in">
        <p>
          The Cactus framework extends JUnit. The Cactus
          plugin for Eclipse extends in a certain manner the existing JUnit
          plugin. For example
          <code>JUnitLaunchShortcut</code>
          is overloaded to be able to:
        </p>
        <ul>
          <li>
            prepare tests: set up the container (deployment) and start it
            up
          </li>
          <li>execute tests using the JUnit plugin</li>
          <li>
            tear down tests: stop the container and clean the deployment.
          </li>
        </ul>
        <p>
          The plugin uses Ant scripts from the Ant integration subproject for
          container management.
        </p>

      </section>
      <section title="How it works">

        <section title="Extension points">
          <ul>
            <li>
              <em>
                org.eclipse.debug.core.launchConfigurationTypes
              </em>
              registers cactusLaunchConfiguration
            </li>
            <li>
              <em>
                org.eclipse.debug.ui.launchShortcuts
              </em>
              registers a shortcut which appears in the run and debug
              cascade menus to launch the current workbench selection in the
              Java perspective
            </li>
            <li>
              <em>
                org.eclipse.ui.preferencePages
              </em>
              adds the Cactus preference page to the preferences.
            </li>
          </ul>
        </section>
        <section title="GUI: preference page">
          <p>
            A preference page is contributed to the Eclipse preferences. It
            shows the following entries:
          </p>
          <ul>
            <li>Cactus properties (contextURL)</li>
            <li>
              directory of all the jars needed for Cactus tests (client
              side and server side)
            </li>
            <li>setting of the container homes</li>
          </ul>
        </section>

        <section title="IContainerProvider">
          <p>
            To enable different ways to setup, start, and stop containers the
            idea of container providers has been introduced in the plugin.
          </p>
          <p>
            A container provider is responsible for deploying a web application
            to the container, starting and stopping it, and undeploying the web
            app. This concept is concretized in the interface
            <code>IContainerProvider</code>
            . See its javadoc for more information.
          </p>
          <p>
            A container manager is implemented in the current version of the
            plugin, which uses Ant scripts to carry out these actions. It is
            called
            <code>AntContainerManager</code>
            and may be used to execute tests on all the containers supported
            by the Ant integration subproject.
          </p>
        </section>
        <section title="What happens when a test is launched">
          <p>
            The
            <code>launch(IType theType, String theMode)</code>
            method of the
            <code>CactusLaunchShortcut</code>
            class is called, which sets up the container, launches the
            tests by delegating these to the JUnit plugin, and then tears down
            the container setup.
          </p>
          <ul>
            <li>
              Tests preparation
              <p>This includes:</p>
              <ul>
                <li>
                  creating the war file for the cactus tests: this is
                  done in a call to the 
                  <link href="site:integration_eclipse_webapp">Webapp 
                  plug-in</link> <code>WarBuilder</code> class.
                </li>
                <li>
                  setting up the container: prepares the configuration
                  for the selected container
                </li>
                <li>
                  starting the container.
                </li>
              </ul>
              <p>
                In the case of
                <code>
                  AntContainerProvider
                </code>
                :
              </p>
              <ul>
                <li>
                  setting up is done by an Ant script
                </li>
                <li>
                  starting the container is delegated to the
                  <code>
                    StartServerHelper
                  </code>
                  class, which initiates a thread starting the container
                  and then pings it constantly to see if it has effectively
                  been launched.
                </li>
              </ul>
            </li>
            <li>
              Tests launch
              <p>
                This behaviour is inherited from the JUnit plugin since
                <code>
                  CactusLaunchShortcut
                </code>
                extends
                <code>
                  JUnitLaunchShortcut
                </code>
                .
              </p>
            </li>
            <li>
              Tests end
              <p>
                To know when tests have ended we register our TestListener to
                the JUnit plugin. To this end the JUnit plugin needed a
                modification which has been integrated in the 2.1 release of
                the Eclipse platform.
              </p>
            </li>

            <li>
              Test environment cleaning
              <p>
                After the tests have completed we stop the container, and
                delete the configuration and war files created beforehand.
              </p>
            </li>
          </ul>
        </section>
      </section>
      <section title="Contributing">
        <p>
          Read the <a href="site:integration_eclipse_dev">Eclipse 
          development evironment setup</a> tutorial.
        </p>
      </section>
    </section>

  </body>
</document>