4.2. Using a Third-Party DataSource

4.2.1. Enlisted Data Sources

Kodo JDO can be used with any third-party javax.sql.DataSource. There are 2 primary ways of telling Kodo JDO about a DataSource:

Some advanced features of Kodo JDO's own DataSource can also be used with third-party implementations. Kodo JDO 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

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

4.2.1. Enlisted Data Sources

Certain application servers automatically enlist their data sources 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 data source will automatically be enlisted in transactions, set the kodo.jdbc.DataSourceMode property to enlisted:

kodo.jdbc.DataSourceMode: enlisted

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

When using an enlisted datasource, you should also configure a second non-enlisted datasource that Kodo can use to perform tasks that are independent of the global transaction in progress. The most comon of these tasks is updating the sequence table Kodo uses to generate unique identity values for your datastore identity objects. Configure the second data source just as the first, but use the various "2" connection properties, such as javax.jdo.option.ConnectionFactory2Name or javax.jdo.option.Connection2DriverName. These properties are outlined in Chapter 2, Configuration. Typically, you will use Kodo's built-in datasource for the second data source (see Section 4.1, “Using the Kodo JDO DataSource”).