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
|
<!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: Cursor operations 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('cursor_ops_lang_java.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Cursor operations in Java </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Common operations in WiredTiger are performed using Cursor handles. A cursor includes:</p>
<ul>
<li>a position within a data source</li>
<li>getter/setters for key and value fields</li>
<li>encoding of fields to store in the data source</li>
<li>methods to navigate within and iterate through the data</li>
</ul>
<h1><a class="anchor" id="cursor_opening_lang_java"></a>
Opening a cursor</h1>
<p>Cursors are created using the Session.open_cursor method. For example, from the program ex_cursor.java:</p>
<div class="fragment"><div class="line"> cursor = session.<a class="code" href="struct_w_t___s_e_s_s_i_o_n.html#afb5b4a69c2c5cafe411b2b04fdc1c75d">open_cursor</a>(<span class="stringliteral">"table:world"</span>, null, null);</div></div><!-- fragment --><p> Another example from the same program:</p>
<div class="fragment"><div class="line"> cursor = session.<a class="code" href="struct_w_t___s_e_s_s_i_o_n.html#afb5b4a69c2c5cafe411b2b04fdc1c75d">open_cursor</a>(<span class="stringliteral">"table:world(country,population)"</span>, null, null);</div></div><!-- fragment --><p> In addition to traditional data sources, cursors in WiredTiger are used to access projections and even created data sources such as the run-time statistics:</p>
<div class="fragment"><div class="line"> cursor = session.<a class="code" href="struct_w_t___s_e_s_s_i_o_n.html#afb5b4a69c2c5cafe411b2b04fdc1c75d">open_cursor</a>(<span class="stringliteral">"statistics:"</span>, null, null);</div></div><!-- fragment --><p> See <a class="el" href="cursors_lang_java.html">Cursors in Java</a> for more information on available cursor types.</p>
<h1><a class="anchor" id="cursor_closing_lang_java"></a>
Closing a cursor</h1>
<p>Cursors remain open until either Cursor.close is called or the cursor's session is closed, which may either be in Session.close or Connection.close.</p>
<h1><a class="anchor" id="cursor_position_lang_java"></a>
Positioning a cursor</h1>
<p>Cursors may be positioned at the beginning of the data source, the end of the data source, at an exact key within the data source, and near a key within the data source.</p>
<p>To invalidate the position of a cursor so that subsequent iterations start from the beginning or end of the data source, use the Cursor.reset method:</p>
<div class="fragment"><div class="line"> <span class="keyword">public</span> <span class="keyword">static</span> <span class="keywordtype">int</span></div><div class="line"> cursor_reset(Cursor cursor)</div><div class="line"> <span class="keywordflow">throws</span> WiredTigerException</div><div class="line"> {</div><div class="line"> <span class="keywordflow">return</span> (cursor.<a class="code" href="struct_w_t___c_u_r_s_o_r.html#afc1b42c22c9c85e1ba08ce3b34437565">reset</a>());</div><div class="line"> }</div></div><!-- fragment --><p> To move a cursor forward in the data source, use the cursor Cursor.next method:</p>
<div class="fragment"><div class="line"> <span class="keyword">public</span> <span class="keyword">static</span> <span class="keywordtype">int</span></div><div class="line"> cursor_forward_scan(Cursor cursor)</div><div class="line"> <span class="keywordflow">throws</span> WiredTigerException</div><div class="line"> {</div><div class="line"> String key, value;</div><div class="line"> <span class="keywordtype">int</span> ret;</div><div class="line"></div><div class="line"> <span class="keywordflow">while</span> ((ret = cursor.<a class="code" href="struct_w_t___c_u_r_s_o_r.html#a0503f16bd8f3d05aa3552f229b3a8e1b">next</a>()) == 0) {</div><div class="line"> key = cursor.getKeyString();</div><div class="line"> value = cursor.getValueString();</div><div class="line"> }</div><div class="line"> <span class="keywordflow">return</span> (ret);</div><div class="line"> }</div></div><!-- fragment --><p> If the Cursor.next method is called on a cursor without a position in the data source, it is positioned at the beginning of the data source.</p>
<p>To move a cursor backward in the data source, use the cursor Cursor.prev method:</p>
<div class="fragment"><div class="line"> <span class="keyword">public</span> <span class="keyword">static</span> <span class="keywordtype">int</span></div><div class="line"> cursor_reverse_scan(Cursor cursor)</div><div class="line"> <span class="keywordflow">throws</span> WiredTigerException</div><div class="line"> {</div><div class="line"> String key, value;</div><div class="line"> <span class="keywordtype">int</span> ret;</div><div class="line"></div><div class="line"> <span class="keywordflow">while</span> ((ret = cursor.<a class="code" href="struct_w_t___c_u_r_s_o_r.html#a43d6664d2f68902aa63f933864242e76">prev</a>()) == 0) {</div><div class="line"> key = cursor.getKeyString();</div><div class="line"> value = cursor.getValueString();</div><div class="line"> }</div><div class="line"> <span class="keywordflow">return</span> (ret);</div><div class="line"> }</div></div><!-- fragment --><p> If the Cursor.prev method is called on a cursor without a position in the data source, it is positioned at the end of the data source.</p>
<p>To position a cursor at a specific location in the data source, use the Cursor.search method:</p>
<div class="fragment"><div class="line"> <span class="keyword">public</span> <span class="keyword">static</span> <span class="keywordtype">int</span></div><div class="line"> cursor_search(Cursor cursor)</div><div class="line"> <span class="keywordflow">throws</span> WiredTigerException</div><div class="line"> {</div><div class="line"> String value;</div><div class="line"> <span class="keywordtype">int</span> ret;</div><div class="line"></div><div class="line"> cursor.putKeyString(<span class="stringliteral">"foo"</span>);</div><div class="line"></div><div class="line"> <span class="keywordflow">if</span> ((ret = cursor.<a class="code" href="struct_w_t___c_u_r_s_o_r.html#a7e25b2ced2cf3ec68bd5429bf921c79f">search</a>()) != 0)</div><div class="line"> value = cursor.getValueString();</div><div class="line"></div><div class="line"> <span class="keywordflow">return</span> (ret);</div><div class="line"> }</div></div><!-- fragment --><p> To position a cursor at or near a location in the data source, use the Cursor.search_near method:</p>
<div class="fragment"><div class="line"> <span class="keyword">public</span> <span class="keyword">static</span> <span class="keywordtype">int</span></div><div class="line"> cursor_search_near(Cursor cursor)</div><div class="line"> <span class="keywordflow">throws</span> WiredTigerException</div><div class="line"> {</div><div class="line"> String key, value;</div><div class="line"> SearchStatus exact;</div><div class="line"></div><div class="line"> key = <span class="stringliteral">"foo"</span>;</div><div class="line"> cursor.putKeyString(key);</div><div class="line"></div><div class="line"> exact = cursor.<a class="code" href="struct_w_t___c_u_r_s_o_r.html#a8068ddce20d0775f26f6dac6e5eb209c">search_near</a>();</div><div class="line"> <span class="keywordflow">if</span> (exact == SearchStatus.SMALLER)</div><div class="line"> <span class="comment">/* Returned key smaller than search key */</span></div><div class="line"> key = cursor.getKeyString();</div><div class="line"> <span class="keywordflow">else</span> <span class="keywordflow">if</span> (exact == SearchStatus.LARGER)</div><div class="line"> <span class="comment">/* Returned key larger than search key */</span></div><div class="line"> key = cursor.getKeyString();</div><div class="line"> <span class="comment">/* Else exact match found, and key already set */</span></div><div class="line"></div><div class="line"> value = cursor.getValueString();</div><div class="line"></div><div class="line"> <span class="keywordflow">return</span> (0);</div><div class="line"> }</div></div><!-- fragment --><p> Cursor positions do not survive transactions: cursors that are open during Session.begin_transaction, Session.commit_transaction or Session.rollback_transaction will lose their position as if Cursor.reset was called.</p>
<p>Cursors can be configured to move to a random position with Cursor.next is called, see <a class="el" href="cursor_random_lang_java.html">Cursor random in Java</a> for details.</p>
<h1><a class="anchor" id="cursor_writes_lang_java"></a>
Inserting and updating</h1>
<p>To insert new data, and optionally update existing data, using a cursor, use the Cursor.insert method:</p>
<div class="fragment"><div class="line"> <span class="keyword">public</span> <span class="keyword">static</span> <span class="keywordtype">int</span></div><div class="line"> cursor_insert(Cursor cursor)</div><div class="line"> <span class="keywordflow">throws</span> WiredTigerException</div><div class="line"> {</div><div class="line"> cursor.putKeyString(<span class="stringliteral">"foo"</span>);</div><div class="line"> cursor.putValueString(<span class="stringliteral">"bar"</span>);</div><div class="line"></div><div class="line"> <span class="keywordflow">return</span> (cursor.<a class="code" href="struct_w_t___c_u_r_s_o_r.html#aac90d9fbcc031570f924db55f8a1cee3">insert</a>());</div><div class="line"> }</div></div><!-- fragment --><p> To update existing data using a cursor, use the Cursor.update method:</p>
<div class="fragment"><div class="line"> <span class="keyword">public</span> <span class="keyword">static</span> <span class="keywordtype">int</span></div><div class="line"> cursor_update(Cursor cursor)</div><div class="line"> <span class="keywordflow">throws</span> WiredTigerException</div><div class="line"> {</div><div class="line"> cursor.putKeyString(<span class="stringliteral">"foo"</span>);</div><div class="line"> cursor.putValueString(<span class="stringliteral">"newbar"</span>);</div><div class="line"></div><div class="line"> <span class="keywordflow">return</span> (cursor.<a class="code" href="struct_w_t___c_u_r_s_o_r.html#a444cdc0952e7f8d55d23173516c7037f">update</a>());</div><div class="line"> }</div></div><!-- fragment --><p> To remove existing data using a cursor, use the Cursor.remove method:</p>
<div class="fragment"><div class="line"> <span class="keyword">public</span> <span class="keyword">static</span> <span class="keywordtype">int</span></div><div class="line"> cursor_remove(Cursor cursor)</div><div class="line"> <span class="keywordflow">throws</span> WiredTigerException</div><div class="line"> {</div><div class="line"> cursor.putKeyString(<span class="stringliteral">"foo"</span>);</div><div class="line"> <span class="keywordflow">return</span> (cursor.<a class="code" href="struct_w_t___c_u_r_s_o_r.html#abbba24fe607fee519c4c9c4669cd4455">remove</a>());</div><div class="line"> }</div></div><!-- fragment --><p> The Session.open_cursor <code>overwrite</code> configuration is <code>true</code> by default, causing Cursor.insert, Cursor.remove and Cursor.update to ignore the current state of the record, and these methods will succeed regardless of whether or not the record previously exists.</p>
<p>When an application configures <code>overwrite</code> to <code>false</code>, Cursor.insert will fail with <a class="el" href="group__wt.html#gaeca1f3c4a70b8b71b56d2c2fc99a469c" title="Attempt to insert an existing key. ">WT_DUPLICATE_KEY</a> if the record previously exists, and Cursor.update and Cursor.remove will fail with <a class="el" href="group__wt.html#ga3c9e1b494d95cf34404ab7a974af6bf8" title="Item not found. ">WT_NOTFOUND</a> if the record does not previously exist.</p>
<h1><a class="anchor" id="cursor_error_lang_java"></a>
Cursor position after error</h1>
<p>After any cursor handle method failure, the cursor's position is undetermined. For cursor operations that expect a key to be set before the operation begins (including Cursor.search, Cursor.insert, Cursor.update and Cursor.remove), the application's key and value will not be cleared by an error.</p>
<p>Applications that cannot re-position the cursor after failure must duplicate the cursor by calling Session.open_cursor and passing the cursor as the <code>to_dup</code> parameter before calling a cursor method that will attempt to re-position the cursor. Cursor duplication is not supported for the backup, config and statistics cursor types.</p>
<h1><a class="anchor" id="cursor_memory_scoping_lang_java"></a>
Cursor key/value memory scoping</h1>
<p>When applications pass a pointer (either to a <a class="el" href="group__wt.html#struct_w_t___i_t_e_m" title="A raw item of data to be managed, including a pointer to the data and a length. ">WT_ITEM</a> or a string), to Cursor.set_key or Cursor.set_value, WiredTiger does not copy the memory referenced by the pointer. For this reason, the application must keep the referenced memory unchanged and valid until the next operation that successfully positions the cursor, modifies the underlying data, or the cursor is reset or closed (discarding its resources). The operations that position the cursor are Cursor.next, Cursor.prev, Cursor.search and Cursor.search_near; the operations that modify the underlying data are Cursor.insert, Cursor.update and Cursor.remove.</p>
<p>If a cursor operation fails (for example, due to a <a class="el" href="group__wt.html#ga5ee3c6fcd074e11efd118f3e68e91db8" title="Conflict between concurrent operations. ">WT_ROLLBACK</a> error), it may be retried without calling Cursor.set_key or Cursor.set_value again. That is, the cursor may still reference the application-supplied memory until the cursor is successfully positioned, underlying data is modified, or the cursor is closed or reset. </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="navelem"><a class="el" href="cursors_lang_java.html">Cursors 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>
|
