Chapter 9. Runtime Extensions
Prev | Part 3. Reference Guide | Next

## Chapter 9. Runtime Extensions

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

## 1. Architecture

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

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

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

- `jakarta.persistence.EntityManagerFactory`: `org.apache.openjpa.kernel.BrokerFactory`

- `jakarta.persistence.EntityManager`: `org.apache.openjpa.kernel.Broker`

- `jakarta.persistence.Query`: `org.apache.openjpa.kernel.Query`

- `org.apache.openjpa.persistence.Extent`: `org.apache.openjpa.kernel.Extent`

- `org.apache.openjpa.persistence.StoreCache`: `org.apache.openjpa.datacache.DataCache`

- `org.apache.openjpa.persistence.QueryResultCache`: `org.apache.openjpa.datacache.QueryCache`

- `org.apache.openjpa.persistence.FetchPlan`: `org.apache.openjpa.kernel.FetchConfiguration`

- `org.apache.openjpa.persistence.Generator`: `org.apache.openjpa.kernel.Seq`

The `org.apache.openjpa.persistence.OpenJPAPersistence` helper allows you to convert between `EntityManagerFactories` and `BrokerFactories`, `EntityManager`s and `Broker`s.

### 1.1. Broker Finalization

Outside of a Java EE application server or other JPA persistence container environment, the default OpenJPAEntityManager implementation automatically closes itself during instance finalization. This guards against accidental resource leaks that may occur if a developer fails to explicitly close EntityManagers when finished with them, but it also incurs a scalability bottleneck, since the JVM must perform synchronization during instance creation, and since the finalizer thread will have more instances to monitor. To avoid this overhead, set the `openjpa.BrokerImpl` configuration property to `non-finalizing`.

### 1.2. Broker Customization and Eviction

As a plugin string, this property can be used to configure the `BrokerImpl` with the following properties:

- `EvictFromDataCache`: When evicting an object through the `OpenJPAEntityManager.evict` methods, whether to also evict it from the OpenJPA's data cache. Defaults to `false`.

Example 9.1. Evict from Data Cache

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

Additionally, some advanced users may want to add capabilities to OpenJPA's internal `org.apache.openjpa.kernel.BrokerImpl`. You can configure OpenJPA to use a custom subclass of `BrokerImpl` with the `openjpa.BrokerImpl` configuration property. Set this property to the full class name of your custom subclass. When implementing your subclass, consider the finalization issues mentioned in Section 1.1, “ Broker Finalization ”. It may be appropriate to create a subtype of both `org.apache.openjpa.kernel.BrokerImpl` and `org.apache.openjpa.kernel.FinalizingBrokerImpl`.

Prev | Up | Next
3. XA Transactions | Home | 2. JPA Extensions