| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>2. JPA Extensions</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.2 User's Guide"><link rel="up" href="ref_guide_runtime.html" title="Chapter 9. Runtime Extensions"><link rel="prev" href="ref_guide_runtime.html" title="Chapter 9. Runtime Extensions"><link rel="next" href="ref_guide_locking.html" title="3. Object Locking"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2. |
| JPA Extensions |
| </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_runtime.html">Prev</a> </td><th width="60%" align="center">Chapter 9. |
| Runtime Extensions |
| </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_locking.html">Next</a></td></tr></table><hr></div><div class="section" title="2. JPA Extensions"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_runtime_jpa">2. |
| JPA Extensions |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_runtime_jpa.html#ref_guide_runtime_emfactory">2.1. |
| OpenJPAEntityManagerFactory |
| </a></span></dt><dt><span class="section"><a href="ref_guide_runtime_jpa.html#ref_guide_runtime_em">2.2. |
| OpenJPAEntityManager |
| </a></span></dt><dt><span class="section"><a href="ref_guide_runtime_jpa.html#ref_guide_runtime_jpaquery">2.3. |
| OpenJPAQuery |
| </a></span></dt><dt><span class="section"><a href="ref_guide_runtime_jpa.html#ref_guide_runtime_jpaextent">2.4. |
| Extent |
| </a></span></dt><dt><span class="section"><a href="ref_guide_runtime_jpa.html#ref_guide_runtime_jpacache">2.5. |
| StoreCache |
| </a></span></dt><dt><span class="section"><a href="ref_guide_runtime_jpa.html#ref_guide_runtime_jpaquerycache">2.6. |
| QueryResultCache |
| </a></span></dt><dt><span class="section"><a href="ref_guide_runtime_jpa.html#ref_guide_runtime_jpafetch">2.7. |
| FetchPlan |
| </a></span></dt><dt><span class="section"><a href="ref_guide_runtime_jpa.html#ref_guide_runtime_openjpaentitytransaction">2.8. |
| OpenJPAEntityTransaction |
| </a></span></dt><dt><span class="section"><a href="ref_guide_runtime_jpa.html#ref_guide_runtime_openjpapersistence">2.9. |
| OpenJPAPersistence |
| </a></span></dt></dl></div> |
| |
| <p> |
| 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. |
| </p> |
| <p> |
| You may have noticed the examples throughout this document using the |
| <code class="methodname">OpenJPAPersistence.cast</code> 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. <code class="classname">OpenJPAPersistence</code>'s |
| <code class="methodname">cast</code> methods work around these proxies. |
| </p> |
| <pre class="programlisting"> |
| public static OpenJPAEntityManagerFactory cast(EntityManagerFactory emf); |
| public static OpenJPAEntityManager cast(EntityManager em); |
| public static OpenJPAQuery cast(Query q); |
| </pre> |
| <p> |
| We provide additional information on the <code class="classname">OpenJPAPersistence |
| </code> helper <a class="link" href="ref_guide_runtime_jpa.html#ref_guide_runtime_openjpapersistence" title="2.9. OpenJPAPersistence"> |
| below</a>. |
| </p> |
| <div class="section" title="2.1. OpenJPAEntityManagerFactory"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_runtime_emfactory">2.1. |
| OpenJPAEntityManagerFactory |
| </h3></div></div></div> |
| |
| <a class="indexterm" name="d5e15280"></a> |
| <a class="indexterm" name="d5e15282"></a> |
| <p> |
| The <code class="classname">org.apache.openjpa.persistence.OpenJPAEntityManagerFactory |
| </code> interface extends the basic <code class="classname"> |
| javax.persistence.EntityManagerFactory</code> with OpenJPA-specific |
| features. The <code class="classname">OpenJPAEntityManagerFactory</code> offers APIs to |
| access the OpenJPA data and query caches and to perform other OpenJPA-specific |
| operations. See the |
| <a class="ulink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManagerFactory.html" target="_top"> |
| interface Javadoc</a> for details. |
| </p> |
| </div> |
| <div class="section" title="2.2. OpenJPAEntityManager"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_runtime_em">2.2. |
| OpenJPAEntityManager |
| </h3></div></div></div> |
| |
| <a class="indexterm" name="d5e15293"></a> |
| <a class="indexterm" name="d5e15295"></a> |
| <p> |
| All OpenJPA <code class="classname">EntityManager</code>s implement the |
| <a class="ulink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.OpenJPAEntityManager</code> |
| </a> interface. This interface extends the standard <code class="classname"> |
| javax.persistence.EntityManager</code>. Just as the standard <code class="classname"> |
| EntityManager</code> is the primary window into JPA services, the |
| <code class="classname">OpenJPAEntityManager</code> is the primary window from JPA into |
| OpenJPA-specific functionality. We strongly encourage you to investigate the API |
| extensions this interface contains. |
| </p> |
| </div> |
| <div class="section" title="2.3. OpenJPAQuery"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_runtime_jpaquery">2.3. |
| OpenJPAQuery |
| </h3></div></div></div> |
| |
| <a class="indexterm" name="d5e15308"></a> |
| <a class="indexterm" name="d5e15310"></a> |
| <p> |
| OpenJPA extends JPA's standard query functionality with the <code class="classname"> |
| org.apache.openjpa.persistence.OpenJPAQuery</code> interface. See its |
| <a class="ulink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAQuery.html" target="_top">Javadoc |
| </a> for details on the convenience methods it provides. |
| </p> |
| </div> |
| <div class="section" title="2.4. Extent"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_runtime_jpaextent">2.4. |
| Extent |
| </h3></div></div></div> |
| |
| <a class="indexterm" name="d5e15319"></a> |
| <a class="indexterm" name="d5e15321"></a> |
| <p> |
| An <code class="classname">Extent</code> is a logical view of all persistent instances |
| of a given entity class, possibly including subclasses. OpenJPA adds the |
| <a class="ulink" href="../javadoc/org/apache/openjpa/persistence/Extent.html" target="_top"><code class="classname"> |
| org.apache.openjpa.persistence.Extent</code></a> class to the set of |
| Java Persistence APIs. The following code illustrates iterating over all |
| instances of the <code class="classname">Magazine</code> entity, without subclasses: |
| </p> |
| <div class="example"><a name="ref_guide_runtime_jpaextentex"></a><p class="title"><b>Example 9.2. |
| Using a JPA Extent |
| </b></p><div class="example-contents"> |
| |
| <pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| OpenJPAEntityManager kem = OpenJPAPersistence.cast(em); |
| Extent<Magazine> mags = kem.createExtent(Magazine.class, false); |
| for (Magazine m : mags) |
| processMagazine(m); |
| </pre> |
| </div></div><br class="example-break"> |
| </div> |
| <div class="section" title="2.5. StoreCache"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_runtime_jpacache">2.5. |
| StoreCache |
| </h3></div></div></div> |
| |
| <a class="indexterm" name="d5e15335"></a> |
| <p> |
| In addition to the <code class="classname">EntityManager</code> 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 |
| <a class="ulink" href="../javadoc/org/apache/openjpa/persistence/StoreCache.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.StoreCache</code></a>. |
| <a class="xref" href="ref_guide_caching.html#ref_guide_cache" title="1. Data Cache">Section 1, “ |
| Data Cache |
| ”</a> has detailed information on OpenJPA's |
| data caching system, including the <code class="classname">StoreCache</code> facade. |
| </p> |
| </div> |
| <div class="section" title="2.6. QueryResultCache"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_runtime_jpaquerycache">2.6. |
| QueryResultCache |
| </h3></div></div></div> |
| |
| <a class="indexterm" name="d5e15345"></a> |
| <p> |
| OpenJPA can cache query results as well as persistent object data. The |
| <a class="ulink" href="../javadoc/org/apache/openjpa/persistence/QueryResultCache.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.QueryResultCache</code></a> |
| is an JPA-flavored facade to OpenJPA's internal query cache. See |
| <a class="xref" href="ref_guide_caching.html#ref_guide_cache_query" title="1.4. Query Cache">Section 1.4, “ |
| Query Cache |
| ”</a> for details on query caching in |
| OpenJPA. |
| </p> |
| </div> |
| <div class="section" title="2.7. FetchPlan"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_runtime_jpafetch">2.7. |
| FetchPlan |
| </h3></div></div></div> |
| |
| <a class="indexterm" name="d5e15353"></a> |
| <a class="indexterm" name="d5e15355"></a> |
| <p> |
| Many of the aforementioned OpenJPA interfaces give you access to an <code class="classname"> |
| org.apache.openjpa.persistence.FetchPlan</code> instance. The <code class="classname"> |
| FetchPlan</code> allows you to exercise some control over how objects are |
| fetched from the datastore, including <a class="link" href="ref_guide_dbsetup_lrs.html" title="10. Large Result Sets"> |
| large result set support</a>, <a class="link" href="ref_guide_fetch.html" title="7. Fetch Groups">custom fetch |
| groups</a>, and <a class="link" href="ref_guide_locking.html" title="3. Object Locking">lock levels</a>. |
| </p> |
| <p> |
| OpenJPA goes one step further, extending <code class="classname">FetchPlan</code> with |
| <a class="ulink" href="../javadoc/org/apache/openjpa/persistence/jdbc/JDBCFetchPlan.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.jdbc.JDBCFetchPlan</code></a> |
| to add additional JDBC-specific tuning methods. Unless you have customized |
| OpenJPA to use a non-relational back-end (see |
| <a class="xref" href="ref_guide_enterprise_abstractstore.html" title="8. Non-Relational Stores">Section 8, “ |
| Non-Relational Stores |
| ”</a> ), all <code class="classname"> |
| FetchPlan</code>s in OpenJPA implement <code class="classname"> |
| JDBCFetchPlan</code>, so feel free to cast to this interface. |
| </p> |
| <p> |
| Fetch plans pass on from parent components to child components. The <code class="classname"> |
| EntityManagerFactory</code> 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 <code class="classname">EntityManager</code>s it |
| produces. The settings of each <code class="classname">EntityManager</code>, in turn, |
| are passed on to each <code class="classname">Query</code> and <code class="classname">Extent |
| </code> it returns. Note that the opposite, however, is not true. Modifying |
| the fetch plan of a <code class="classname">Query</code> or <code class="classname">Extent |
| </code> does not affect the <code class="classname">EntityManager</code>'s |
| configuration. Likewise, modifying an <code class="classname">EntityManager</code>'s |
| configuration does not affect the <code class="classname"> EntityManagerFactory</code>. |
| </p> |
| <p> |
| <a class="xref" href="ref_guide_fetch.html" title="7. Fetch Groups">Section 7, “ |
| Fetch Groups |
| ”</a> includes examples using <code class="classname"> |
| FetchPlan</code>s. |
| </p> |
| </div> |
| <div class="section" title="2.8. OpenJPAEntityTransaction"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_runtime_openjpaentitytransaction">2.8. |
| OpenJPAEntityTransaction |
| </h3></div></div></div> |
| |
| <a class="indexterm" name="d5e15387"></a> |
| <p> |
| <a class="ulink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityTransaction.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.OpenJPAEntityTransaction</code></a> |
| extends <code class="classname">javax.persistence.EntityTransaction</code> to provide |
| additional transaction-debugging capabilities and some concurrency-related |
| commit and rollback features. |
| </p> |
| </div> |
| <div class="section" title="2.9. OpenJPAPersistence"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_runtime_openjpapersistence">2.9. |
| OpenJPAPersistence |
| </h3></div></div></div> |
| |
| <a class="indexterm" name="d5e15395"></a> |
| <p> |
| <a class="ulink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAPersistence.html" target="_top"> |
| <code class="classname">org.apache.openjpa.persistence.OpenJPAPersistence</code></a> |
| is a static helper class that adds OpenJPA-specific utility methods to |
| <code class="classname">javax.persistence.Persistence</code>. |
| </p> |
| </div> |
| </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_runtime.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_runtime.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_locking.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 9. |
| Runtime Extensions |
| </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 3. |
| Object Locking |
| </td></tr></table></div></body></html> |
