4.2. Using a Third-Party DataSource

4.2.1. Managed and XA DataSources

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

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 DataSources 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, set the kodo.ConnectionFactoryMode property to managed.

Note that Kodo can only use managed DataSources 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 DataSources 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 various "2" connection properties, such as kodo.ConnectionFactory2Name or kodo.Connection2DriverName. These properties are outlined in Chapter 2, Configuration. If your second DataSource is also bound to JNDI, you can use JPA XML's non-jta-data-source to specify its location. Typically, though, you will use Kodo's built-in implementation for the second DataSource (see Section 4.1, “Using the Kodo DataSource”).

Example 4.3. Managed DataSource Configuration

JPA XML format:

<!-- managed DataSource -->
    <!-- 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"/>

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


Skip navigation bar   Back to Top