Table of Contents
This chapter describes OpenJPA extensions to the standard JPA interfaces, and outlines some additional features of the OpenJPA runtime.
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.
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.
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.