All Kodo persistence managers implement the kodo.runtime.KodoPersistenceManager interface. This interface extends the standard javax.jdo.PersistenceManager, and, just as the standard persistence manager is the primary window into JDO runtime services, the KodoPersistenceManager is the primary window into Kodo-specific functionality. We strongly encourage you to investigate the API extensions this interface contains, including many JDO 2.0 preview features.
One very important aspect of the KodoPersistenceManager is its support for broadcasting transaction-related events. By registering one or more kodo.event.TransactionListener's with the persistence manager, you can receive notifications when transactions begin, flush, rollback, commit, and more. Where appropriate, event notifications include the set of persistence-capable objects participating in the transaction.
For details on the transaction framework, see the Javadoc for the kodo.event package.
![[Note]](img/note.gif) | Note |
|---|---|
The Kodo JDO Performance Pack also supports distributed events. | |
Kodo extends PersistenceManager with a variety of methods which preview JDO 2 features. These methods currently require casting to a KodoPersistenceManager to use. The Javadoc for details specifics with regards to using these methods.
| Note |
|---|---|
These methods are JDO 2 preview features and may change before the JDO 2 specification is finalized. | |
getObjectsById (Object[] oids, boolean validate) : Return the instances with the corresponding object ids.
getObjectById (Class cls, Object value): This method returns the persistent instances of the given type by a variety of values:
Primary key value for single field identity or application identity with a single primary key field.
Object id instances.
java.lang.Number instances which wrap kodo.util.Id datastore primary key value. This is a Kodo extension of JDO functionality.
Stringified id instances. This is a Kodo extension of JDO functionality.
attach/detach(All) : Manage persistent copies which can be used to persist changes made outside of a PersistenceManager context, such as during remote use. See Section 11.1, “Detach and Attach”.
add/removeLifecycleListener (InstanceLifecycleListener listener, Class[] classes) : Manage listeners which can be notified of events on persistent instances. See Section 10.2.3, “Lifecycle Events”.
refreshAll (JDOException) : Refresh all failed objects contained in this exception, as well as any nested exceptions.
flush () : Flush changes on the current transactional instances to the datastore. This will trigger changes that would be executed on commit, without permanently altering the datastore.
checkConsistency () : Check the consistency of the persistence manager cache, including optimistic violations, constraint violations, etc.
put/remove/getUserObject (Object key, Object val): Manage key-value pairs in the map of user objects.
setRollbackOnly () : Will be moved to javax.jdo.Transaction. Defer transaction rollback until completion.
Kodo includes the JDO 2 preview feature of listening for lifecycle events without implementing InstanceCallbacks on persistent classes. You can listen to state changes for the objects managed by a single persistence manager by adding InstanceLifecycleListeners to the KodoPersistenceManager of interest. Or, listen to state changes on all instances of all persistence managers by adding your listeners to the KodoPersistenceManagerFactory.
For details on the lifecycle event framework, see the Javadoc for the kodo.event package. For details on instance state changes, see Section 4.4, “InstanceCallbacks”.
| Note |
|---|---|
Lifecycle listeners are a JDO 2 preview feature and may change before the JDO 2 specification is finalized. | |
Some advanced users may want to use a custom PersistenceManager in place of Kodo JDO's kodo.runtime.PersistenceManagerImpl.
Kodo JDO permits simple extension of the PersistenceManager used by the runtime. This can be useful when custom behavior is desired, or when an application needs to receive notification when certain PersistenceManager methods are invoked.
To specify a subclass of PersistenceManagerImpl, set the kodo.PersistenceManagerImpl configuration property to the full class name of you custom persistence manager.
As a plugin string, this property can also be used to configure persistence managers. All PersistenceManagerImpls recognize the following properties:
CloseOnManagedCommit: If true, then the persistence manager will be closed after a managed transaction (such as an EJB container-managed transaction) commits, assuming you have invoked the close method. If this is set to false, then the persistence manager will not be closed. This means that objects that were not properly detached from the persistence manager at the end of a session bean method and were then passed to a processing tier in the same JVM will still be usable, as their owning persistence manager will still be open. This behavior is not in strict compliance with the JDO specification, but is convenient for applications that were coded against Kodo 2, which did not close the persistence manager in these situations. The default for this property is true, meaning that the PersistenceManager will be properly closed.
EvictFromDataCache: When evicting an object through the standard persistence manager evict methods, whether to also evict it from the Kodo's datastore cache. Defaults to false.