4.2. Using a Third-Party DataSource

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

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:

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 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, 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 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 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