# Codehaus Cargo : DataSource and Resource Support

Created by Adrian Cole, last modified by S. Ali Tokmen on Jan 28, 2021

# Container support

Here are the configurations that currently support DataSource or Resource configuration:

This page / section has been automatically generated by Cargo's build. Do not edit it directly as it'll be overwritten next time it's generated again.

Container | Configuration | Resource | DataSource | Transactional DataSource | XA DataSource
--- | --- | --- | --- | --- | ---
Geronimo 2.x | `o.c.c.c.geronimo.Geronimo2xStandaloneLocalConfiguration` |  |  |  |
Geronimo 3.x | `o.c.c.c.geronimo.Geronimo3xStandaloneLocalConfiguration` |  |  |  |
GlassFish 3.x | `o.c.c.c.glassfish.GlassFish3xStandaloneLocalConfiguration` | M |  |  |
GlassFish 4.x | `o.c.c.c.glassfish.GlassFish4xStandaloneLocalConfiguration` | M |  |  |
GlassFish 5.x | `o.c.c.c.glassfish.GlassFish5xStandaloneLocalConfiguration` | M |  |  |
GlassFish 6.x | `o.c.c.c.glassfish.GlassFish6xStandaloneLocalConfiguration` | M |  |  |
GlassFish 7.x | `o.c.c.c.glassfish.GlassFish7xStandaloneLocalConfiguration` | M |  |  |
GlassFish 8.x | `o.c.c.c.glassfish.GlassFish8xStandaloneLocalConfiguration` | M |  |  |
GlassFish 9.x | `o.c.c.c.glassfish.GlassFish9xStandaloneLocalConfiguration` | M |  |  |
JBoss 3.x | `o.c.c.c.jboss.JBoss3x4xStandaloneLocalConfiguration` |  |  |  |
JBoss 4.x | `o.c.c.c.jboss.JBoss3x4xStandaloneLocalConfiguration` |  |  |  |
JBoss 4.2.x | `o.c.c.c.jboss.JBoss42xStandaloneLocalConfiguration` |  |  |  |
JBoss 5.x | `o.c.c.c.jboss.JBoss5xStandaloneLocalConfiguration` |  |  |  |
JBoss 5.1.x | `o.c.c.c.jboss.JBoss51xStandaloneLocalConfiguration` |  |  |  |
JBoss 6.x | `o.c.c.c.jboss.JBoss6xStandaloneLocalConfiguration` |  |  |  |
JBoss 6.1.x | `o.c.c.c.jboss.JBoss6xStandaloneLocalConfiguration` |  |  |  |
JBoss 7.x | `o.c.c.c.jboss.JBoss7xStandaloneLocalConfiguration` |  |  |  |
JBoss 7.1.x | `o.c.c.c.jboss.JBoss71xStandaloneLocalConfiguration` |  |  |  |
JBoss 7.2.x (EAP 6.1.x) | `o.c.c.c.jboss.JBoss72xStandaloneLocalConfiguration` |  |  |  |
JBoss 7.3.x (EAP 6.2.x) | `o.c.c.c.jboss.JBoss73xStandaloneLocalConfiguration` |  |  |  |
JBoss 7.4.x (EAP 6.3.x) | `o.c.c.c.jboss.JBoss73xStandaloneLocalConfiguration` |  |  |  |
JBoss 7.5.x (EAP 6.4.x) | `o.c.c.c.jboss.JBoss75xStandaloneLocalConfiguration` | QT |  |  |
Jetty 7.x | `o.c.c.c.jetty.Jetty7xStandaloneLocalConfiguration` |  |  |  |
Jetty 8.x | `o.c.c.c.jetty.Jetty8xStandaloneLocalConfiguration` |  |  |  |
Jetty 9.x | `o.c.c.c.jetty.Jetty9xStandaloneLocalConfiguration` |  |  |  |
Jetty 10.x | `o.c.c.c.jetty.Jetty10xStandaloneLocalConfiguration` |  |  |  |
Jetty 11.x | `o.c.c.c.jetty.Jetty11xStandaloneLocalConfiguration` |  |  |  |
Jetty 12.x | `o.c.c.c.jetty.Jetty12xStandaloneLocalConfiguration` |  |  |  |
JOnAS 4.x | `o.c.c.c.jonas.Jonas4xStandaloneLocalConfiguration` |  |  |  |
JOnAS 5.x | `o.c.c.c.jonas.Jonas5xStandaloneLocalConfiguration` |  |  |  |
JRun 4.x | `o.c.c.c.jrun.JRun4xExistingLocalConfiguration` |  |  |  |
OC4J 9.x | `o.c.c.c.orion.Oc4j9xStandaloneLocalConfiguration` |  |  |  |
OC4J 10.x | `o.c.c.c.orion.Oc4j10xExistingLocalConfiguration` |  |  |  |
Payara | `o.c.c.c.payara.PayaraStandaloneLocalConfiguration` | M |  |  |
Resin 3.x | `o.c.c.c.resin.Resin3xStandaloneLocalConfiguration` | QT |  |  |
Resin 3.1.x | `o.c.c.c.resin.Resin31xStandaloneLocalConfiguration` | QT |  |  |
Resin 4.x | `o.c.c.c.resin.Resin4xStandaloneLocalConfiguration` | QT |  |  |
Tomcat 4.x | `o.c.c.c.tomcat.Tomcat4xStandaloneLocalConfiguration` | QT |  |  |
Tomcat 5.x | `o.c.c.c.tomcat.Tomcat5xStandaloneLocalConfiguration` | QT |  |  |
Tomcat 6.x | `o.c.c.c.tomcat.Tomcat6xStandaloneLocalConfiguration` | QT |  |  |
Tomcat 7.x | `o.c.c.c.tomcat.Tomcat7xStandaloneLocalConfiguration` | QT |  |  |
Tomcat 8.x | `o.c.c.c.tomcat.Tomcat8xStandaloneLocalConfiguration` | QT |  |  |
Tomcat 9.x | `o.c.c.c.tomcat.Tomcat9xStandaloneLocalConfiguration` | QT |  |  |
Tomcat 10.x | `o.c.c.c.tomcat.Tomcat10xStandaloneLocalConfiguration` | QT |  |  |
Tomcat 11.x | `o.c.c.c.tomcat.Tomcat11xStandaloneLocalConfiguration` | QT |  |  |
TomEE 1.x | `o.c.c.c.tomee.Tomee1xStandaloneLocalConfiguration` |  |  |  |
TomEE 7.x | `o.c.c.c.tomee.Tomee7xStandaloneLocalConfiguration` |  |  |  |
TomEE 8.x | `o.c.c.c.tomee.Tomee8xStandaloneLocalConfiguration` |  |  |  |
TomEE 9.x | `o.c.c.c.tomee.Tomee9xStandaloneLocalConfiguration` |  |  |  |
TomEE 10.x | `o.c.c.c.tomee.Tomee10xStandaloneLocalConfiguration` |  |  |  |
WebLogic 8.x | `o.c.c.c.weblogic.WebLogic8xStandaloneLocalConfiguration` |  |  |  |
WebLogic 9.x | `o.c.c.c.weblogic.WebLogic9xStandaloneLocalConfiguration` |  |  |  |
WebLogic 10.x | `o.c.c.c.weblogic.WebLogic10xStandaloneLocalConfiguration` |  |  |  |
WebLogic 10.3.x | `o.c.c.c.weblogic.WebLogic103xStandaloneLocalConfiguration` |  |  |  |
WebLogic 12.x | `o.c.c.c.weblogic.WebLogic12xStandaloneLocalConfiguration` |  |  |  |
WebLogic 12.1.x | `o.c.c.c.weblogic.WebLogic121xStandaloneLocalConfiguration` | T |  |  |
WebLogic 12.2.x | `o.c.c.c.weblogic.WebLogic122xStandaloneLocalConfiguration` | T |  |  |
WebLogic 14.x | `o.c.c.c.weblogic.WebLogic14xStandaloneLocalConfiguration` | T |  |  |
WebLogic 15.x | `o.c.c.c.weblogic.WebLogic15xStandaloneLocalConfiguration` | T |  |  |
WebSphere 8.5.x | `o.c.c.c.websphere.WebSphere85xStandaloneLocalConfiguration` | TM |  |  |
WebSphere 9.x | `o.c.c.c.websphere.WebSphere9xStandaloneLocalConfiguration` | TM |  |  |
WebSphere Liberty | `o.c.c.c.liberty.LibertyStandaloneLocalConfiguration` |  |  |  |
WildFly 8.x | `o.c.c.c.wildfly.WildFly8xStandaloneLocalConfiguration` |  |  |  |
WildFly 9.x | `o.c.c.c.wildfly.WildFly9xStandaloneLocalConfiguration` |  |  |  |
WildFly 10.x (JBoss EAP 7.0) | `o.c.c.c.wildfly.WildFly10xStandaloneLocalConfiguration` | QT |  |  |
WildFly 11.x (JBoss EAP 7.1) | `o.c.c.c.wildfly.WildFly11xStandaloneLocalConfiguration` |  |  |  |
WildFly 12.x | `o.c.c.c.wildfly.WildFly12xStandaloneLocalConfiguration` |  |  |  |
WildFly 13.x (JBoss EAP 7.2) | `o.c.c.c.wildfly.WildFly13xStandaloneLocalConfiguration` |  |  |  |
WildFly 14.x | `o.c.c.c.wildfly.WildFly14xStandaloneLocalConfiguration` |  |  |  |
WildFly 15.x | `o.c.c.c.wildfly.WildFly15xStandaloneLocalConfiguration` |  |  |  |
WildFly 16.x | `o.c.c.c.wildfly.WildFly16xStandaloneLocalConfiguration` |  |  |  |
WildFly 17.x | `o.c.c.c.wildfly.WildFly17xStandaloneLocalConfiguration` |  |  |  |
WildFly 18.x (JBoss EAP 7.3) | `o.c.c.c.wildfly.WildFly18xStandaloneLocalConfiguration` |  |  |  |
WildFly 19.x | `o.c.c.c.wildfly.WildFly19xStandaloneLocalConfiguration` |  |  |  |
WildFly 20.x | `o.c.c.c.wildfly.WildFly20xStandaloneLocalConfiguration` |  |  |  |
WildFly 21.x | `o.c.c.c.wildfly.WildFly21xStandaloneLocalConfiguration` |  |  |  |
WildFly 22.x (JBoss EAP 7.4) | `o.c.c.c.wildfly.WildFly22xStandaloneLocalConfiguration` |  |  |  |
WildFly 23.x | `o.c.c.c.wildfly.WildFly23xStandaloneLocalConfiguration` |  |  |  |
WildFly 24.x | `o.c.c.c.wildfly.WildFly24xStandaloneLocalConfiguration` |  |  |  |
WildFly 25.x | `o.c.c.c.wildfly.WildFly25xStandaloneLocalConfiguration` |  |  |  |
WildFly 26.x | `o.c.c.c.wildfly.WildFly26xStandaloneLocalConfiguration` |  |  |  |
WildFly 27.x | `o.c.c.c.wildfly.WildFly27xStandaloneLocalConfiguration` | QTM |  |  |
WildFly 28.x | `o.c.c.c.wildfly.WildFly28xStandaloneLocalConfiguration` | QTM |  |  |
WildFly 29.x | `o.c.c.c.wildfly.WildFly29xStandaloneLocalConfiguration` | QTM |  |  |
WildFly 30.x | `o.c.c.c.wildfly.WildFly30xStandaloneLocalConfiguration` | QTM |  |  |
WildFly 31.x | `o.c.c.c.wildfly.WildFly31xStandaloneLocalConfiguration` | QTM |  |  |
WildFly 32.x | `o.c.c.c.wildfly.WildFly32xStandaloneLocalConfiguration` | QTM |  |  |
WildFly 33.x | `o.c.c.c.wildfly.WildFly33xStandaloneLocalConfiguration` | QTM |  |  |
WildFly 34.x | `o.c.c.c.wildfly.WildFly34xStandaloneLocalConfiguration` | QTM |  |  |
WildFly 35.x | `o.c.c.c.wildfly.WildFly35xStandaloneLocalConfiguration` | QTM |  |  |
WildFly 36.x | `o.c.c.c.wildfly.WildFly36xStandaloneLocalConfiguration` | QTM |  |  |
WildFly 37.x | `o.c.c.c.wildfly.WildFly37xStandaloneLocalConfiguration` | QTM |  |  |
WildFly 38.x | `o.c.c.c.wildfly.WildFly38xStandaloneLocalConfiguration` | QTM |  |  |
WildFly 39.x | `o.c.c.c.wildfly.WildFly39xStandaloneLocalConfiguration` | QTM |  |  |
WildFly 40.x | `o.c.c.c.wildfly.WildFly40xStandaloneLocalConfiguration` | QTM |  |  |

Container-specific notes:

- Q: JMS Queues are not supported by this container
- T: JMS Topics are not supported by this container
- M: Mail resources are not supported by this container

Notes:

- Datasources on the Jetty container use the c3p0 datasource pool.
- JOnAS handles transactions for datasources using its `jtm` service.

### DataSource properties

DataSources are added through pipe-delimited configuration properties that starts with `cargo.datasource.datasource`. Example:

    cargo.datasource.datasource1=cargo.datasource.url=jdbc:mydriver:userdb\|cargo.datasource.driver=org.database.Driver\|...
    cargo.datasource.datasource2=cargo.datasource.url=jdbc:mydriver:referencedb\|cargo.datasource.driver=org.database.Driver\|...

Here are the properties that are valid for this:

- Note that `c.d` means `cargo.datasource`
- Note that if you specify a property marked do not set you will get a `CargoException`.

Property | Purpose | Valid Values | DataSource | Transactional DataSource | XA DataSource
--- | --- | --- | --- | --- | ---
`c.d.jndi` | The path to this DataSource in JNDI | Any jndi path, like `jdbc/userds` | mandatory | mandatory | mandatory
`c.d.driver` | The implementation class | ex. `my.Driver` | mandatory: must implement `java.sql.Driver` | mandatory: must implement `java.sql.Driver` | mandatory: must implement `javax.sql.XADataSource`
`c.d.properties` | Properties to pass to the driver | Semi-colon delimited string | optional | optional | mandatory
`c.d.url` | URL for the `java.sql.Driver` | ex. `jdbc:host:port/mydb` | mandatory | mandatory | optional
`c.d.type` | Determines the type of the driver | Defaults to `java.sql.Driver`, only set if you want to use a `javax.sql.XADataSource` | do not set | do not set | `javax.sql.XADataSource`
`c.d.transactionsupport` | Determines transaction support type | `LOCAL_TRANSACTION` or `XA_TRANSACTION` | do not set | mandatory | unset defaults to only valid option: `XA_TRANSACTION`
`c.d.id` | Identifier used in configuration files to reference this DataSource | Must contain no path-like characters | optional | optional | optional
`c.d.username` | Username to connect to the database | String | optional | optional | optional
`c.d.password` | Password to connect to the database | String | optional | optional | optional

### JMS resource properties

JMS resources (such as connection factories, queues or topics) are added through pipe-delimited configuration properties that starts with `cargo.resource.resource`. Example:

    cargo.resource.resource.jms.cf=cargo.resource.name=jms/cf/MyCf\|cargo.resource.type=javax.jms.ConnectionFactory\|cargo.resource.id=MyCf
    cargo.resource.resource.jms.queue=cargo.resource.name=jms/MyQueue\|cargo.resource.type=javax.jms.Queue\|cargo.resource.id=MyQueue

Here are the properties that are valid for this:

- Note that `c.r` means `cargo.resource`

Property | Purpose | Valid Values | Mandatory?
--- | --- | --- | ---
`c.r.id` | The ID for the JNDI entry of this JMS resource | ID used in configuration files, if not specified an identifier is created using the `name` | optional
`c.r.name` | The path to this JMS resource in JNDI | Any JNDI path, like `jms/cf/MyCf` or `jms/cf/MyQueue` | mandatory
`c.r.type` | Interface of the object | Any JNDI path, like: On J2EE / Java EE containers: `javax.jms.ConnectionFactory` or `javax.jms.Queue` On Jakarta EE containers: `jakarta.jms.ConnectionFactory` or `jakarta.jms.Queue` | mandatory
`c.r.parameters` | Properties to to populate the class with | Semi-colon delimited string; must correspond to setters | optional

Java EE vs. Jakarta EE

Even when you use Codehaus Cargo with a Jakarta EE container, you can keep on using `javax.jms.` definitions, which Codehaus Cargo will automatically translate to `jakarta.jms.` for your specific container if need be. This ensures you can easily test on Java EE and Jakarta EE without having to create very complex Codehaus Cargo property sets.

Please note that this doesn't work the other way round: `jakarta.jms.` definitions will not be "mapped back" to `javax.jms.` definitions on non Jakarta EE containers.

### Other resource properties

All other resources are added through pipe-delimited configuration properties that starts with `cargo.resource.resource`. Example:

    cargo.resource.resource1=cargo.resource.name=resource/apple\|cargo.resource.class=org.mycompany.Apple\|...
    cargo.resource.resource2=cargo.resource.name=resource/pear\|cargo.resource.driver=org.mycompany.Pear\|...

Here are the properties that are valid for this:

- Note that `c.r` means `cargo.resource`

Property | Purpose | Valid Values | Mandatory?
--- | --- | --- | ---
`c.r.id` | The ID for this JNDI entry | ID used in configuration files, if not specified an identifier is created using the `name` | optional
`c.r.name` | The path to this resource in JNDI | Any JNDI path, like `resource/apple` | mandatory
`c.r.type` | Interface of the object | Any valid interface | mandatory
`c.r.class` | The implementation class | Any valid class implementing the interface | mandatory
`c.r.parameters` | Properties to to populate the class with | Semi-colon delimited string; must correspond to setters | optional

### Known issues

The Glassfish container has various known issues with regards to DataSource support.

When you try to use GlassFish 3.x or GlassFish 4.x with Derby DataSources, you might run into issues where Glassfish doesn't start, and the Glassfish logs show you messages such as the below:

    java.lang.SecurityException: sealing violation: package org.apache.derby is sealed

This is because Glassfish is already shipped with Derby, and the Glassfish class loaders do not know how to the manage the situation where the same class is duplicated. So, the solution is to simply remove the Derby JAR from dependencies; on the other hand this is not feasible if you are using the same CARGO profile with different containers. Here is how you can work around the issue:

    <dependencies>
      <dependency>
        <groupId>org.apache.derby</groupId>
        <artifactId>derby</artifactId>
        <version>${derby.version}</version>
        <scope>test</scope>
      </dependency>
    </dependencies>

      ...

    <build>
      <plugins>
        <plugin>
          <groupId>org.codehaus.cargo</groupId>
          <artifactId>cargo-maven3-plugin</artifactId>
          <version>${cargo.version}</version>
          <!--
            This configuration will be used in general.
            -->
          <configuration>
            <container>
              <dependencies>
                <dependency>
                  <groupId>org.apache.derby</groupId>
                  <artifactId>derby</artifactId>
                </dependency>
              </dependencies>
              <systemProperties>
                <derby.system.home>\${project.build.directory}/derby</derby.system.home>
              </systemProperties>
            </container>
            <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>
            </configuration>

              ...

          </configuration>
        </plugin>
      </plugins>
    </build>

    <profiles>

        ...

      <profile>
        <id>glassfish3x</id>
        <build>
          <pluginManagement>
            <plugins>
              <plugin>
                <groupId>org.codehaus.cargo</groupId>
                <artifactId>cargo-maven3-plugin</artifactId>
                <configuration>
                  <container>
                    <containerId>glassfish3x</containerId>
                    <artifactInstaller>
                      <groupId>org.glassfish.main.distributions</groupId>
                      <artifactId>glassfish</artifactId>
                      <version>3.1.2.2</version>
                    </artifactInstaller>
                    <dependencies>
                      <!--
                        Remove the org.apache.derby dependency since GlassFish 3.x is already
                        shipped with Derby, and adding the dependency twice results in a
                        java.lang.SecurityException: sealing violation: package org.apache.derby.
                        -->
                        <dependency>
                          <groupId>org.apache.derby</groupId>
                          <artifactId>derby</artifactId>
                          <classpath>none</classpath>
                        </dependency>
                    </dependencies>
                  </container>
                </configuration>
              </plugin>
            </plugins>
          </pluginManagement>
        </build>
      </profile>
    </profiles>

### Examples

Users of the Java API can take a look at the following classes as example:

- `ConfigurationFixtureFactory`: class with static methods showing examples for creating various DataSource and resource types:
  - `createDataSource` and `createAnotherDataSource`: Creation of a DataSource
  - `createDriverConfiguredDataSourceWithLocalTransactionSupport`: Creation of a DataSource with local transaction support
  - `createDriverConfiguredDataSourceWithXaTransactionSupport`: Creation of a DataSource with XA transaction support
  - `createXADataSourceConfiguredDataSource`: Creation of an XA DataSource as DataSource
  - `createConnectionPoolDataSourceAsResource`: Creation of a connection pool
  - `createXADataSourceAsResource`: Creation of an XA DataSource as a resource
  - `createMailSessionAsResource`: Creation of a Mail resource
  - `createDataSourceWithWindowsPath`: Creation of a DataSource with a Windows path
  - `createJmsQueueAsResource` and `createJmsTopicAsResource`: Creation of a JMS queue and topic resource, respectively
- `DataSourceOnStandaloneConfigurationTest`: DataSource definition.
- `TransactionEmulationDataSourceOnStandaloneConfigurationTest`: DataSource definition with transaction emulation.
- `XATransactionDataSourceOnStandaloneConfigurationTest`: XA DataSource definition.
- `MailResourceOnStandaloneConfigurationTest`: Resource definition, showing for example `mailsession`.
- `JmsQueueResourceOnStandaloneConfigurationTest` and `JmsTopicResourceOnStandaloneConfigurationTest`: Resource definition, showing for example a JMS queue and topic, respectively.

Users of the Maven 3 Plugin can refer to the Maven 3 Archetype showing DataSource support.