In its default configuration, Kodo JDO obtains JDBC connections on an as-needed basis. Kodo persistence managers 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, persistence managers 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 JDO's use of JDBC connections through the kodo.ConnectionRetainMode configuration property. The property accepts the following values:
persistence-manager: Each persistence manager obtains a single connection and uses it until the persistence manager is closed.
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 data store flush and commit process.
You can also specify the connection retain mode of individual persistence managers when you retrieve them from the persistence manager factory. See Section 10.1, “KodoPersistenceManagerFactory” for details.
The kodo.FlushBeforeQueries configuration property controls another aspect of connection usage: whether to flush transactional changes before executing JDO queries. This setting only applies to queries that would otherwise have to be executed in-memory because the IgnoreCache 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.
false: Never flush before a query.
with-connection: Flush only if the persistence manager has already established a dedicated connection to the data store, 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 set on individual Kodo JDO persistence manager and query instances using the fetch configuration API, discussed in the JDO Runtime Extensions chapter.
The table below describes the behavior of automatic flushing in various different situations. In all these situations, flushing will only occur if Kodo detects that you have made modifications in the current transaction to instances of types that are in the current query's access path.
Table 4.2. Kodo Automatic Flush Behavior
| FlushBeforeQueries = false | FlushBeforeQueries = true | FlushBeforeQueries = with-connection; ConnectionRetainMode = on-demand | FlushBeforeQueries = with-connection; ConnectionRetainMode = transaction or persistence-manager | |
|---|---|---|---|---|
| IgnoreCache = true | no flush | no flush | no flush | no flush |
| IgnoreCache = false; no tx active | no flush | no flush | no flush | no flush |
| IgnoreCache = false; datastore tx active | no flush | flush | flush | flush |
| IgnoreCache = false; optimistic tx active | no flush | flush | no flush unless KodoPeristenceManager.flush has already been invoked | flush |
Example 4.7. Specifying Connection Usage Defaults
kodo.ConnectionRetainMode: on-demand kodo.FlushBeforeQueries: true
Example 4.8. Specifying Connection Usage at Runtime
import kodo.runtime.*;
...
// obtaining a pm with a certain transaction and connection retain mode
KodoPersistenceManagerFactory pmf = (KodoPersistenceManagerFactory) JDOHelper.
getPersistenceManagerFactory (props);
PersistenceManager pm = pmf.getPersistenceManager
(KodoPersistenceManager.TRANS_LOCAL, KodoPersistenceManager.CONN_RETAIN_PM);
...
// changing the flush mode for an individual persistence manager
KodoPersistenceManager kpm = (KodoPersistenceManager) pm;
FetchConfiguration fetch = kpm.getFetchConfiguration ();
kpm.getFetchConfiguration ().setFlushBeforeQueries (fetch.QUERY_FLUSH_TRUE);