2011/08/05 - Jakarta Cactus has been retired.

For more information, please explore the Attic.

CactifyWar Task

The task cactifywar allows the enhancement of an existing web-application archive (WAR) with the elements needed to run Cactus in-container tests. This includes adding the definitions of the test redirectors to the deployment descriptor, as well as adding the libraries that Cactus requires on the server side (see the Classpath Guide for details).

If you want to use the HttpUnit integration in your tests, you'll need to explicitly add the httpunit.jar to the cactified WAR. You can easily do this by using a nested <lib> element.

The cactifywar task extends the built-in Ant task war, so it also supports all attributes and nested elements that war supports.

Parameters

As this task is an extension of the war task, it also supports all the attributes supported by the war task. The only exception is the warfile attribute, which has been renamed to destfile for the cactifywar task.

Name Description Required
destfile The location of the cactified web-application archive to create. Yes
srcfile The original web-application archive that is going to be cactified. If this attribute is not specified, a new web-app archive will be created. You'll need to specify the version attribute in that case. No
mergewebxml Allows the specification of a web deployment descriptor whose content will get merged into the resulting descriptor. This is only required for purposes like adding special security constraints for testing, as the Cactus test redirectors will be added to the cactified deployment descriptor anyway. The merging of the descriptors is based on the same principles as used by the webxmlmerge task. No
version The version of the web application archive to create if no source archive has been specified with the srcfile attribute. Can be either 2.2 or 2.3. No, unless the srcfile attribute is omitted

Nested Elements

As this task is an extension of the war task, it also supports all attributes that the war task supports. In addition, you can specify the URL-patterns to map the Cactus test redirectors to which the nested elements filterredirector, jspredirector and servletredirector. If you don't specify those elements, the test redirectors will be mapped to the default URL-pattern.

filterredirector

The filterredirector element lets you specify the URL pattern to which the Cactus filter test redirector is mapped in the web application.

Parameters

Name Description Required
name The name of the filter redirector. Only needed if you want to add multiple filter redirectors to the deployment descriptor. No, the default is FilterRedirector
mapping The URL-pattern to which the redirector should be mapped. Must start with a forward slash ("/"). No, the default is /FilterRedirector
roles A comma-separated list of role names which will be granted access to the redirector. If this attribute is ommitted, access to the redirector will not be constrained. Unless the roles are already defined in the deployment descriptor, they will be added automatically. No
This element will be ignored for Servlet 2.2 web applications.

jspredirector

The jspredirector element lets you specify the URL pattern to which the Cactus JSP test redirector is mapped in the web application.

Parameters

Name Description Required
name The name of the JSP redirector. Only needed if you want to add multiple JSP redirectors to the deployment descriptor. No, the default is JspRedirector
mapping The URL-pattern to which the redirector should be mapped. Must start with a forward slash ("/"). No, the default is /JspRedirector
roles A comma-separated list of role names which will be granted access to the redirector. If this attribute is ommitted, access to the redirector will not be constrained. Unless the roles are already defined in the deployment descriptor, they will be added automatically. No

servletredirector

The servletredirector element lets you specify the URL pattern to which the Cactus servlet test redirector is mapped in the web application.

Parameters

Name Description Required
name The name of the servlet redirector. Only needed if you want to add multiple servlet redirectors to the deployment descriptor. No, the default is ServletRedirector
mapping The URL-pattern to which the redirector should be mapped. Must start with a forward slash ("/"). No, the default is /ServletRedirector
roles A comma-separated list of role names which will be granted access to the redirector. If this attribute is ommitted, access to the redirector will not be constrained. Unless the roles are already defined in the deployment descriptor, they will be added automatically. No

xmlcatalog

The xmlcatalog element can be used to perform Entity and DTD resolution. This is a built-in Ant type. See the Ant Manual for details.

The cactifywar task resolves the DTDs of web-app descriptors (version 2.2 as well as 2.3) automatically to copies stored in the JAR. So normally, you shouldn't need to specify a nested xmlcatalog element. Further, actually specifying it will disable the default behaviour, and you'll need to provide the web-app DTDs yourself.

Examples

The following example demonstrates the simplest-possible use of the task. It will add the redirectors with the default mappings to the cactified WARs, as well as the Cactus libraries and the JSP page needed for the JSP redirector.

<cactifywar srcfile="${build.dir}/my.war" destfile="${build.dir}/test.war"/>

The next example demonstrates how to modify the mappings of the redirectors.

<cactifywar srcfile="${build.dir}/my.war" destfile="${build.dir}/test.war">
  <filterredirector mapping="/test/filterRedirector"/>
  <jspredirector mapping="/test/jspRedirector"/>
  <servletredirector mapping="/test/servletRedirector"/>
</cactifywar>

In the following example, we add the test classes as well as the HttpUnit library to the cactified WAR.

<cactifywar srcfile="${build.dir}/my.war" destfile="${build.dir}/test.war">
  <classes dir="${build.dir}/classes/test" includes="**/*.class"/>
  <lib file="${httpunit.jar}"/>
</cactifywar>

In the next example, we add a security-constrained instance of the servlet redirector to be able to run tests using authentication (see Using Authentication for details). Note that you need to provide an empty servlet redirector element, so that the default redirector is included along side the secured redirector (it would just be overridden otherwise).

<cactifywar srcfile="${build.dir}/my.war" destfile="${build.dir}/test.war">
  <servletredirector/>
  <servletredirector name="ServletRedirectorSecure"
      mapping="/ServletRedirectorSecure" roles="test"/>
</cactifywar>