10.2. KodoPersistenceManager
Prev | Chapter 10. JDO Runtime Extensions | Next

## 10.2. KodoPersistenceManager

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.

### 10.2.1. JDO Transaction Events

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
The Kodo JDO Performance Pack also supports distributed events.

### 10.2.2. JDO 2 Preview Methods

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.

### 10.2.3. Lifecycle Events

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.

### 10.2.4. PersistenceManager Extension

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 `PersistenceManagerImpl`s 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`.

Prev | Up | Next
Chapter 10. JDO Runtime Extensions | Home | 10.3. KodoExtent