Chapter 9.  Runtime Extensions

Table of Contents

1. Architecture
1.1. Broker Finalization
1.2. Broker Customization and Finalization
2. JPA Extensions
2.1. OpenJPAEntityManagerFactory
2.2. OpenJPAEntityManager
2.3. OpenJPAQuery
2.4. Extent
2.5. StoreCache
2.6. QueryResultCache
2.7. FetchPlan
2.8. OpenJPAPersistence
3. Object Locking
3.1. Configuring Default Locking
3.2. Configuring Lock Levels at Runtime
3.3. Object Locking APIs
3.4. Lock Manager
3.5. Rules for Locking Behavior
3.6. Known Issues and Limitations
4. Savepoints
4.1. Using Savepoints
4.2. Configuring Savepoints
5. MethodQL
6. Generators
6.1. Runtime Access
7. Transaction Events
8. Non-Relational Stores

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 can OpenJPA's native kernel can adopt.

As a 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.

1.1.  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.

1.2.  Broker Customization and Finalization

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.