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

For more information, please explore the Attic.

Introduction

This tutorial explains how to build Cactus from SVN or from a source download.

If you just want to use Cactus, it will be easier to simply download a nightly build (if you need the latest and greatest), or the latest stable release otherwise.

Getting the Source

There are two ways to obtain the source code for Cactus: either directly from SVN, or by downloading a prepackaged source archive.

SVN

To get the current development version of the Cactus source code, you'll need to download the source from SVN. To do this, you'll need to have a SVN client installed.

Detailed instructions about accessing the Apache SVN repository can be found here.

Prepackaged Source Archives

If you don't have access to the Apache SVN repository (because you're behind a firewall, for example), or you don't need to be absolutely up to date, you can download an archive containing a snapshot of the Cactus code base.

Such archives are made available for each release as well as for the nightly builds. Go here to find out about the download locations.

Prerequisites

The following sections list java libraries that you need to have present in your local filesystem for the build. Do not worry! We won't ask you to fish around to get these libraries :-) The Maven2 build system does this automatically. The next section on Performing Builds explains how to use it.

Maven

To build Cactus from source, you'll need to have Maven 2.0.4 (or later) installed. For building the samples module you'll need to have Ant 1.6.5 (or later) installed.

You'll need to have the following libraries put in your [ANT_HOME]/lib/ directory.

Name Optional? Version Description
junit.jar No 3.8.1 or later The JUnit unit testing framework.
ivy-[version].jar No 2.0.0-beta1 The Ivy dependency management library.
xalan.jar Yes. Required only if you're building with a JDK version lower than 1.4. You should also be able to use a different XSLT processor. (not sure - we need to find the version) A XSLT processor.
clover.jar Yes. Required only to run the release build of Cactus or if you have turned on "clovering" (clover.enable = true). 1.2.3 Clover code coverage tool.

Required Libraries

In addition, Cactus depends on a number of additional external libraries at build time. The Maven2 build system will download automatically these dependencies in the local repository.

Name Version Description
aspectjrt.jar 1.1.1 + The AspectJ runtime.
aspectjtools.jar 1.1.1 + The AspectJ compiler and other tools.
commons-httpclient.jar 2.0 + Jakarta Commons HttpClient.
commons-logging.jar 1.0.3 + Jakarta Commons Logging.
junit.jar 3.8.1 + The JUnit framework.

This JAR file must be placed in the lib directory of your Ant installation, or Ant will not be able to load the required classes.
servlet.jar 2.2, 2.3 or 2.4 The Servlet/JSP API.

This JAR file comes with your servlet container or application server. To perform a complete build of Cactus, you'll need to have JARs for versions 2.2, 2.3 and 2.4 of the servlet API.
checkstyle.jar 3.4 The Checkstyle code auditing tool.
antlr.jar 2.7.2 The ANTLR translator generator (required by Checkstyle).
commons-beanutils.jar 1.6.1 Jakarta Commons BeanUtils (required by Checkstyle).
commons-collections.jar 2.1 Jakarta Commons Collections (required by Checkstyle).
regexp.jar 1.3 Jakarta RegExp (required by Checkstyle).
httpunit.jar 1.5.4 + HttpUnit. Required for testing the HttpUnit integration.
nekohtml.jar 0.8.1 The Cyberneko HTML parser (required by HttpUnit).
log4j.jar 1.2.8 Jakarta Log4j. Required for packaging the Cactus distribution.
jstl.jar 1.0.2 JSP Standard Tag Library. Required for compiling and running the servlet sample test suite on J2EE 1.3.
standard.jar 1.0.2 Jakarta Standard Taglib. Required for compiling and running the servlet sample test suite on J2EE 1.3.
jetty.jar 4.2.17 + Jetty Servlet container. Required to build and run the Jetty sample project.
jasper-compiler.jar 4.1.30 + JSP engine required by Jetty to process JSPs. Required to build and run the Jetty sample project.
jasper-runtime.jar 4.1.30 + JSP engine required by Jetty to process JSPs. Required to build and run the Jetty sample project.
jmock.jar 1.2.0 Mock object library used by several unit tests.
cargo-uberjar.jar 0.9 Cargo framework for manipulating the different containers.
cargo-ant.jar 0.9 Cargo-ant tasks for manipulating the different containers.

Understanding the Directory Structure

The Cactus project is divided into several modules, each having its own build:

cactus-site/
The Cactus documentation.
framework/
The Cactus framework itself.
integration/
Various tool integration modules.
ant/
Ant tasks and support classes provided by Cactus.
eclipse/
Plugins for integration with the open-source IDE Eclipse.
maven/
Maven plugins for Cactus.
shared-api/
Some shared resources that are used by all of the other integration componenets..
samples/
Sample applications using Cactus.
servlet
Sample web-application using Cactus. It currently also acts as functional and regression test suite for the Cactus framework. (in order to build it correctly you will have to specify your [TOMCAT_HOME] folder in the build.properties file in the samples directory)
ejb
Sample EJB using Cactus. It currently also acts as functional and regression test suite for the Cactus framework. (in order to build it correctly you will have to specify your [JBOSS_HOME] folder in the build.properties file in the samples directory)

All modules follow a similar directory structure and they all use Maven as the build tool.

Performing Maven builds

Good news: it should be extremely easy to build Cactus from the sources! :-) After ensuring that you connected to internet, type the following command one after another:

  • mvn clean install: This will automatically download all the required dependencies. It takes about 7 minutes on a 512 kbps internet connection the first time. If you're behind a firewall, you'll need to read this tutorial for specifying a proxy.
The build result will be located in the [USER_HOME]/.m2/repository/org/apache/cactus/ directory. Some projects depend on others and thus you may need to run the build for those projects first. For example, the servlet sample depends on the framework and the Ant integration, so these will need to be built before the servlet sample is built. To avoid these problems you can simply type mvn install at the top level as it builds the different projects in the correct order.

Before creating a patch, and especially before committing changes, be sure to run both the checkstyle and test plugins of the corresponding module. Often we will also need to run the servlet sample tests, because they effectively represent the regression test suite for Cactus. You might want to simply perform a full rebuild to be sure that nothing has been negatively affected by your changes.

Create the Cactus Archives From Source

So after you have checked out the source of Cactus there is one more step to make in order to get the assemblies. First, as usual, ensure that you are connected to the internet. After that go to the top-folder of the Cactus check-out and follow these steps.

  • In order to make the archives you need to prepare the content for the archives. First package all the jars with: mvn clean package: This will make all of the submodules to package their jars.
  • mvn assembly:assembly -N: This will automatically start making the assemblies, and once the download of all of the required dependencies is finished you will see a target/ folder in the top-level folder. This folder will contain the assemblies for the Cactus project.

Generating the Cactus web-site.

If you want to generate the Cactus web-site, this is what you should do:
  • Navigate to the top-folder of the Cactus check-out and generate the javadoc:

    mvn javadoc:javadoc

    and XRef:

    mvn jxr:jxr

    contents of the web-site. These two line will generate the reports in the cactus-site/src/site/resources/ folder.
  • After that navigate to the cactus-site submodule:

    cd cactus-site/

    and execute the following:

    mvn site:site

    As a result you will have the Cactus web-site generated in the [CACTUS_ROOT]/cactus-site/target/site folder.