Cargo Maven2 plugin

Cargo - Maven2 plugin

A Maven 2 plugin that wraps the Cargo Java API

Functional tests The usage of Cargo for executing functional tests on a container does not mandate this m2 plugin. You could also directly use the Cargo Java API from your Java unit test classes (JUnit, TestNG, etc), as described on the Functional testing page. The choice is yours, thought the Maven2 plugin is generally more straightforward to use and integrates better with the whole build process (with profiles, easier to use deployer, proxy server support, etc.)

Table of Contents

The documentatation for this Maven2 plugin includes:

• Installation: explains how to install the plugin
• Getting started: explains how to use the plugin on several use cases
• Reference Guide: provide reference documentation for all configuration options
• Tips: tips for using the plugin

 

Getting Started

Very quick start

CARGO can be directly run on any existing Maven2 Java EE project (WAR, EAR or other) by running:

mvn clean verify org.codehaus.cargo:cargo-maven2-plugin:run

This will create a default Jetty 6.x embedded container and start it using the Cargo Maven2 plugin with your Maven2 project's deployable (a WAR, for example) deployed to it; so you can run manual tests (as a first introduction).

What is magic is that if you now want to run the same tests with Tomcat 7.x you simply need to run (in one line):

mvn clean verify org.codehaus.cargo:cargo-maven2-plugin:run
    -Dcargo.maven.containerId=tomcat7x
    -Dcargo.maven.containerUrl=http://archive.apache.org/dist/tomcat/tomcat-7/v7.0.16/bin/apache-tomcat-7.0.16.zip

That command will automatically download Tomcat 7.0.16 from the specified URL (taking into account any proxy server setting you would have in Maven2/Maven3), instantiate the container, create a local configuration with your application and run it. It will also save the downloaded container in the default directory (see the Maven2 Plugin Reference Guide for details), so it won't get downloaded when you run the same command twice.

Now, if you want to run this time on Glassfish 3.x with with the HTTP port set to 9000, run:

mvn clean verify org.codehaus.cargo:cargo-maven2-plugin:run
    -Dcargo.maven.containerId=glassfish3x
    -Dcargo.maven.containerUrl=http://download.java.net/glassfish/3.1.1/release/glassfish-3.1.1.zip
    -Dcargo.servlet.port=9000

CARGO's main advantage is that the commands and configuration remains the same for any version of any container supported by CARGO -be it Tomcat, Jetty, JBoss, JOnAS, GlassFish, WebLogic, etc.

Like it? Well, keep on reading, then!

More examples

As usual the best way to learn to use a tool is through examples.

We have several Maven2 Archetypes that contain sample Maven2/Maven3 projects with different use cases for the CARGO plugin, we would really recommend that you check them out. For more details, read here: Maven2 Archetypes.

In addition here are the typical uses cases covered by the plugin:

• Deploying to a running container
• Generating a container configuration deployment structure
• Merging WAR files
• Starting and stopping a container
  • Configuration files option — The configuration files are the files to add to your container's configuration. It is internally used by some containers and is accessible for you can to add extra files.
  • DataSource and Resource Support
    • Containers with DataSource and Resource support

The Cargo Maven plugin in detail

Here are the different goals available to call on this plugin:

Goals	Description
cargo:start	Start a container. That goal will: If the plugin configuration requires so, installs the container. If the plugin configuration defines a container with a standalone local configuration, it will create the configuration. If the plugin configuration contains one or more deployables, it will deploy these to the container automatically. If the plugin configuration contains no deployables but the project's packaging is Java EE (WAR, EAR, etc.), it will deploy the project's deployable to to the container automatically. And, of course, start the container. Note: A container that's started with cargo:start will automatically shut down as soon as the parent Maven instance quits (i.e., you see a BUILD SUCCESSFUL or BUILD FAILED message). If you want to start a container and perform manual testing, see our next goal cargo:run.
cargo:run	Start a container and wait for the user to press CTRL + C to stop. That goal will: If the plugin configuration requires so, installs the container. If the plugin configuration defines a container with a standalone local configuration, it will create the configuration. If the plugin configuration contains one or more deployables, it will deploy these to the container automatically. If the plugin configuration contains no deployables but the project's packaging is Java EE (WAR, EAR, etc.), it will deploy the project's deployable to to the container automatically. And, of course, start the container and wait for the user to press CTRL + C to stop.
cargo:stop	Stop a container.
cargo:configure	Create the configuration for a local container, without starting it. Note that the cargo:start and cargo:run goals will also install the container automatically (but will not call cargo:install).
cargo:package	Package the local container.
cargo:deployer-deploy (aliased to cargo:deploy)	Deploy a deployable to a running container.
cargo:deployer-undeploy (aliased to cargo:undeploy)	Undeploy a deployable from a running container.
cargo:deployer-start	Start a deployable already installed in a running container.
cargo:deployer-stop	Stop a deployed deployable without undeploying it.
cargo:deployer-redeploy (aliased to cargo:redeploy)	Undeploy and deploy again a deployable.
cargo:uberwar	Merge several WAR files into one.
cargo:install	Installs a container distribution on the file system. Note that the cargo:start goal will also install the container automatically (but will not call cargo:install).
cargo:help	Get help (list of available goals, available options, etc.).