Chapter 9. Runtime Extensions

9.1. Architecture
9.1.1. Broker Customization
9.2. JPA Extensions
9.2.1. OpenJPAEntityManagerFactory
9.2.2. OpenJPAEntityManager
9.2.3. OpenJPAQuery
9.2.4. Extent
9.2.5. StoreCache
9.2.6. QueryResultCache
9.2.7. FetchPlan
9.2.8. OpenJPAPersistence
9.3. JDO API Extensions
9.3.1. KodoPersistenceManagerFactory
9.3.2. KodoPersistenceManager
9.3.3. KodoQuery
9.3.4. KodoExtent
9.3.5. KodoDataStoreCache
9.3.6. QueryResultCache
9.3.7. KodoFetchPlan
9.3.8. KodoJDOHelper
9.4. Object Locking
9.4.1. Configuring Default Locking
9.4.2. Configuring Lock Levels at Runtime
9.4.3. Object Locking APIs
9.4.4. Lock Manager
9.4.5. Rules for Locking Behavior
9.4.6. Known Issues and Limitations
9.5. Savepoints
9.5.1. Using Savepoints
9.5.2. Configuring Savepoints
9.6. Query Language Extensions
9.6.1. Filter Extensions Included Filter Extensions Developing Custom Filter Extensions Configuring Filter Extensions
9.6.2. Aggregate Extensions Configuring Query Aggregates
9.6.3. JDOQL Non-Distinct Results
9.6.4. JDOQL Subqueries Subquery Parameters, Variables, and Imports
9.6.5. MethodQL
9.7. Generators
9.7.1. Runtime Access
9.8. Transaction Events
9.9. Non-Relational Stores

This chapter describes Kodo extensions to the standard JPA and JDO interfaces, and outlines some additional features of the Kodo runtime.

9.1. Architecture

Internally, Kodo does not adhere to any persistence specification. The Kodo kernel has its own set of APIs and components. Specifications like JPA and JDO are simply different "personalities" that can Kodo's native kernel can adopt.

As a Kodo JPA/JDO user, you will not normally see beneath Kodo's JPA and JDO personalities. Kodo allows you to access its feature set without leaving the comfort of JPA or JDO. Where Kodo goes beyond standard functionality, we have crafted JPA-specific and JDO-specific APIs to each Kodo extension for as seamless an experience as possible.

When writing Kodo plugins or otherwise extending the Kodo runtime, however, you will use Kodo's native APIs. So that you won't feel lost, the list below associates each specification interface with its backing native Kodo component:

  • javax.persistence.EntityManagerFactory: kodo.kernel.BrokerFactory

  • javax.jdo.PersistenceManagerFactory: kodo.kernel.BrokerFactory

  • javax.persistence.EntityManager: kodo.kernel.Broker

  • javax.jdo.PersistenceManager: kodo.kernel.Broker

  • javax.persistence.Query: kodo.kernel.Query

  • javax.jdo.Query: kodo.kernel.Query

  • org.apache.openjpa.persistence.Extent: kodo.kernel.Extent

  • javax.jdo.Extent: kodo.kernel.Extent

  • org.apache.openjpa.persistence.StoreCache: kodo.datacache.DataCache

  • javax.jdo.datastore.DataStoreCache: kodo.datacache.DataCache

  • org.apache.openjpa.persistence.QueryResultCache: kodo.datacache.QueryCache

  • kodo.jdo.QueryResultCache: kodo.datacache.QueryCache

  • org.apache.openjpa.persistence.FetchPlan: kodo.kernel.FetchConfiguration

  • javax.jdo.FetchPlan: kodo.kernel.FetchConfiguration

  • org.apache.openjpa.persistence.Generator: kodo.kernel.Seq

  • javax.jdo.datastore.Sequence: kodo.kernel.Seq

The org.apache.openjpa.persistence.OpenJPAPersistence helper allows you to convert between EntityManagerFactories and BrokerFactories, EntityManagers and Brokers.

The kodo.jdo.KodoJDOHelper allows you to convert between PersistenceManagerFactories and BrokerFactories, PersistenceManagers and Brokers.

As a Kodo JPA/JDO user, you can use these methods to move from an JPA to a JDO persistence API (or vice versa) at any time. You can even switch back and forth within the same persistence context, as the following example illustrates:

Example 9.1. Switching APIs within a Persistence Context

EntityManager em = ...;
em.getTransaction ().begin ();

Magazine mag = em.find (Magazine.class, magId);
setHigherSellers (mag);

em.getTransaction ().commit ();
em.close ();


private void setHigherSellers (Magazine mag)
    // or we could get the EM using OpenJPAPersistence, convert it to a Broker,
    // and convert the Broker to a PM using KodoJDOHelper. this is easier
    PersistenceManager pm = JDOHelper.getPersistenceManager (mag);
    Query q = pm.newQuery (Magazine.class, "sales > :s");
    List results = (List) q.execute (mag.getSales ());
    mag.setHigherSellingMagazines (new HashSet (results)); 

9.1.1. Broker Customization

Some advanced users may want to add capabilities to Kodo's internal kodo.kernel.BrokerImpl. You can configure Kodo to use a custom subclass of BrokerImpl through the kodo.BrokerImpl configuration property. Set this property to the full class name of your custom subclass.

As a plugin string, you can also use this property to configure the BrokerImpl with the following properties:

  • EvictFromDataCache: When evicting an object through the OpenJPAEntityManager.evict or PersistenceManager.evict methods, whether to also evict it from the Kodo's data cache. Defaults to false.

Example 9.2. Evict from Data Cache

JPA XML format:

<property name="kodo.BrokerImpl" value="EvictFromDataCache=true"/>

JDO properties format:

kodo.BrokerImpl: EvictFromDataCache=true


Skip navigation bar   Back to Top