1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
<?xml version="1.0" encoding="ISO-8859-1" 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=ISO-8859-1" />
<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="Chapter2. 		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">Chapter2.
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 Sleepycat 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.3/docs/api/java/util/Map.html#put" target="_top">Map.put</a>.
</p>
</li>
</ul>
</div>
<p>
The Sleepycat 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>
|
