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>Chapter 9. Using Cursors</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="Getting Started with Berkeley DB" /> 10 <link rel="up" href="baseapi.html" title="Part II. Programming with the Base API" /> 11 <link rel="prev" href="dbtJavaUsage.html" title="Database Usage Example" /> 12 <link rel="next" href="Positioning.html" title="Getting Records Using the Cursor" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Chapter 9. Using Cursors</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbtJavaUsage.html">Prev</a> </td> 22 <th width="60%" align="center">Part II. Programming with the Base API</th> 23 <td width="20%" align="right"> <a accesskey="n" href="Positioning.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="chapter" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title"><a id="Cursors"></a>Chapter 9. Using Cursors</h2> 33 </div> 34 </div> 35 </div> 36 <div class="toc"> 37 <p> 38 <b>Table of Contents</b> 39 </p> 40 <dl> 41 <dt> 42 <span class="sect1"> 43 <a href="Cursors.html#openCursor">Opening and Closing Cursors</a> 44 </span> 45 </dt> 46 <dt> 47 <span class="sect1"> 48 <a href="Positioning.html">Getting Records Using the Cursor</a> 49 </span> 50 </dt> 51 <dd> 52 <dl> 53 <dt> 54 <span class="sect2"> 55 <a href="Positioning.html#cursorsearch">Searching for Records</a> 56 </span> 57 </dt> 58 <dt> 59 <span class="sect2"> 60 <a href="Positioning.html#getdups">Working with Duplicate Records</a> 61 </span> 62 </dt> 63 </dl> 64 </dd> 65 <dt> 66 <span class="sect1"> 67 <a href="PutEntryWCursor.html">Putting Records Using Cursors</a> 68 </span> 69 </dt> 70 <dt> 71 <span class="sect1"> 72 <a href="DeleteEntryWCursor.html">Deleting Records Using Cursors</a> 73 </span> 74 </dt> 75 <dt> 76 <span class="sect1"> 77 <a href="ReplacingEntryWCursor.html">Replacing Records Using Cursors</a> 78 </span> 79 </dt> 80 <dt> 81 <span class="sect1"> 82 <a href="cursorJavaUsage.html">Cursor Example</a> 83 </span> 84 </dt> 85 </dl> 86 </div> 87 <p> 88 Cursors provide a mechanism by which you can iterate over the records in a 89 database. Using cursors, you can get, put, and delete database records. If 90 a database allows duplicate records, then cursors are 91 92 93 94 <span>the easiest way that you can access anything 95 other than the first record for a given key.</span> 96 </p> 97 <p> 98 This chapter introduces cursors. It explains how to open and close them, how 99 to use them to modify databases, and how to use them with duplicate records. 100 </p> 101 <div class="sect1" lang="en" xml:lang="en"> 102 <div class="titlepage"> 103 <div> 104 <div> 105 <h2 class="title" style="clear: both"><a id="openCursor"></a>Opening and Closing Cursors</h2> 106 </div> 107 </div> 108 </div> 109 <p> 110 To use a cursor, you must open it using the <code class="methodname">Database.openCursor()</code> 111 method. When you open a 112 cursor, you can optionally pass it a <code class="classname">CursorConfig</code> 113 object to set cursor properties. 114 115 <span> 116 The cursor properties that you can set allows you to 117 control the isolation level that the cursor will obey. See 118 the 119 <em class="citetitle">Berkeley DB Getting Started with Transaction Processing</em> guide for more 120 information. 121 </span> 122 </p> 123 <p>For example:</p> 124 <a id="java_cursor1"></a> 125 <pre class="programlisting">package db.GettingStarted; 126 127import com.sleepycat.db.Cursor; 128import com.sleepycat.db.Database; 129import com.sleepycat.db.DatabaseException; 130 131import java.io.FileNotFoundException; 132 133... 134Database myDatabase = null; 135Cursor myCursor = null; 136 137try { 138 myDatabase = new Database("myDB", null, null); 139 140 myCursor = myDatabase.openCursor(null, null); 141} catch (FileNotFoundException fnfe) { 142 // Exception handling goes here ... 143} catch (DatabaseException dbe) { 144 // Exception handling goes here ... 145}</pre> 146 <p> 147 To close the cursor, call the <code class="methodname">Cursor.close()</code> 148 method. Note that if you close a database that has cursors open in it, 149 then it will throw an exception and close any open cursors for you. 150 For best results, close your cursors from within a 151 <code class="literal">finally</code> block. 152 153 </p> 154 <a id="java_cursor2"></a> 155 <pre class="programlisting">package db.GettingStarted; 156 157import com.sleepycat.db.Cursor; 158import com.sleepycat.db.Database; 159 160... 161try { 162 ... 163} catch ... { 164} finally { 165 try { 166 if (myCursor != null) { 167 myCursor.close(); 168 } 169 170 if (myDatabase != null) { 171 myDatabase.close(); 172 } 173 } catch(DatabaseException dbe) { 174 System.err.println("Error in close: " + dbe.toString()); 175 } 176} </pre> 177 </div> 178 </div> 179 <div class="navfooter"> 180 <hr /> 181 <table width="100%" summary="Navigation footer"> 182 <tr> 183 <td width="40%" align="left"><a accesskey="p" href="dbtJavaUsage.html">Prev</a> </td> 184 <td width="20%" align="center"> 185 <a accesskey="u" href="baseapi.html">Up</a> 186 </td> 187 <td width="40%" align="right"> <a accesskey="n" href="Positioning.html">Next</a></td> 188 </tr> 189 <tr> 190 <td width="40%" align="left" valign="top">Database Usage Example </td> 191 <td width="20%" align="center"> 192 <a accesskey="h" href="index.html">Home</a> 193 </td> 194 <td width="40%" align="right" valign="top"> Getting Records Using the Cursor</td> 195 </tr> 196 </table> 197 </div> 198 </body> 199</html> 200