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 cm...@apache.org on 2003/05/06 18:11:09 UTC
cvs commit: jakarta-cactus/documentation/docs/xdocs/integration howto_classpath.xml howto_config.xml
cmlenz 2003/05/06 09:11:09
Added: documentation/docs/xdocs/integration howto_classpath.xml
howto_config.xml
Removed: documentation/docs/xdocs/integration/manual
howto_classpath.xml howto_config.xml
Log:
Move files directly into the 'integration' directory
Revision Changes Path
1.1 jakarta-cactus/documentation/docs/xdocs/integration/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/integration/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>
<th>Property Name</th>
<td>
<code>cactus.contextURL</code>
</td>
</tr>
<tr>
<th>Required</th>
<td>
Yes
</td>
</tr>
<tr>
<th>Description</th>
<td>
Webapp Context under which the application to test runs.
</td>
</tr>
<tr>
<th>Example</th>
<td>
<code>cactus.contextURL = http://localhost:8080/test</code>
</td>
</tr>
</table>
<p>
<br/>
</p>
<table>
<tr>
<th>Property Name</th>
<td>
<code>cactus.servletRedirectorName</code>
</td>
</tr>
<tr>
<th>Required</th>
<td>
No. Defaults to "<code>ServletRedirector</code>".
</td>
</tr>
<tr>
<th>Description</th>
<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>
<th>Example</th>
<td>
<code>cactus.servletRedirectorName = ServletRedirector</code>
</td>
</tr>
</table>
<p>
<br/>
</p>
<table>
<tr>
<th>Property Name</th>
<td>
<code>cactus.jspRedirectorName</code>
</td>
</tr>
<tr>
<th>Required</th>
<td>
No. Defaults to "<code>JspRedirector</code>".
</td>
</tr>
<tr>
<th>Description</th>
<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>
<th>Example</th>
<td>
<code>cactus.jspRedirectorName = JspRedirector</code>
</td>
</tr>
</table>
<p>
<br/>
</p>
<table>
<tr>
<th>Property Name</th>
<td>
<code>cactus.filterRedirectorName</code> (For J2EE API 1.3 only)
</td>
</tr>
<tr>
<th>Required</th>
<td>
No. Defaults to "<code>FilterRedirector</code>".
</td>
</tr>
<tr>
<th>Description</th>
<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>
<th>Example</th>
<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>
---------------------------------------------------------------------
To unsubscribe, e-mail: cactus-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: cactus-dev-help@jakarta.apache.org