In its default configuration, Kodo obtains JDBC connections on
an as-needed basis. Kodo EntityManagers and
PersistenceManagers do not retain a connection
to the database unless they are in a datastore transaction or there are
open Extent iterators or
Query
results that are using a live JDBC result set. At all other times,
including during optimistic transactions,
EntityManagers and
PersistenceManagers request a connection for each query,
then immediately release the connection back to the pool.
In some cases, it may be more efficient to retain connections for
longer periods of time. You can configure Kodo's use of JDBC
connections through the
kodo.ConnectionRetainMode configuration property.
The property accepts the following values:
always: Each EntityManager
or PersistenceManager
obtains a single connection and uses it until the
EntityManager or PersistenceManager
closes.
transaction: A connection is obtained
when each transaction begins (optimistic or datastore),
and is released when the transaction completes.
Non-transactional connections are obtained on-demand.
on-demand: Connections are obtained
only when needed. This option is equivalent to
the transaction option when datastore
transactions are used. For optimistic transactions,
though, it means that a connection will be retained only
for the duration of the datastore flush and commit process.
You can also specify the connection retain mode of individual
EntityManagers and
PersistenceManagers when you retrieve them from
their respective factories. See
Section 9.2.1, “OpenJPAEntityManagerFactory”
and Section 9.3.1, “KodoPersistenceManagerFactory” for details.
The
kodo.FlushBeforeQueries configuration property controls
another aspect of connection usage: whether to flush transactional
changes before executing object queries. This setting only applies to
queries that would otherwise have to be executed in-memory because the
IgnoreChanges
property is set to false and the query may involve objects that
have been changed in the current transaction. Legal values are:
true: Always flush rather than executing
the query in-memory. If the current transaction is
optimistic, Kodo will begin a non-locking datastore
transaction. This is the default.
false: Never flush before a query.
with-connection: Flush only if the
EntityManager or
PersistenceManager has already established a
dedicated connection to the datastore, otherwise execute the
query in-memory.
This option is useful if you use long-running optimistic transactions and want to ensure that these transactions do not consume database resources until commit. Kodo's behavior with this option is dependent on the transaction status and mode, as well as the configured connection retain mode described earlier in this section.
The flush mode can also be varied at runtime using the Kodo fetch configuration API, discussed in Chapter 9, Runtime Extensions.
The table below describes the behavior of automatic flushing in various situations. In all cases, flushing will only occur if Kodo detects that you have made modifications in the current transaction that may affect the query's results.
Table 4.2. Kodo Automatic Flush Behavior
| FlushBeforeQueries = false | FlushBeforeQueries = true | FlushBeforeQueries = with-connection; ConnectionRetainMode = on-demand | FlushBeforeQueries = with-connection; ConnectionRetainMode = transaction or always | |
|---|---|---|---|---|
| IgnoreChanges = true | no flush | no flush | no flush | no flush |
| IgnoreChanges = false; no tx active | no flush | no flush | no flush | no flush |
| IgnoreChanges = false; datastore tx active | no flush | flush | flush | flush |
| IgnoreChanges = false; optimistic tx active | no flush | flush |
no flush unless flush has
already been invoked
| flush |
Example 4.12. Specifying Connection Usage Defaults
JPA XML format:
<property name="kodo.ConnectionRetainMode" value="on-demand"/> <property name="kodo.FlushBeforeQueries" value="true"/>
JDO properties format:
kodo.ConnectionRetainMode: on-demand kodo.FlushBeforeQueries: true
Example 4.13. Specifying Connection Usage at Runtime
JPA:
// obtaining an em with a certain connection retain mode
Map props = new HashMap();
props.put("kodo.ConnectionRetainMode", "always");
EntityManager em = emf.createEntityManager(props);
JDO:
import kodo.jdo.*;
...
// obtaining a pm with a certain transaction and connection retain mode
KodoPersistenceManagerFactory kpmf = KodoJDOHelper.cast (pmf);
PersistenceManager pm = kpmf.getPersistenceManager (false,
KodoPersistenceManager.CONN_RETAIN_ALWAYS);
...
// changing the flush mode for an individual PersistenceManager
KodoFetchPlan fetch = (KodoFetchPlan) pm.getFetchPlan ();
fetch.setFlushBeforeQueries (KodoFetchPlan.QUERY_FLUSH_TRUE);
|
|
