This page last changed on Jun 02, 2011 by alitokmen.

Definition

Cargo provides Ant tasks to perform all the operations available from the Java API

Functional tests
The usage of Cargo for executing functional tests on a container does not mandate these ANT tasks. You could directly use the Cargo Java API from your Java unit test classes (JUnit, TestNG, etc), as described on the Functional testing page.

Explanation

Before using the Ant API you need to register the Cargo Ant tasks into Ant. This is done in the following manner:

<taskdef resource="cargo.tasks">
  <classpath>
    <pathelement location="${cargo-core-uberjar.jar}"/>
    <pathelement location="${cargo-ant.jar}"/>
  </classpath>
</taskdef>

Some additional dependencies might also be required for the ANT task. Please see the Installation page for details.

The Cargo ANT tasks in detail

Here are the different task actions available to call on this plugin:

Action Description
start Start a container.
run Start a container and wait for the user to press CTRL + C to stop (since v1.1.1).
stop Stop a container
configure Create the configuration for a local container, without starting it. Note that the start and run actions will also install the container automatically.
deploy Deploy a deployable to a running container
undeploy Undeploy a deployable from a running container
redeploy Undeploy and deploy again a deployable


Wait after the container has started
If using Cargo for integration tests, remember to set the wait parameter of the <cargo> task to false, otherwise Cargo will start the container and show the following message: Press Ctrl-C to stop the container.... The default value for the wait parameter is:
  • For CARGO 1.1.0 and onwards, false
  • For older versions, true
    Starting from CARGO 1.1.1, the wait parameter has been deprecated as it was confusing for most users:
  • If you want to just start the container and then do other tasks (for example, execute tests), use the start action
  • If you want start the container and have ANT "blocked" afterwards (i.e., until you press CTRL + C to stop), use the run action

Examples

Orion 2.x

Here's a full example showing how to deploy a WAR, and expanded WAR and an EAR in an Orion 2.x container. Please note that the output and log attribute are optional. The property elements allow you to tune how the container is configured. Here we're telling it to start on port 8180 and to generate the maximum amount of logs in the container output file.

<taskdef resource="cargo.tasks">
  <classpath>
    <pathelement location="path/to/cargo-uberjar.jar"/>
    <pathelement location="path/to/cargo-ant-tasks.jar"/>
  </classpath>
</taskdef>

<cargo containerId="orion2x" home="c:/apps/orion-2.0.3" output="target/output.log"
    log="target/cargo.log" action="start">
  <configuration>
    <property name="cargo.servlet.port" value="8180"/>
    <property name="cargo.logging" value="high"/>
    <deployable type="war" file="path/to/my/simple.war"/>
    <deployable type="war" file="path/to/my/expandedwar/simple"/>
    <deployable type="ear" file="path/to/my/simple.ear"/>
  </configuration>
</cargo>

Tomcat 5.x

This example gives a walk through of how to get a Cargo Ant build to work with Tomcat 5.x .

Prerequisites
  • It is assumed that Tomcat 5.x is already installed
  • The cargo-core-uberjar.jar and cargo-ant.jar JARs have been downloaded
  • A mimimum knowledge of Ant is required
  • User already has a war target that properly generates a working war file
Steps

Follow the following steps to configure your build.xml :

  • Create a folder under your basedir called cargolib that will hold cargo-core-uberjar.jar and cargo-ant.jar
  • Define a property for cargolib
<property name="cargolib.dir" value="${basedir}/cargolib"/>
  • Define 2 new properties cargo-uberjar and cargo-antjar as shown below:
<property name="cargo-uberjar" value="${cargolib.dir}/cargo-core-uberjar.jar"/>
<property name="cargo-antjar" value="${cargolib.dir}/cargo-ant.jar"/>
  • Add additional properties for defining the following:
    Property Description
    tomcat.home Installation directory of tomcat5x
    tomcatlog.dir This is where our logs are going to be generated
    tomcatconfig.dir Cargo needs an empty config folder
    pathtowarfile The full path of the war file e.g c:/devtools/myapp/dist/myfile.war
  • Add the following code to your build.xml :
    <taskdef resource="cargo.tasks">
      <classpath>
        <pathelement location="${cargo-uberjar}"/>
        <pathelement location="${cargo-antjar}"/>
      </classpath>
    </taskdef>
    	
    <target name="cargostart" depends="war">
      <delete dir="${tomcatconfig.dir}" />
      <mkdir dir="${tomcatlog.dir}"/>
      <mkdir dir="${tomcatconfig.dir}"/>
      <echo message="Starting Cargo..."/>
      <echo message="Using tomcat.home = ${tomcat.home} "/>
      <echo message="Using war = ${mywarfile} "/>
      <echo message="Jars used = ${cargo-uberjar} , ${cargo-antjar}"/>
    		
      <cargo containerId="tomcat5x" home="${tomcat.home}" output="${tomcatlog.dir}/output.log" 
          log="${tomcatlog.dir}/cargo.log" action="start">
        <configuration home="${tomcatconfig.dir}">
          <property name="cargo.servlet.port" value="8080"/>
          <property name="cargo.logging" value="high"/>
          <deployable type="war" file="${mywarfile}"/>
        </configuration>
      </cargo>
    
    </target>

Remote deployment

Remote deployer availability
Please note that the remote deployer is only available with CARGO 1.1.0 and onwards.

Here's a full example showing how to deploy a WAR to a remote Tomcat 6.x container.

<taskdef resource="cargo.tasks">
  <classpath>
    <pathelement location="path/to/cargo-uberjar.jar"/>
    <pathelement location="path/to/cargo-ant-tasks.jar"/>
  </classpath>
</taskdef>

<cargo containerId="tomcat6x" action="deploy" type="remote">
  <configuration type="runtime">
    <property name="cargo.hostname" value="production27"/>
    <property name="cargo.servlet.port" value="8080"/>
    <property name="cargo.remote.username" value="admin"/>
    <property name="cargo.remote.password" value=""/>
    <deployable type="war" file="path/to/simple-war.war">
      <property name="context" value="application-context"/>
    </deployable>
  </configuration>
</cargo>

For more details, please check the example in the Remote Container section for the ANT tasks. The ANT tasks support the deployer actions deploy, undeploy and redeploy.

Document generated by Confluence on Oct 05, 2011 19:31