The following sections outline the runtime interfaces you can use to access OpenJPA-specific functionality from JPA. Each interface contains services and convenience methods missing from the JPA specification. OpenJPA strives to use the same naming conventions and API patterns as standard JPA methods in all extensions, so that OpenJPA extension APIs feel as much as possible like standard JPA.
You may have noticed the examples throughout this document using the
OpenJPAPersistence.cast methods to cast from standard
JPA interfaces to OpenJPA extended interfaces. This is the recommended practice.
Some application server vendors may proxy OpenJPA's JPA implementation,
preventing a straight cast.
cast methods work around these proxies.
public static OpenJPAEntityManagerFactory cast(EntityManagerFactory emf); public static OpenJPAEntityManager cast(EntityManager em); public static OpenJPAQuery cast(Query q);
We provide additional information on the
interface extends the basic
javax.persistence.EntityManagerFactory with OpenJPA-specific
OpenJPAEntityManagerFactory offers APIs to
access the OpenJPA data and query caches and to perform other OpenJPA-specific
operations. See the
interface Javadoc for details.
EntityManagers implement the
interface. This interface extends the standard
javax.persistence.EntityManager. Just as the standard
EntityManager is the primary window into JPA services, the
OpenJPAEntityManager is the primary window from JPA into
OpenJPA-specific functionality. We strongly encourage you to investigate the API
extensions this interface contains.
OpenJPA extends JPA's standard query functionality with the
org.apache.openjpa.persistence.OpenJPAQuery interface. See its
for details on the convenience methods it provides.
Extent is a logical view of all persistent instances
of a given entity class, possibly including subclasses. OpenJPA adds the
org.apache.openjpa.persistence.Extent class to the set of
Java Persistence APIs. The following code illustrates iterating over all
instances of the
Magazine entity, without subclasses:
Example 9.2. Using a JPA Extent
import org.apache.openjpa.persistence.*; ... OpenJPAEntityManager kem = OpenJPAPersistence.cast(em); Extent<Magazine> mags = kem.createExtent(Magazine.class, false); for (Magazine m : mags) processMagazine(m);
In addition to the
EntityManager object cache the JPA
specification provides access to a second level cache via the
javax.persistence.Cache interface. OpenJPA provides further extensions via
the org.apache.openjpa.persistence.StoreCache interface documented at
Section 1, “
” has detailed information on OpenJPA's
data caching system, including the
OpenJPA can cache query results as well as persistent object data. The
is an JPA-flavored facade to OpenJPA's internal query cache. See
Section 1.4, “
” for details on query caching in
Many of the aforementioned OpenJPA interfaces give you access to an
org.apache.openjpa.persistence.FetchPlan instance. The
FetchPlan allows you to exercise some control over how objects are
fetched from the datastore, including
large result set support, custom fetch
groups, and lock levels.
OpenJPA goes one step further, extending
to add additional JDBC-specific tuning methods. Unless you have customized
OpenJPA to use a non-relational back-end (see
Section 8, “
” ), all
FetchPlans in OpenJPA implement
JDBCFetchPlan, so feel free to cast to this interface.
Fetch plans pass on from parent components to child components. The
EntityManagerFactory settings (via your configuration properties)
for things like the fetch size, result set type, and custom fetch groups are
passed on to the fetch plan of the
produces. The settings of each
EntityManager, in turn,
are passed on to each
it returns. Note that the opposite, however, is not true. Modifying
the fetch plan of a
does not affect the
configuration. Likewise, modifying an
configuration does not affect the
Section 7, “
” includes examples using
javax.persistence.EntityTransaction to provide
additional transaction-debugging capabilities and some concurrency-related
commit and rollback features.
is a static helper class that adds OpenJPA-specific utility methods to