View Source

For manipulating the various type of application containers (Java EE and others), Cargo has two types of containers:

An installed container means you have the container available as an installation (either locally on the machine or "locally" to the Cargo Daemon). In this case, the typical build / test cycle would be:
1. Perform any preparations you need to in order to create your deployables
2. Use Cargo to start the container (which will actually configure, start and deploy your deployable(s))
3. Perform any actions you want to do on the container
4. Use Cargo to stop the container
A remote container means you have the container running (usually, on another machine). In this case, the typical build / test cycle would be:
1. Perform any preparations you need to in order to create your deployables
2. Use Cargo to perform a remote deployment to the container
3. Perform any actions you want to do on the container
4. Use Cargo to undeploy your deployables

Of course, Cargo is not limited to testing - You can also use it to configure, package or remotely handle many containers.

Codehaus Cargo can be used using its Java API as it is shown here. In addition to a Java API, Codehaus Cargo also has Ant tasks and a Maven 3 plugin:

The Ant support page contains the Quick Start for the Codehaus Cargo Ant tasks
The Getting started with the Codehaus Cargo Maven 3 plugin contains the Quick Start for the Codehaus Cargo Maven 3 plugin

The following examples demonstrate how to configure Tomcat 9.0.78 to start with a standalone local configuration in target/tomcat9x and deploy a WAR located in path/to/simple.war using the Java API. The default port is 8080.

Please note that the container.start() and container.stop() methods wait until the container is fully started and fully stopped before continuing. Thus, for any action you are executing after, you are assured the container is completely operational.

Static deployment

Static deployment means that the Deployable is deployed before the container is started. Here's an example using the strongly typed Java API:

Deployable war = new WAR("path/to/simple.war");

LocalConfiguration configuration =
    new Tomcat9xStandaloneLocalConfiguration("target/tomcat9x");
configuration.addDeployable(war);

InstalledLocalContainer container =
    new Tomcat9xInstalledLocalContainer(configuration);
container.setHome("c:/apps/tomcat-9.0.78");

container.start();
// Here you are assured the container is started.

container.stop();
// Here you are assured the container is stopped.

Here's the same example using the generic untyped API (which we recommend as it leads to more generic code):

Deployable war = new DefaultDeployableFactory().createDeployable(
    "tomcat9x", "path/to/simple.war", DeployableType.WAR);

ConfigurationFactory configurationFactory =
    new DefaultConfigurationFactory();
LocalConfiguration configuration =
    (LocalConfiguration) configurationFactory.createConfiguration(
        "tomcat9x", ContainerType.INSTALLED,
            ConfigurationType.STANDALONE, "target/tomcat9x");
configuration.addDeployable(war);

InstalledLocalContainer container =
    (InstalledLocalContainer) new DefaultContainerFactory().createContainer(
        "tomcat9x", ContainerType.INSTALLED, configuration);
container.setHome("c:/apps/tomcat-9.0.78");

container.start();
// Here you are assured the container is started.

container.stop();
// Here you are assured the container is stopped.

Hot deployment

Hot deployment means that the Deployable is deployed after the container is started.

InstalledLocalContainer container = new Tomcat9xInstalledLocalContainer(
    new Tomcat9StandaloneLocalConfiguration("target/tomcat9x"));
container.setHome("c:/apps/tomcat-9.0.78");

container.start();
// Here you are assured the container is started.

Deployable war = new WAR("path/to/simple.war");
Deployer deployer = new TomcatCopyingInstalledLocalDeployer(container);

// To be sure that the deployable is deployed, we can use a DeployableMonitor
// to monitor the deployment. The following code deploys the WAR and waits until
// it is available to serve requests (i.e., the URL specified returns an HTTP
// code 2xx or 3xx and, in our example, the text connection-ok in the body)
deployer.deploy(war, new URLDeployableMonitor(
    new URL("http://localhost:8080/simple/jsp-status"), "connection-ok"));

container.stop();
// Here you are assured the container is stopped.

Functional tests

For a detailed documentation on how to use Cargo for executing functional tests on a container, directly from your Java unit test classes (JUnit, TestNG, etc), read our Functional testing page.