<html>

<head>
<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252">
<title>Cactus Integration in WTP</title>
<link rel="stylesheet" href="../../../../default_style.css">
</head>

<body LINK="#0000ff" VLINK="#800080">
<div align="right">&nbsp; <font face="Times New Roman, Times, serif" size="2">Copyright
  &copy; BEA Systems, Inc</font>
  <table border=0 cellspacing=0 cellpadding=2 width="100%">
    <tr>
      <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">&nbsp;</font></font></b></td>
    </tr>
  </table>
</div>
<div align="left">
  <h1><img src="../../../../images/Idea.jpg" height=86 width=120 align=CENTER></h1>
</div>
<p>&nbsp;</p>

<h1 ALIGN="CENTER">Cactus Integration in the Web Tools Project</h1>

<blockquote>
<b>Summary</b>

<br>
  This article briefly explains Cactus, its common uses and advantages and then provides a step-by-step tutorial on how to use the Cactus integration provided by WTP. The article assumes that you are familiar with <a href="http://www.junit.org/" target="_top">JUnit</a> and the basics of using WTP to build, deploy and run web projects.
  <p><b> Daniel R Somerfield, BEA Systems</b> <br>
    <font size="-1">May 31, 2005</font> </p>
</blockquote>
<hr width="100%">
<h2>What is Cactus?</h2>
<p>
	Cactus is actually very, very simple. It is often valuable to be able to test components (plain Java classes, Servlets, EJBs, etc.) within the container in which they will eventually be deployed. Cactus provides proxies for unit tests so that although you run the vanilla JUnit client (or any other JUnit client) locally, the tests are actually invoked on the target container. A servlet within the container fields requests from your local test case and delegates that actual running of the test to the test case running on the server and reports back the results. The test case can be deployed locally or remotely. Either way, Cactus works the same since it uses HTTP to do the invocation and reporting.
</p>
<p>
	Really, the only trick to using Cactus is setup and deployment. Fortunately, we get help from the Web Tools Project on the deployment. At the present, setup is still a manual process (something that will hopefully change in the future).
</p>
<hr width="100%">
<h2>Using WTP Cactus Integration</h2>
<p>
We start off with an existing web project and a class we want to test on Tomcat or any other WTP-supported servlet container. Let's say we have a <a href="code/components/security/PermissionManager.java">PermissionManager</a> class we want to test to see if it is correctly managing the permissions in the HTTP session. The important part of the PermissionManager is this method:
	<pre>
	public void validate(HttpServletRequest request)
	throws InsufficientPermissionsException
	{
		Permission permission = (Permission) request.getSession().getAttribute(TOKEN_KEY);
		if (!permission.implies(fPermissionRequired))
		{
			throw new InsufficientPermissionsException("You do not have permission for that operation");
		}
	}
	</pre>
	In theory, it should check whether the user has permissions for the operation and if not, it should throw an <a href="code/components/security/InsufficientPermissionsException.java">InsufficientPermissionsException</a>. To check that it is doing it's job, we will want to write a unit test.
</p>
<p>
	But first, we need to get the cactus dependencies available on the class path. You will want to put them in the WebModule under WEB-INF/lib so that they are visible in the web module at runtime. The dependencies are all from the Cactus 1.7 distribution (available at <a href="http://jakarta.apache.org/site/downloads/downloads_cactus.cgi">http://jakarta.apache.org/site/downloads/downloads_cactus.cgi</a>). As of the writing of this document, they are:
	<ul>
		<li>cactus-1.7.jar
		<li>junit-3.8.1.jar
		<li>aspectjrt-1.2.1.jar
		<li>commons-logging-1.0.4.jar
		<li>commons-httpclient-2.0.2.jar
	</ul>
	Once you have added the libraries to the WEB-INF/lib (you can simply drag and drop them there), you can either add the libraries to the the build path by editing the build path in the project properties, or by right-clicking them while in the Java Perspective and choosing "Build Path->Add to Build Path".
</p>
<p>
	Now that we have the dependencies on the classpath, we can write our test. Rather than the usual JUnit TestCase, we need to extend ServletTestCase. As in JUnit, the testXXX() methods are discovered via introspection and run when the test executes. Unless you have any special needs via the beginXXX() and endXXX() client-side methods, the test will really look like any other unit test (see the cactus docs for more details on using beginXXX() and endXXX()).

	First let's write a test method to make sure the PermissionManager class is allowing requests it is supposed to. In the JavaSource folder, create the <a href="code/components/security/test/PermissionManagerTest.java">PermissionManagerTest</a> class and add the following method:
<pre>
	public void testPermissionManagerAllow() throws Exception
	{
		//Make sure that the AllPermission gives us permission to our test permission
		session.setAttribute(PermissionManager.TOKEN_KEY, new AllPermission());
		PermissionManager manager = new PermissionManager(new TestPermission("Test"));
		manager.validate(request);
	}
</pre>

	The test is quite simple. It just calls the validate method. If the validation fails, an InsufficientPermissionException will be thrown and the test will fail.

	Before we can run the test, we need to set up Cactus. In the web module, under WebContent/WEB-INF there should be a web.xml. To this file, add the following mark-up before the final web-app tag:

<pre>

    &lt;filter&gt;
        &lt;filter-name&gt;FilterRedirector&lt;/filter-name&gt;
        &lt;filter-class&gt;org.apache.cactus.server.FilterTestRedirector&lt;/filter-class&gt;
    &lt;/filter&gt;

    &lt;filter-mapping&gt;
        &lt;filter-name&gt;FilterRedirector&lt;/filter-name&gt;
        &lt;url-pattern&gt;/FilterRedirector&lt;/url-pattern&gt;
    &lt;/filter-mapping&gt;

    &lt;servlet&gt;
        &lt;servlet-name&gt;ServletRedirector&lt;/servlet-name&gt;
        &lt;servlet-class&gt;org.apache.cactus.server.ServletTestRedirector&lt;/servlet-class&gt;
    &lt;/servlet&gt;

    &lt;servlet&gt;
        &lt;servlet-name&gt;JspRedirector&lt;/servlet-name&gt;
        &lt;jsp-file&gt;/jspRedirector.jsp&lt;/jsp-file&gt;
    &lt;/servlet&gt;

    &lt;servlet-mapping&gt;
        &lt;servlet-name&gt;ServletRedirector&lt;/servlet-name&gt;
        &lt;url-pattern&gt;/ServletRedirector&lt;/url-pattern&gt;
    &lt;/servlet-mapping&gt;

    &lt;servlet-mapping&gt;
        &lt;servlet-name&gt;JspRedirector&lt;/servlet-name&gt;
        &lt;url-pattern&gt;/JspRedirector&lt;/url-pattern&gt;
    &lt;/servlet-mapping&gt;
</pre>

</p>
<p>
	This configures the redirectors that need to field the HTTP requests from Cactus and execute the unit test in the container.

	Once you have saved the web.xml, you might need to restart the HTTP container if you have already started it. Otherwise, you can right-click on the test case and choose "Run->Run on Server". If you want to debug the component or the test you can choose "Debug->Debug on Server" instead. Assuming our test passes, we should get that wonderful JUnit "green bar" in the JUnit window.
</p>
<!-- Note: this behavior changed in RC1. Leaving the comment just in case it changes back.
<p>
	Incidentally, by default the JUnit window will only appear on a failure. If you would like the JUnit window to appear all the time, go to the Preferences under Java->JUnit and disable "Show junit results view only when a failure or error occurs".
</p>
-->
<p>
	Now we write a second test method to make sure the PermissionManager is denying requests if you only have the insufficient <a href="code/components/security/ApplicationPermission.java">ApplicationPermission</a>:
<pre>
	public void testPermissionManagerDisallow() throws Exception
	{
		try
		{
			//Make sure that the ApplicationPermission does not give test permission
			session.setAttribute(PermissionManager.TOKEN_KEY, new ApplicationPermission("Login"));
			PermissionManager manager = new PermissionManager(new TestPermission("Test"));
			manager.validate(request);

		} catch (InsufficientPermissionsException e)
		{
		}
		fail("Should not have allowed this request");
	}
</pre>
Ooops--the red bar. It looks like our test failed. Looking at it, it is obvious why. If the InsufficientPermissionsException is being caught and execution is falling through to the fail() call. What we really meant was this:
<pre>
	public void testPermissionManagerDisallow() throws Exception
	{
		try
		{
			//Make sure that the ApplicationPermission does not give test permission
			session.setAttribute(PermissionManager.TOKEN_KEY, new ApplicationPermission("Login"));
			PermissionManager manager = new PermissionManager(new TestPermission("Test"));
			manager.validate(request);
			fail("Should not have allowed this request");
		} catch (InsufficientPermissionsException e)
		{
		}
	}
</pre>
Much better. Back to the green bar.
</p>
That's really all there is to it. All the normal JUnit best practices apply. You can aggregate tests with Suites and run Cactus tests and vanilla JUnit tests side-by-side. For more sophisticated Cactus test development, such as testing JSPs and Filters and using authentication, consult the <a href="http://jakarta.apache.org/cactus/" target="_top">Cactus website</a>.
<hr width="100%">
<h2>Source Code</h2>
<p>The source code for this article is pretty contrived and you could easily come up with your own, but if you want it, the entire web project is available in this <a href="code/CactusWebProject.zip">zip file</a>.
<hr width="100%">
</body>
</html>