Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Example of a minimalist configuration:

Code Block
xml
xml

[...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.cargo</groupId>
        <artifactId>cargo-maven2-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
[...]

...

Info
titleWait after the container has started

If you want Cargo to start the container and "wait" (i.e., do not stop it right afterwards, so that you can for example to manual tests), please run the following command:

Code Block

mvn cargo:run

Cargo will then start the container and show the following message: Press Ctrl-C to stop the container....

Example of a lightweight configuration:

Code Block
xml
xml

[...]
<configuration>

  <!-- Container configuration -->
  <container>
    <containerId>tomcat5x</containerId>
    <home>c:/apps/jakarta-tomcat-5.0.30</home>
  </container>

  <!-- Configuration to use with the container -->
  <configuration>
    <home>${project.build.directory}/tomcat5x</home>
  </configuration>

</configuration>
[...]

...

Example of a full-fledged m2 configuration:

Code Block
xml
xml

[...]
<configuration>

  <!-- Container configuration -->
  <container>
    <containerId>tomcat6x</containerId>
    <zipUrlInstaller>
      <url>http://archive.apache.org/dist/tomcat/tomcat-6/v6.0.32/bin/apache-tomcat-6.0.32.zip</url>
    </zipUrlInstaller>
    <!--
      Instead of downloading the container, you can also reuse an
      existing installation by settings its directory:

      <home>c:/apps/tomcat-6.0.32</home>
      -->
    <output>${project.build.directory}/tomcat6x/container.log</output>
    <append>false</append>
    <log>${project.build.directory}/tomcat6x/cargo.log</log>
  </container>

  <!-- Configuration to use with the container or the deployer -->
  <configuration>
    <type>standalone</type>
    <home>${project.build.directory}/tomcat6x</home>
    <properties>
      <cargo.servlet.port>8080</cargo.servlet.port>
      <cargo.logging>high</cargo.logging>
    </properties>
  </configuration>
  <deployables>
      <deployable>
        <groupId>war group id</groupId>
        <artifactId>war artifact id</artifactId>
        <type>war</type>
        <properties>
          <context>optional root context</context>
        </properties>
      </deployable>
      <deployable>
        <groupId>ear group id</groupId>
        <artifactId>ear artifact id</artifactId>
        <type>ear</type>
      </deployable>
      [...]
    </deployables>

  < </configuration>

</configuration>
[...]

This example shows the usage of a standalone configuration for configuring Tomcat 6.x. Note that it's possible to define deployables 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 Tomcat 6.x to start on port 8080 and to output highly verbose logs (useful for debugging).

...

The most basic container you can use in cargo is an Embedded Jetty 4x/5x/6x Container. The following maven 2 plugin definition will configure an embedded Jetty 6x container. Note the use of the embedded type element to specify an embedded container.

Code Block
xml
xml

[...]
<plugin>
 <groupId>org.codehaus.cargo</groupId>
 <artifactId>cargo-maven2-plugin</artifactId>
 <configuration>
   <container>
     <containerId>jetty6x</containerId>
     <type>embedded</type>
   </container>
 </configuration>
</plugin>
[...]

...

You can set an alternate JAVA_HOME for non-embedded containers. This will allow you to run a container that uses JDK 1.4 even if your build runs on Java 5. Here's an example of how to do this.

Code Block
xml
xml

[...]
<plugin>
 <groupId>org.codehaus.cargo</groupId>
 <artifactId>cargo-maven2-plugin</artifactId>
 <configuration>
   [...]
   <properties>
     <cargo.java.home>/usr/package/j2dsk1.4.2_11</cargo.java.home>
   </properties>
   [...]
 </configuration>
</plugin>
[...]

...

If your project is a J2EE project (i.e. of type <packaging>war</packaging>, <packaging>ear</packaging>, <packaging>ejb</packaging> or <packaging>uberwar</packaging>) and you use the Cargo m2 plugin on that project then 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 <location> 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:

Code Block
xml
xml

<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven2-plugin</artifactId>
  <configuration>
    [...]
    <configuration>
      [...]
      <deployables>
        <deployable>
          <location>${project.build.directory}/${project.build.finalName}.${project.packaging}</location>
          <pingURL>http://localhost:port/mycontext/index.html</pingURL>
        </deployable>
      </deployables>
      [...]

Anchor
lifecycle
lifecycle

...

You might to automate the execution of cargo:start and cargo:stop. Of course you can bind those goals to any lifecycle phase (see Maven2's introduction to the lifecycle tutorial). Here's a common example used to start and the stop the container for doing integration tests:

Code Block
xml
xml

<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven2-plugin</artifactId>
  <executions>
    <execution>
      <id>start-container</id>
      <phase>pre-integration-test</phase>
      <goals>
        <goal>start</goal>
      </goals>
    </execution>
    <execution>
      <id>stop-container</id>
      <phase>post-integration-test</phase>
      <goals>
        <goal>stop</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    [Cargo plugin configuration goes in here]
  </configuration>
</plugin>

...

There are cases when you want to add extra JARs to your container's classpath, in order to share them between webapps for example. In order to add them, the first step is to define them as standard Maven2 dependencies. Then you should add a <dependencies> element under the <container> element and one <dependency> element for each JAR to add. For example, to add the Spring 2.0 JAR to your container's classpath you would write:

Code Block
xml
xml

[...]
<dependencies>
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring</artifactId>
    <version>2.0</version>
  </dependency>
</dependencies>
[...]
<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven2-plugin</artifactId>
  <configuration>
    <container>
      [...]
      <dependencies>
        <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring</artifactId>
        </dependency>
      </dependencies>
    </container>
    [...]
  </configuration>
</plugin>

...

Just add a property that starts with cargo.datasource.datasource. Note that you will probably need to add a classpath dependency for the driver.

Code Block
xml
xml

[...]
<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven2-plugin</artifactId>
  <configuration>
    [...]
    <properties>
      <cargo.datasource.datasource.derby>
        cargo.datasource.driver=org.apache.derby.jdbc.EmbeddedDriver|
        cargo.datasource.url=jdbc:derby:derbyDB;create=true|
        cargo.datasource.jndi=jdbc/CargoDS|
        cargo.datasource.username=APP|
        cargo.datasource.password=nonemptypassword
      </cargo.datasource.datasource.derby>
    </properties>
    [...]
    <container>
      [...]
      <dependencies>
        <dependency>
          <groupId>org.apache.derby</groupId>
          <artifactId>derby</artifactId>
        </dependency>
      </dependencies>
    </container>
  </configuration>
</plugin>

...

To have multiple DataSources bound to JNDI, simply add more properties that start with cargo.datasource.datasource.

Code Block
xml
xml

[...]
<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven2-plugin</artifactId>
  <configuration>
    [...]
    <properties>
      <cargo.datasource.datasource.derby>
        cargo.datasource.driver=org.apache.derby.jdbc.EmbeddedDriver|
        cargo.datasource.url=jdbc:derby:derbyDB;create=true|
        cargo.datasource.jndi=jdbc/CargoDS|
        cargo.datasource.username=foo|
        cargo.datasource.password=foopassword
      </cargo.datasource.datasource.derby>
      <cargo.datasource.datasource.derby2>
        cargo.datasource.driver=org.apache.derby.jdbc.EmbeddedDriver|
        cargo.datasource.url=jdbc:derby:derbyDB2;create=true|
        cargo.datasource.jndi=jdbc/CargoDS2|
        cargo.datasource.username=bar|
        cargo.datasource.password=barpassword
      </cargo.datasource.datasource.derby2>
    </properties>
    [...]
  </configuration>
</plugin>

...

  • Note that if you specify this on a container that does not support transactions, you will get a CargoException during the configuration phase.
  • valid values are LOCAL_TRANSACTION or XA_TRANSACTION. Note that XA_TRANSACTION is emulated in this case.

    Code Block
    xml
    xml
    
    [...]
    <plugin>
      <groupId>org.codehaus.cargo</groupId>
      <artifactId>cargo-maven2-plugin</artifactId>
      <configuration>
        [...]
        <properties>
          <cargo.datasource.datasource.derbytx>
            cargo.datasource.driver=org.apache.derby.jdbc.EmbeddedDriver|
            cargo.datasource.url=jdbc:derby:derbyDB;create=true|
            cargo.datasource.jndi=jdbc/CargoDS|
            cargo.datasource.username=foo|
            cargo.datasource.password=foopassword|
            cargo.datasource.transactionsupport=LOCAL_TRANSACTION
          </cargo.datasource.datasource.derbytx>
        </properties>
        [...]
      </configuration>
    </plugin>
    

...

  1. set cargo.datasource.type=javax.sql.XADataSource
  2. set cargo.datasource.driver=a valid implementation of javax.sql.XADataSource
  3. set cargo.datasource.properties=a semi-colon delimited list of properties for that class
  • Note that if you specify this on a container that does not support XADataSource configuration, you will get a CargoException during the configuration phase.

    Code Block
    xml
    xml
    
    [...]
    <plugin>
      <groupId>org.codehaus.cargo</groupId>
      <artifactId>cargo-maven2-plugin</artifactId>
      <configuration>
        [...]
        <properties>
          <cargo.datasource.datasource.derbytx>
            cargo.datasource.type=javax.sql.XADataSource|
            cargo.datasource.driver=org.apache.derby.jdbc.EmbeddedXADataSource|
            cargo.datasource.jndi=jdbc/CargoDS|
            cargo.datasource.username=foo|
            cargo.datasource.password=foopassword|
            cargo.datasource.properties=createDatabase=create;databaseName=derbyDB
          </cargo.datasource.datasource.derbytx>
        </properties>
        [...]
      </configuration>
    </plugin>
    

...

  • Resin and Tomcat require you supply the mail and activation jars externally due to Sun license requirements. The below example shows this.
Code Block
xml
xml

[...]
<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven2-plugin</artifactId>
  <configuration>
    [...]
    <properties>
      <cargo.resource.resource.mail>
        cargo.resource.name=mail/Session|
        cargo.resource.type=javax.mail.Session|
        cargo.resource.parameters=mail.smtp.host=localhost;mail.smtp.connectiontimeout=10000
      </cargo.resource.resource.mail>
    </properties>
    [...]
    <container>
      [...]
      <dependencies>
        <dependency>
          <groupId>javax.activation</groupId>
          <artifactId>activation</artifactId>
        </dependency>
        <dependency>
          <groupId>javax.mail</groupId>
          <artifactId>mail</artifactId>
        </dependency>
      </dependencies>
    </container>
  </configuration>
</plugin>
...
<dependencies>
  <dependency>
    <groupId>javax.activation</groupId>
    <artifactId>activation</artifactId>
    <version>1.1</version>
  </dependency>
  <dependency>
    <groupId>javax.mail</groupId>
    <artifactId>mail</artifactId>
    <version>1.4</version>
  </dependency>
</dependencies>

...

If you use a framework that does its own database connection pooling, you may need to configure a native ConnectionPoolDataSource. Here's how:

Code Block
xml
xml

[...]
<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven2-plugin</artifactId>
  <configuration>
    [...]
    <properties>
      <cargo.resource.resource.nativederby>
        cargo.resource.name=resource/nativeCPDataSource|
        cargo.resource.type=javax.sql.ConnectionPoolDataSource|
        cargo.resource.class=org.apache.derby.jdbc.EmbeddedConnectionPoolDataSource|
        cargo.resource.parameters=createDatabase=create;databaseName=derbyDB;user=APP;password=nonemptypassword
      </cargo.resource.resource.nativederby>
    </properties>
    [...]
    <container>
      [...]
      <dependencies>
        <dependency>
          <groupId>org.apache.derby</groupId>
          <artifactId>derby</artifactId>
        </dependency>
      </dependencies>
    </container>
  </configuration>
</plugin>

...

To have multiple POJO Resources bound to JNDI, simply add more properties that start with cargo.resource.resource.

Code Block
xml
xml

[...]
<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven2-plugin</artifactId>
  <configuration>
    [...]
    <properties>
      <cargo.resource.resource.apple>
        cargo.resource.name=resource/apple|
        cargo.resource.type=my.app.Fruit|
        cargo.resource.class=my.app.AppleImpl|
        cargo.resource.parameters=color=red;texture=crunchy
      </cargo.resource.resource.apple>
      <cargo.resource.resource.orange>
        cargo.resource.name=resource/orange|
        cargo.resource.type=my.app.Fruit|
        cargo.resource.class=my.app.OrangeImpl|
        cargo.resource.parameters=color=orange;texture=rindy
      </cargo.resource.resource.orange>
    </properties>
    [...]
  </configuration>
</plugin>