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