content/builds/1.2.0/apache-openjpa-1.2.0/docs/manual/ref_guide_savepoints.html - openjpa-site - Git at Google

 <html><head>
       <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
    <title>4.&nbsp; Savepoints</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_runtime.html" title="Chapter&nbsp;9.&nbsp; Runtime Extensions"><link rel="prev" href="ref_guide_locking.html" title="3.&nbsp; Object Locking"><link rel="next" href="ref_guide_enterprise_methodql.html" title="5.&nbsp; 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.&nbsp;
             Savepoints
         </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_locking.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;9.&nbsp;
         Runtime Extensions
     </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_enterprise_methodql.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_savepoints"></a>4.&nbsp;
             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="d0e28973"></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 flexibilty 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" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="reg_guide_savepoints_using"></a>4.1.&nbsp;
                 Using Savepoints
             </h3></div></div></div><p>
 OpenJPA's
 <a xmlns:xlink="http://www.w3.org/1999/xlink" 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&nbsp;9.7.&nbsp;
                     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" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_savepoints_conf"></a>4.2.&nbsp;
                 Configuring Savepoints
             </h3></div></div></div><p>
 OpenJPA uses the
 <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/SavepointManager" target="_top">
 <code class="classname">org.apache.openjpa.kernel.SavepointManager</code></a>
 <a href="ref_guide_conf_plugins.html" title="4.&nbsp; Plugin Configuration">plugin</a> to handle perserving the
 savepoint state. OpenJPA includes the following <code class="classname">SavepointManager
 </code> plugins:
             </p><div class="itemizedlist"><ul type="disc"><li><p>
 <code class="literal">in-mem</code>: The default. This is an alias for the
 <a xmlns:xlink="http://www.w3.org/1999/xlink" href="org.apache.openjpa.kernel.InMemorySavepointManager" 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><p>
 <code class="literal">jdbc</code>: This is an alias for the
 <a xmlns:xlink="http://www.w3.org/1999/xlink" href="org.apache.openjpa.jdbc.kernel.JDBCSavepointManager" target="_top"><code class="classname">
 org.apache.openjpa.jdbc.kernel.JDBCSavepointManager</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><li><p>
 <code class="literal">oracle</code>: This is an alias for the
 <a xmlns:xlink="http://www.w3.org/1999/xlink" href="org.apache.openjpa.jdbc.sql.OracleSavepointManager" target="_top"><code class="classname">
 org.apache.openjpa.jdbc.sql.OracleSavepointManager</code></a>. This
 plugin operates similarly to the <code class="literal">JDBC</code> plugin; however, it
 uses Oracle-specific calls. This plugin requires using the Oracle JDBC driver
 and database, versions <code class="literal">9.2</code> or higher. 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>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_runtime.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_enterprise_methodql.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.&nbsp;
             Object Locking
         &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;5.&nbsp;
                 MethodQL
             </td></tr></table></div></body></html>
	<html><head>
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<title>4.  Savepoints</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_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" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_savepoints"></a>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="d0e28973"></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 flexibilty 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" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="reg_guide_savepoints_using"></a>4.1.
	Using Savepoints
	</h3></div></div></div><p>
	OpenJPA's
	<a xmlns:xlink="http://www.w3.org/1999/xlink" 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" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_savepoints_conf"></a>4.2.
	Configuring Savepoints
	</h3></div></div></div><p>
	OpenJPA uses the
	<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/kernel/SavepointManager" target="_top">
	<code class="classname">org.apache.openjpa.kernel.SavepointManager</code></a>
	<a href="ref_guide_conf_plugins.html" title="4.  Plugin Configuration">plugin</a> to handle perserving the
	savepoint state. OpenJPA includes the following <code class="classname">SavepointManager
	</code> plugins:
	</p><div class="itemizedlist"><ul type="disc"><li><p>
	<code class="literal">in-mem</code>: The default. This is an alias for the
	<a xmlns:xlink="http://www.w3.org/1999/xlink" href="org.apache.openjpa.kernel.InMemorySavepointManager" 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><p>
	<code class="literal">jdbc</code>: This is an alias for the
	<a xmlns:xlink="http://www.w3.org/1999/xlink" href="org.apache.openjpa.jdbc.kernel.JDBCSavepointManager" target="_top"><code class="classname">
	org.apache.openjpa.jdbc.kernel.JDBCSavepointManager</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><li><p>
	<code class="literal">oracle</code>: This is an alias for the
	<a xmlns:xlink="http://www.w3.org/1999/xlink" href="org.apache.openjpa.jdbc.sql.OracleSavepointManager" target="_top"><code class="classname">
	org.apache.openjpa.jdbc.sql.OracleSavepointManager</code></a>. This
	plugin operates similarly to the <code class="literal">JDBC</code> plugin; however, it
	uses Oracle-specific calls. This plugin requires using the Oracle JDBC driver
	and database, versions <code class="literal">9.2</code> or higher. 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>