| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>Chapter 9. Runtime Extensions</title><link rel="stylesheet" href="css/docbook.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"><link rel="start" href="manual.html" title="Apache OpenJPA User's Guide"><link rel="up" href="ref_guide.html" title="Part 3. Reference Guide"><link rel="prev" href="ref_guide_enterprise_xa.html" title="3. XA Transactions"><link rel="next" href="ref_guide_runtime_jpa.html" title="2. JPA Extensions"></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">Chapter 9. |
| Runtime Extensions |
| </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_enterprise_xa.html">Prev</a> </td><th width="60%" align="center">Part 3. Reference Guide</th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_runtime_jpa.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en" id="ref_guide_runtime"><div class="titlepage"><div><div><h2 class="title"><a name="ref_guide_runtime"></a>Chapter 9. |
| Runtime Extensions |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="ref_guide_runtime.html#ref_guide_runtime_arch">1. |
| Architecture |
| </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_runtime.html#ref_guide_runtime_broker_finalization">1.1. |
| Broker Finalization |
| </a></span></dt><dt><span class="section"><a href="ref_guide_runtime.html#ref_guide_runtime_broker_extension">1.2. |
| Broker Customization and Finalization |
| </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_runtime_jpa.html">2. |
| JPA Extensions |
| </a></span></dt><dd><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_openjpapersistence">2.8. |
| OpenJPAPersistence |
| </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_locking.html">3. |
| Object Locking |
| </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_locking.html#ref_guide_locking_default">3.1. |
| Configuring Default Locking |
| </a></span></dt><dt><span class="section"><a href="ref_guide_locking.html#ref_guide_locking_runtime">3.2. |
| Configuring Lock Levels at Runtime |
| </a></span></dt><dt><span class="section"><a href="ref_guide_locking.html#ref_guide_locking_apis">3.3. |
| Object Locking APIs |
| </a></span></dt><dt><span class="section"><a href="ref_guide_locking.html#ref_guide_locking_lockmgr">3.4. |
| Lock Manager |
| </a></span></dt><dt><span class="section"><a href="ref_guide_locking.html#ref_guide_locking_rules">3.5. |
| Rules for Locking Behavior |
| </a></span></dt><dt><span class="section"><a href="ref_guide_locking.html#ref_guide_locking_issues">3.6. |
| Known Issues and Limitations |
| </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_savepoints.html">4. |
| Savepoints |
| </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_savepoints.html#reg_guide_savepoints_using">4.1. |
| Using Savepoints |
| </a></span></dt><dt><span class="section"><a href="ref_guide_savepoints.html#ref_guide_savepoints_conf">4.2. |
| Configuring Savepoints |
| </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_enterprise_methodql.html">5. |
| MethodQL |
| </a></span></dt><dt><span class="section"><a href="ref_guide_sequence.html">6. |
| Generators |
| </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_sequence.html#ref_guide_sequence_runtime">6.1. |
| Runtime Access |
| </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_runtime_pm_event.html">7. |
| Transaction Events |
| </a></span></dt><dt><span class="section"><a href="ref_guide_enterprise_abstractstore.html">8. |
| Non-Relational Stores |
| </a></span></dt></dl></div><p> |
| This chapter describes OpenJPA extensions to the standard JPA |
| interfaces, and outlines some additional features of the OpenJPA runtime. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_runtime_arch"></a>1. |
| Architecture |
| </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_runtime.html#ref_guide_runtime_broker_finalization">1.1. |
| Broker Finalization |
| </a></span></dt><dt><span class="section"><a href="ref_guide_runtime.html#ref_guide_runtime_broker_extension">1.2. |
| Broker Customization and Finalization |
| </a></span></dt></dl></div><p> |
| 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. |
| </p><p> |
| 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. |
| </p><p> |
| 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: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="classname">javax.persistence.EntityManagerFactory</code>: <span class="emphasis"><em> |
| <code class="classname">org.apache.openjpa.kernel.BrokerFactory</code></em></span> |
| </p></li><li><p> |
| <code class="classname">javax.persistence.EntityManager</code>: <span class="emphasis"><em><code class="classname"> |
| org.apache.openjpa.kernel.Broker</code></em></span> |
| </p></li><li><p> |
| <code class="classname">javax.persistence.Query</code>: <span class="emphasis"><em><code class="classname"> |
| org.apache.openjpa.kernel.Query</code></em></span> |
| </p></li><li><p> |
| <code class="classname">org.apache.openjpa.persistence.Extent</code>: <span class="emphasis"><em> |
| <code class="classname">org.apache.openjpa.kernel.Extent</code></em></span> |
| </p></li><li><p> |
| <code class="classname">org.apache.openjpa.persistence.StoreCache</code>: <span class="emphasis"><em> |
| <code class="classname">org.apache.openjpa.datacache.DataCache</code></em></span> |
| </p></li><li><p> |
| <code class="classname">org.apache.openjpa.persistence.QueryResultCache</code>: |
| <span class="emphasis"><em><code class="classname">org.apache.openjpa.datacache.QueryCache</code> |
| </em></span> |
| </p></li><li><p> |
| <code class="classname">org.apache.openjpa.persistence.FetchPlan</code>: <span class="emphasis"><em> |
| <code class="classname">org.apache.openjpa.kernel.FetchConfiguration</code></em></span> |
| </p></li><li><p> |
| <code class="classname">org.apache.openjpa.persistence.Generator</code>: <span class="emphasis"><em> |
| <code class="classname">org.apache.openjpa.kernel.Seq</code></em></span> |
| </p></li></ul></div><p> |
| The <a href="ref_guide_runtime_jpa.html#ref_guide_runtime_openjpapersistence" title="2.8. OpenJPAPersistence"><code class="classname"> |
| org.apache.openjpa.persistence.OpenJPAPersistence</code></a> helper |
| allows you to convert between <code class="classname">EntityManagerFactories</code> and |
| <code class="classname">BrokerFactories</code>, <code class="classname">EntityManager</code>s |
| and <code class="classname">Broker</code>s. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_runtime_broker_finalization"></a>1.1. |
| Broker Finalization |
| </h3></div></div></div><a class="indexterm" name="d0e27115"></a><p> |
| 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 |
| <a href="ref_guide_conf_openjpa.html#openjpa.BrokerImpl" title="5.4. openjpa.BrokerImpl"><code class="literal">openjpa.BrokerImpl</code></a> |
| configuration property to <code class="literal">non-finalizing</code>. |
| </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_runtime_broker_extension"></a>1.2. |
| Broker Customization and Finalization |
| </h3></div></div></div><a class="indexterm" name="d0e27134"></a><p> |
| As a <a href="ref_guide_conf_plugins.html" title="4. Plugin Configuration">plugin string</a>, this property |
| can be used to configure the <code class="classname"> BrokerImpl</code> with the |
| following properties: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">EvictFromDataCache</code>: When evicting an object through the |
| <code class="methodname">OpenJPAEntityManager.evict</code> methods, whether to also |
| evict it from the OpenJPA's <a href="ref_guide_caching.html#ref_guide_cache" title="1. Data Cache">data cache</a>. |
| Defaults to <code class="literal">false</code>. |
| </p></li></ul></div><div class="example"><a name="ref_guide_runtime_pm_evictex"></a><p class="title"><b>Example 9.1. |
| Evict from Data Cache |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.BrokerImpl" value="EvictFromDataCache=true"/> |
| </pre></div></div><br class="example-break"><p> |
| Additionally, some advanced users may want to add capabilities to OpenJPA's |
| internal <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/BrokerImpl.html" target="_top"> |
| <code class="classname">org.apache.openjpa.kernel.BrokerImpl</code></a>. You can |
| configure OpenJPA to use a custom subclass of <code class="classname">BrokerImpl</code> |
| with the <a href="ref_guide_conf_openjpa.html#openjpa.BrokerImpl" title="5.4. openjpa.BrokerImpl"><code class="literal">openjpa.BrokerImpl |
| </code></a> configuration property. Set this property to the full class |
| name of your custom subclass. When implementing your subclass, consider the |
| finalization issues mentioned in |
| <a href="ref_guide_runtime.html#ref_guide_runtime_broker_finalization" title="1.1. Broker Finalization">Section 1.1, “ |
| Broker Finalization |
| ”</a>. It may be appropriate |
| to create a subtype of both |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/BrokerImpl.html" target="_top"> |
| <code class="classname">org.apache.openjpa.kernel.BrokerImpl</code></a> and |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/FinalizingBrokerImpl.html" target="_top"> |
| <code class="classname">org.apache.openjpa.kernel.FinalizingBrokerImpl</code></a>. |
| </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_enterprise_xa.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_runtime_jpa.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3. |
| XA Transactions |
| </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 2. |
| JPA Extensions |
| </td></tr></table></div></body></html> |
