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
|
<!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/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>WiredTiger: Error handling in Java</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="wiredtiger.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><a href="http://wiredtiger.com/"><img alt="Logo" src="LogoFinal-header.png" alt="WiredTiger" /></a></td>
<td style="padding-left: 0.5em;">
<div id="projectname">
 <span id="projectnumber">Version 3.2.1</span>
</div>
<div id="projectbrief"><!-- 3.2.1 --></div>
</td>
</tr>
</tbody>
</table>
</div>
<div class="banner">
<a href="https://github.com/wiredtiger/wiredtiger">Fork me on GitHub</a>
<a class="last" href="http://groups.google.com/group/wiredtiger-users">Join my user group</a>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',false,false,'search.php','Search');
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('error_handling_lang_java.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Error handling in Java </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>WiredTiger operations return a value of 0 on success and a non-zero value on error. Error codes may be either positive or negative: positive error codes are standard error codes as described for POSIX-like systems (for example, <code>EINVAL</code> or <code>EBUSY</code>), negative error codes are WiredTiger-specific (for example, <code>WT_ROLLBACK</code>).</p>
<p>WiredTiger-specific error codes always appear in the -31,800 to -31,999 range, inclusive.</p>
<p>Informational return values, like <code>wiredtiger.WT_NOTFOUND</code> or <code>wiredtiger.WT_DUPLICATE_KEY</code> or 0 (success), are directly returned by APIs. More severe errors are thrown as <code>WiredTigerException</code>, which may be caught by the application.</p>
<p>The <code>WiredTigerRollbackException</code> is a specific type of <code>WiredTigerException</code>, thrown when there is a conflict between concurrent operations. An application that catches this exception should call rollback() on the relevant transaction, and retry as necessary.</p>
<p>The <code>WiredTigerPanicException</code> is a specific type of <code>WiredTigerException</code>, thrown when there is a fatal error requiring database restart. Applications will normally handle <code>WiredTigerPanicException</code> as a special case. A correctly-written WiredTiger application will likely catch <code>WiredTigerPanicException</code> and immediately exit or otherwise handle fatal errors. Note that no further WiredTiger calls are required after <code>WiredTigerPanicException</code> is caught (and further calls will themselves immediately fail).</p>
<p>WiredTiger returns <code>EBUSY</code> for operations requiring exclusive access, when an object is not available for exclusive access. For example, the Session.drop or Session.verify methods will fail if the object has open cursors. Note that internal WiredTiger threads may temporarily open cursors on objects (for example, threads performing operations like statistics logging), and operations may temporarily fail and return <code>EBUSY</code> when there are no application cursors open on the object.</p>
<p>The following is a complete list of the WiredTiger-specific return values, all constants defined in the <a class="el" href="classcom_1_1wiredtiger_1_1db_1_1wiredtiger.html">com.wiredtiger.db.wiredtiger</a> class:</p>
<dl class="section user"><dt>WT_ROLLBACK</dt><dd>This error is generated when an operation cannot be completed due to a conflict with concurrent operations. The operation may be retried; if a transaction is in progress, it should be rolled back and the operation retried in a new transaction.</dd></dl>
<dl class="section user"><dt>WT_DUPLICATE_KEY</dt><dd>This error is generated when the application attempts to insert a record with the same key as an existing record without the 'overwrite' configuration to Session.open_cursor.</dd></dl>
<dl class="section user"><dt>WT_ERROR</dt><dd>This error is returned when an error is not covered by a specific error return.</dd></dl>
<dl class="section user"><dt>WT_NOTFOUND</dt><dd>This error indicates an operation did not find a value to return. This includes cursor search and other operations where no record matched the cursor's search key such as Cursor.update or Cursor.remove.</dd></dl>
<dl class="section user"><dt>WT_PANIC</dt><dd>This error indicates an underlying problem that requires a database restart. The application may exit immediately, no further WiredTiger calls are required (and further calls will themselves immediately fail).</dd></dl>
<dl class="section user"><dt>WT_RUN_RECOVERY</dt><dd>This error is generated when wiredtiger_open is configured to return an error if recovery is required to use the database.</dd></dl>
<dl class="section user"><dt>WT_CACHE_FULL</dt><dd>This error is only generated when wiredtiger_open is configured to run in-memory, and an insert or update operation requires more than the configured cache size to complete. The operation may be retried; if a transaction is in progress, it should be rolled back and the operation retried in a new transaction.</dd></dl>
<dl class="section user"><dt>WT_PREPARE_CONFLICT</dt><dd>This error is generated when the application attempts to update an already updated record which is in prepared state. An updated record will be in prepared state, when the transaction that performed the update is in prepared state.</dd></dl>
<dl class="section user"><dt>WT_TRY_SALVAGE</dt><dd>This error is generated when corruption is detected in an on-disk file. During normal operations, this may occur in rare circumstances as a result of a system crash. The application may choose to salvage the file or retry wiredtiger_open with the 'salvage=true' configuration setting.</dd></dl>
<h1><a class="anchor" id="error_translation_lang_java"></a>
Translating errors</h1>
<p>The Session.strerror and <a class="el" href="group__wt.html#gae8bf720ddb4a7a7390b70424594c40fd" title="Return information about a WiredTiger error as a string (see WT_SESSION::strerror for a thread-safe A...">wiredtiger_strerror</a> functions return the standard text message associated with any WiredTiger, ISO C, or POSIX standard API.</p>
<div class="fragment"><div class="line"> <span class="keywordflow">try</span> {</div><div class="line"> String key = <span class="stringliteral">"non-existent key"</span>;</div><div class="line"> cursor.putKeyString(key);</div><div class="line"> <span class="keywordflow">if</span> ((ret = cursor.remove()) != 0) {</div><div class="line"> System.err.println(</div><div class="line"> <span class="stringliteral">"cursor.remove: "</span> + wiredtiger.wiredtiger_strerror(ret));</div><div class="line"> <span class="keywordflow">return</span> (ret);</div><div class="line"> }</div><div class="line"> } <span class="keywordflow">catch</span> (WiredTigerException wte) { <span class="comment">/* Catch severe errors. */</span></div><div class="line"> System.err.println(<span class="stringliteral">"cursor.remove exception: "</span> + wte);</div><div class="line"> }</div></div><!-- fragment --> <div class="fragment"><div class="line"> <span class="keywordflow">try</span> {</div><div class="line"> String key = <span class="stringliteral">"non-existent key"</span>;</div><div class="line"> cursor.putKeyString(key);</div><div class="line"> <span class="keywordflow">if</span> ((ret = cursor.remove()) != 0) {</div><div class="line"> System.err.println(</div><div class="line"> <span class="stringliteral">"cursor.remove: "</span> + wiredtiger.wiredtiger_strerror(ret));</div><div class="line"> <span class="keywordflow">return</span> (ret);</div><div class="line"> }</div><div class="line"> } <span class="keywordflow">catch</span> (WiredTigerException wte) { <span class="comment">/* Catch severe errors. */</span></div><div class="line"> System.err.println(<span class="stringliteral">"cursor.remove exception: "</span> + wte);</div><div class="line"> }</div></div><!-- fragment --><p> Note that <a class="el" href="group__wt.html#gae8bf720ddb4a7a7390b70424594c40fd" title="Return information about a WiredTiger error as a string (see WT_SESSION::strerror for a thread-safe A...">wiredtiger_strerror</a> is not thread-safe. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="index.html">Reference Guide</a></li><li class="navelem"><a class="el" href="programming_lang_java.html">Writing WiredTiger applications in Java</a></li>
<li class="footer">Copyright (c) 2008-2019 MongoDB, Inc. All rights reserved. Contact <a href="mailto:info@wiredtiger.com">info@wiredtiger.com</a> for more information.</li>
</ul>
</div>
</body>
</html>
|
