A Maven 2 plugin that wraps the Cargo Java API

Functional tests The usage of Cargo for executing functional tests on a container do not need this m2 plugin. You should directly use the Cargo Java API from your Java unit test classes (JUnit, TestNG, etc), as described on http://tinyurl.com/btmwa.

Installation

The Cargo m2 plugin is currently hosted on a private repository on codehaus. This repository is currently not synced to ibiblio so you'll need the following <pluginRepository> definition in your pom.xml if you want to use the Cargo plugin:

Features

As usual the best way to learn to use a tool is through examples. We have several sample projects that we use as our internal functional tests suite. We'd really recommend that you check them out. In addition here are the typical uses cases coverer by the plugin:

• Start/stop a container
• Deploy to a running container
• Generate container configuration deployment structure

The configuration elements are described in the configuration section.

Start/stop a container

Ability to start/stop a container (possibly deploying some deployables to it as it starts). In this scenario Maven 2 is used as a convenience to easily and quickly start a container.

Example of m2 minimal configuration:

This minimal configuration allows you to configure a default Tomcat 5.x standalone configuration (when the configuration type is not defined as above, the plugin will use a standalone configuration by default) in ${basedir}/target/resin. You can start the Tomcat 5.x container with mvn cargo:start and stop it with mvn cargo:stop.

Example of a full-fledged m2 configuration:

This example shows the usage of a standalone configuration for configuring Orion 2.x. Note that it's possible to define J2EE archives in the <configuration> element and they'll be deployed before the container starts (this is what we call static deployment). We have also defined some configuration properties to tell Cargo to configure Orion 2.x to start on port 8080 and to output highly verbose logs (useful for debugging).

If you have a container that is already installed and configured, say with other J2EE archives already in there, you may want to use an existing configuration. This done by specifying <type>existing</type>. In that case you won't be able to control the configuration from Cargo (like port to use, logging levels, etc) as it'll be defined externally.

Deploy to a running container

Ability to deploy to a remote container. Very useful for automating deployments with Maven (cargo:deploy).

Not all containers have a Deployer implemented We haven't finished implementing Deployers for all containers yet. Please check if your favorite container has it implemented. If not you'll need to deploy your J2EE archives by defining them in a standalone local configuration as shown in the start/stop a container use case above.

Example of m2 configuration using a local deployer

In addition, if your project is of type war or ear the generated artifact will be automatically added to the list of deployables to deploy. You can control the location of the artifact by using the <deployableLocation> element (it defaults to ${project.build.directory}/${project.build.finalName}.${project.packaging}). In addition if you want to wait for the deployment to be finished you can specify a <pingURL> (none is used by default). Here's an example:

Example of m2 configuration using a remote deployer

Generate container configuration deployment structure

Ability to create a fully working custom configuration and possibly package some deployables in it. Then deliver this configuration as an artifact (cargo:package).

TODO

Configuration

TODO

Additional notes and Todos

• Proposal: We'll define a default for all configuration element so that just typing "mvn cargo:start" without any config will work. Let's use Jetty as the default container for war packaging (because it's the fastest to load) and Orion as the default for EAR packaging (again because it's the fastest we have for now - We really need to implement support for OpenEJB though).
• TODO: For the deployer, allow replacing <type> by <class> if the user wants to specify his own deployer.

Tips

• Starting mutiple containers conditionally

Starting mutiple containers conditionally

Maven 2 supports the notion of profiles which can be used with Cargo to decide for example when to run tests on a specific container. Here's how you could use the Cargo m2 plugin to that effect:

Then to start the tomcat 5.x container you would type mvn -P tomcat5x integration-test. if you want to start both containers you would type mvn -P tomcat5x,orion2x integration-test.

If you want to define a profile as the default you can use the <activation> element with an activation strategy. For example if you want a profile to be always on, use:

TODO: Show how to share configuration data between profiles (this should work by defining the default config data in the <build> element).