You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cactus-dev@jakarta.apache.org by vm...@apache.org on 2003/01/28 16:48:20 UTC
cvs commit: jakarta-cactus/documentation/docs/xdocs/participating logos.xml
vmassol 2003/01/28 07:48:19
Modified: documentation/docs/xdocs/writing howto_testcase_jsp.xml
documentation/docs/xdocs javadoc_13.xml sitemap.xml
javadoc.xml javadoc_12.xml
documentation/docs/xdocs/participating logos.xml
Added: documentation/docs/xdocs/petals/ant howto_ant_cactus.xml
howto_ant_install.xml howto_ant.xml
howto_ant_primer.xml navigation.xml
documentation/docs/xdocs/petals/manual
howto_ide_vajava_wte.xml howto_ide_jbuilder5.xml
howto_ide_vajava_tomcat.xml navigation.xml
howto_classpath.xml howto_config.xml
howto_ide_jbuilder4.xml howto_ide.xml
documentation/docs/xdocs/petals navigation.xml
howto_runner.xml
documentation/docs/xdocs/petals/browser howto_tomcat.xml
howto_junitee.xml navigation.xml
documentation/docs/xdocs/petals/eclipse navigation.xml
eclipse_plugin.xml
Removed: documentation/docs/xdocs/spines/ant howto_ant_install.xml
howto_ant_cactus.xml howto_ant_primer.xml
navigation.xml howto_ant.xml
documentation/docs/xdocs/spines/manual
howto_ide_vajava_tomcat.xml
howto_ide_vajava_wte.xml howto_config.xml
howto_classpath.xml howto_ide.xml navigation.xml
howto_ide_jbuilder5.xml howto_ide_jbuilder4.xml
documentation/docs/xdocs/spines/browser howto_junitee.xml
howto_tomcat.xml navigation.xml
documentation/docs/xdocs/spines/eclipse eclipse_plugin.xml
navigation.xml
documentation/docs/xdocs/spines navigation.xml
howto_runner.xml
Log:
- Renamed "spines" into "petals"
- Fixed remaining site ids for <link> elements
Revision Changes Path
1.1 jakarta-cactus/documentation/docs/xdocs/petals/ant/howto_ant_cactus.xml
Index: howto_ant_cactus.xml
===================================================================
<?xml version="1.0"?>
<document id="howto_ant_cactus">
<properties>
<title>Running Cactus tests from Ant</title>
<authors>
<author name="Vincent Massol" email="vmassol@apache.org"/>
</authors>
</properties>
<body>
<section title="Introduction">
<note>
<strong>You need to have a good understanding of Ant before
reading this tutorial. If you don't, I suggest you read the
<link href="http://jakarta.apache.org/ant/manual/index.html">Ant
User Manual</link> first</strong>.
</note>
<p>
This tutorial explains how start Cactus tests from your Ant build
script (i.e. <code>build.xml</code>).
</p>
<p>
The Ant tasks involved for running a Cactus test are the following:
</p>
<ul>
<li>
<em>Step 0</em>: (optional) Deploy configuration files for your
container,
</li>
<li>
<em>Step 1</em>: Package your Cactus tests as a WAR file and
deploy it to your servlet engine webapps directory,
</li>
<li>
<em>Step 2</em>: Start your servlet engine if it is not already
started,
</li>
<li>
<em>Step 3</em>: Run the tests using JUnit,
</li>
<li>
<em>Step 4</em>: Stop the servlet engine (if need be)
</li>
</ul>
<p>
Cactus provides a custom Ant task (called the
<code>runservertests</code> task) that helps perform all these tasks.
The rest of this tutorial will explain how to write an Ant build
file (<code>build.xml</code>) that performs these tasks and use
the Cactus custom Ant task.
</p>
<p>
During the remainder of this tutorial we will show examples for
Tomcat 4.0. However, the principle can be applied to any other
container. Ant Scripts for other containers can be found in the
<code>/sample/build</code> directory where you have unpacked the
Cactus distribution.
</p>
</section>
<section title="The 'runservertests' task">
<p>
This task will perform several actions, in the following order:
</p>
<ul>
<li>
Check if a server is already started by constantly trying to
call the test URL defined by the <code>testURL</code>
attribute (see the example below),
</li>
<li>
If a server is not started, call the Ant target defined by the
<code>startTarget</code> attribute (see the example below). This
target is
supposed to start your container. The <code>runservertests</code>
task will then constantly poll the server by calling the test URL
until the server answers back,
</li>
<li>
It will then call the Ant target defined by the
<code>testTarget</code> attribute (see the example below). This
target is
supposed to start the unit tests. This is usually implemented
by using the Ant <code>junit</code> task,
</li>
<li>
Once the tests are finished (i.e. when the
<code>testTarget</code> has finished executing), it will then
call the Ant target defined by the <code>stopTarget</code>
attribute (see the example below). This target is supposed to stop
the container. The <code>runservertests</code>
task will then constantly poll the server by calling the test URL
until the server stops answering, at which point it will consider
the server to be stopped. Note that the <code>stopTarget</code>
will only get called if the server was not already started when
the <code>runservertests</code> task began executing. This is to
allow keeping running servers for intensive debugging phases.
</li>
</ul>
<p>
The <code>runservertests</code> task is generic in the sense that
you are free to implement the <code>startTarget</code>,
<code>testTarget</code> and <code>stopTarget</code> as you wish and
they will get called at the right time.
</p>
<p>
Example:
</p>
<source><![CDATA[
<!--
========================================================================
Run Tomcat 4.0 tests
========================================================================
-->
<target name="test.tomcat.40" depends="prepare.test.tomcat.40"
if="tomcat.home.40" description="Run tests on Tomcat 4.0">
<!-- Start the servlet engine, wait for it to be started, run the
unit tests, stop the servlet engine, wait for it to be stopped.
The servlet engine is stopped if the tests fail for any reason -->
<runservertests
testURL="http://localhost:${test.port}/test/ServletRedirector?Cactus_Service=RUN_TEST"
startTarget="start.tomcat.40"
stopTarget="stop.tomcat.40"
testTarget="test"/>
</target>
]]></source>
<p>
Before you can execute the <code>runservertests</code> task, you
need to define it for Ant as it is not a standard Ant task. A
good place to do this is in an <code>init</code> target.
</p>
<p>
Example:
</p>
<source><![CDATA[
<!--
======================================================================
Initialize the build. Must be called by all targets
======================================================================
-->
<target name="init">
[...]
<taskdef name="runservertests" classname="org.apache.cactus.ant.RunServerTestsTask">
<classpath>
<pathelement location="${cactus.ant.jar}"/>
</classpath>
</taskdef>
[...]
</target>
]]></source>
<p>
where <code>${cactus.ant.jar}</code> is an Ant property that points
to the <code>cactus-ant.jar</code> file found in the
<code>lib/</code> directory where you unpacked the Cactus
distribution.
</p>
<note>
The <code>prepare.test.tomcat.40</code> target is described in
Step 0 below.
</note>
<note>
The <code>tomcat.home.40</code> is simply an Ant property that
points to the directory where Tomcat 4.0 has been installed. If this
property is not defined we don't run the tests.
</note>
</section>
<section title="Step 0: Deploy container configuration files">
<p>
There are 2 possibilities for configuring your application server:
</p>
<ol>
<li>
You install it somewhere on your computer (or on another machine)
and you deploy your test WAR (see Step 1 below) by copying it
to the right subdirectory within it. Your WAR will then be placed
alongside with others and your webapp will use the configuration
files common to all webapps,
</li>
<li>
Or, you can create your own set of container configuration files,
hosted within your project, that you copy to your own deployment
subdirectory (i.e. not shared).
</li>
</ol>
<p>
In the provided Cactus Ant scripts, we have decided to follow
approach 2 for the following reasons:
</p>
<ul>
<li>
We keep the control of our project files as they are deployed
within the directory of our project and thus it is easy to
perform a clean of all generated files,
</li>
<li>
We do not "pollute" the installed container by dropping files
within it and we do not need to modify global configuration
files that may prevent other applications we are developing
from not running someday (because we would have made an
incompatible change),
</li>
<li>
We completely control our needed container configuration.
</li>
<li>
We can guarantee to the user who wants to try the Cactus sample
application that it will not deploy anything outside the scope of
the Sample directory. Unlike windows applications that you install
and that copies tens of DLL to shared directory, overwrite existing
files, ... :(
</li>
</ul>
<p>
However, this may not be the best approach for all cases, as:
</p>
<ul>
<li>
It is more difficult to set up as you need to understand how your
container is configured (However, we have already done the job for
you for most of the existing containers),
</li>
<li>
You have only a single application to run and test and have
dedicated your application server installation for it so you don't
care about putting files in there and modifying global
configuration,
</li>
<li>
You want to be able to deploy in production several webapps that
share the same server and thus must coexist and share common
configuration files.
</li>
</ul>
<p>
If you choose solution 1, then you can simply skip this step. The
only actions to perform will be, for some containers, to edit their
configuration files to tell them about your webapp (some will
automatically pick you test WAR if you drop it in the correct
directory).
</p>
<p>
Example:
</p>
<source><![CDATA[
<!--
========================================================================
Prepare directories and variables for running the tests
========================================================================
-->
<target name="prepare.test.tomcat.40"
depends="check.test.tomcat.40,testwar" if="tomcat.home.40">
<echo message="tomcat.home.40 = ${tomcat.home.40}"/>
<property name="target.tomcat40.dir"
value="${target.test.dir}/tomcat40"/>
<property name="conf.tomcat40.dir" value="${conf.test.dir}/tomcat40"/>
<!-- Create work and conf directories and copy configuration files -->
<mkdir dir="${target.tomcat40.dir}/conf"/>
<mkdir dir="${target.tomcat40.dir}/work"/>
<mkdir dir="${target.tomcat40.dir}/webapps"/>
<!-- Delete some config file so that they will be copied every time -->
<delete file="${target.tomcat40.dir}/conf/server.xml"/>
<!-- Remove the auto deployed webapp so that it is redeployed every
time -->
<delete dir="${target.tomcat40.dir}/webapps/test"/>
<copy todir="${target.tomcat40.dir}/conf" filtering="on">
<fileset dir="${conf.tomcat40.dir}"/>
</copy>
<!-- Copy the Tomcat web.xml -->
<copy file="${tomcat.home.40}/conf/web.xml"
todir="${target.tomcat40.dir}/conf"/>
<!-- Copy the war file -->
<copy file="${target.test.dir}/test.war"
tofile="${target.tomcat40.dir}/webapps/test.war"/>
</target>
]]></source>
<note>
The <code>${target.test.dir}</code> Ant property needs to be
defined prior to calling this target and needs to be set to the
location where the tests will be deployed. It should be set to any
subdirectory of your output directory. This property will also be
used later on in step 1 to copy the test WAR file.
</note>
<note>
The <code>${conf.test.dir}</code> Ant property also needs to be
defined prior to calling this target and represent the location of
server configuration files (in the current example of Tomcat 4.0,
these are the global <code>web.xml</code> and
<code>server.xml</code>).
</note>
</section>
<section title="Step 1: create and deploy test WAR file">
<p>
Creating a WAR file is the preferred way of deploying Cactus tests
to your servlet engine. Check the
<link href="site:getting_started">Getting Started</link> guide and
the example below for details on what files to include in the WAR.
</p>
<p>
Example:
</p>
<source><![CDATA[
<!--
========================================================================
Create a Cactus test war file for the sample application.
========================================================================
-->
<target name="testwar" depends="compile">
<!-- Create the war file -->
<war warfile="${target.test.dir}/test.war"
webxml="${conf.test.dir}/web.xml">
<classes dir="${target.classes.sample.dir}"/>
<classes dir="${target.classes.unit.dir}"/>
<!-- log_server.properties need to be in the server classpath -->
<classes dir="${conf.test.dir}">
<include name="log_server.properties"/>
<include name="cactus.properties"/>
</classes>
<lib dir="${target.lib.dir}"/>
<fileset dir="${web.dir}"/>
</war>
</target>
]]></source>
<p>
where:
</p>
<ul>
<li>
<code>${conf.test.dir}</code>: directory containing configuration
files for the test,
</li>
<li>
<code>${target.classes.*.dir}</code>: directory where the java
classes have been compiled. These are the classes under test + the
test classes,
</li>
<li>
<code>${target.lib.dir}</code>: directory containing the needed jars
(<code>junit.jar</code>, <code>cactus.jar</code>, ...).
</li>
<li>
<code>${web.dir}</code>: directory containing the web files to
include in the test webapp (JSPs, HTML, ...).
</li>
</ul>
<note>
The <code>compile</code> target is used to compile all java classes
into the <code>${target.classes.*.dir}</code> directory.
</note>
</section>
<section title="Step 2: Start the container">
<p>
Example:
</p>
<source><![CDATA[
<!--
========================================================================
Start Tomcat 4.0
========================================================================
-->
<target name="start.tomcat.40">
<java classname="org.apache.catalina.startup.Bootstrap" fork="yes">
<jvmarg value="-Dcatalina.home=${tomcat.home.40}"/>
<jvmarg value="-Dcatalina.base=${target.tomcat40.dir}"/>
<arg value="start"/>
<classpath>
<pathelement path="${java.home}/../lib/tools.jar"/>
<fileset dir="${tomcat.home.40}">
<include name="bin/bootstrap.jar"/>
</fileset>
</classpath>
</java>
</target>
]]></source>
</section>
<section title="Step 3: Run the unit tests">
<p>
We start the unit test by calling a JUnit test runner (we use the
text runner in this example). Example:
</p>
<source><![CDATA[
<!--
========================================================================
Run the client JUnit test cases.
========================================================================
-->
<target name="test">
<junit printsummary="yes" haltonfailure="yes" haltonerror="yes"
fork="yes">
<classpath>
<!-- Cactus.propertie and log_client.properties need to be in
the classpath -->
<pathelement location="${target.conf.dir}"/>
<pathelement location="${target.classes.sample.dir}"/>
<pathelement location="${target.classes.unit.dir}"/>
<path refid="project.class.path"/>
</classpath>
<formatter type="plain" usefile="false"/>
<test name="org.apache.cactus.unit.TestAll"/>
<test name="org.apache.cactus.sample.TestAll"/>
</junit>
</target>
]]></source>
<note>
The list of jars to include in your classpath is explained and
detailed in the <link href="site:howto_classpath">Classpath
Howto</link> guide.
</note>
</section>
<section title="Step 4: Stop the container">
<p>
Example:
</p>
<source><![CDATA[
<!--
========================================================================
Stop Tomcat 4.0
========================================================================
-->
<target name="stop.tomcat.40">
<java classname="org.apache.catalina.startup.Bootstrap" fork="yes">
<jvmarg value="-Dcatalina.home=${tomcat.home.40}"/>
<jvmarg value="-Dcatalina.base=${target.tomcat40.dir}"/>
<arg value="stop"/>
<classpath>
<fileset dir="${tomcat.home.40}">
<include name="bin/bootstrap.jar"/>
</fileset>
</classpath>
</java>
</target>
]]></source>
</section>
</body>
</document>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/ant/howto_ant_install.xml
Index: howto_ant_install.xml
===================================================================
<?xml version="1.0"?>
<document id="howto_ant_install">
<properties>
<title>Installing Ant</title>
<authors>
<author name="Vincent Massol" email="vmassol@apache.org"/>
</authors>
</properties>
<body>
<section title="Forewords">
<note>
<strong>You need to have a good understanding of Ant before
reading this tutorial. If you don't, I suggest you read the
<link href="http://jakarta.apache.org/ant/manual/index.html">Ant
User Manual</link> first</strong>.
</note>
<p>
This tutorial explains how to install Ant properly to be able to
run the Sample application provided with the Cactus distribution and
also build the Cactus distribution from the sources.
</p>
</section>
<section title="Ant tasks needed by Cactus">
<p>
Cactus uses the following optional tasks of Ant:
</p>
<ul>
<li>
The <strong><code>junit</code></strong> task: it is used to run
the unit tests of Cactus itself and the Cactus unit tests of the
Sample application. This task is
normally found in the <code>optional.jar</code> Ant jar.
</li>
<li>
The Cactus Sample application uses some Ant custom tasks provided
by Cactus in the <code>cactus-ant.jar</code> jar file (
found in the <code>lib/</code> directory where you unpacked the
Cactus distribution).
</li>
<li>
The <strong><code>checkstyle</code></strong> task: it is used only
to buidl Cactus from the sources (i.e. not needed for building the
Cactus sample application). The version of
<link href="http://checkstyle.sf.net">Checkstyle</link> used is 2.2+.
</li>
</ul>
<p>
In order to simplify the installation of Ant and the gathering of
the required Ant tasks as described above, we provide a
prepackaged zip containing everything needed. This is available from
the <link href="site:downloads">downloads</link> section.
</p>
</section>
<section title="Installing Ant on Windows systems">
<p>
Follow the steps below to install Ant:
</p>
<ol>
<li>
Download Jakarta Ant
(<code>jakarta-ant-<version>-bin.zip</code>) from
<link href="http://jakarta.apache.org/ant/index.html">here</link>. I
recommend version 1.4.1 or above. Alternatively you can download the
prepackaged Ant version, as mentioned above.
</li>
<li>
Unzip it in a directory. Let's call this directory
<code>antroot</code>,
</li>
<li>
Create an environment variable named <code>ANT_HOME</code> that
points to the <code>antroot</code> directory,
</li>
<li>
Modify the <code>PATH</code> environment variable to include the
<code>%ANT_HOME%\bin</code> directory (so that you'll be able to type
<code>ant</code> in a DOS shell, in whatever directory and it will
call the <code>%ANT_HOME%\bin\ant.bat</code> script,
</li>
<li>
Download the Ant optional task jar
(<code>jakarta-ant-<version>-optional.jar</code>) from
<link href="http://jakarta.apache.org/ant/index.html">here</link>
and put it in <code>%ANT_HOME%\lib</code>. <em>Note that this step
is needed only if you haven't downloaded the prepackaged zip</em>,
</li>
<li>
If you haven't downloaded the prepackaged Ant zip, you'll need to
download the Stylebook 1.0b3 for Xalan 2 jar, the latest
<link href="http://xml.apache.org/xalan-j/">Xalan</link>, the latest
<link href="http://xml.apache.org/xerces-j">Xerces</link>, the
latest <link href="ext:junit">JUnit</link> and the latest
<link href="ext:checkstyle">Checkstyle</link> jars. You'll
also need to ensure that you use a JAXP 1.1 parser. You can download
one (crimson) from
<link href="http://java.sun.com/xml/download.html">here</link>. Put
all these jars in <code>%ANT_HOME%\lib</code>.
</li>
</ol>
</section>
</body>
</document>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/ant/howto_ant.xml
Index: howto_ant.xml
===================================================================
<?xml version="1.0"?>
<document id="howto_ant">
<properties>
<title>Ant Howto</title>
<authors>
<author name="Vincent Massol" email="vmassol@apache.org"/>
</authors>
</properties>
<body>
<section title="Ant integration">
<p>
This tutorial has several trails:
</p>
<ul>
<li>
<link href="site:howto_ant_cactus">Using Cactus with Ant</link>:
Explain how to integrate Cactus tests in your own Ant build process,
</li>
<li>
<link href="site:howto_ant_install">Ant installation</link>:
Explains how to install Ant to run the samples provided in the Cactus
distribution or to build Cactus from the sources,
</li>
<li>
<link href="site:howto_ant_primer">Ant Primer</link>:
Provides an Ant primer that explains how to best organize a project
around an Ant build process (directory structure, Ant targets, ...).
At the same time it described the principles that have been followed
for Cactus's own build process (it is no longer in sync with current
Cactus build).
</li>
</ul>
</section>
</body>
</document>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/ant/howto_ant_primer.xml
Index: howto_ant_primer.xml
===================================================================
<?xml version="1.0"?>
<document id="howto_ant_primer">
<properties>
<title>Ant Integration</title>
<authors>
<author name="Vincent Massol" email="vmassol@apache.org"/>
</authors>
</properties>
<body>
<section title="Continuous integration">
<note>
<strong>This tutorial was written when I wrote Cactus 1.2. Since then
I have improved my command of Ant. However this tutorial has not yet
been updated. I believe it still provides some very good
methodology on how to use Ant, although not the latest. If you wish to
keep track of the latest change, have a look at the Cactus build files,
found in the source distribution.</strong>
</note>
<p>
A strong principle of eXtreme Programming (XP) is the continuous
integration aspect (see the
<link href="http://www.martinfowler.com/articles/continuousIntegration.html">
Continuous Integration</link> article by Martin Fowler). The traditional
approach has been
to developing the code first, then test it and then integrate
it with other appications. The continuous integration principle is to
develop code, tests and integrate at the same time, i.e. at any point
in time, you have a functioning code along with tests and integrated.
</p>
<p>
In order to be able to do continuous integration, you need to be able
to automatically run the build for your application, including passing
the unit tests (based on JUnit, Cactus, HttpUnit or others). Ant is
the perfect tool for this task.
</p>
</section>
<section title="Ant benefits">
<p>
The benefits of using Ant for running unit tests are as follows:
</p>
<table>
<tr>
<th>
Benefits
</th>
</tr>
<tr>
<td>
Ant is written in Java and thus the same scripts can be used on
several systems (Windows and Unix for example). Is is therefore very
well suited for building java applications.
</td>
</tr>
<tr>
<td>
Ant provides enough built-in and optional tasks to be able to
achieve almost any needed build task without needing to use
system dependent scripts.
</td>
</tr>
<tr>
<td>
By being able to very quickly rerun unit test you can verify that
your tests still pass when you modify some part of your code (
regression testing)
</td>
</tr>
<tr>
<td>
As it is automated, it fits well in the continuous integration
principle and your tests can thus be ran automatically and
continously
</td>
</tr>
</table>
</section>
<section title="Writing an Ant build script tutorial">
<p>
The sample Ant build file described below is taken from the
<link href="site:downloads">Cactus Sample for Servlet API 2.2
</link> project.
</p>
<note>
This section is both a tutorial for automating builds and unit testing
with Ant and Cactus and also a best practice and methodology guide
for using Ant in general (independent of Cactus). This is an Ant
configuration that has been working for me on several project. Of course,
you are free to adapt/modify it to suit your needs.
</note>
<section title="Project directory structure">
<p>
Create the following directories:
</p>
<table>
<tr>
<th>
Directory name
</th>
<th>
Content of the directory
</th>
</tr>
<tr>
<td>
<code>build</code>
</td>
<td>
The Ant build file and some other ancillary files (properties file, ...)
</td>
</tr>
<tr>
<td>
<code>conf</code>
</td>
<td>
Configuration files for the project. These are the configuration
files that will <em>not</em> be put into the runtime jar. They
are configuration file that need to be visible and modifyable
by a user of the project. If they were bundled in the jar they
would be hard to modify. On the other hand, we don't want a
proliferation of configuration files, so all <em>technical</em>
configuration files (messages to display for errors, ...)
should be put in the <code>src</code> directory in correct java
packages.
</td>
</tr>
<tr>
<td>
<code>conf/test</code>
</td>
<td>
Configuration files needed for testing the project only.
</td>
</tr>
<tr>
<td>
<code>docs</code>
</td>
<td>
Project documentation.
</td>
</tr>
<tr>
<td>
<code>docs/skins</code>
</td>
<td>
Documentation skin for Stylebook (if using Stylebook).
</td>
</tr>
<tr>
<td>
<code>docs/xdocs</code>
</td>
<td>
Documentation files (XML files) for Stylebook (if using Stylebook).
</td>
</tr>
<tr>
<td>
<code>src</code>
</td>
<td>
The project sources: java files + java test files +
properties files + test properties files + other files for
runtime or test (XML files, ...). Note that all test files
should begin by 'Test' or 'test' in order to easily separate them
from other files so that in an Ant target we'll be able to include
only the runtime files.
</td>
</tr>
<tr>
<td>
<code>web</code>
</td>
<td>
The project web files: HTML, JSP, ... (if any)
</td>
</tr>
</table>
<note>
An <code>out</code> directory will be created by the Ant build. All
build-generated files will be put in that directory (compiled classes,
generated javadoc documentation, test configuration files for running
an application server, ...).
</note>
<note>
We don't have any <code>lib</code> directory because it is always
better not to include dependent jars in your project whenever
possible for the following reasons: better continuous integration
with other libraries (meaning they also evolve and you should test
as much as possible with the latest version to discover potential
problems early, more lightweight downloads, less jar proliferation
(you'll end up with tens of the same jars otherwise), more version
control and integration checks (if your project uses 2 external
libraries that need another third library but not in the same version
you are in trouble !), ...
</note>
</section>
<section title="Ant Target List">
<p>
Define the following targets in your <code>build.xml</code>.
</p>
<note>
The <em>Type</em> column specify whether the target is an external
target that can be called by the user of the build file or if it is
an internal target, intended to be called internally by another
target inside the build script.
</note>
<table>
<tr>
<th>
Target name
</th>
<th>
Description
</th>
<th>
Type
</th>
</tr>
<tr>
<td>
<jump anchor="init"><code>init</code></jump>
</td>
<td>
Defines token filters, timestamp, display some information on
screen, ...
</td>
<td>
Internal
</td>
</tr>
<tr>
<td>
<jump anchor="usage"><code>usage</code></jump>
</td>
<td>
Display usage information about the targets.
</td>
<td>
External
</td>
</tr>
<tr>
<td>
<jump anchor="prepare"><code>prepare</code></jump>
</td>
<td>
Set up the output directory where build generated files will be
put and copy the java sources to this output directory,
replacing tokens with the values defined in the <code>init</code>
target.
</td>
<td>
Internal
</td>
</tr>
<tr>
<td>
<jump anchor="compile"><code>compile</code></jump>
</td>
<td>
Compile the java sources and put the result in the output
directory. All copies non java source files such as
<code>.properties</code> files, XML configuration files, ...
</td>
<td>
Internal
</td>
</tr>
<tr>
<td>
<jump anchor="source"><code>source</code></jump>
</td>
<td>
Generate a zipped file containing the full sources of the project
(i.e. the whole directory structure, excluding any build
generated files).
</td>
<td>
External
</td>
</tr>
<tr>
<td>
<jump anchor="javadoc"><code>javadoc</code></jump>
</td>
<td>
Generates the javadoc of the project. This javadoc will be part
of the project documentation, as generated by the <code>doc</code>
target.
</td>
<td>
Internal
</td>
</tr>
<tr>
<td>
<jump anchor="doc"><code>doc</code></jump>
</td>
<td>
Generates the full project documentation: javadoc + README files
+ documentation web site (using Stylebook for example).
</td>
<td>
External
</td>
</tr>
<tr>
<td>
<jump anchor="clean"><code>clean</code></jump>
</td>
<td>
Remove any build generated files. In particular, delete the
output directory.
</td>
<td>
External
</td>
</tr>
<tr>
<td>
<jump anchor="jar"><code>jar</code></jump>,
<jump anchor="war"><code>war</code></jump>,
<code>ear</code>, ...
</td>
<td>
Generate the project runtime. If the project is a framework, it
is usually a jar. If the project is a web application, it is
usually a war file. If the project is an EJB application, it is
usually either one or several jars or an ear file. Etc ...
</td>
<td>
External
</td>
</tr>
<tr>
<td>
<jump anchor="tests"><code>tests_XXX</code></jump> where XXX is
the name of the servlet engine on which the tests run.
</td>
<td>
Run the Cactus unit tests.
</td>
<td>
External
</td>
</tr>
</table>
</section>
<anchor id="basedir"/>
<section title="Step 1: The Ant project basedir">
<p>
You <code>build.xml</code> file being in located in
<code>build/</code> you should set the <code>project</code> tag
<code>basedir</code>
attribute to '<code>..</code>' so that all other paths are relative
to your project root directory. Indeed, the batch file (shell script)
that was used to bootstrap Ant is located in
<code><root>/build</code>, so '<code>..</code>' is the root
directory.
</p>
<p>
Example:
</p>
<source><![CDATA[
<?xml version="1.0"?>
[...]
<project name="Cactus Sample" default="war" basedir="..">
]]></source>
</section>
<section title="Step 2: initialization of project properties">
<p>
You should define as properties all values that can be factorized
and which are used often in your build file such as source locations,
output locations, external jar locations and names, ... You can also
define useful file patterns there (see the sample below).
</p>
<p>
A good principle is to defined any properties that depend on your
environment (such as external jar locations) in a file (let's call
it <code>build.properties</code> located either where
<code>build.xml</code> is located or in your home directory. The
properties defined in this file will be loaded by
<code>build.xml</code> using the following code:
</p>
<source><![CDATA[
<!-- Give user a chance to override without editing this file
(and without typing -D each time it compiles it) -->
<property file="build/build.properties" />
<property file="${user.home}/build.properties" />
]]></source>
<p>
Here are our properties initializations:
</p>
<source><![CDATA[
<project name="Cactus Sample" default="war" basedir="..">
<!-- Give user a chance to override without editing this file
(and without typing -D each time it compiles it) -->
<property file="build/build.properties" />
<property file="${user.home}/build.properties" />
<!-- Generic project properties -->
<property name="project.fullname" value="Cactus Sample"/>
<property name="project.version" value="@version@"/>
<property name="project.name" value="cactus-sample"/>
<!-- Miscellaneous settings -->
<property name="year" value="@year@"/>
<property name="debug" value="on"/>
<property name="optimize" value="off"/>
<property name="deprecation" value="off"/>
<!--
========================================================================
Set the properties related to the source tree
========================================================================
-->
<!-- Source locations for the build -->
<property name="src.dir" value="src"/>
<property name="src.java.dir" value="${src.dir}/share"/>
<property name="src.java.servlet.dir" value="${src.dir}/servlet@servlet.api@"/>
<property name="build.dir" value="build"/>
<property name="etc.dir" value="${build.dir}/etc"/>
<property name="lib.dir" value="lib"/>
<property name="conf.dir" value="conf"/>
<property name="conf.test.dir" value="conf/test"/>
<property name="web.dir" value="web"/>
<!--
========================================================================
Set the properties related to the build area
========================================================================
-->
<!-- Destination locations for the build (relative to the basedir as -->
<!-- specified in the basedir attribute of the project tag) -->
<property name="out.dir" value="out"/>
<property name="out.dist.dir" value="${out.dir}/dist"/>
<property name="out.lib.dir" value="${out.dir}/lib"/>
<property name="out.test.dir" value="${out.dir}/test"/>
<property name="out.src.dir" value="${out.dir}/src"/>
<property name="out.classes.dir" value="${out.dir}/classes"/>
<property name="out.doc.dir" value="${out.dir}/doc"/>
<property name="out.javadoc.dir" value="${out.doc.dir}/javadoc"/>
<property name="out.conf.dir" value="${out.dir}/conf"/>
<!-- Names of deliverables -->
<!-- The Cactus Sample war file. This is the file that should be
used at runtime by end users (it excludes the test classes) -->
<property name="final.war.name" value="${out.dir}/${project.name}-@servlet.api@.war"/>
<!-- The full sources of Cactus Sample in a zip file -->
<property name="final.src.name" value="${out.dir}/${project.name}-src-@servlet.api@.zip"/>
<!-- The Cactus sample documentation in a zip file -->
<property name="final.doc.name" value="${out.dir}/${project.name}-doc-@servlet.api@.zip"/>
<!--
========================================================================
Useful file patterns for targets
========================================================================
-->
<!-- All source files of the projet. These source files will be copied
to the destination source directory in the prepare task -->
<patternset id="all.src.files">
<!-- All java files -->
<include name="**/*.java"/>
<!-- All doc files -->
<include name="**/package.html"/>
<include name="**/overview.html"/>
<!-- All conf files (including test files) -->
<include name="**/*.txt"/>
<include name="**/*.xml"/>
<include name="**/*.properties"/>
</patternset>
<!-- All non java files in the src directory -->
<patternset id="all.nonjava.files">
<!-- All conf files (including test files) -->
<include name="**/*.txt"/>
<include name="**/*.xml"/>
<include name="**/*.properties"/>
</patternset>
]]></source>
</section>
<anchor id="init"/>
<section title="Step 3: 'init' target">
<p>
Useful for initializing a timestamp (DSTAMP, TODAY, TSTAMP), defining
token filters, printing some information messages, registering
custom Ant tasks, ...
</p>
<source><![CDATA[
<!--
========================================================================
Initialize the build. Must be called by all targets
========================================================================
-->
<target name="init">
<!-- So that we can use the ${TSTAMP}, ${DSTAMP}, ... time stamps
in targets, if need be -->
<tstamp/>
<echo message="--------- ${project.fullname} ${project.version} ---------"/>
<echo message=""/>
<echo message="java.class.path = ${java.class.path}"/>
<echo message=""/>
<echo message="java.home = ${java.home}"/>
<echo message="user.home = ${user.home}"/>
<echo message=""/>
<echo message="basedir = ${basedir}"/>
<echo message=""/>
<echo message="servlet.jar = ${servlet.jar}"/>
<echo message="cactus.jar = ${cactus.jar}"/>
<echo message="junit.jar = ${junit.jar}"/>
<echo message="cactus.ant.jar = ${cactus.ant.jar}"/>
<!-- Filters -->
<filter token="version" value="${project.version}"/>
<filter token="year" value="${year}"/>
<!-- Initialize custom Ant task needed for running the server tests -->
<taskdef name="runservertests" classname="org.apache.cactus.ant.RunServerTestsTask">
<classpath>
<pathelement location="${cactus.ant.jar}"/>
<pathelement path="${java.class.path}"/>
</classpath>
</taskdef>
</target>
]]></source>
</section>
<anchor id="usage"/>
<section title="Step 4: 'usage' targets">
<p>
Display a usage message.
</p>
<source><![CDATA[
<!--
========================================================================
Help on usage. List available targets
========================================================================
-->
<target name="usage" depends="init">
<echo message=""/>
<echo message="${project.fullname} build file"/>
<echo message="------------------------------------------------------"/>
<echo message=""/>
<echo message=" Available targets are:"/>
<echo message=""/>
<echo message=" war --> generates the war file (default)"/>
<echo message=" clean --> cleans up the build directory"/>
<echo message=" source --> generates source zip of the project"/>
<echo message=" doc --> generates the docs (javadoc, ...)"/>
<echo message=" all --> do it all at once"/>
<echo message=" (clean, war, source, doc)"/>
<echo message=""/>
<echo message=" Targets for running the tests for Servlet API 2.2:"/>
<echo message=""/>
<echo message=" tests_resin_12 --> run tests for Resin 1.2"/>
<echo message=" tests_tomcat_32 --> run tests for Tomcat 3.2"/>
<echo message=" tests_weblogic_51 --> run tests for WebLogic 5.1"/>
<echo message=" tests_orion_14 --> run tests for Orion 1.4"/>
<echo message=""/>
</target>
]]></source>
</section>
<anchor id="prepare"/>
<section title="Step 5: 'prepare' target">
<p>
This target is needed for both compiling and generating the javadoc.
It copies all the source files from their <code>src/</code> directory
to the <code>out</code> directory, replacing tokens in the source
code (replacing the <code>@version@</code> by the version number
for example).
</p>
<source><![CDATA[
<!--
========================================================================
Prepare the output directory by copying the source files into it
========================================================================
-->
<target name="prepare" depends="init">
<mkdir dir="${out.src.dir}"/>
<!-- Copy all source files to destination dir. Apply the filters in
order to replace the tokens for the copyright year and the
version -->
<copy todir="${out.src.dir}" filtering="on">
<fileset dir="${src.java.dir}">
<patternset refid="all.src.files"/>
</fileset>
<fileset dir="${src.java.servlet.dir}">
<patternset refid="all.src.files"/>
</fileset>
</copy>
</target>
]]></source>
</section>
<anchor id="compile"/>
<section title="Step 6: 'compile' target">
<p>
The <code>compile</code> target simply compiles the java files into
<code>.class</code> files and also copies the support files that are
in <code>src/</code> to the directory where the class file have been
generated.
</p>
<source><![CDATA[
<!--
========================================================================
Compiles the source directory
========================================================================
-->
<!-- Preparation target for the compile target -->
<target name="prepare-compile" depends="prepare">
<mkdir dir="${out.classes.dir}"/>
</target>
<!-- Run the java compilation -->
<target name="compile" depends="prepare-compile">
<javac srcdir="${out.src.dir}"
destdir="${out.classes.dir}"
debug="${debug}"
deprecation="${deprecation}"
optimize="${optimize}">
<!-- Exclude all files that are not .java source files -->
<!-- All doc files -->
<exclude name="**/package.html"/>
<exclude name="**/overview.html"/>
<!-- All conf files (including test files) -->
<exclude name="**/*.txt"/>
<exclude name="**/*.xml"/>
<exclude name="**/*.properties"/>
<classpath>
<pathelement path="${java.class.path}"/>
<pathelement location="${servlet.jar}"/>
<pathelement location="${cactus.jar}"/>
</classpath>
</javac>
<!-- Copies non java files that need to be in the classes directory -->
<copy todir="${out.classes.dir}">
<fileset dir="${src.java.dir}">
<patternset refid="all.nonjava.files"/>
</fileset>
<fileset dir="${conf.test.dir}">
<include name="cactus.properties"/>
</fileset>
</copy>
</target>
]]></source>
</section>
<anchor id="source"/>
<section title="Step 7: 'source' target">
<p>
Zip up the sources for distribution.
</p>
<source><![CDATA[
<!--
========================================================================
Generates source zip of the project
========================================================================
-->
<target name="source" depends="prepare">
<zip zipfile="${final.src.name}" basedir=".">
<exclude name="${out.dir}/**"/>
<exclude name="**/*.log"/>
<exclude name="**/*.bak"/>
<exclude name="**/*.class"/>
<exclude name="${build.dir}/build.properties"/>
</zip>
</target>
]]></source>
</section>
<anchor id="javadoc"/>
<section title="Step 8: 'javadoc' target">
<p>
Generate the project's javadoc.
</p>
<source><![CDATA[
<!--
========================================================================
Generate the javadoc
========================================================================
-->
<!-- Preparation target for the javadoc target -->
<target name="prepare-javadoc" depends="prepare">
<mkdir dir="${out.javadoc.dir}"/>
</target>
<!-- Generate the javadoc for the current Servlet API -->
<target name="javadoc" depends="prepare-javadoc">
<javadoc
sourcepath="${out.src.dir}"
packagenames="org.apache.cactus.sample.*"
destdir="${out.javadoc.dir}"
author="true"
public="true"
version="true"
use="true"
windowtitle="${project.fullname} ${project.version} for Servlet @servlet.api@ API"
doctitle="${project.fullname} ${project.version} for Servlet @servlet.api@ API"
bottom="Copyright &copy; ${year} Apache Software Foundation. All Rights Reserved.">
<classpath>
<pathelement path="${java.class.path}"/>
<pathelement location="${servlet.jar}"/>
<pathelement location="${cactus.jar}"/>
</classpath>
</javadoc>
</target>
]]></source>
</section>
<anchor id="doc"/>
<section title="Step 9: 'doc' target">
<p>
Generate the project's documentation. It includes the javadoc,
additional README files (if any) and the documentation web site
</p>
<p>
Example:
</p>
<source><![CDATA[
<!--
========================================================================
Generate the full documentation
========================================================================
-->
<!-- Preparation target for the doc target -->
<target name="prepare-doc" depends="javadoc">
<mkdir dir="${out.doc.dir}"/>
</target>
<!-- Generate the documentation -->
<target name="doc" depends="prepare-doc">
<!-- Create the zipped documentation -->
<zip zipfile="${final.doc.name}" basedir="${out.doc.dir}"/>
</target>
]]></source>
</section>
<anchor id="clean"/>
<section title="Step 10: 'clean' target">
<p>
Removes all build generated files.
</p>
<source><![CDATA[
<!--
========================================================================
Remove all build generated files
========================================================================
-->
<target name="clean" depends="init">
<!-- Deletes all files ending with '~' -->
<delete>
<fileset dir="." includes="**/*~" defaultexcludes="no"/>
</delete>
<!-- Remove the out directory -->
<delete dir="${out.dir}"/>
<!-- Delete log files -->
<delete>
<fileset dir=".">
<include name="**/*.log"/>
</fileset>
</delete>
</target>
]]></source>
</section>
<section title="Step 11: 'jar', 'war' targets">
<anchor id="jar"/>
<section title="'jar' target">
<p>
This target is useful if your project is a framework for example and
you need to deliver a jar file. We also include a manifest file
in the jar, with version information. We copy the manifest to the
output directory in order to replace the <code>@version@</code>
token with it's value.
</p>
<p>
Example (from the Cactus build file):
</p>
<source><![CDATA[
<!--
========================================================================
Create the runtime jar file
========================================================================
-->
<!-- Preparation target for the jar target -->
<target name="prepare-jar" depends="compile">
<mkdir dir="${out.conf.dir}"/>
<mkdir dir="${out.lib.dir}"/>
<!-- Copy the manifest in order to replace the version token filter -->
<copy todir="${out.conf.dir}" filtering="on">
<fileset dir="${conf.dir}" >
<include name="manifest"/>
</fileset>
</copy>
</target>
<!-- Generate the jar file -->
<target name="jar" depends="prepare-jar">
<jar jarfile="${final.jar.name}" basedir="${out.classes.dir}"
manifest="${out.conf.dir}/manifest">
<!-- Do not include test files in the runtime jar -->
<exclude name="**/Test*.*"/>
<exclude name="**/test*.*"/>
</jar>
</target>
]]></source>
</section>
<anchor id="war"/>
<section title="'war' target">
<p>
This target is useful if you're building a web application.
We also include a manifest file in the war, with version
information. We copy the manifest to the output directory in order
to replace the <code>@version@</code> token with it's value.
</p>
<p>
Example (from the Cactus sample):
</p>
<source><![CDATA[
<!--
========================================================================
Create the runtime war file
========================================================================
-->
<!-- Preparation target for the war target -->
<target name="prepare-war" depends="compile">
<mkdir dir="${out.conf.dir}"/>
<!-- Copy the manifest in order to replace the version token filter -->
<copy todir="${out.conf.dir}" filtering="on">
<fileset dir="${conf.dir}" >
<include name="manifest"/>
</fileset>
</copy>
</target>
<!-- Generate the war file -->
<target name="war" depends="prepare-war">
<war warfile="${final.war.name}"
webxml="${conf.dir}/web.xml"
manifest="${out.conf.dir}/manifest">
<classes dir="${out.classes.dir}">
<!-- Do not include test files in the runtime jar -->
<exclude name="**/Test*.*"/>
<exclude name="**/test*.*"/>
<!-- Also exclude the test cactus.properties file -->
<exclude name="cactus.properties"/>
</classes>
<fileset dir="${web.dir}">
<exclude name="test/**"/>
</fileset>
</war>
</target>
]]></source>
</section>
</section>
<anchor id="tests"/>
<section title="Step 12: 'tests_XXX' target">
<p>
The <code>tests_XXX</code> target is in charge of running the
Cactus unit tests. It must prepare the test environment for a
given servlet engine and package the tests, start that servlet
engine, run the tests by starting the JUnit runner and stop the
servlet engine.
</p>
<p>
See the <link href="site:howto_ant_cactus">Using Cactus with
Ant</link> tutorial for details on to do this.
</p>
</section>
</section>
</body>
</document>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/ant/navigation.xml
Index: navigation.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE navigation
PUBLIC "-//Apache Software Foundation//DTD Cactus Navigation V1.0//EN"
"file:../../../dtds/navigation-v10.dtd">
<navigation>
</navigation>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/manual/howto_ide_vajava_wte.xml
Index: howto_ide_vajava_wte.xml
===================================================================
<?xml version="1.0"?>
<document id="howto_ide_vajava_wte">
<properties>
<title>VAJava and WebSphere Test Environment</title>
<authors>
<author name="Vincent Massol" email="vmassol@apache.org"/>
</authors>
</properties>
<body>
<section title="Forewords and Requirements">
<note>
<strong>This tutorial is written for Cactus 1.2 only. It will need
to adapted if you're using Cactus 1.3</strong>
</note>
<p>
This tutorial explains how to run Cactus tests within VisualAge for
Java WebSphere Test Environment.
</p>
<p>
We have received reports that the following tutorial works with
VAJava 3.5.2 and 3.5.3. Please tell us if you find that it works with
other versions.
</p>
</section>
<section title="Step 1: Import the correct packages in VAJava">
<p>
Let's assume the following conventions:
<strong><code>{Cactus dir}</code></strong> is the directory where you
have unzipped the Cactus distribution or sources and
<strong><code>{VAJava dir}</code></strong> is the directory where
VAJava is installed. Let's also define <strong><code>{WTE dir}</code>
</strong> to be the WebSphere Test Environment directories, i.e.
<code>{VAJava dir}/ide/project_resources/IBM WebSphere Test
Environment</code>.
</p>
<p>
You need to create 4 projects: one for JUnit, one for Cactus (
let's call it "Cactus"), one for HttpClient and
optionally one for Log4j. Note that the Log4j one is useful only if
wish to get some Cactus runtime logs. If you don't import the Log4j
classes, some Cactus classes will appear with a red cross in VAJava
but you can safely ignore them as they won't be executed.
</p>
<note>
You can either import the source files or the compiled classes as you
wish. If you import the source file, you should import the following
directories: <code>{Cactus dir}/src/framework/servlet22</code> and
<code>{Cactus dir}/src/framework/share</code>. You also need to
copy the following files into
<code>{VAJava dir}/ide/project_resources/Cactus</code>:
<code>log_client.properties</code> and
<code>log_server.properties</code> which are located in
<code>{Cactus dir}/sample/conf/test</code>. If you have imported from
the Cactus jar file, and you have selected to import resources files
then they have been automatically imported for you.
</note>
</section>
<section title="Step 2: Set up the cactus.properties file">
<p>
Copy your <code>cactus.properties</code> file (see the
<link href="site:howto_config">Configuration Howto</link>
tutorial for details on <code>cactus.properties</code>) to
<code>{VAJava dir}/ide/project_resources/Cactus</code>.
</p>
<note>
As WebSphere does not support the <code>jsp-file</code> tag in
<code>web.xml</code>, we cannot map the redirector JSP to a name, so
instead of writing
"<code>cactus.jspRedirectorURL =
http://localhost:8080/test/JspRedirector</code>" in
<code>cactus.properties</code>, you should simply
put the JSP file name, as in
"<code>cactus.jspRedirectorURL =
http://localhost:8080/test/jspRedirector.jsp</code>". This is only needed
if you have test cases that extend <code>JspTestCase</code>.
</note>
</section>
<section title="Step 3: Modify WebSphere Test Environment">
<section title="Edit default.servlet_engine">
<p>
Edit <code>{WTE dir}/properties/default.servlet_engine</code> and
add the following under the <code>default_app</code> webgroup:
</p>
<source><![CDATA[
<websphere-webgroup name="test">
<description>Cactus Testing Web Application</description>
<document-root>$approot$/web</document-root>
<classpath>$approot$/servlets</classpath>
<root-uri>/test</root-uri>
<auto-reload enabled="true" polling-interval="3000"/>
<shared-context>false</shared-context>
</websphere-webgroup>
]]></source>
<note>
The <code>init-parameter</code> is only needed if you wish to run
sample application provided in the Cactus distribution. Also, in
order to run this sample application you'll need to copy the
<code>{Cactus dir}/sample/web/test/test.jsp</code> file to
<code>{WTE dir}/hosts/default_host/test/web/test</code> as it is
used by a test case.
</note>
</section>
<section title="Create a test directory">
<p>
Create a directory called <code>test</code> under
<code>{WTE dir}/hosts/default_host</code>. Under <code>test</code>
create another 2 subdirectories: <code>servlets</code> and
<code>web</code>.
</p>
</section>
<section title="Create a test.webapp file">
<p>
Create a test.webapp file in
<code>{WTE dir}/hosts/default_host/test/servlets</code> and put the
following content:
</p>
<source><![CDATA[
<?xml version="1.0"?>
<webapp>
<name>test</name>
<description>Cactus testing web application</description>
<error-page>/ErrorReporter</error-page>
<servlet>
<name>ServletRedirector</name>
<description>Cactus Testing ServletRedirector</description>
<code>org.apache.cactus.server.ServletTestRedirector</code>
<servlet-path>/ServletRedirector</servlet-path>
<autostart>false</autostart>
<init-parameter>
<name>param1</name>
<value>value1 used for testing</value>
</init-parameter>
</servlet>
<!-- Note: We don't provide a mapping for the JSP Redirector because
WebSphere does not support the jsp-file tag of the Servlet 2.2
specification -->
<servlet>
<name>ErrorReporter</name>
<description>Default error reporter servlet</description>
<code>com.ibm.servlet.engine.webapp.DefaultErrorReporter</code>
<servlet-path>/ErrorReporter</servlet-path>
<autostart>true</autostart>
</servlet>
<servlet>
<name>jsp</name>
<description>JSP support servlet</description>
<!--
WARNING:
If you use the JSP 1.0 compiler, use the following
<code>com.ibm.ivj.jsp.runtime.JspDebugServlet</code>
If you use the JSP 1.1 compiler (VAJava 3.5.3 only), use the following
<code>com.ibm.ivj.jsp.jasper.runtime.JspDebugServlet</code>
-->
<code>com.ibm.ivj.jsp.jasper.runtime.JspDebugServlet</code>
<init-parameter>
<name>workingDir</name>
<value>$server_root$/temp/default_app</value>
</init-parameter>
<init-parameter>
<name>jspemEnabled</name>
<value>true</value>
</init-parameter>
<init-parameter>
<name>scratchdir</name>
<value>$server_root$/temp/JSP1_1/default_app</value>
</init-parameter>
<init-parameter>
<name>keepgenerated</name>
<value>true</value>
</init-parameter>
<autostart>true</autostart>
<servlet-path>*.jsp</servlet-path>
</servlet>
<servlet>
<name>file</name>
<description>File serving servlet</description>
<code>com.ibm.servlet.engine.webapp.SimpleFileServlet</code>
<servlet-path>/</servlet-path>
<init-parameter>
<name></name>
<value></value>
</init-parameter>
<autostart>true</autostart>
</servlet>
</webapp>
]]></source>
</section>
<section title="Copy the Cactus JSP Redirector file">
<p>
Copy the <code>{Cactus dir}/sample/web/test/jspRedirector.jsp</code>
file to <code>{WTE dir}/hosts/default_host/test/web</code>.
</p>
</section>
</section>
<section title="Step 4: Edit VAJava workspace classpath">
<p>
Add the following to the VAJava workspace classpath (select menu
"Window... | Resources" under VAJava):
</p>
<source><![CDATA[
{VAJava dir}\ide\project_resources\JUnit\;
{VAJava dir}\ide\project_resources\Cactus\;
{VAJava dir}\ide\project_resources\HttpClient\;
{VAJava dir}\ide\project_resources\Log4j\;
{VAJava dir}\ide\project_resources\Servlet API Classes\;
]]></source>
</section>
<section title="Step 5: Edit VAJava workspace classpath">
<p>
In the WebSphere Test Environment under Servlet Engine, add Cactus,
JUnit, HttpClient, Log4j, and the project that contained the tests to
the classpath.
</p>
</section>
<section title="Final note">
<note>
With this configuration, you'll find <code>cactus_client.log</code>
under <code>{VAJava dir}/ide/project_resources/{project being
tested}</code> and <code>cactus_server.log</code> under
<code>{VAJava dir}/ide/tools/com-ibm-ivj-ui-webcontrolcenter</code>
when you run your tests.
</note>
<note>
If you get a "Failed to invoke suite():
java.lang.NoClassDefFoundError" error message, you msy get around that
problem by explicitly adding the test cases to the TestSuite that's
returned in suite(), for your test case.
</note>
</section>
</body>
</document>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/manual/howto_ide_jbuilder5.xml
Index: howto_ide_jbuilder5.xml
===================================================================
<?xml version="1.0"?>
<document id="howto_ide_jbuilder5">
<properties>
<title>JBuilder 5 Integration</title>
<authors>
<author name="Sean Zhang" email="sean.zhang@verizon.com"/>
<author name="Vincent Massol" email="vmassol@apache.org"/>
</authors>
</properties>
<body>
<section title="Forewords and Requirements">
<p>
This document describes steps to setup Cactus to unit test Server side
code (i.e. EJBs, Servlets, etc) deployed to Weblogic 6.1 within
JBuilder5 IDE.
</p>
<p>
The steps described below apply to current release (Cactus 1.3 as of
this writing) and assume that Cactus has been installed correctly
(which means that you can run sample successfully).
</p>
</section>
<section title="Step 1: Create cactus.properties file">
<p>
Create cactus.properties file: Add entry to identify the URL of the
redirector (see the <link href="site:howto_config">Configuration
Howto</link> for details).
</p>
</section>
<section title="Step 2: Configure Cactus to work with JBuilder5">
<p>
Follow these steps:
</p>
<ol>
<li>
Click Menu item Tools/Configure Libraries to open Configure Libraries
wizard
</li>
<li>
On the lefthand side of Configure Libraries wizard, click on New
button to open New Library Wizard.
</li>
<li>
Enter value <code>"cactus"</code> in the Name field. Choose
<code>"user home"</code> from the Location drop down menu.
</li>
<li>
Click on Add button to open the dialog to choose files.
</li>
<li>
Navigate to <code>[cactus home]/lib/</code> directory, select
<code>cactus.jar</code> and click OK button.
</li>
<li>
Click on Add button again to open the dialog to choose files.
</li>
<li>
Navigate to the directory where the <code>cactus.properties</code>
file is saved.
</li>
<li>
Click OK button.
</li>
<li>
Click "Add as Class Path" button if "No Paths Found" dialog box pops
up
</li>
<li>
Follow steps 2 - 6 to add <code>junit.jar</code>,
<code>httpclient.jar</code> and <code>aspectjrt.jar</code> which are
all in <code>[cactus home]/lib</code> directory
</li>
<li>
Optionally, add <code>log4j.jar</code> in
<code>[cactus home]/lib</code> directory to enable cactus logging
</li>
<li>
Click Menu item Project/Project Properties to open Project
Properties dialog box
</li>
<li>
Click Path tab and then Required Libraries tab
</li>
<li>
Click Add button and add the libraries created above to your project.
</li>
</ol>
</section>
<section title="Step 3: Configure Cactus for Weblogic6.1">
<ol>
<li>
Open <code>web.xml</code> in <code>WEB-INF</code> directory of the
web application deployed on Weblogic
</li>
<li>
Add the mapping for the redirector under the
<code><web-app></code> element.
</li>
<li>
Copy <code>cactus.jar</code>, <code>junit.jar</code>,
<code>aspectjrt.jar</code> and
<code>log4j.jar</code>(optional) to <code>WEB-INF/lib</code>
directory of the web application
</li>
<li>
Copy your classes files to <code>WEB-INF/classes</code> directory of
the web application
</li>
</ol>
</section>
<section title="Step 4: Run the test">
<ol>
<li>
In JBuilder, click Menu item Project/Project Properties
</li>
<li>
Click Run tab and then Application tab
</li>
<li>
Open "Select Main Class for Project" dialog box and choose the test
case class which has a main method in it.
</li>
<li>
Run your project
</li>
</ol>
</section>
</body>
</document>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/manual/howto_ide_vajava_tomcat.xml
Index: howto_ide_vajava_tomcat.xml
===================================================================
<?xml version="1.0"?>
<document id="howto_ide_vajava_tomcat">
<properties>
<title>VAJava and Tomcat Test Environment</title>
<authors>
<author name="Vincent Massol" email="vmassol@apache.org"/>
</authors>
</properties>
<body>
<section title="Forewords and Requirements">
<note>
<strong>This tutorial is written for Cactus 1.2 only. It will need
to adapted if you're using Cactus 1.3</strong>
</note>
<p>
This tutorial explains how to run Cactus tests within VisualAge for
Java Tomcat Test Environment.
</p>
<p>
The following tutorial has been tested with VisualAge 3.5.3 and Apache
Tomcat Test Environment 3.1. Please tell us if you find that it works
with other versions.
</p>
</section>
<section title="Steps">
<p>
Let's call <strong><code>{VAJava dir}</code></strong> the directory
where VAJava is installed. Let's also suppose that the context of our
webapp is called <strong><code>myApp</code></strong>.
</p>
<ul>
<li>
Import Cactus and JUnit into VisualAge as projects,
</li>
<li>
Add the Cactus redirector mappings to your web.xml file (see the
<link href="site:howto_config">Configuration Howto</link>), which is
located at
<code>{VAJava dir}\ide\project_resources\Apache_Tomcat_Test_Environment\webapps\myApp\WEB-INF\</code>,
</li>
<li>
Make sure the <code>cactus.properties</code> file has the correct
URL for the redirectors (see the
<link href="site:howto_config">Configuration Howto</link>). Put the
file in
<code>{VAJava dir}\ide\project_resources\Apache_Tomcat_Test_Environment\webapps\myApp\WEB-INF\</code>,
</li>
<li>
Add the following directories to JUnit's TestRunner project classpath
(project's properties dialog box):
</li>
</ul>
<source><![CDATA[
{VAJava dir}\ide\project_resources\Apache_Tomcat_Test_Environment\webapps\myApp\WEB-INF\;
{VAJava dir}\ide\project_resources\Apache_Tomcat_Test_Environment\webapps\myApp\WEB-INF\classes\;
]]></source>
<ul>
<li>
Add the Cactus project to both JUnit's TestRunner and Apache's
TomcatRunner project classpath (project properties dialog boxes).
</li>
</ul>
</section>
</body>
</document>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/manual/navigation.xml
Index: navigation.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE navigation
PUBLIC "-//Apache Software Foundation//DTD Cactus Navigation V1.0//EN"
"file:../../../dtds/navigation-v10.dtd">
<navigation>
</navigation>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/manual/howto_classpath.xml
Index: howto_classpath.xml
===================================================================
<?xml version="1.0"?>
<document id="howto_classpath">
<properties>
<title>Setting the Cactus CLASSPATH</title>
<authors>
<author name="Vincent Massol" email="vmassol@apache.org"/>
</authors>
</properties>
<body>
<section title="Setting up Cactus Classpaths">
<p>
You must understand that your Cactus tests are started by a JUnit
Test Runner (in the client JVM) and that the Cactus TestCase that you
have extended will connect to the Cactus Redirector (in the server
JVM), where your <code>testXXX()</code> methods will be executed. See
<link href="site:how_it_works">How it works</link> to understand the
mechanism.
</p>
<p>
Please also check the <link href="site:howto_runner">TestRunner
Howto</link> tutorial which explains all the different ways to
start a JUnit Test Runner.
</p>
<note>
<strong>It is very important that you understand what files you need
to put in the client and server classpaths, as 99% of Cactus
errors come from an incorrect classpath !</strong>
</note>
<figure src="images/classpath.jpg" alt="Classpaths"/>
<section title="Client side classpath">
<p>
The Cactus tests are started by running a JUnit Test Runner (For
explanations on how JUnit works see the
<link href="http://junit.sourceforge.net">JUnit web site</link>).
As pictured in figure 1, you need to have the following jars and
classes in your client side classpath:
</p>
<ul>
<li>
<strong><code>junit.jar</code></strong>: obviously this is needed
for the JUnit Test Runner and because the Cactus
<code>XXXTestCase</code> classes extend the JUnit
<code>org.junit.framework.TestCase</code> class.
</li>
<li>
<strong><code>cactus.jar</code></strong>: well, this is the
Cactus jar containing all Cactus classes,
</li>
<li>
<strong>your test classes</strong>: these are
your test classes that extend the Cactus <code>XXXTestCase</code>
classes,
</li>
<li>
<strong><code>servlet.jar or j2ee.jar</code></strong>: these are
the Servlet API / J2EE API interfaces. This
is needed on the client side classpath because your test cases
extend one or several of <code>XXXTestCase</code> which use class
variables that are Servlet / J2EE objects
(<code>HttpSevletRequest</code>, <code>PageContext</code>, ...).
You can get this jar either from your servlet engine or from the
<link href="http://java.sun.com">Sun Web Site</link> (
<link href="http://java.sun.com/products/servlet/download.html">
Servlet download page</link> or
<link href="http://java.sun.com/j2ee/download.html">J2EE download
page</link>).
</li>
<li>
<strong><code>httpclient.jar</code></strong>: needed for
Cactus Cookie handling.
</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>logging framework jar</code>(optional)</strong>: The
logging framework to use (Log4j jar, LogKit jar, etc). It is
optional as it is only needed for internal Cactus logging and in
addition, the Commons Logging framework provides a simple logger
that logs on the console.
</li>
<li>
<strong><code>httpunit.jar</code></strong>, <strong>
<code>Tidy.jar</code></strong> and <strong>
<code>xerces.jar</code> (optional)</strong>: only needed if you
wish to use
<link href="http://httpunit.sourceforge.net">HttpUnit</link>
in your <code>endXXX()</code> methods (see the
<link href="site:howto_httpunit">HttpUnit Howto</link> tutorial).
The 3 jars mentioned above are part of the HttpUnit distribution.
</li>
<li>
<strong><code>aspectjrt.jar</code></strong>:
<link href="ext:aspectj">AspectJ</link> runtime jar.
</li>
</ul>
<note>
If you have the habit of using class variables for the classes
to test (as opposed to declaring them within the
<code>testXXX()</code> method), you'll also need to put your classes
under test in the client side classpath.
</note>
<p>
In addition to the above mentioned jars and classes, you may have
to put the <strong><code>cactus.properties</code></strong>
configuration file in your classpath (Only if you are using it to
configure Cactus of course). Details are described in the
<link href="site:howto_config">Config Howto</link> tutorial).
</p>
<note>
If you are using Log4J as the logging framework, you will also
need to put a <code>log4j.properties</code> Log4j configuration
file in your client side classpath (See the
<link href="site:howto_config">Config Howto</link> tutorial).
</note>
</section>
<section title="Server side classpath">
<p>
The server side part is a webapp. It can be packaged as a .war file
or as expanded war. It should have the following structure, which
will ensure that the classpath is correct:
</p>
<ul>
<li>
<strong><code>WEB-INF/lib/cactus.jar</code></strong>: the
Cactus main jar,
</li>
<li>
<strong><code>WEB-INF/lib/junit.jar</code></strong>: this is
needed because the Cactus <code>XXXTestCase</code> extends
the JUnit <code>org.junit.framework.TestCase</code> class.
</li>
<li>
<strong><code>WEB-INF/classes/<your test classes></code>
</strong>: obviously as their <code>testXXX()</code> methods will
get executed in the container.
</li>
<li>
<strong><code>WEB-INF/classes/<your classes under test></code>
</strong>: will be called by your test classes.
</li>
<li>
<strong><code>aspectjrt.jar</code></strong>:
<link href="ext:aspectj">AspectJ</link> runtime jar.
</li>
<li>
<strong><code>WEB-INF/lib/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>WEB-INF/lib/logging framework jar</code>
(optional)</strong>: The logging framework to use (Log4j jar,
LogKit jar, etc). It is optional as it is only needed for internal
Cactus logging and in addition, the Commons Logging framework
provides a simple logger that logs on the console.
</li>
</ul>
<note>
If you have several webapps that use cactus you can put all Cactus
jars in a place loaded by your container System classloader (provided
your container correctly sets the Context classloader). The location
is container-dependent; for example for Tomcat 4.x, you can put the
jars in <code>TOMCAT_HOME/common/lib</code>.
</note>
<note>
If you are using Log4J as the logging framework, you will also
need to put a <code>log4j.properties</code> Log4j configuration
file in your server side classpath (usually in
<code>WEB-INF/classes</code>).
</note>
</section>
</section>
</body>
</document>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/manual/howto_config.xml
Index: howto_config.xml
===================================================================
<?xml version="1.0"?>
<document id="howto_config">
<properties>
<title>Configuration Howto</title>
<authors>
<author name="Vincent Massol" email="vmassol@apache.org"/>
</authors>
</properties>
<body>
<section title="Cactus Configuration">
<note>
You should read the <link href="site:getting_started">Getting
Started</link> guide first.
</note>
<p>
Here are the configuration files used by Cactus:
</p>
<figure src="images/config.jpg" alt="Configuration files"/>
<p>
There are 3 kinds of configuration:
</p>
<ul>
<li>
<jump anchor="clientside">Client side configuration</jump>
</li>
<li>
<jump anchor="serverside">Server side configuration</jump>
</li>
<li>
<jump anchor="logging">Cactus Logging configuration</jump>
</li>
</ul>
<p>
Cactus configuration works by setting Java System properties. You can
set the Cactus configuration properties:
</p>
<ul>
<li>
On the command line (using <code>-Dxxx=yyy</code>).
</li>
<li>
In a configuration file (recommended). By default Cactus will look
for a <code>cactus.properties</code> file located in your
classpath. You can override the name and location of the
configuration file by setting the <code>cactus.config</code> System
property. For example you can pass the following when starting the
JVM: <code>-Dcactus.config=c:/cactus.txt</code>.
</li>
<li>
In your tests (using <code>System.setProperty()</code>). This
option is not recommended as it is better to share a single
configuration across all tests.
</li>
</ul>
<note>
Please note that the different options for configuring Cactus works
both for Cactus client side (i.e. from where you start the JUnit Test
Runner) and for the Cactus server side (i.e. from where you start your
application server).
</note>
<anchor id="clientside"/>
<section title="Client side configuration">
<p>
The following table lists the properties that can be defined on
Cactus client side:
</p>
<table>
<tr>
<td>
<strong>Property Name</strong>
</td>
<td>
<code>cactus.contextURL</code>
</td>
</tr>
<tr>
<td>
<strong>Required</strong>
</td>
<td>
Yes
</td>
</tr>
<tr>
<td>
<strong>Description</strong>
</td>
<td>
Webapp Context under which the application to test runs.
</td>
</tr>
<tr>
<td>
<strong>Example</strong>
</td>
<td>
<code>cactus.contextURL = http://localhost:8080/test</code>
</td>
</tr>
</table>
<p>
<br/>
</p>
<table>
<tr>
<td>
<strong>Property Name</strong>
</td>
<td>
<code>cactus.servletRedirectorName</code>
</td>
</tr>
<tr>
<td>
<strong>Required</strong>
</td>
<td>
No. Defaults to "<code>ServletRedirector</code>".
</td>
</tr>
<tr>
<td>
<strong>Description</strong>
</td>
<td>
Name of the Cactus Servlet Redirector as it is mapped on the
server side in <code>web.xml</code> (see below). This property
is needed only if your test classes are extending
<code>ServletTestCase</code> (see the
<link href="site:howto_testcase">TestCase Howto</link>
tutorial).
</td>
</tr>
<tr>
<td>
<strong>Example</strong>
</td>
<td>
<code>cactus.servletRedirectorName = ServletRedirector</code>
</td>
</tr>
</table>
<p>
<br/>
</p>
<table>
<tr>
<td>
<strong>Property Name</strong>
</td>
<td>
<code>cactus.jspRedirectorName</code>
</td>
</tr>
<tr>
<td>
<strong>Required</strong>
</td>
<td>
No. Defaults to "<code>JspRedirector</code>".
</td>
</tr>
<tr>
<td>
<strong>Description</strong>
</td>
<td>
Name of the Cactus JSP Redirector as it is mapped on the
server side in <code>web.xml</code> (see below). This property
is needed only if your test classes are extending
<code>JspTestCase</code> (see the
<link href="site:howto_testcase">TestCase Howto</link>
tutorial).
</td>
</tr>
<tr>
<td>
<strong>Example</strong>
</td>
<td>
<code>cactus.jspRedirectorName = JspRedirector</code>
</td>
</tr>
</table>
<p>
<br/>
</p>
<table>
<tr>
<td>
<strong>Property Name</strong>
</td>
<td>
<code>cactus.filterRedirectorName</code> (For J2EE API 1.3 only)
</td>
</tr>
<tr>
<td>
<strong>Required</strong>
</td>
<td>
No. Defaults to "<code>FilterRedirector</code>".
</td>
</tr>
<tr>
<td>
<strong>Description</strong>
</td>
<td>
Name of the Cactus Filter Redirector as it is mapped on the
server side in <code>web.xml</code> (see below). This property
is needed only if your test classes are extending
<code>FilterTestCase</code> (see the
<link href="site:howto_testcase">TestCase Howto</link>
tutorial).
</td>
</tr>
<tr>
<td>
<strong>Example</strong>
</td>
<td>
<code>cactus.filterRedirectorName = FilterRedirector</code>
</td>
</tr>
</table>
</section>
<anchor id="serverside"/>
<section title="Server side configuration">
<p>
On Cactus server side, you only need to properly configure your
application <code>web.xml</code> file to include definitions for
Cactus Redirectors (see <link href="site:how_it_works">How it
works</link> if you don't know what a Cactus Redirector is).
</p>
<p>
You need to register the Cactus Redirectors that you use, and you
need to map them to the <code>cactus.servletRedirectorName</code>,
<code>cactus.jspRedirectorName</code> and
<code>cactus.filterRedirectorName</code> that you have configured
on the client side (or simply make sure that you use the default
names, i.e. <code>ServletRedirector</code>,
<code>JspRedirector</code> and <code>FilterRedirector</code>
respectively).
</p>
<p>
Here is a sample <code>web.xml</code> that defines the 3 Cactus
Redirectors:
</p>
<source><![CDATA[
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">
<web-app>
<filter>
<filter-name>FilterRedirector</filter-name>
<filter-class>org.apache.cactus.server.FilterTestRedirector</filter-class>
</filter>
<filter-mapping>
<filter-name>FilterRedirector</filter-name>
<url-pattern>/FilterRedirector</url-pattern>
</filter-mapping>
<servlet>
<servlet-name>ServletRedirector</servlet-name>
<servlet-class>org.apache.cactus.server.ServletTestRedirector</servlet-class>
</servlet>
<servlet>
<servlet-name>JspRedirector</servlet-name>
<jsp-file>/jspRedirector.jsp</jsp-file>
</servlet>
<servlet-mapping>
<servlet-name>ServletRedirector</servlet-name>
<url-pattern>/ServletRedirector</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>JspRedirector</servlet-name>
<url-pattern>/JspRedirector</url-pattern>
</servlet-mapping>
</web-app>
]]></source>
<note>
If you are using the JSP Redirector (i.e. you have test classes
that extend <code>JspTestCase</code>), you <strong>must</strong>
copy the <code>jspRedirector.jsp</code> file (found in the
<code>sample/web</code> directory where you unpacked your
Cactus distribution) in a directory in your webapp and you need to
put it's relative path in the mapping defined above (here we
have put it in the webapp root.
</note>
<p>
If you want to provide some initialisation parameters that will
be available to the <code>config</code> implicit object available
in your test case, simply use the standard <code>
<init-param></code> tags.
</p>
<p>
For example, for the Servlet Redirector (same principle applies
to all other redirectors):
</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>
[...]
]]></source>
<note>
Within your <code>testXXX()</code> code, you can also call the
<code>config.setInitParameter()</code> method (<code>config</code>
being the implicit object of type <code>ServletConfig</code>) to
simulate initialisation parameters as if they had been defined in
your <code>web.xml</code>.
</note>
<p>
Last, if you need to unit test code that uses the Servlet
Security API, please check the
<link href="site:howto_security">Security Howto</link>.
</p>
</section>
<anchor id="logging"/>
<section title="Cactus logging configuration">
<p>
Since Cactus 1.4, we have switched to using the
<link href="http://jakarta.apache.org/commons/logging.html">Jakarta
Commons Logging</link> framework for Cactus internal logs (and any
log you may wish to output as part of your test).
</p>
<p>
This allow Cactus to use any underlying logging framework such as:
<link href="http://jakarta.apache.org/log4j">Log4J</link>,
<link href="http://jakarta.apache.org/avalon/logkit">LogKit</link>,
JDK 1.4 Logging or even a Simple Logger provided as part of Commons
Logging (it outputs to the console).
</p>
<p>
Cactus is completely agnostic with regards to the logging framework
configuration, so you will have to learn how to configure your
favorite logging yourself. However, here are some tips on how to
easily configure Log4j.
</p>
<section title="Log4J configuration">
<p>
Create a <code>log4j.properties</code> file and drop it in both
your client side and server side classpaths. Log4j automatically
looks for such a file in the classpath so it should find it easily.
</p>
<p>
Now you need to add the categories that you want to log to that
file. If you wish to see Cactus logs, you will need to add the
"<code>org.apache.cactus.*</code>" category and set the logging
level to <code>DEBUG</code> as Cactus only outputs logs in that
level.
</p>
<p>
Here is a sample <code>log4j.properties</code> file for Cactus
client side. You can use the same one for the Server side but we
recommend to change the name of the output file in order not to
mix the logs.
</p>
<source><![CDATA[
# Properties for configuring Log4j
# This is the configuring for logging on the JUnit side (i.e. the client side)
log4j.appender.cactus = org.apache.log4j.FileAppender
log4j.appender.cactus.File = cactus_client.log
log4j.appender.cactus.Append = false
log4j.appender.cactus.layout = org.apache.log4j.PatternLayout
log4j.appender.cactus.layout.ConversionPattern = %d{ABSOLUTE} [%t] %-5p %-30.30c{2} %x - %m %n
# Any application log which uses Log4J will be logged to the Cactus log file
log4j.rootCategory=DEBUG, cactus
# By default we don't log at the DEBUG level for Cactus log, in order not to generate too
# many logs. However, should a problem arise and logs need to be sent to the Cactus dev team,
# then we will ask you to change this to DEBUG.
log4j.category.org.apache.cactus = WARN, cactus
log4j.additivity.org.apache.cactus=false
# Don't show debug logs for HttpClient
log4j.category.org.apache.commons.httpclient = WARN, cactus
log4j.additivity.org.apache.commons.httpclient=false
log4j.category.httpclient = WARN, cactus
log4j.additivity.httpclient=false
]]></source>
<note>
JUnit uses a different classloader to load each test of a TestCase
class. Thus, Log4j will reinitialise for each test, thus
overwriting the <code>cactus_client.log</code> file each time (this
is because we have set <code>log4j.appender.cactus.Append</code> to
<code>false</code>. You can set it to <code>true</code> if you
wish to keep all the logs but the file size will grow quickly. In
addition logs are really only useful when there is a failure and
thus not appending is usually a good choice.
</note>
</section>
</section>
</section>
</body>
</document>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/manual/howto_ide_jbuilder4.xml
Index: howto_ide_jbuilder4.xml
===================================================================
<?xml version="1.0"?>
<document id="howto_ide_jbuilder4">
<properties>
<title>JBuilder 4 Integration</title>
<authors>
<author name="Cedric Chabanois" email="cchabanois@ifrance.com"/>
<author name="Kunal Vaishnav" email="Kunal_Vaishnav@jdedwards.com"/>
<author name="Vincent Massol" email="vmassol@apache.org"/>
</authors>
</properties>
<body>
<section title="Forewords and Requirements">
<p>
First of all, you need to download the
<link href="site:downloads">Cactus distribution</link>
</p>
</section>
<section title="Step 1: Create JBuilder libraries">
<p>
Let's assume the following conventions:
<strong><code>{Cactus dir}</code></strong> is the directory where you
have unzipped the Cactus distribution or sources.
Let's also assume <strong><code>{Tomcat dir}</code></strong> to be the Tomcat directory.
</p>
<figure src="images/jb_libraries.gif" alt="jbuilder libraries" />
<section title="Create the JUnit library">
<p>
Create a JUnit library and include <code>junit.jar</code>.
</p>
</section>
<section title="Create the Cactus library">
<p>
Create a Cactus library containing <code>cactus.jar</code> and
<code>aspectjrt.jar</code> (you can actually create a separate
library for AspectJ if you wish).
</p>
<note>
You can also add the source file directories in the source tab.
This way, you will be able to debug inside cactus sources.
</note>
</section>
<section title="Create the tomcat library">
<p>
Create another library named <code>tomcat</code>
and add all the jar files from <code>{Tomcat dir}/lib</code>.
</p>
<note>
If you use JBuilder 4 Enterprise or JBuilder 4 Professionnal, you don't need to create
this library because Tomcat 3.1 is provided with those versions.
</note>
</section>
</section>
<section title="Step 2: Set up the cactus.properties file">
<p>
Edit a new file named <code>cactus.properties</code>
(see the <link href="site:howto_config">Configuration Howto</link>
tutorial for more details on <code>cactus.properties</code>).
</p>
<p>
Copy your <code>cactus.properties</code> file to a directory present
in your classpath. You can copy it to a directory and add this
directory in the class tab of the cactus library.
</p>
</section>
<section title="Step 3: Configure Tomcat Environment">
<section title="Create a cactus webapp">
<p>
Create and edit the file
<code>{Tomcat dir}/webapps/cactus/WEB-INF/web.xml</code>. Here is an
example for Servlet API 2.2:
</p>
<source><![CDATA[
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
<web-app>
<servlet>
<servlet-name>ServletRedirector</servlet-name>
<servlet-class>org.apache.cactus.server.ServletTestRedirector</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>ServletRedirector</servlet-name>
<url-pattern>/ServletRedirector</url-pattern>
</servlet-mapping>
</web-app>
]]></source>
</section>
<note>
You can edit <code>{Tomcat dir}/conf/web.xml</code> instead if you
prefer. <br/>
You can also edit the <code>web.xml</code> file of the webapp where is
located the servlet(s) you want to test. <br/>
Don't forget to modify <code>cactus.properties</code> file accordingly.
</note>
</section>
<section title="Step 4: Configure your project">
<ol>
<li>
Put <code>-classic -Dtomcat.home="{Tomcat dir}"</code> as the VM
parameters for your project and
<code>org.apache.tomcat.startup.Tomcat</code> as the main class.
</li>
<li>
Add the following libraries in the <code>Required Libraries</code>
tab in the project properties:
<ul>
<li>tomcat</li>
<li>servlet</li>
<li>junit</li>
<li>cactus</li>
</ul>
<figure src="images/jb_paths.gif" alt="jbuilder libraries" />
</li>
</ol>
</section>
<section title="Step 5: Test and debug your servlet">
<section title="Test your servlet">
<ol>
<li>
Start Tomcat using the <code>Run/Run Project</code> menu.
</li>
<li>
Run your unit tests: right click on the file containing your test
case and click on <code>run</code>
</li>
</ol>
</section>
<section title="Debug your servlet and your tests">
<p>
You can easily print the results of the methods on the server-side
itself.
</p>
<p>
You can also start Tomcat in debug mode (<code>Run/debug
project</code>). This way, you can stop at breakpoints on methods
that are executed on the server side (<code>void testXXX()</code> for
example)
</p>
<p>
If you right click on the file containing your test case and click
on <code>debug</code>, you can stop at breakpoints on methods that
are executed on the client side like
<code>void endXXX(WebResponse)</code> or
<code>void beginXXX(WebRequest)</code>
</p>
</section>
</section>
</body>
</document>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/manual/howto_ide.xml
Index: howto_ide.xml
===================================================================
<?xml version="1.0"?>
<document id="howto_ide">
<properties>
<title>IDE Howto</title>
<authors>
<author name="Vincent Massol" email="vmassol@apache.org"/>
</authors>
</properties>
<body>
<section title="IDE integration">
<p>
In order to simplify Cactus integration within your IDE (i.e. running
the Cactus tests from your IDE), we have
provided several tutorial detailing the involved steps for several
IDEs:
</p>
<ul>
<li>
<link href="site:howto_ide_jbuilder4">JBuilder Integration
Tutorial</link> (more focused on JBuilder 4),
</li>
<li>
Another <link href="site:howto_ide_jbuilder5">JBuilder Integration
Tutorial</link> (more focused on JBuilder 5),
</li>
<li>
VisualAge for Java Integration:
<ul>
<li>
<link href="site:howto_ide_vajava_wte">VAJava and integrated WebSphere Test
Environment (WTE)</link>
</li>
<li>
<link href="site:howto_ide_vajava_tomcat">VAJava and Tomcat Test Environment</link>
</li>
</ul>
</li>
</ul>
<p>
If your favorite IDE is not listed there, don't despair ! It is
actually very simple to integrate Cactus within your
environment. You simply need to know how to start your servlet engine
from your IDE (possibly in debug mode if you wish to debug your
test case) and set up correctly the class path (see the
<link href="site:howto_classpath">Classpath Howto</link> tutorial
for understanding the classpath). Look at the tutorials for other IDEs
and do the same for yours.
</p>
</section>
</body>
</document>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/navigation.xml
Index: navigation.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE navigation
PUBLIC "-//Apache Software Foundation//DTD Cactus Navigation V1.0//EN"
"file:../../dtds/navigation-v10.dtd">
<navigation>
</navigation>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/howto_runner.xml
Index: howto_runner.xml
===================================================================
<?xml version="1.0"?>
<document id="howto_runner">
<properties>
<title>TestRunner Howto</title>
<authors>
<author name="Vincent Massol" email="vmassol@apache.org"/>
</authors>
</properties>
<body>
<section title="Starting Cactus tests">
<p>
The Cactus tests are started using a JUnit Test Runner. There are
several configurations for executing these test runners:
</p>
<ul>
<li>
<jump anchor="from_ant">From Ant</jump>, by using the
<code><junit></code> task
</li>
<li>
<jump anchor="from_command_line">From the java command line</jump>,
calling the <code>main()</code> method of a Test Runner.
</li>
<li>
<jump anchor="from_ide">From an IDE</jump> or any tool providing a
JUnit integration plugin.
</li>
<li>
<jump anchor="from_browser">From a browser</jump>, by using the
Cactus Servlet Test Runner, which is a special JUnit Test Runner.
</li>
</ul>
</section>
<anchor id="from_ant"/>
<section title="Running Cactus tests from Ant">
<p>
Refer to the <link href="site:howto_ant">Ant Howto</link>.
</p>
</section>
<anchor id="from_command_line"/>
<section title="Running Cactus tests from the command line">
<p>
You need to set up your classpath in the same way as when you run
Cactus tests from Ant. However, you start the test with the following
command line (this is an example using the Swing UI TestRunner found
in the junit jar):
</p>
<p>
<code>junit.swingui.TestRunner.main [test case class]</code>
</p>
</section>
<anchor id="from_ide"/>
<section title="Running Cactus tests from an IDE">
<p>
Refer to the <link href="site:howto_ide">IDE Howto</link>.
</p>
</section>
<anchor id="from_browser"/>
<section title="Running Cactus tests from a browser">
<note>
This section only applies for Cactus 1.4 and greater.
</note>
<section title="Step 1: Setting up the classpath">
<p>
In order to run Cactus tests from a browser you need to have a webapp
containing your classes to test and your test classes. In addition,
both Cactus client side and server side jar classes must be able to be
loaded from your webapp (i.e located in your <code>WEB-INF/lib</code>
directory or in a location available through your container Context
class loader (refer to your container documentation).
</p>
<note>
Refer to the <link href="site:howto_classpath">Classpath Howto</link>
guide for the exact list of jars.
</note>
</section>
<section title="Step 2: Mapping the Cactus Servlet Test Runner">
<p>
Then, in addition to the Cactus redirectors that you have mapped in
your <code>web.xml</code> (see the
<link href="site:howto_config">Configuration howto</link>), you also
need to map the Cactus Servlet Test Runner, as follows:
</p>
<source><![CDATA[
[...]
<servlet>
<servlet-name>ServletTestRunner</servlet-name>
<servlet-class>
org.apache.cactus.server.runner.ServletTestRunner
</servlet-class>
</servlet>
[...]
<servlet-mapping>
<servlet-name>ServletTestRunner</servlet-name>
<url-pattern>/ServletTestRunner</url-pattern>
</servlet-mapping>
[...]
]]></source>
</section>
<section title="Step 3: Executing the tests">
<p>
Open a browser and type <code>http://server:port/mywebapp/ServletTestRunner?suite=mytestcase</code>
where:
</p>
<ul>
<li>
<code>server:port</code> is the name of your server machine and
port on which your container is running
</li>
<li>
<code>mywebapp</code> is the name of your webapp (usually the name
of your war file)
</li>
<li>
<code>mytestcase</code> is the fully qualified name (i.e. with
packages) of your <code>TestCase</code> class containing a
<code>suite()</code> method listing all the tests, in standard
JUnit fashion.
</li>
</ul>
<p>
Here is an example of what you will get:
</p>
<figure src="images/servlettestrunner_xml.jpg" alt="XML output of ServletTestRunner"/>
<note>
If you see a blank page, click on the View source option of your
browser. It means your browser doesn't know how to display XML data.
</note>
<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:code_junit_noframes">stylesheet</link>
used to format JUnitReport Ant task results and drop it in your
webapp and name it <code>junit-noframes.xsl</code> (in the root
directory for example). Then, open a browser and type
<code>http://server:port/mywebapp/ServletTestRunner?suite=mytestcase&xsl=junit-noframes.xsl</code>.
You should see the following:
</p>
<figure src="images/servlettestrunner_html.jpg" alt="HTML output of ServletTestRunner"/>
<note>
This will work with Internet Explorer as the XSL transformation is
performed on the client side (i.e by the browser). I'm not sure
about other browsers.
</note>
</section>
<section title="Enabling Server-Side XSLT Transformations">
<p>
In the previous section, the XSLT transformation was performed on the
client. This requires a browser capable of doing XSLT transformations
in a standards-compliant manner, and requires adding the location of
the stylesheet as a request parameter.
</p>
<p>
Since Cactus 1.5, the ServletTestRunner can also perform the
transformation on the server-side. To enable that feature, make sure
that a JAXP compliant XSLT processor (such as
<link href="ext:xalanj">Xalan</link>) is available to the
web-application.
</p>
<p>
In addition, the location of the XSLT stylesheet needs to specified as
initialization parameter of the ServletTestRunner. For example:
</p>
<source><![CDATA[
[...]
<servlet>
<servlet-name>ServletTestRunner</servlet-name>
<servlet-class>
org.apache.cactus.server.runner.ServletTestRunner
</servlet-class>
<init-param>
<param-name>xsl-stylesheet</param-name>
<param-value>styles/cactus-report.xsl</param-value>
</init-param>
</servlet>
[...]
]]></source>
<p>
The specified path is relative to the root of the web-application. Of
course, the stylesheet needs to exist at that location. In contrast to
client-side transformations, the stylesheet may be placed somewhere
inside the <code>WEB-INF</code> directory, because clients do not need
to access it directly.
</p>
<p>
If all of the above is correctly set up, you can enable the actual
transformation by including a <code>transform</code> parameter with
the request (the value of the parameter does not matter). For example
</p>
<source><![CDATA[
http://server:port/mywebapp/ServletTestRunner?suite=mytestcase&transform=yes
]]></source>
<note>
The stylesheet specified as initialization parameter is loaded when
the ServletTestRunner gets initialized. Changes to the stylesheet will
not get picked up until the web-application is reloaded.
</note>
</section>
</section>
</body>
</document>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/browser/howto_tomcat.xml
Index: howto_tomcat.xml
===================================================================
<?xml version="1.0"?>
<document id="howto_tomcat">
<properties>
<title>Tomcat Quickstart</title>
<authors>
<author name="Vincent Massol" email="vmassol@apache.org"/>
</authors>
</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><webapp></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><servlet></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>
</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>. Note that
you can download the pre-compiled class file
<link href="site:code_sample_servlet">here</link>.
</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>. Note that
you can download the pre-compiled class file
<link href="site:code_test_sample_servlet">here</link>.
</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:code_junit_noframes">junit-noframes.xsl</link>
stylesheet used to format JUnitReport Ant task results and drop it in
<code>[tomcat root]/webapps/test</code>. Then, open a browser and type
<code>http://localhost:8080/test/ServletTestRunner?suite=TestSampleServlet&xsl=junit-noframes.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 Internet Explorer as the XSL transformation is
performed on the client side (i.e by the browser). I'm not sure
about other browsers.
</note>
</section>
</body>
</document>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/browser/howto_junitee.xml
Index: howto_junitee.xml
===================================================================
<?xml version="1.0"?>
<document id="howto_junitee">
<properties>
<title>JUnitEE Howto</title>
<authors>
<author name="Kaarle Kaila" email="kaarle.kaila@iki.fi"/>
<author name="Vincent Massol" email="vmassol@apache.org"/>
</authors>
</properties>
<body>
<section title="JUnitEE, a TestRunner inside the Container">
<note>
Since Version 1.4 Cactus contains a new Servlet Test Runner that
enables the same features than the JUnitEE was providing, but in an
even easier way. Please check the
<link href="site:howto_runner">TestRunner Howto</link> tutorial.
</note>
<p>
You can use the
<link href="http://junitee.sourceforge.net">JUnitEE</link> user
interface to run your all your tests inside the Container. JUnitEE is
a JUnit TestRunner that has been written as a servlet with the user
interface in HTML format.
</p>
<p>
You cannot achieve all features of Cactus using JUnitEE as
part of them depend on being executed on the client side.
Executing JUnitEE from ANT commands will probably not be possible.
Some benefits however of JUnitEE are:
</p>
<ul>
<li>
<strong>All class files are in one place</strong>: Install all your
TestCase class-files only in your container classpath. Both
TestCases derived from
<code>junit.framework.TestCase</code> and from
<code>org.apache.cactus.JspTestCase</code>
will be located in the same place and only once.
</li>
<li>
<strong>Run all TestCases in the container</strong>: You can mix
both types of TestCases mentioned above in your test. All tests are
executed inside the Container. You can use testcases derived from
<code>junit.framework.TestCase</code> to test methods that do not
require the http objects such as the
<code>HttpServletRequest</code> or
<code>HttpServletResponse</code> objects.
</li>
</ul>
<p>
Using JUnitEE is (relatively) simple. Assuming you have a container
such as Weblogic, Tomcat or Orion functioning and you know how to
configure Servlets and adding libraries to the Containers classpath and
you are familiar with the basics of Cactus then the rest is easy.
</p>
<ul>
<li>
One good reason to use JUnitEE would be when you want to try Cactus
quickly and are not concerned with automatic unit testing.
</li>
<li>
Usage of standard JUnit testrunner (textui,swingui, ...) will not be
possible if cactus is configured this way and thus the ant junit task
cannot be used to automate the test.
</li>
</ul>
</section>
<section title="How to install JUnitEE">
<p>
Download the
<link href="http://junitee.sourceforge.net">JUnitEE</link>
zip-file. Add a reference to junitee.jar to your Container classpath.
Add also references to
<code>junit.jar</code>,
<code>httpunit.jar</code>
<code>cactus.jar</code> and
<code>aspectjrt.jar</code> if you have not
already done that.
</p>
<note>
add
<code>junitee.jar</code> in the same way as cactus.jar is added.
</note>
<p>
Configure TestServlet in your Container. You may use the example servlet
<code>org.infohazard.servlet.TestServlet</code> that
comes with JUnitEE. Check JUnitEE documentation. TestServlet extends
<code>junit.htmlui.TestServletBase</code> that executes
<code>junit.htmlui.TestRunner</code>
i.e. the JUnitEE interface.
</p>
</section>
<section title="Executing the tests with JUnitEE">
<p>
You request the tests from an html-page in your container. You can
write the name of your testclasses according to the examples with
JUnitEE as:
</p>
<ul>
<li>
a commandstring parameter such as "
<code>/TestServlet?suite=fi.iki.kaila.MyTests&list=yes</code>"
</li>
<li>
as input using
<code><input type="text" name="suite" size=60 /></code> in
a form element that requests TestServlet
</li>
<li>
as one or more option elements in a select element in the
form-element
</li>
</ul>
</section>
<section title="Tell JUnitEE to use Cactus redirector">
<p>
The
<code>cactus.properties</code> file must be located so that your
container can find it e.g. in your containers classpath.
</p>
</section>
</body>
</document>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/browser/navigation.xml
Index: navigation.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE navigation
PUBLIC "-//Apache Software Foundation//DTD Cactus Navigation V1.0//EN"
"file:../../../dtds/navigation-v10.dtd">
<navigation>
</navigation>
1.5 +1 -1 jakarta-cactus/documentation/docs/xdocs/writing/howto_testcase_jsp.xml
Index: howto_testcase_jsp.xml
===================================================================
RCS file: /home/cvs/jakarta-cactus/documentation/docs/xdocs/writing/howto_testcase_jsp.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- howto_testcase_jsp.xml 18 Jan 2003 00:08:34 -0000 1.4
+++ howto_testcase_jsp.xml 28 Jan 2003 15:48:18 -0000 1.5
@@ -65,7 +65,7 @@
routines, and provides many convenient shortcut methods to test
tag handlers. For detailled documentation, check out the
corresponding
- <link href="api/framework-13/org/apache/cactus/extension/jsp/JspTagLifecycle.html">API documentation</link>.
+ <link href="site:javadoc_framework_jsptaglifecycle">API documentation</link>.
Currently, <code>JspTagLifecycle</code> is only available for
JSP 1.2.
</note>
1.6 +2 -2 jakarta-cactus/documentation/docs/xdocs/javadoc_13.xml
Index: javadoc_13.xml
===================================================================
RCS file: /home/cvs/jakarta-cactus/documentation/docs/xdocs/javadoc_13.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- javadoc_13.xml 28 Jan 2003 14:13:44 -0000 1.5
+++ javadoc_13.xml 28 Jan 2003 15:48:18 -0000 1.6
@@ -25,13 +25,13 @@
</tr>
<tr>
<td>
- <link href="site:javadoc_anttasks_api">Javadoc for Cactus custom Ant
+ <link href="site:javadoc_anttasks">Javadoc for Cactus custom Ant
tasks</link>
</td>
</tr>
<tr>
<td>
- <link href="site:javadoc_framework_13_api">Javadoc for Cactus for
+ <link href="site:javadoc_framework_13">Javadoc for Cactus for
J2EE 1.3</link>
</td>
</tr>
1.9 +25 -18 jakarta-cactus/documentation/docs/xdocs/sitemap.xml
Index: sitemap.xml
===================================================================
RCS file: /home/cvs/jakarta-cactus/documentation/docs/xdocs/sitemap.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- sitemap.xml 28 Jan 2003 14:58:22 -0000 1.8
+++ sitemap.xml 28 Jan 2003 15:48:18 -0000 1.9
@@ -47,35 +47,37 @@
<resource id="javadoc_12" target="javadoc_12.html"/>
<resource id="javadoc_13" target="javadoc_13.html"/>
<resource id="faq" target="faq.html"/>
- <resource id="eclipse_plugin" target="spines/eclipse/eclipse_plugin.html"/>
- <resource id="howto_classpath" target="spines/manual/howto_classpath.html"/>
- <resource id="howto_config" target="spines/manual/howto_config.html"/>
+ <resource id="eclipse_plugin" target="petals/eclipse/eclipse_plugin.html"/>
+ <resource id="howto_classpath" target="petals/manual/howto_classpath.html"/>
+ <resource id="howto_config" target="petals/manual/howto_config.html"/>
<resource id="howto_migration" target="howto_migration.html"/>
<resource id="howto_testcase" target="writing/howto_testcase.html"/>
<resource id="howto_testcase_servlet" target="writing/howto_testcase_servlet.html"/>
<resource id="howto_testcase_jsp" target="writing/howto_testcase_jsp.html"/>
<resource id="howto_testcase_filter" target="writing/howto_testcase_filter.html"/>
<resource id="howto_jsp" target="writing/howto_jsp.html"/>
- <resource id="howto_runner" target="spines/howto_runner.html"/>
+ <resource id="howto_runner" target="petals/howto_runner.html"/>
<resource id="howto_security" target="writing/howto_security.html"/>
- <resource id="howto_ant" target="spines/ant/howto_ant.html"/>
- <resource id="howto_ant_cactus" target="spines/ant/howto_ant_cactus.html"/>
- <resource id="howto_ant_install" target="spines/ant/howto_ant_install.html"/>
- <resource id="howto_ant_primer" target="spines/ant/howto_ant_primer.html"/>
+ <resource id="howto_ant" target="petals/ant/howto_ant.html"/>
+ <resource id="howto_ant_cactus" target="petals/ant/howto_ant_cactus.html"/>
+ <resource id="howto_ant_install" target="petals/ant/howto_ant_install.html"/>
+ <resource id="howto_ant_primer" target="petals/ant/howto_ant_primer.html"/>
<resource id="howto_httpunit" target="writing/howto_httpunit.html"/>
<resource id="howto_sample" target="howto_sample.html"/>
<resource id="howto_ejb" target="writing/howto_ejb.html"/>
<resource id="howto_ejb_j2eeri" target="writing/howto_ejb_j2eeri.html"/>
- <resource id="howto_ide" target="spines/manual/howto_ide.html"/>
- <resource id="howto_ide_vajava_wte" target="spines/manual/howto_ide_vajava_wte.html"/>
- <resource id="howto_ide_vajava_tomcat" target="spines/manual/howto_ide_vajava_tomcat.html"/>
- <resource id="howto_ide_jbuilder4" target="spines/manual/howto_ide_jbuilder4.html"/>
- <resource id="howto_ide_jbuilder5" target="spines/manual/howto_ide_jbuilder5.html"/>
- <resource id="howto_tomcat" target="spines/browser/howto_tomcat.html"/>
- <resource id="howto_junitee" target="spines/browser/howto_junitee.html"/>
+ <resource id="howto_ide" target="petals/manual/howto_ide.html"/>
+ <resource id="howto_ide_vajava_wte" target="petals/manual/howto_ide_vajava_wte.html"/>
+ <resource id="howto_ide_vajava_tomcat" target="petals/manual/howto_ide_vajava_tomcat.html"/>
+ <resource id="howto_ide_jbuilder4" target="petals/manual/howto_ide_jbuilder4.html"/>
+ <resource id="howto_ide_jbuilder5" target="petals/manual/howto_ide_jbuilder5.html"/>
+ <resource id="howto_tomcat" target="petals/browser/howto_tomcat.html"/>
+ <resource id="howto_junitee" target="petals/browser/howto_junitee.html"/>
<resource id="mailinglist" target="mailinglist.html"/>
<resource id="cactusname" target="cactusname.html"/>
<resource id="logos" target="participating/logos.html"/>
+ <resource id="logos_img_vgritsenko" target="images/logos/vgritsenko.jpg"/>
+ <resource id="logos_img_vgritsenko2" target="images/logos/vgritsenko2.jpg"/>
<resource id="resources" target="resources.html"/>
<resource id="coverage" target="participating/coverage.html"/>
<resource id="coverage_12" target="participating/coverage_12.html"/>
@@ -87,9 +89,14 @@
<resource id="release_checklist" target="participating/release_checklist.html"/>
<resource id="howto_build" target="participating/howto_build.html"/>
- <resource id="javadoc_anttasks_api" check="false" target="api/anttasks/index.html"/>
- <resource id="javadoc_framework_12_api" check="false" target="api/framework-12/index.html"/>
- <resource id="javadoc_framework_13_api" check="false" target="api/framework-13/index.html"/>
+ <resource id="code_sample_servlet" target="misc/SampleServlet.class"/>
+ <resource id="code_test_sample_servlet" target="misc/TestSampleServlet.class"/>
+ <resource id="code_junit_noframes" target="misc/junit-noframes.xsl"/>
+
+ <resource id="javadoc_anttasks" check="false" target="api/anttasks/index.html"/>
+ <resource id="javadoc_framework_12" check="false" target="api/framework-12/index.html"/>
+ <resource id="javadoc_framework_13" check="false" target="api/framework-13/index.html"/>
+ <resource id="javadoc_framework_jsptaglifecycle" check="false" target="api/framework-13/org/apache/cactus/extension/jsp/JspTagLifecycle.html"/>
<resource id="coverage_clover_12_report" check="false" target="clover-12/index.html"/>
<resource id="coverage_clover_13_report" check="false" target="clover-13/index.html"/>
1.7 +3 -3 jakarta-cactus/documentation/docs/xdocs/javadoc.xml
Index: javadoc.xml
===================================================================
RCS file: /home/cvs/jakarta-cactus/documentation/docs/xdocs/javadoc.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- javadoc.xml 28 Jan 2003 14:13:44 -0000 1.6
+++ javadoc.xml 28 Jan 2003 15:48:19 -0000 1.7
@@ -25,19 +25,19 @@
</tr>
<tr>
<td>
- <link href="site:javadoc_anttasks_api">Javadoc for Cactus custom Ant
+ <link href="site:javadoc_anttasks">Javadoc for Cactus custom Ant
tasks</link>
</td>
</tr>
<tr>
<td>
- <link href="site:javadoc_framework_12_api">Javadoc for Cactus for
+ <link href="site:javadoc_framework_12">Javadoc for Cactus for
J2EE 1.2</link>
</td>
</tr>
<tr>
<td>
- <link href="site:javadoc_framework_13_api">Javadoc for Cactus for
+ <link href="site:javadoc_framework_13">Javadoc for Cactus for
J2EE 1.3</link>
</td>
</tr>
1.6 +2 -2 jakarta-cactus/documentation/docs/xdocs/javadoc_12.xml
Index: javadoc_12.xml
===================================================================
RCS file: /home/cvs/jakarta-cactus/documentation/docs/xdocs/javadoc_12.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- javadoc_12.xml 28 Jan 2003 14:13:44 -0000 1.5
+++ javadoc_12.xml 28 Jan 2003 15:48:19 -0000 1.6
@@ -25,13 +25,13 @@
</tr>
<tr>
<td>
- <link href="site:javadoc_anttasks_api">Javadoc for Cactus custom Ant
+ <link href="site:javadoc_anttasks">Javadoc for Cactus custom Ant
tasks</link>
</td>
</tr>
<tr>
<td>
- <link href="site:javadoc_framework_12_api">Javadoc for Cactus for
+ <link href="site:javadoc_framework_12">Javadoc for Cactus for
J2EE 1.2</link>
</td>
</tr>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/eclipse/navigation.xml
Index: navigation.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE navigation
PUBLIC "-//Apache Software Foundation//DTD Cactus Navigation V1.0//EN"
"file:../../../dtds/navigation-v10.dtd">
<navigation>
</navigation>
1.1 jakarta-cactus/documentation/docs/xdocs/petals/eclipse/eclipse_plugin.xml
Index: eclipse_plugin.xml
===================================================================
<?xml version="1.0"?>
<document id="eclipse_plugin">
<properties>
<title>Architecture of the Eclipse Plugin for Cactus</title>
<authors>
<author name="Julien Ruaux" email="jruaux@octo.com" />
</authors>
</properties>
<body>
<section title="Overview">
<p>
Cactus uses and extends JUnit. It might then seem natural
that 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: setup of the container (deployment) and startup</li>
<li>execute tests using the JUnit plugin methods</li>
<li>tear down tests: stop the container and clean the deployment.</li>
</ul>
<p>
In its actual state the plugin uses Ant scripts for these
container setup and teardown.
</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 Tomcat 4.0 and Weblogic 7.0.
</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 by the
<code>WarBuilder</code>
class, and relies on an Ant script for that.
</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 been effectively 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.
</p>
<p>
For that the JUnit plugin had to be modified, a
patch is avaible at the root of the Cactus CVS.
</p>
<p>
The
<code>JUnitViewFinder</code>
class is launched which looks for the
JUnitView, so that we can eventually register our
listener.
</p>
</li>
<li>
Tests environment cleaning
<p>
After the tests have completed, work has to be
done to stop the container and delete all
configuration files and the war file we created
before.
</p>
</li>
</ul>
</section>
</section>
<section title="What has been done so far">
<p>
In its actual state the plugin is a proof of concept. It is
able to run the distribution sample tests.
</p>
</section>
<section title="Features">
<ul>
<li>a minimalistic launch configuration</li>
<li>a minimalistic launch shortcut</li>
<li>a minimalistic launch configuration tab group</li>
</ul>
<ul>
<li>
Validates calling Ant script before and after running
the tests to package and deploy the application to the
container and start it.
</li>
<li>
Executes the Cactus Ant script for Tomcat before
starting the JUnit Test Runner (and after). This Ant script
needs to be part of the Cactus plugin and does the
following: creates a WAR from the application sources and
start Tomcat. After the test is finished a second script is
run to stop Tomcat.
</li>
</ul>
<ul>
<li>Cactus preference page (see below for content)</li>
<li>Support for several containers</li>
<li>
On preference page and on Cactus TabGroup page: ability to
choose the port on which the container is started.
</li>
<li>
On preference page, ability to specify the working
directory where the Cactus plugin will create all its files
(packaged war, app server config files, etc)
</li>
<li>Minimal plugin documentation</li>
</ul>
</section>
<section title="What is next">
<p>
In order to have a production-quality tool the following
points must be done:
</p>
<ul>
<li>integrate the plugin to the Cactus build process</li>
<li>automate tests on the plugin</li>
<li>ability to leave the container running between redeployments</li>
<li>
the user must be able to provide its own web.xml file.
Otherwise the plugin will use the one provided by default.
</li>
</ul>
</section>
</body>
</document>
1.4 +8 -5 jakarta-cactus/documentation/docs/xdocs/participating/logos.xml
Index: logos.xml
===================================================================
RCS file: /home/cvs/jakarta-cactus/documentation/docs/xdocs/participating/logos.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- logos.xml 18 Jan 2003 00:08:33 -0000 1.3
+++ logos.xml 28 Jan 2003 15:48:19 -0000 1.4
@@ -52,8 +52,10 @@
.
</p>
- <link href="images/logos/vgritsenko.jpg"><figure src="images/logos/vgritsenko.jpg" height="185" width="119"
- alt="Proposition 2: Tomahawk"/></link>
+ <link href="site:logos_img_vgritsenko">
+ <figure src="images/logos/vgritsenko.jpg" height="185" width="119"
+ alt="Proposition 2: Tomahawk"/>
+ </link>
</section>
@@ -77,9 +79,10 @@
.
</p>
- <link href="images/logos/vgritsenko2.jpg">
- <figure src="images/logos/vgritsenko2.jpg" alt="Proposition 3: Severe testing"
- height="64" width="311"/></link>
+ <link href="site:logos_img_vgritsenko2">
+ <figure src="images/logos/vgritsenko2.jpg" alt="Proposition 3: Severe testing"
+ height="64" width="311"/>
+ </link>
</section>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>