cvs commit: jakarta-cactus/documentation/docs/xdocs/integration/eclipse eclipse.xml runner_plugin.xml

[jr...@apache.org]

jruaux      2003/03/27 09:53:45

  Added:       documentation/docs/xdocs/integration/eclipse eclipse.xml
                        runner_plugin.xml
  Log:
  Added a page for both plug-ins
  
  Revision  Changes    Path
  1.1                  jakarta-cactus/documentation/docs/xdocs/integration/eclipse/eclipse.xml
  
  Index: eclipse.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document id="eclipse">
  
    <properties>
      <title>Cactus integration in Eclipse</title>
      <authors>
        <author name="Julien Ruaux" email="jruaux@octo.com" />
      </authors>
    </properties>
  
    <body>
      <section title="Overview">
        <p>
          The integration of Cactus in the 
          <link href="ext:eclipse">Eclipse</link> platform relies on 2 separate plug-ins :
        </p>
        <li>
          The <link href="site:runner_plugin">Cactus runner plug-in</link>
        </li>
        <li>
          The <link href="site:webapp_plugin">Webapp Eclipse plug-in</link>
        </li>
      </section>
  
      <anchor id="features" />
      <section title="Features at a glance">
        <ul>
          <li>
            Shortcut for launching Cactus tests
            <figure src="images/eclipse/runner/launchshortcut.png"
              alt="Cactus launch shortcut"/>
          </li>
        </ul>
        <ul>
          <li>
            Project property page for setting up the web application.
            <figure src="images/eclipse/webapp/propertypage.png"
              alt="Webapp property page"/>
          </li>
        </ul>    
      </section>
  
      <anchor id="installation"/>
      <section title="Installation">
        <section title="Requirements">
          <p>
            A version of the Eclipse platform later than 2.1 RC2 is needed.
          </p>
        </section>
        <section title="Installation">
          <p>
            Connect to the Cactus update site (available soon) from Eclipse
            to install both plug-ins at once as an <code>Eclipse feature</code>.
          </p>
        </section>
        <section title="Configuration">
          <p>
            The plug-ins are functional 'off the shelf'.
            Refer to the corresponding plug-in section for specific configuration.
          </p>
        </section>
      </section>
  
    </body>
  </document>
  
  
  1.1                  jakarta-cactus/documentation/docs/xdocs/integration/eclipse/runner_plugin.xml
  
  Index: runner_plugin.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document id="runner_plugin">
  
    <properties>
      <title>Eclipse plug-in for Cactus</title>
      <authors>
        <author name="Julien Ruaux" email="jruaux@octo.com" />
      </authors>
    </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:webapp_plugin">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>
      </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 RC2.
          </p>
        </section>
        <section title="Installation">
          <p>
            Uncompress the zip file and copy the
            'org.apache.cactus.integration.eclipse_[version]' folder to your
            Eclipse 'plugins' 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>
          While the Cactify action is not implemented you have to do the
          following :
          <ul>
            <li>
              add Cactus client and common libraries to your Java project
            </li>
            <li>
              your Java project must have the following directory structure :
              [project's root]/web/WEB-INF/lib (create these as 'folders')
            </li>
          </ul>
          Select any Cactus test class file and select from the toolbar :
          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 remain to
          be done.
        </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. In the same way 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 provider is implemented in the current version of the
              plugin, which uses Ant scripts to carry out these actions. It is
              called
              <code>GenericAntProvider</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:webapp_plugin">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>
                    GenericAntProvider
                  </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 DEV-README.txt file for indications on how to set up your
            Eclipse environment.
          </p>
        </section>
      </section>
  
    </body>
  </document>
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: cactus-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: cactus-dev-help@jakarta.apache.org