Edit File: usingtransactions.html
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title> Using Transactions </title> <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" /> <link rel="home" href="index.html" title="Berkeley DB Collections Tutorial" /> <link rel="up" href="BasicProgram.html" title="Chapter 2. 		The Basic Program 	" /> <link rel="previous" href="implementingmain.html" title=" 		Implementing the Main Program 	" /> <link rel="next" href="addingdatabaseitems.html" title=" 		Adding Database Items 	" /> </head> <body> <div class="navheader"> <table width="100%" summary="Navigation header"> <tr> <th colspan="3" align="center"> Using Transactions </th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="implementingmain.html">Prev</a> </td> <th width="60%" align="center">Chapter 2. The Basic Program </th> <td width="20%" align="right"> <a accesskey="n" href="addingdatabaseitems.html">Next</a></td> </tr> </table> <hr /> </div> <div class="sect1" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"><a id="usingtransactions"></a> Using Transactions </h2> </div> </div> <div></div> </div> <p> DB transactional applications have standard transactional characteristics: recoverability, atomicity and integrity (this is sometimes also referred to generically as <span class="emphasis"><em>ACID properties</em></span>). The DB Java Collections API provides these transactional capabilities using a <span class="emphasis"><em>transaction-per-thread</em></span> model. Once a transaction is begun, it is implicitly associated with the current thread until it is committed or aborted. This model is used for the following reasons. </p> <div class="itemizedlist"> <ul type="disc"> <li> <p> The transaction-per-thread model is commonly used in other Java APIs such as J2EE. </p> </li> <li> <p> Since the Java collections API is used for data access, there is no way to pass a transaction object to methods such as <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#put" target="_top">Map.put</a>. </p> </li> </ul> </div> <p> The DB Java Collections API provides two transaction APIs. The lower-level API is the <a href="../../java/com/sleepycat/collections/CurrentTransaction.html" target="_top">CurrentTransaction</a> class. It provides a way to get the transaction for the current thread, and to begin, commit and abort transactions. It also provides access to the Berkeley DB core API <a href="../../java/com/sleepycat/db/Transaction.html" target="_top">Transaction</a> object. With <a href="../../java/com/sleepycat/collections/CurrentTransaction.html" target="_top">CurrentTransaction</a>, just as in the <span>com.sleepycat.db</span> API, the application is responsible for beginning, committing and aborting transactions, and for handling deadlock exceptions and retrying operations. This API may be needed for some applications, but it is not used in the example. </p> <p> The example uses the higher-level <a href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a> and <a href="../../java/com/sleepycat/collections/TransactionWorker.html" target="_top">TransactionWorker</a> APIs, which are build on top of <a href="../../java/com/sleepycat/collections/CurrentTransaction.html" target="_top">CurrentTransaction</a>. <tt class="methodname">TransactionRunner.run()</tt> automatically begins a transaction and then calls the <tt class="methodname">TransactionWorker.doWork()</tt> method, which is implemented by the application. </p> <p> The <tt class="methodname">TransactionRunner.run()</tt> method automatically detects deadlock exceptions and performs retries by repeatedly calling the <tt class="methodname">TransactionWorker.doWork()</tt> method until the operation succeeds or the maximum retry count is reached. If the maximum retry count is reached or if another exception (other than <span> <a href="../../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a>) </span> is thrown by <tt class="methodname">TransactionWorker.doWork()</tt>, then the transaction will be automatically aborted. Otherwise, the transaction will be automatically committed. </p> <p> Using this high-level API, if <tt class="methodname">TransactionRunner.run()</tt> throws an exception, the application can assume that the operation failed and the transaction was aborted; otherwise, when an exception is not thrown, the application can assume the operation succeeded and the transaction was committed. </p> <p> The <tt class="methodname">Sample.run()</tt> method creates a <tt class="classname">TransactionRunner</tt> object and calls its <tt class="methodname">run()</tt> method. </p> <a id="cb_sample1"></a> <pre class="programlisting"><b class="userinput"><tt>import com.sleepycat.collections.TransactionRunner; import com.sleepycat.collections.TransactionWorker;</tt></b> ... public class Sample { private SampleDatabase db; ... <b class="userinput"><tt> private void run() throws Exception { TransactionRunner runner = new TransactionRunner(db.getEnvironment()); runner.run(new PopulateDatabase()); runner.run(new PrintDatabase()); } ... private class PopulateDatabase implements TransactionWorker { public void doWork() throws Exception { } } private class PrintDatabase implements TransactionWorker { public void doWork() throws Exception { } }</tt></b> } </pre> <p> The <tt class="methodname">run()</tt> method is called by <tt class="methodname">main()</tt> and was outlined in the previous section. It first creates a <tt class="classname">TransactionRunner</tt>, passing the database environment to its constructor. </p> <p> It then calls <tt class="methodname">TransactionRunner.run()</tt> to execute two transactions, passing instances of the application-defined <tt class="classname">PopulateDatabase</tt> and <tt class="classname">PrintDatabase</tt> nested classes. These classes implement the <tt class="methodname">TransactionWorker.doWork()</tt> method and will be fully described in the next two sections. </p> <p> For each call to <tt class="methodname">TransactionRunner.run()</tt>, a separate transaction will be performed. The use of two transactions in the example — one for populating the database and another for printing its contents — is arbitrary. A real-life application should be designed to create transactions for each group of operations that should have ACID properties, while also taking into account the impact of transactions on performance. </p> <p> The advantage of using <tt class="classname">TransactionRunner</tt> is that deadlock retries and transaction begin, commit and abort are handled automatically. However, a <tt class="classname">TransactionWorker</tt> class must be implemented for each type of transaction. If desired, anonymous inner classes can be used to implement the <tt class="classname">TransactionWorker</tt> interface. </p> </div> <div class="navfooter"> <hr /> <table width="100%" summary="Navigation footer"> <tr> <td width="40%" align="left"><a accesskey="p" href="implementingmain.html">Prev</a> </td> <td width="20%" align="center"> <a accesskey="u" href="BasicProgram.html">Up</a> </td> <td width="40%" align="right"> <a accesskey="n" href="addingdatabaseitems.html">Next</a></td> </tr> <tr> <td width="40%" align="left" valign="top"> Implementing the Main Program </td> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> <td width="40%" align="right" valign="top"> Adding Database Items </td> </tr> </table> </div> </body> </html>
Back to File Manager