1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title> 7 Using Transactions 8 </title> 9 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 10 <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" /> 11 <link rel="home" href="index.html" title="Berkeley DB Collections Tutorial" /> 12 <link rel="up" href="BasicProgram.html" title="Chapter��2.�� 		The Basic Program 	" /> 13 <link rel="previous" href="implementingmain.html" title=" 		Implementing the Main Program 	" /> 14 <link rel="next" href="addingdatabaseitems.html" title=" 		Adding Database Items 	" /> 15 </head> 16 <body> 17 <div class="navheader"> 18 <table width="100%" summary="Navigation header"> 19 <tr> 20 <th colspan="3" align="center"> 21 Using Transactions 22 </th> 23 </tr> 24 <tr> 25 <td width="20%" align="left"><a accesskey="p" href="implementingmain.html">Prev</a>��</td> 26 <th width="60%" align="center">Chapter��2.�� 27 The Basic Program 28 </th> 29 <td width="20%" align="right">��<a accesskey="n" href="addingdatabaseitems.html">Next</a></td> 30 </tr> 31 </table> 32 <hr /> 33 </div> 34 <div class="sect1" lang="en" xml:lang="en"> 35 <div class="titlepage"> 36 <div> 37 <div> 38 <h2 class="title" style="clear: both"><a id="usingtransactions"></a> 39 Using Transactions 40 </h2> 41 </div> 42 </div> 43 <div></div> 44 </div> 45 <p> 46 DB transactional applications have standard 47 transactional characteristics: recoverability, atomicity and 48 integrity (this is sometimes also referred to generically as <span class="emphasis"><em>ACID 49 properties</em></span>). The DB Java Collections API provides these 50 transactional capabilities using a <span class="emphasis"><em>transaction-per-thread</em></span> 51 model. Once a transaction is begun, it is implicitly associated 52 with the current thread until it is committed or aborted. This 53 model is used for the following reasons. 54</p> 55 <div class="itemizedlist"> 56 <ul type="disc"> 57 <li> 58 <p> 59 The transaction-per-thread model is commonly used in other Java 60 APIs such as J2EE. 61 </p> 62 </li> 63 <li> 64 <p> 65 Since the Java collections API is used for data access, there 66 is no way to pass a transaction object to methods such 67 as 68 <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#put" target="_top">Map.put</a>. 69 </p> 70 </li> 71 </ul> 72 </div> 73 <p> 74 The DB Java Collections API provides two transaction APIs. The 75 lower-level API is the 76 <a href="../../java/com/sleepycat/collections/CurrentTransaction.html" target="_top">CurrentTransaction</a> 77 78 class. It provides a way to get the transaction for the current 79 thread, and to begin, commit and abort transactions. It also 80 provides access to the Berkeley DB core API 81 82 <a href="../../java/com/sleepycat/db/Transaction.html" target="_top">Transaction</a> 83 84 object. With 85 <a href="../../java/com/sleepycat/collections/CurrentTransaction.html" target="_top">CurrentTransaction</a>, 86 just as in the 87 88 <span>com.sleepycat.db</span> 89 API, the application is responsible 90 for beginning, committing and aborting transactions, and for 91 handling deadlock exceptions and retrying operations. This API may 92 be needed for some applications, but it is not used in the 93 example. 94</p> 95 <p> 96 The example uses the higher-level 97 <a href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a> 98 99 and 100 <a href="../../java/com/sleepycat/collections/TransactionWorker.html" target="_top">TransactionWorker</a> 101 102 APIs, which are build on top of 103 <a href="../../java/com/sleepycat/collections/CurrentTransaction.html" target="_top">CurrentTransaction</a>. 104 <tt class="methodname">TransactionRunner.run()</tt> automatically begins a transaction and 105 then calls the <tt class="methodname">TransactionWorker.doWork()</tt> method, which is 106 implemented by the application. 107</p> 108 <p> 109 The <tt class="methodname">TransactionRunner.run()</tt> method automatically detects 110 deadlock exceptions and performs retries by repeatedly calling the 111 <tt class="methodname">TransactionWorker.doWork()</tt> method until the operation succeeds 112 or the maximum retry count is reached. If the maximum retry count 113 is reached or if another exception (other than 114 115 <span> 116 <a href="../../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a>) 117 </span> 118 is thrown by <tt class="methodname">TransactionWorker.doWork()</tt>, then the transaction 119 will be automatically aborted. Otherwise, the transaction will be 120 automatically committed. 121</p> 122 <p> 123 Using this high-level API, if <tt class="methodname">TransactionRunner.run()</tt> 124 throws an exception, the application can assume that the operation 125 failed and the transaction was aborted; otherwise, when an 126 exception is not thrown, the application can assume the operation 127 succeeded and the transaction was committed. 128</p> 129 <p> 130 The <tt class="methodname">Sample.run()</tt> method creates a <tt class="classname">TransactionRunner</tt> 131 object and calls its <tt class="methodname">run()</tt> method. 132</p> 133 <a id="cb_sample1"></a> 134 <pre class="programlisting"><b class="userinput"><tt>import com.sleepycat.collections.TransactionRunner; 135import com.sleepycat.collections.TransactionWorker;</tt></b> 136... 137public class Sample 138{ 139 private SampleDatabase db; 140 ... 141<b class="userinput"><tt> private void run() 142 throws Exception 143 { 144 TransactionRunner runner = new TransactionRunner(db.getEnvironment()); 145 runner.run(new PopulateDatabase()); 146 runner.run(new PrintDatabase()); 147 } 148 ... 149 private class PopulateDatabase implements TransactionWorker 150 { 151 public void doWork() 152 throws Exception 153 { 154 } 155 } 156 157 private class PrintDatabase implements TransactionWorker 158 { 159 public void doWork() 160 throws Exception 161 { 162 } 163 }</tt></b> 164} </pre> 165 <p> 166 The <tt class="methodname">run()</tt> method is called by <tt class="methodname">main()</tt> and was outlined 167 in the previous section. It first creates a 168 <tt class="classname">TransactionRunner</tt>, passing the database environment to its 169 constructor. 170</p> 171 <p> 172 It then calls <tt class="methodname">TransactionRunner.run()</tt> to execute two 173 transactions, passing instances of the application-defined 174 <tt class="classname">PopulateDatabase</tt> and 175 <tt class="classname">PrintDatabase</tt> nested classes. 176 These classes implement the <tt class="methodname">TransactionWorker.doWork()</tt> method 177 and will be fully described in the next two sections. 178</p> 179 <p> 180 For each call to <tt class="methodname">TransactionRunner.run()</tt>, a separate 181 transaction will be performed. The use of two transactions in the 182 example ��� one for populating the database and another for printing 183 its contents ��� is arbitrary. A real-life application should be 184 designed to create transactions for each group of operations that 185 should have ACID properties, while also 186 taking into account the impact of transactions on performance. 187</p> 188 <p> 189 The advantage of using <tt class="classname">TransactionRunner</tt> is that deadlock 190 retries and transaction begin, commit and abort are handled 191 automatically. However, a <tt class="classname">TransactionWorker</tt> class must be 192 implemented for each type of transaction. If desired, anonymous 193 inner classes can be used to implement the <tt class="classname">TransactionWorker</tt> 194 interface. 195</p> 196 </div> 197 <div class="navfooter"> 198 <hr /> 199 <table width="100%" summary="Navigation footer"> 200 <tr> 201 <td width="40%" align="left"><a accesskey="p" href="implementingmain.html">Prev</a>��</td> 202 <td width="20%" align="center"> 203 <a accesskey="u" href="BasicProgram.html">Up</a> 204 </td> 205 <td width="40%" align="right">��<a accesskey="n" href="addingdatabaseitems.html">Next</a></td> 206 </tr> 207 <tr> 208 <td width="40%" align="left" valign="top"> 209 Implementing the Main Program 210 ��</td> 211 <td width="20%" align="center"> 212 <a accesskey="h" href="index.html">Home</a> 213 </td> 214 <td width="40%" align="right" valign="top">�� 215 Adding Database Items 216 </td> 217 </tr> 218 </table> 219 </div> 220 </body> 221</html> 222