Chapter 9. Runtime Extensions
Prev | Part 6. Kodo JPA/JDO Reference Guide | Next

## Chapter 9. Runtime Extensions

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`

- `kodo.persistence.Extent`: `kodo.kernel.Extent`

- `javax.jdo.Extent`: `kodo.kernel.Extent`

- `kodo.persistence.StoreCache`: `kodo.datacache.DataCache`

- `javax.jdo.datastore.DataStoreCache`: `kodo.datacache.DataCache`

- `kodo.persistence.QueryResultCache`: `kodo.datacache.QueryCache`

- `kodo.jdo.QueryResultCache`: `kodo.datacache.QueryCache`

- `kodo.persistence.FetchPlan`: `kodo.kernel.FetchConfiguration`

- `javax.jdo.FetchPlan`: `kodo.kernel.FetchConfiguration`

- `kodo.persistence.Generator`: `kodo.kernel.Seq`

- `javax.jdo.datastore.Sequence`: `kodo.kernel.Seq`

The `kodo.persistence.KodoPersistence` helper allows you to convert between `EntityManagerFactories` and `BrokerFactories`, `EntityManager`s and `Broker`s.

The `kodo.jdo.KodoJDOHelper` allows you to convert between `PersistenceManagerFactories` and `BrokerFactories`, `PersistenceManager`s and `Broker`s.

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

    import kodo.persistence.*;

    ...

    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 KodoPersistence, 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 `KodoEntityManager.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

Prev | Up | Next
8.3. XA Transactions | Home | 9.2. JPA Extensions