Reference Guide

These are the various XML configuration elements that you can use to configure the Cargo Maven 2 / Maven 3 plugin. Make sure you also check the use cases which show Maven 3 Archetypes which contain practical examples on how to use some of them.

Top level configuration elements	Description	Default value
`<configuration>`	Definition of a Configuration	Defaults to a standalone configuration if the container is of type local and a runtime one if it's of type remote
`<container>`	Definition of a Container	Defaults to a Jetty 89.x installed local container if not specified
`<deployer>`	Definition of a Deployer	Defaults to a deployer matching the container's type if none is specified (installed local deployer for an installed container, remote deployer for a remote container and embedded local deployer for an embedded container)
`<deployables>`	A list of deployables that are going to be deployed in the container when it is started or when `cargo:deploy` / `cargo:undeploy` is called.	If the project's packaging is `war`, `ear` or `ejb`, the generated artifact is added automatically to the list of deployables to deploy. If you wish the generated artifact not to be added to the deployables list, just add an empty `<deployer/>` element.
`<daemon>`	Additional configuration that is used when deploying with the Cargo Daemon.	For more information, please read: Cargo Daemon.
`<skip>`	Set this to `true` to bypass cargo executionthe executions of the Codehaus Cargo Maven 3 plugin.	Defaults to `false`, you can also steer it using the system property `cargo.maven.skip`
`<ignoreFailures>`	Set this to `true` to make the mojo ignore failures, so that Maven 2 / Maven 3 can still progress through on integration tests with more than one container domain started.	Defaults to `false`, you can also steer it using the system property `cargo.ignore.failures`

...

List of files that are to be added

<configuration> elements

Description

Mandatory?

Default value

<configfiles>

List of Configuration files that are to be added to a local container's configuration. Each file is specified using a <configfile> element. Cargo token replacement is applied to the files and any existing file is overwritten.

No default

<files>

<useLogCategoryPrefix>

Set this to true to display the log message category prefixes, which could help diagnosing issues.

Since Codehaus Cargo Maven 3 Plugin version 1.10.11 onwards.

Defaults to false, you can also steer it using the system property cargo.maven.useLogCategoryPrefix

Anchor

	configuration
	configuration

<configuration> elements

Description

Mandatory?

Default value

<configfiles>

List of Configuration files that are to be added to a local container's configuration. Each file is specified using a <file> <configfile> element. Cargo token replacement is applied to the files and any existing file is overwritten.

No default

<home>

For standalone configuration <files>

List of files that are to be added to a local container's configuration. Each file is specified using a <file> element.

No default

<home>

For standalone configuration this is the location where Cargo will create the configuration and for existing configuration this is where it is located.

${project.build.directory}/cargo/configurations/${containerId}

<implementation>

Full classname of a custom configuration implementation to use. In that case the custom configuration is registered with the <containerId> and <type> specified.

Defaults to the Cargo-provided implementation if not specified

<properties>

Values to use for various Configuration properties.

You can also use the <propertiesFile> element to load configuration properties from a file.

Default configuration properties

Note that these configuration properties can also be overriden using Java properties; for example:

Code Block
mvn -Dcargo.servlet.port=8082 cargo:start

In addition to this, properties can also be set using the Maven 2 / Maven 3 settings.xml file. See the setting configuration options via the Maven settings.xml section for details.

<xmlReplacements>

Values to use for various XML replacements.

No default

<type>

Configuration's type. Valid values are standalone, existing and runtime.

standalone

<users>

List of users to be created in container configuration.

No default

<datasources>

List of datasources to be created in container configuration.

No default

Anchor

	container
	container

`<container>` elements	Description	Default value
`<append>`	If `true`, then the file specified by `<output>` will not be erased across different runs.	`false`
`<containerId>`	Id of the container to use. Valid values can be found in the description page for each container.	`jetty7xjetty9x`
`<contextKey>`	Container context key, which can be used for two purposes: Start, stop, configure or deploy to the same Cargo container (together with its configuration) from different Maven artifacts. Inject configuration properties via the Maven `settings.xml` file, as explained in the setting configuration options via the Maven 2 / Maven 3 settings.xml section.	No reusable default The Cargo Maven 2 / Maven 3 plugin will actually generate a unique context key for each container based on the container and configuration's type and home - Which is not meant to be reused by end users.
`<dependencies>`	List of extra dependencies or shared dependencies that will be added to the container or applications execution classpath.	No default
`<home>`	Location where the container is installed. If specified in conjunction with the `<zipUrlInstaller>` or `<artifactInstaller>` element, it will override the home directory defined by the installer.	No default If the user has not defined any `home`, `<zipUrlInstaller>` nor `<artifactInstaller>` element then the plugin will automatically attempt to download the container using the URL used by its tests (see the Tested On section of each container).
`<implementation>`	Full classname of a custom container implementation to use. In that case, the custom container is registered with the `<containerId>` and `<type>` specified.	Defaults to the Cargo-provided implementation if not specified
`<log>`	Path to a file where Cargo logs are saved.	Logs to the Maven 2 / Maven 3 console if no log file is specified
`<output>`	Path to a file where container logs are saved.	Logs to the file specified by the `<log>` element or to the Maven 2 / Maven 3 console if no such file has been specified
`<systemProperties>`	List of `<key>value</key>` pairs to be passed as System properties to the container when it is started. You can also use the `<systemPropertiesFile>` element to load system properties from a file.	No default
`<timeout>`	The timeout after which Cargo reports an error if the container is not started or stopped.	`120000` ms (2 minutes)
`<type>`	The container's type. Valid values are `installed`, `embedded` and `remote`.	Default value is `installed` unless the `<containerId>` has not been specified, in which case the default is to use the Jetty 89.x installed local container.
`<zipUrlInstaller>`	Defines the location of a container distribution zip that will be downloaded and installed.	No default If the user has not defined any `home`, `<zipUrlInstaller>` nor `<artifactInstaller>` element then the plugin will automatically attempt to download the container using the URL used by its tests (see the Tested On section of each container).
`<artifactInstaller>`	Defines the location of a container Maven 2 / Maven 3 artifact that will be downloaded and installed.	No default If the user has not defined any `home`, `<zipUrlInstaller>` nor `<artifactInstaller>` element then the plugin will automatically attempt to download the container using the URL used by its tests (see the Tested On section of each container).

...

`<deployable>` elements	Description	Default value
`<artifactId>`	Maven 2 / Maven 3 artifact id for the module. This artifact id must match either the project's artifact id if your project generates a J2EE artifact (WAR, EAR, EJB and RAR) or it must match a specified `<project>/<dependencies>/<dependency>` artifact id	Defaults to the project's artifact id
`<groupId>`	Maven 2 / Maven 3 group id for the module. This group id must match either the project's group id if your project generates a J2EE artifact (WAR, EAR, EJB and RAR) or it must match a specified `<project>/<dependencies>/<dependency>` group id	Defaults to the project's group id
`<implementation>`	Deployable implementation class. Usage of this option is not recommended, please prefer `type` instead.	No default
`<location>`	Path location where the module can be found	Default's to the project's generated artifact location or to the specified `<project>/<dependencies>/<dependency>` location
`<pingURL>`	URL on which to ping the deployed or undeployed application (to check if deployment or undeployment is successful), that should return an HTTP OK response only after the deployment is complete. If not set, the deployed or undeployed application will not be pinged, hence the deployment considered as complete as soon as the target server's method returns successfully.	No default
`<pingUrlPath>`	URL path used to ping the deployed or undeployed application. It has similar functionality as `<pingURL>`, but in this case there is omitted protocol, server and port informations - they are retrieved from container configuration. For example for the URL `http://localhost:8080/cargo` its URL path is just `/cargo`.	No default
`<pingTimeout>`	If `<pingURL>` is set, the number of milliseconds after which the ping fails the build if still not successful.	`20000` (i.e., `20` seconds)
`<properties>`	User-defined properties of a deployable.	No default
`<type>`	Maven 2 / Maven 3 type for the module. This type must match either the project's packaging if your project generates a J2EE artifact (WAR, EAR, EJB and RAR) or it must match a specified `<project>/<dependencies>/<dependency>` type	Defaults to the project's packaging

...

<dependency> elements

Description

Mandatory?

Default value

<artifactId>

Maven 2 / Maven 3 's artifact id of the dependency. This artifact id must match a specified <project>/<dependencies>/<dependency> artifact id

Defaults to the project's artifact id

<groupId>

Maven 2 / Maven 3 's group id of the dependency. This group id must match a specified <project>/<dependencies>/<dependency> group id

Defaults to the project's group id

<type>

Maven 2 / Maven 3 's artifact type of the dependency. This type must match a specified <project>/<dependencies>/<dependency> type

Defaults to the project's packaging

<classpath>

Target classpath, either extra (default) or shared. Shared application classpath deployment is only available for local containers which support shared Application Classpaths.

extra (container classpath)

<location>

The path of a folder or a jar file you wish to add to deployable classpath. This element can be used to explicitly add entries to the classpath. For example:

Code Block
<dependency> <location>src/main/resources/conf</location> </dependency>

If the groupId and artifactId match those of the project then the deployable is the artifact generated by the project. Otherwise the location is the location of the dependency in your local repository.

...

<zipUrlInstaller>

extra (default) or shared. Shared application classpath deployment is only available for local containers which support shared Application Classpaths.

extra (container classpath)

<location>

The path of a folder or a jar file you wish to add to deployable classpath. This element can be used to explicitly add entries to the classpath. For example:

Code Block
<dependency> <location>src/main/resources/conf</location> </dependency>

If the groupId and artifactId match those of the project then the deployable is the artifact generated by the project. Otherwise the location is the location of the dependency in your local repository.

Anchor

	zipUrlInstaller
	zipUrlInstaller

`<zipUrlInstaller>` elements	Description	Default value
`<url>`	URL from which to download the container's ZIP or TAR.GZ file.	No default
`<downloadDir>`	Directory in which the `zipUrlInstaller` should download the container's ZIP or TAR.GZ file.	`${java.io.tmpdir}/cargo/installs`
`<extractDir>`	Directory in which the `zipUrlInstaller` should extract the container's ZIP or TAR.GZ file.	`${project.build.directory}/cargo/installs`
`<proxy>`	Proxy server settings, if required.	No default

Anchor

	proxy
	proxy

Info

title	Automatic proxy settings

Note that Codehaus Cargo will by default reuse existing Maven 3 proxy configuration, so you won't need to type the proxy settings for the zipUrlInstaller element.

`<proxy>` elements (under the `zipUrlInstaller` element)	Description	Default value
`<cargo.proxy.host>`	Proxy host name or IP address.	No default
`<cargo.proxy.port>`	Proxy port.	Very probably `80`
`<cargo.proxy.user>`	User name to connect to the proxy server.	No default
`<cargo.proxy.password>`	Password to connect to the proxy server.	No default

Anchor

	artifactInstaller
	artifactInstaller

...

Info

title	Automatic proxy settings

Note that CARGO will by default reuse existing Maven 2 / Maven 3 proxy configuration -so you won't need to type the proxy settings for the zipUrlInstaller element.

`<artifactInstaller>` elements	Description	Default value
`<url>`	URL from which to download the container's ZIP or TAR.GZ file.	No default
`<downloadDir>`	Directory in which the `zipUrlInstaller` should download the container's ZIP or TAR.GZ file.	`${java.io.tmpdir}/cargo/installs`
`<extractDir>`	Directory in which the `zipUrlInstaller` should extract the container's ZIP or TAR.GZ file.	`${project.build.directory}/cargo/installs`
`<proxy>`	Proxy server settings, if required.	No default

...

<proxy> elements (under the zipUrlInstaller element)

`<groupId>`	Group id.	No default
`<artifactId>`	Artifact id.	No default
`<version>`	Version.	No default
`<type>`	Artifact type.	`zip`
`<classifier>`	Classifier.	No default
`<extractDir>`	Directory in which the `artifactInstaller` should extract the container's ZIP or TAR.GZ file.	`${project.build.directory}/cargo/installs`

Anchor

	user
	user

<user> elements Description Mandatory? Default value

<cargo.proxy.host>

Proxy host name or IP address.

No default

<cargo.proxy.port>

Proxy port.

Very probably 80

<cargo.proxy.user>

User name to connect to the proxy server<name>

User name.

No default

<password>

User password.

No default

<cargo.proxy.password>

Password to connect to the proxy server.

<roles>

List of roles which should be assigned to user.

Example of roles configuration:

Code Block

language	xml

<roles>
    <role>cargo</role>
</roles>

No default

Anchor

	artifactInstallerdatasourceartifactInstaller
	datasource

Classifier.

`<artifactInstaller>` `<datasource>` elements	Description	Mandatory?	Default value
`<groupId>`	Group id`<jndiName>`	JNDI name where to find this DataSource.		No default
`<artifactId>`	Artifact id.		No default
`<version>`	Version.	`<connectionType>`	Type of this DataSource, for example "javax.sql.XADataSource"		No default
`<type>`	Artifact type.		`zip`
`<classifier>`	`<transactionSupport>`	Transaction support of the datasource, for example "XA_TRANSACTION"		No default
`<extractDir>`	Directory in which the `artifactInstaller` should extract the container's ZIP or TAR.GZ file.		`${project.build.directory}/cargo/installs`

...

User No default

<user> elements Description Mandatory? Default value

<name>

User name.

<driverClass>

The class name of the Driver, for example "org.hsqldb.jdbcDriver"

No default

<url>

DataSource connection URL.

No default

<username>

DataSource username.

No default

<password>

DataSource password.

Empty string

<roles>

List of roles which should be assigned to user.

Example of roles configuration:

Code Block

language	xml

<roles>
    <role>cargo</role>
</roles>

<id>

Id used in configuration files.

No default

<connectionProperties>

Extra properties passed to the DataSource.

No default

Anchor

	daemon
	daemon

Daemon configuration

The Cargo Daemon is a Web-based application that uses the Cargo API to configure, start and stop containers on a remote machine. The daemon is meant to be listening 24/7, to allow users to deploy new containers and web applications at their command. For more information, please read: Cargo Daemon.

Info

title	Container configuration for the Daemon

For the Maven plugin, the "daemonized server" is actually a local container with a hostname that points to a remote machine. This implies that:

You should not set the container type to a remote container nor add any remote deployers to the configuration; but instead define the container as a local container (with either a standalone or existing configuration)
When you define the home paths for the container and the configuration, remember these paths are for the machine where the Daemon is running (and, preferably, use absolute paths)

When you call cargo:daemon-start, the Maven 2 / Maven 3 plugin will do the following:

If an installer is defined:
- Download the archive locally
- Send the archive over to the machine running the Daemon
- Instruct the Daemon to extract the archive
If a standalone local configuration is defined, instruct the Daemon to create it
In all cases:
- Send the configuration files and deployables to the machine running the Daemon
- Instruct the Daemon to deploy them
Finally, instruct the Daemon to start the container

...

Anchor

	settingsXML
	settingsXML

Setting configuration options via the Maven

...

3 settings.xml

The Cargo Maven 2 / Maven 3 plugin also allows you to define container configuration properties using the settings.xml file. This way, you can for example store properties like usernames and passwords in a centralized location (as opposed to pom.xml files).

...

Code Block

	xml
	xml

<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven2maven3-plugin</artifactId>
  <configuration>
    [...]
    <configuration>
      <properties>
        <cargo.server.settings>jonas1</cargo.server.settings>
      </properties>
    </configuration>
  </configuration>
</plugin>

...

Code Block

	xml
	xml

<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven2maven3-plugin</artifactId>
  <configuration>
    [...]
    <configuration>
      <properties>
        <cargo.remote.uri>jmx://jonas1</cargo.remote.uri>
        <cargo.jonas.domain.name>jonas</cargo.jonas.domain.name>
        <cargo.remote.username>jonas</cargo.remote.username>
        <cargo.remote.password>jonas</cargo.remote.password>
      </properties>
    </configuration>
  </configuration>
</plugin>

...

Note

title	Careful with properties set in the POM

Priority for property values are as follows:

First and highest priority (i.e., will always override all below): Properties set using environment variables
Second priority: Properties set in the <configuration> of the Maven 3 plugin (following Maven's own override rules for configurations set across parents, executions, etc.)
Third priority: Properties loaded from a file
Third priorityFourth priority: Properties set in the POM
Fourth priorityFifth priority: Properties that should be loaded using the cargo.server.settings option
Fifth prioritySixth priority: Properties that should be loaded using <contextKey> option
Sixth Seventh and lowest priority: Default properties set by the container itself

...

Versions Compared

Old Version 107

New Version Current

Key

Reference Guide

Daemon configuration

Setting configuration options via the Maven

3 settings.xml

Page Comparison

Versions Compared

Old Version 107

New Version Current

Key

Reference Guide

Daemon configuration

Setting configuration options via the Maven

3 settings.xml