Chapter 25.  Runtime Extensions

Table of Contents

Architecture
Broker Finalization
Broker Customization and Eviction
JPA Extensions
OpenJPAEntityManagerFactory
OpenJPAEntityManager
OpenJPAQuery
Extent
StoreCache
QueryResultCache
FetchPlan
OpenJPAEntityTransaction
OpenJPAPersistence
Object Locking
Configuring Default Locking
Configuring Lock Levels at Runtime
Object Locking APIs
Lock Manager
Rules for Locking Behavior
Known Issues and Limitations
Savepoints
Using Savepoints
Configuring Savepoints
MethodQL
Generators
Runtime Access
Transaction Events
Non-Relational Stores

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

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:

  • javax.persistence.EntityManagerFactory: org.apache.openjpa.kernel.BrokerFactory

  • javax.persistence.EntityManager: org.apache.openjpa.kernel.Broker

  • javax.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, EntityManagers and Brokers.

Broker Finalization

Outside of a Java EE 5 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.

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 25.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 the section called “ Broker Finalization ”. It may be appropriate to create a subtype of both org.apache.openjpa.kernel.BrokerImpl and org.apache.openjpa.kernel.FinalizingBrokerImpl.