| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>8. Configuring the Use of JDBC Connections</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_dbsetup.html" title="Chapter 4. JDBC"><link rel="prev" href="ref_guide_dbsetup_multidb.html" title="7. Accessing Multiple Databases"><link rel="next" href="ref_guide_dbsetup_stmtbatch.html" title="9. Statement Batching"></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">8. |
| Configuring the Use of JDBC Connections |
| </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_dbsetup_multidb.html">Prev</a> </td><th width="60%" align="center">Chapter 4. |
| JDBC |
| </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_dbsetup_stmtbatch.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_dbsetup_retain"></a>8. |
| Configuring the Use of JDBC Connections |
| </h2></div></div></div><a class="indexterm" name="d0e19900"></a><p> |
| In its default configuration, OpenJPA obtains JDBC connections on an as-needed |
| basis. OpenJPA <code class="classname">EntityManager</code>s do not retain a connection |
| to the database unless they are in a datastore transaction or there are open |
| <code class="classname">Query</code> results that are using a live JDBC result set. At |
| all other times, including during optimistic transactions, <code class="classname"> |
| EntityManager</code>s request a connection for each query, then |
| immediately release the connection back to the pool. |
| </p><p> |
| <a class="indexterm" name="d0e19918"></a> |
| In some cases, it may be more efficient to retain connections for longer periods |
| of time. You can configure OpenJPA's use of JDBC connections through the |
| <a href="ref_guide_conf_openjpa.html#openjpa.ConnectionRetainMode" title="5.24. openjpa.ConnectionRetainMode"><code class="literal"> |
| openjpa.ConnectionRetainMode</code></a> configuration property. The |
| property accepts the following values: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">always</code>: Each <code class="classname">EntityManager</code> obtains a |
| single connection and uses it until the <code class="classname">EntityManager</code> |
| closes. |
| </p></li><li><p> |
| <code class="literal">transaction</code>: A connection is obtained when each transaction |
| begins (optimistic or datastore), and is released when the transaction |
| completes. Non-transactional connections are obtained on-demand. |
| </p></li><li><p> |
| <code class="literal">on-demand</code>: Connections are obtained only when needed. This |
| option is equivalent to the <code class="literal">transaction</code> option when datastore |
| transactions are used. For optimistic transactions, though, it means that a |
| connection will be retained only for the duration of the datastore flush and |
| commit process. |
| </p></li></ul></div><p> |
| You can also specify the connection retain mode of individual <code class="classname"> |
| EntityManager</code>s when you retrieve them from the <code class="classname"> |
| EntityManagerFactory</code>. See |
| <a href="ref_guide_runtime_jpa.html#ref_guide_runtime_emfactory" title="2.1. OpenJPAEntityManagerFactory">Section 2.1, “ |
| OpenJPAEntityManagerFactory |
| ”</a> for details. |
| </p><p> |
| <a class="indexterm" name="d0e19966"></a> |
| The <a href="ref_guide_conf_openjpa.html#openjpa.FlushBeforeQueries" title="5.32. openjpa.FlushBeforeQueries"><code class="literal"> |
| openjpa.FlushBeforeQueries</code></a> configuration property controls |
| another aspect of connection usage: whether to flush transactional changes |
| before executing object queries. This setting only applies to queries that would |
| otherwise have to be executed in-memory because the |
| <a href="ref_guide_conf_openjpa.html#openjpa.IgnoreChanges" title="5.33. openjpa.IgnoreChanges"><code class="literal">IgnoreChanges</code></a> |
| property is set to false and the query may involve objects that have been |
| changed in the current transaction. Legal values are: |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">true</code>: Always flush rather than executing the query |
| in-memory. If the current transaction is optimistic, OpenJPA will begin a |
| non-locking datastore transaction. This is the default. |
| </p></li><li><p> |
| <code class="literal">false</code>: Never flush before a query. |
| </p></li><li><p> |
| <code class="literal">with-connection</code>: Flush only if the <code class="classname">EntityManager |
| </code> has already established a dedicated connection to the datastore, |
| otherwise execute the query in-memory. |
| This option is useful if you use long-running optimistic transactions and want |
| to ensure that these transactions do not consume database resources until |
| commit. OpenJPA's behavior with this option is dependent on the transaction |
| status and mode, as well as the configured connection retain mode described |
| earlier in this section. |
| </p></li></ul></div><p> |
| The flush mode can also be varied at runtime using the OpenJPA fetch |
| configuration API, discussed in <a href="ref_guide_runtime.html" title="Chapter 9. Runtime Extensions">Chapter 9, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Runtime Extensions |
| </i></a>. |
| </p><p> |
| <a class="indexterm" name="d0e20006"></a> |
| The table below describes the behavior of automatic flushing in various |
| situations. In all cases, flushing will only occur if OpenJPA detects that you |
| have made modifications in the current transaction that may affect the query's |
| results. |
| </p><div class="table"><a name="d0e20012"></a><p class="title"><b>Table 4.1. |
| OpenJPA Automatic Flush Behavior |
| </b></p><div class="table-contents"><table summary="
 OpenJPA Automatic Flush Behavior
 " border="1"><colgroup><col align="left"><col align="left"><col align="left"><col align="left"><col align="left"></colgroup><thead><tr><th align="left"> |
| </th><th align="left"> |
| FlushBeforeQueries = false |
| </th><th align="left"> |
| FlushBeforeQueries = true |
| </th><th align="left"> |
| FlushBeforeQueries = with-connection; |
| ConnectionRetainMode = on-demand |
| </th><th align="left"> |
| FlushBeforeQueries = with-connection; |
| ConnectionRetainMode = transaction or always |
| </th></tr></thead><tbody><tr><td align="left"> |
| <span class="bold"><strong> |
| IgnoreChanges = true |
| </strong></span> |
| </td><td align="left"> |
| no flush |
| </td><td align="left"> |
| no flush |
| </td><td align="left"> |
| no flush |
| </td><td align="left"> |
| no flush |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| IgnoreChanges = false; no tx active |
| </strong></span> |
| </td><td align="left"> |
| no flush |
| </td><td align="left"> |
| no flush |
| </td><td align="left"> |
| no flush |
| </td><td align="left"> |
| no flush |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| IgnoreChanges = false; datastore tx active |
| </strong></span> |
| </td><td align="left"> |
| no flush |
| </td><td align="left"> |
| flush |
| </td><td align="left"> |
| flush |
| </td><td align="left"> |
| flush |
| </td></tr><tr><td align="left"> |
| <span class="bold"><strong> |
| IgnoreChanges = false; optimistic tx active |
| </strong></span> |
| </td><td align="left"> |
| no flush |
| </td><td align="left"> |
| flush |
| </td><td align="left"> |
| no flush unless <code class="methodname">flush</code> has already been invoked |
| </td><td align="left"> |
| flush |
| </td></tr></tbody></table></div></div><br class="table-break"><div class="example"><a name="ref_guide_dbsetup_sql92_retain_conf"></a><p class="title"><b>Example 4.10. |
| Specifying Connection Usage Defaults |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <property name="openjpa.ConnectionRetainMode" value="on-demand"/> |
| <property name="openjpa.FlushBeforeQueries" value="true"/> |
| </pre></div></div><br class="example-break"><div class="example"><a name="ref_guide_dbsetup_sql92_retain_runtime"></a><p class="title"><b>Example 4.11. |
| Specifying Connection Usage at Runtime |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| // obtaining an em with a certain connection retain mode |
| Map props = new HashMap(); |
| props.put("openjpa.ConnectionRetainMode", "always"); |
| EntityManager em = emf.createEntityManager(props); |
| </pre></div></div><br class="example-break"></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_dbsetup_multidb.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_dbsetup.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_dbsetup_stmtbatch.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">7. |
| Accessing Multiple Databases |
| </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 9. |
| Statement Batching |
| </td></tr></table></div></body></html> |
