| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>4. Savepoints</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.3 User's Guide"><link rel="up" href="ref_guide_runtime.html" title="Chapter 9. Runtime Extensions"><link rel="prev" href="ref_guide_locking.html" title="3. Object Locking"><link rel="next" href="ref_guide_enterprise_methodql.html" title="5. MethodQL"></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">4. |
| Savepoints |
| </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_locking.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_enterprise_methodql.html">Next</a></td></tr></table><hr></div><div class="section" title="4. Savepoints"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_savepoints">4. |
| Savepoints |
| </h2></div></div></div><div class="toc"><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></div> |
| |
| <a class="indexterm" name="d5e15614"></a> |
| <p> |
| Savepoints allow for fine grained control over the transactional behavior of |
| your application. OpenJPA's savepoint API allow you to set intermediate rollback |
| points in your transaction. You can then choose to rollback changes made only |
| after a specific savepoint, then commit or continue making new changes in the |
| transaction. This feature is useful for multi-stage transactions, such as |
| editing a set of objects over several web pages or user screens. Savepoints also |
| provide more flexibility to conditional transaction behavior, such as choosing to |
| commit or rollback a portion of the transaction based on the results of the |
| changes. This chapter describes how to use and configure OpenJPA savepoints. |
| </p> |
| <div class="section" title="4.1. Using Savepoints"><div class="titlepage"><div><div><h3 class="title" id="reg_guide_savepoints_using">4.1. |
| Using Savepoints |
| </h3></div></div></div> |
| |
| <p> |
| OpenJPA's |
| <a class="ulink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top"> |
| <code class="classname">OpenJPAEntityManager</code></a> have the following |
| methods to control savepoint behavior. Note that the savepoints work in tandem |
| with the current transaction. This means that savepoints require an open |
| transaction, and that a rollback of the transaction will rollback all of the |
| changes in the transaction regardless of any savepoints set. |
| </p> |
| <pre class="programlisting"> |
| void setSavepoint(String name); |
| void releaseSavepoint(String name); |
| void rollbackToSavepoint(String name); |
| </pre> |
| <p> |
| To set a savepoint, simply call <code class="methodname">setSavepoint</code>, passing |
| in a symbolic savepoint name. This savepoint will define a point at which you |
| can preserve the state of transactional objects for the duration of the current |
| transaction. |
| </p> |
| <p> |
| Having set a named savepoint, you can rollback changes made after that point by |
| calling <code class="methodname">rollbackToSavepoint</code>. This method will keep the |
| current transaction active, while restoring all transactional instances back to |
| their saved state. Instances that were deleted after the save point will no |
| longer be marked for deletion. Similarly, transient instances that were made |
| persistent after the savepoint will become transient again. Savepoints made |
| after this savepoint will be released and no longer valid, although you can |
| still set new savepoints. Savepoints will also be cleared after the current |
| transaction is committed or rolled back. |
| </p> |
| <p> |
| If a savepoint is no longer needed, you can release any resources it is |
| consuming resources by calling <code class="methodname">releaseSavepoint</code>. This |
| method should not be called for savepoints that have been |
| released automatically through other means, such as commit of a transaction or |
| rollback to a prior savepoint. While savepoints made after this savepoint will |
| also be released, there are no other effects on the current transaction. |
| </p> |
| <p> |
| The following simple example illustrates setting, releasing, and rolling back to |
| a savepoint. |
| </p> |
| <div class="example"><a name="ref_guide_savepoints_example"></a><p class="title"><b>Example 9.7. |
| Using Savepoints |
| </b></p><div class="example-contents"> |
| |
| <pre class="programlisting"> |
| import org.apache.openjpa.persistence.*; |
| |
| ... |
| |
| OpenJPAEntityManager oem = OpenJPAPersistence.cast(em); |
| oem.getTransaction().begin(); |
| |
| Magazine mag = oem.find(Magazine.class, id); |
| mag.setPageCount(300); |
| oem.setSavepoint("pages"); |
| |
| mag.setPrice(mag.getPageCount() * pricePerPage); |
| // we decide to release "pages"... |
| oem.releaseSavepoint("pages"); |
| // ... and set a new savepoint which includes all changes |
| oem.setSavepoint("price"); |
| |
| mag.setPrice(testPrice); |
| // we determine the test price is not good |
| oem.rollbackToSavepoint("price"); |
| // had we chosen to not release "pages", we might have rolled back to |
| // "pages" instead |
| |
| // the price is now restored to mag.getPageCount() * pricePerPage |
| oem.getTransaction().commit(); |
| </pre> |
| </div></div><br class="example-break"> |
| </div> |
| <div class="section" title="4.2. Configuring Savepoints"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_savepoints_conf">4.2. |
| Configuring Savepoints |
| </h3></div></div></div> |
| |
| <p> |
| OpenJPA uses the |
| <a class="ulink" href="../javadoc/org/apache/openjpa/kernel/SavepointManager" target="_top"> |
| <code class="classname">org.apache.openjpa.kernel.SavepointManager</code></a> |
| <a class="link" href="ref_guide_conf_plugins.html" title="4. Plugin Configuration">plugin</a> to handle preserving the |
| savepoint state. OpenJPA includes the following <code class="classname">SavepointManager |
| </code> plugins: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> |
| <p> |
| <code class="literal">in-mem</code>: The default. This is an alias for the |
| <a class="ulink" href="../javadoc/org/apache/openjpa/kernel/InMemorySavepointManager.html" target="_top"><code class="classname"> |
| org.apache.openjpa.kernel.InMemorySavepointManager</code></a>. This |
| plugin stores all state, including field values, in memory. Due to this |
| behavior, each set savepoint is designed for small to medium transactional |
| object counts. |
| </p> |
| </li><li class="listitem"> |
| <p> |
| <code class="literal">jdbc</code>: This is an alias for the |
| <a class="ulink" href="../javadoc/org/apache/openjpa/jdbc/kernel/JDBC3SavepointManager.html" target="_top"><code class="classname"> |
| org.apache.openjpa.jdbc.kernel.JDBC3SavepointManager</code></a>. This |
| plugin requires <code class="literal">JDBC 3</code> and <code class="classname"> java.sql.Savepoint |
| </code> support to operate. Note that this plugin implements savepoints by |
| issuing a flush to the database. |
| </p> |
| </li></ul></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_locking.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_enterprise_methodql.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3. |
| Object Locking |
| </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 5. |
| MethodQL |
| </td></tr></table></div></body></html> |