4.2. Using a Third-Party DataSource
Prev | Chapter 4. JDBC | Next

## 4.2. Using a Third-Party DataSource

You can use Kodo with any third-party `javax.sql.DataSource`. There are multiple ways of telling Kodo about a `DataSource`:

- Set the `DataSource` into the map passed to `Persistence.createEntityManagerFactory` under the `kodo.ConnectionFactory` key.

- Bind the `DataSource` into JNDI, and then specify its location in the `jta-data-source` or `non-jta-data-source` element of the JPA XML format (depending on whether the `DataSource` is managed by JTA), or in the `kodo.ConnectionFactoryName` property.

- Specify the full class name of the `DataSource` implementation in the `kodo.ConnectionDriverName` property in place of a JDBC driver. In this configuration Kodo will instantiate an instance of the named class via reflection. It will then configure the `DataSource` with the properties in the `kodo.ConnectionProperties` setting.

Some advanced features of Kodo's own `DataSource` can also be used with third-party implementations. Kodo layers on top of the third-party `DataSource` to provide the extra functionality. To configure these advanced features, including prepared statement caching, use the `kodo.ConnectionFactoryProperties` property described in the previous section.

Example 4.2. Properties File for a Third-Party DataSource

JPA XML format:

    <property name="kodo.ConnectionDriverName" value="oracle.jdbc.pool.OracleDataSource"/>
    <property name="kodo.ConnectionProperties"
        value="PortNumber=1521, ServerName=saturn, DatabaseName=solarsid, DriverType=thin"/>
    <property name="kodo.ConnectionFactoryProperties" value="QueryTimeout=5000"/>

JDO properties format:

    kodo.ConnectionDriverName: oracle.jdbc.pool.OracleDataSource
    kodo.ConnectionProperties: PortNumber=1521, ServerName=saturn, \
        DatabaseName=solarsid, DriverType=thin
    kodo.ConnectionFactoryProperties: QueryTimeout=5000

### 4.2.1. Managed and XA DataSources

Certain application servers automatically enlist their `DataSource`s in global transactions. When this is the case, Kodo should not attempt to commit the underlying connection, leaving JDBC transaction completion to the application server. To notify Kodo that your third-party `DataSource` is managed by the application server, use the `jta-data-source` element of your `persistence.xml` file or set the `kodo.ConnectionFactoryMode` property to `managed`.

Note that Kodo can only use managed `DataSource`s when it is also integrating with the application server's managed transactions, as discussed in Section 8.2, “Integrating with the Transaction Manager”. Also note that all XA `DataSource`s are enlisted, and you must set this property when using any XA `DataSource`. XA transactions are detailed in Section 8.3, “XA Transactions”.

When using a managed `DataSource`, you should also configure a second unmanaged `DataSource` that Kodo can use to perform tasks that are independent of the global transaction. The most common of these tasks is updating the sequence table Kodo uses to generate unique primary key values for your datastore identity objects. Configure the second `DataSource` just as the first, but use the `non-jta-data-source` element of your `persistence.xml` or the various "2" connection properties, such as `kodo.ConnectionFactory2Name` or `kodo.Connection2DriverName`. These properties are outlined in Chapter 2, Configuration.

Example 4.3. Managed DataSource Configuration

JPA XML format:

    <!-- managed DataSource -->
    <jta-data-source>java:/OracleXASource</jta-data-source>
    <properties>
        <!-- use Kodo's built-in DataSource for unmanaged connections -->
        <property name="kodo.Connection2UserName" value="scott"/>
        <property name="kodo.Connection2Password" value="tiger"/>
        <property name="kodo.Connection2URL" value="jdbc:oracle:thin:@CROM:1521:KodoDB"/>
        <property name="kodo.Connection2DriverName" value="oracle.jdbc.driver.OracleDriver"/>
        <property name="kodo.ConnectionFactory2Properties" value="MaxActive=20, MaxIdle=10"/>
        <!-- managed transaction and enlisted configuration -->
        <property name="kodo.TransactionMode" value="managed"/>
        <property name="kodo.ConnectionFactoryMode" value="managed"/>
    </properties>

JDO properties format:

    # managed DataSource
    kodo.ConnectionFactoryName: java:/OracleXASource

    # use Kodo's built-in DataSource for unmanaged connections
    kodo.Connection2UserName: scott
    kodo.Connection2Password: tiger
    kodo.Connection2URL: jdbc:oracle:thin:@CROM:1521:KodoDB
    kodo.Connection2DriverName: oracle.jdbc.driver.OracleDriver
    kodo.ConnectionFactory2Properties: MaxActive=20, MaxIdle=10

    # managed transaction and enlisted configuration
    kodo.TransactionMode: managed
    kodo.ConnectionFactoryMode: managed

Prev | Up | Next
Chapter 4. JDBC | Home | 4.3. Runtime Access to DataSource