Debian Codegraph @

docs/collections/tutorial/handlingexceptions.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>Handling Exceptions</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="retrievingdatabaseitems.html" title="Retrieving Database Items" />
12 <link rel="next" href="UsingSecondaries.html" title="Chapter 3.  Using Secondary Indices" />
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 Handling Exceptions
23 </th>
24 </tr>
25 <tr>
26 <td width="20%" align="left"><a accesskey="p" href="retrievingdatabaseitems.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="UsingSecondaries.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="handlingexceptions"></a>
40 Handling Exceptions
41 </h2>
42 </div>
43 </div>
44 </div>
45 <p>
46 Exception handling was illustrated previously in
47 <a class="xref" href="implementingmain.html" title="Implementing the Main Program">
48 Implementing the Main Program
49 </a>
50 and
51 <a class="xref" href="usingtransactions.html" title="Using Transactions">
52 Using Transactions
53 </a>
54 exception handling in a DB Java Collections API application in
55 more detail.
56 </p>
57 <p>
58 There are two exceptions that must be treated specially:
59
60 <a class="ulink" href="../../java/com/sleepycat/db/RunRecoveryException.html" target="_top">RunRecoveryException</a>
61
62 and
63
64 <span>
65 <a class="ulink" href="../../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a>.
66 </span>
67 </p>
68 <p>
69
70 <a class="ulink" href="../../java/com/sleepycat/db/RunRecoveryException.html" target="_top">RunRecoveryException</a>
71
72 is thrown when the only solution is to shut down the application
73 and run recovery. All applications must catch this exception and
74 follow the recovery procedure.
75 </p>
76 <p>
77 When
78
79 <a class="ulink" href="../../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a>
80
81 is thrown, the application should normally retry the operation. If
82 a deadlock continues to occur for some maximum number of retries,
83 the application should give up and try again later or take other
84 corrective actions. The DB Java Collections API provides two APIs
85 for transaction execution.
86 </p>
87 <div class="itemizedlist">
88 <ul type="disc">
89 <li>
90 <p>
91 When using the
92 <a class="ulink" href="../../java/com/sleepycat/collections/CurrentTransaction.html" target="_top">CurrentTransaction</a>
93
94 class directly, the application must catch
95
96 <a class="ulink" href="../../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a>
97
98 and follow the procedure described previously.
99 </p>
100 </li>
101 <li>
102 <p>
103 When using the
104 <a class="ulink" href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>
105
106 class, retries are performed automatically and the application need
107 only handle the case where the maximum number of retries has been
108 reached. In that case,
109 <a class="ulink" href="../../java/com/sleepycat/collections/TransactionRunner.html#run(com.sleepycat.collections.TransactionWorker)" target="_top">TransactionRunner.run</a>
110
111 will throw
112
113 <span>
114 <a class="ulink" href="../../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a>.
115 </span>
116 </p>
117 </li>
118 </ul>
119 </div>
120 <p>
121 When using the
122 <a class="ulink" href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>
123
124 class there are two other considerations.
125 </p>
126 <div class="itemizedlist">
127 <ul type="disc">
128 <li>
129 <p>
130 First, if the application-defined
131 <a class="ulink" href="../../java/com/sleepycat/collections/TransactionWorker.html#doWork()" target="_top">TransactionWorker.doWork</a>
132
133 method throws an exception the
134 transaction will automatically be aborted, and otherwise the
135 transaction will automatically be committed. Applications should
136 design their transaction processing with this in mind.
137 </p>
138 </li>
139 <li>
140 <p>
141 Second, please be aware that
142 <a class="ulink" href="../../java/com/sleepycat/collections/TransactionRunner.html#run(com.sleepycat.collections.TransactionWorker)" target="_top">TransactionRunner.run</a>
143
144 unwraps exceptions in order to discover whether a nested exception is a
145
146 <span>
147 <a class="ulink" href="../../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a>.
148 </span>
149 This is particularly important since all Berkeley DB exceptions
150 that occur while calling a stored collection method are wrapped
151 with a
152 <a class="ulink" href="../../java/com/sleepycat/util/RuntimeExceptionWrapper.html" target="_top">RuntimeExceptionWrapper</a>.
153 This wrapping is necessary because Berkeley DB exceptions are
154 checked exceptions, and the Java collections API does not allow
155 such exceptions to be thrown.
156 </p>
157 </li>
158 </ul>
159 </div>
160 <p>
161 When calling
162 <a class="ulink" href="../../java/com/sleepycat/collections/TransactionRunner.html#run(com.sleepycat.collections.TransactionWorker)" target="_top">TransactionRunner.run</a>,
163 the unwrapped (nested) exception will be unwrapped and thrown
164 automatically. If you are not using
165 <a class="ulink" href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>
166
167 or if you are handling exceptions directly for some other reason,
168 use the
169 <a class="ulink" href="../../java/com/sleepycat/util/ExceptionUnwrapper.html#unwrap(java.lang.Exception)" target="_top">ExceptionUnwrapper.unwrap</a>
170
171 method to get the nested exception. For example, this can be used
172 to discover that an exception is a
173
174 <a class="ulink" href="../../java/com/sleepycat/db/RunRecoveryException.html" target="_top">RunRecoveryException</a>
175
176 as shown below.
177 </p>
178 <a id="cb_java_manageexceptions"></a>
179 <pre class="programlisting"><strong class="userinput"><code>import com.sleepycat.db.RunRecoveryException;
180 import com.sleepycat.util.ExceptionUnwrapper;
181 ...
182 catch (Exception e)
183 {
184 e = ExceptionUnwrapper.unwrap(e);
185 if (e instanceof RunRecoveryException)
186 {
187 // follow recovery procedure
188 }
189 }</code></strong> </pre>
190 </div>
191 <div class="navfooter">
192 <hr />
193 <table width="100%" summary="Navigation footer">
194 <tr>
195 <td width="40%" align="left"><a accesskey="p" href="retrievingdatabaseitems.html">Prev</a> </td>
196 <td width="20%" align="center">
197 <a accesskey="u" href="BasicProgram.html">Up</a>
198 </td>
199 <td width="40%" align="right"> <a accesskey="n" href="UsingSecondaries.html">Next</a></td>
200 </tr>
201 <tr>
202 <td width="40%" align="left" valign="top">
203 Retrieving Database Items
204  </td>
205 <td width="20%" align="center">
206 <a accesskey="h" href="index.html">Home</a>
207 </td>
208 <td width="40%" align="right" valign="top"> Chapter 3. 
209 Using Secondary Indices
210 </td>
211 </tr>
212 </table>
213 </div>
214 </body>
215 </html>