2. JPA Extensions
Prev | Chapter 9. Runtime Extensions | Next

## 2. JPA Extensions

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. `OpenJPAPersistence`'s `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 `OpenJPAPersistence` helper below.

### 2.1. OpenJPAEntityManagerFactory

The `org.apache.openjpa.persistence.OpenJPAEntityManagerFactory` interface extends the basic `javax.persistence.EntityManagerFactory` with OpenJPA-specific features. The `OpenJPAEntityManagerFactory` offers APIs to access the OpenJPA data and query caches and to perform other OpenJPA-specific operations. See the interface Javadoc for details.

### 2.2. OpenJPAEntityManager

All OpenJPA `EntityManager`s implement the `org.apache.openjpa.persistence.OpenJPAEntityManager` 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.

### 2.3. OpenJPAQuery

OpenJPA extends JPA's standard query functionality with the `org.apache.openjpa.persistence.OpenJPAQuery` interface. See its Javadoc for details on the convenience methods it provides.

### 2.4. Extent

An `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);

### 2.5. StoreCache

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 `org.apache.openjpa.persistence.StoreCache`. Section 1, “ Data Cache ” has detailed information on OpenJPA's data caching system, including the `StoreCache` facade.

### 2.6. QueryResultCache

OpenJPA can cache query results as well as persistent object data. The `org.apache.openjpa.persistence.QueryResultCache` is an JPA-flavored facade to OpenJPA's internal query cache. See Section 1.4, “ Query Cache ” for details on query caching in OpenJPA.

### 2.7. FetchPlan

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 `FetchPlan` with `org.apache.openjpa.persistence.jdbc.JDBCFetchPlan` to add additional JDBC-specific tuning methods. Unless you have customized OpenJPA to use a non-relational back-end (see Section 8, “ Non-Relational Stores ” ), all `FetchPlan`s 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 `EntityManager`s it produces. The settings of each `EntityManager`, in turn, are passed on to each `Query` and `Extent` it returns. Note that the opposite, however, is not true. Modifying the fetch plan of a `Query` or `Extent` does not affect the `EntityManager`'s configuration. Likewise, modifying an `EntityManager`'s configuration does not affect the `EntityManagerFactory`.

Section 7, “ Fetch Groups ” includes examples using `FetchPlan`s.

### 2.8. OpenJPAEntityTransaction

`org.apache.openjpa.persistence.OpenJPAEntityTransaction` extends `javax.persistence.EntityTransaction` to provide additional transaction-debugging capabilities and some concurrency-related commit and rollback features.

### 2.9. OpenJPAPersistence

`org.apache.openjpa.persistence.OpenJPAPersistence` is a static helper class that adds OpenJPA-specific utility methods to `javax.persistence.Persistence`.

Prev | Up | Next
Chapter 9. Runtime Extensions | Home | 3. Object Locking