Debian Codegraph @

docs/collections/tutorial/usingtransactions.html

raw
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>Using Transactions</title>
7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
9 <link rel="start" href="index.html" title="Berkeley DB Collections Tutorial" />
10 <link rel="up" href="BasicProgram.html" title="Chapter 2.  The Basic Program" />
11 <link rel="prev" href="implementingmain.html" title="Implementing the Main Program" />
12 <link rel="next" href="addingdatabaseitems.html" title="Adding Database Items" />
13 </head>
14 <body>
15 <div xmlns="" class="navheader">
16 <div class="libver">
17 <p>Library Version 11.2.5.3</p>
18 </div>
19 <table width="100%" summary="Navigation header">
20 <tr>
21 <th colspan="3" align="center">
22 Using Transactions
23 </th>
24 </tr>
25 <tr>
26 <td width="20%" align="left"><a accesskey="p" href="implementingmain.html">Prev</a> </td>
27 <th width="60%" align="center">Chapter 2. 
28 The Basic Program
29 </th>
30 <td width="20%" align="right"> <a accesskey="n" href="addingdatabaseitems.html">Next</a></td>
31 </tr>
32 </table>
33 <hr />
34 </div>
35 <div class="sect1" lang="en" xml:lang="en">
36 <div class="titlepage">
37 <div>
38 <div>
39 <h2 class="title" style="clear: both"><a id="usingtransactions"></a>
40 Using Transactions
41 </h2>
42 </div>
43 </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 class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.html#put(K, V)" 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 class="ulink" 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 class="ulink" href="../../java/com/sleepycat/db/Transaction.html" target="_top">Transaction</a>
83
84 object. With
85 <a class="ulink" 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 class="ulink" href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>
98
99 and
100 <a class="ulink" href="../../java/com/sleepycat/collections/TransactionWorker.html" target="_top">TransactionWorker</a>
101
102 APIs, which are build on top of
103 <a class="ulink" href="../../java/com/sleepycat/collections/CurrentTransaction.html" target="_top">CurrentTransaction</a>.
104 <code class="methodname">TransactionRunner.run()</code> automatically begins a transaction and
105 then calls the <code class="methodname">TransactionWorker.doWork()</code> method, which is
106 implemented by the application.
107 </p>
108 <p>
109 The <code class="methodname">TransactionRunner.run()</code> method automatically detects
110 deadlock exceptions and performs retries by repeatedly calling the
111 <code class="methodname">TransactionWorker.doWork()</code> 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 class="ulink" href="../../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a>)
117 </span>
118 is thrown by <code class="methodname">TransactionWorker.doWork()</code>, 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 <code class="methodname">TransactionRunner.run()</code>
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 <code class="methodname">Sample.run()</code> method creates a <code class="classname">TransactionRunner</code>
131 object and calls its <code class="methodname">run()</code> method.
132 </p>
133 <a id="cb_sample1"></a>
134 <pre class="programlisting"><strong class="userinput"><code>import com.sleepycat.collections.TransactionRunner;
135 import com.sleepycat.collections.TransactionWorker;</code></strong>
136 ...
137 public class Sample
138 {
139 private SampleDatabase db;
140 ...
141 <strong class="userinput"><code> private void run()
142 throws Exception
143 {
144 TransactionRunner runner =
145 new TransactionRunner(db.getEnvironment());
146 runner.run(new PopulateDatabase());
147 runner.run(new PrintDatabase());
148 }
149 ...
150 private class PopulateDatabase implements TransactionWorker
151 {
152 public void doWork()
153 throws Exception
154 {
155 }
156 }
157
158 private class PrintDatabase implements TransactionWorker
159 {
160 public void doWork()
161 throws Exception
162 {
163 }
164 }</code></strong>
165 } </pre>
166 <p>
167 The <code class="methodname">run()</code> method is called by <code class="methodname">main()</code> and was outlined
168 in the previous section. It first creates a
169 <code class="classname">TransactionRunner</code>, passing the database environment to its
170 constructor.
171 </p>
172 <p>
173 It then calls <code class="methodname">TransactionRunner.run()</code> to execute two
174 transactions, passing instances of the application-defined
175 <code class="classname">PopulateDatabase</code> and
176 <code class="classname">PrintDatabase</code> nested classes.
177 These classes implement the <code class="methodname">TransactionWorker.doWork()</code> method
178 and will be fully described in the next two sections.
179 </p>
180 <p>
181 For each call to <code class="methodname">TransactionRunner.run()</code>, a separate
182 transaction will be performed. The use of two transactions in the
183 example — one for populating the database and another for printing
184 its contents — is arbitrary. A real-life application should be
185 designed to create transactions for each group of operations that
186 should have ACID properties, while also
187 taking into account the impact of transactions on performance.
188 </p>
189 <p>
190 The advantage of using <code class="classname">TransactionRunner</code> is that deadlock
191 retries and transaction begin, commit and abort are handled
192 automatically. However, a <code class="classname">TransactionWorker</code> class must be
193 implemented for each type of transaction. If desired, anonymous
194 inner classes can be used to implement the <code class="classname">TransactionWorker</code>
195 interface.
196 </p>
197 </div>
198 <div class="navfooter">
199 <hr />
200 <table width="100%" summary="Navigation footer">
201 <tr>
202 <td width="40%" align="left"><a accesskey="p" href="implementingmain.html">Prev</a> </td>
203 <td width="20%" align="center">
204 <a accesskey="u" href="BasicProgram.html">Up</a>
205 </td>
206 <td width="40%" align="right"> <a accesskey="n" href="addingdatabaseitems.html">Next</a></td>
207 </tr>
208 <tr>
209 <td width="40%" align="left" valign="top">
210 Implementing the Main Program
211  </td>
212 <td width="20%" align="center">
213 <a accesskey="h" href="index.html">Home</a>
214 </td>
215 <td width="40%" align="right" valign="top"> 
216 Adding Database Items
217 </td>
218 </tr>
219 </table>
220 </div>
221 </body>
222 </html>