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>Reading and Writing Database Records</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" /> 9 <link rel="home" href="index.html" title="Getting Started with Berkeley DB" /> 10 <link rel="up" href="DBEntry.html" title="Chapter��8.��Database Records" /> 11 <link rel="previous" href="DBEntry.html" title="Chapter��8.��Database Records" /> 12 <link rel="next" href="bindAPI.html" title="Using the BIND APIs" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Reading and Writing Database Records</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="DBEntry.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��8.��Database Records</th> 23 <td width="20%" align="right">��<a accesskey="n" href="bindAPI.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="sect1" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title" style="clear: both"><a id="usingDbt"></a>Reading and Writing Database Records</h2> 33 </div> 34 </div> 35 <div></div> 36 </div> 37 <p> 38 When reading and writing database records, be aware that there are some 39 slight differences in behavior depending on whether your database supports duplicate 40 records. Two or more database records are considered to be duplicates of 41 one another if they share the same key. The collection of records 42 sharing the same key are called a <span class="emphasis"><em>duplicates set.</em></span> 43 44 <span> 45 In DB, a given key is stored only once for a single duplicates set. 46 </span> 47 </p> 48 <p> 49 By default, DB databases do 50 not support duplicate records. Where duplicate records are supported, 51 cursors (see below) are <span>typically</span> used 52 to access all of the records in the duplicates set. 53 </p> 54 <p> 55 DB provides two basic mechanisms for the storage and retrieval of database 56 key/data pairs: 57 </p> 58 <div class="itemizedlist"> 59 <ul type="disc"> 60 <li> 61 <p> 62 The 63 <tt class="methodname">Database.put()</tt> 64 65 66 and 67 <tt class="methodname">Database.get()</tt> 68 69 70 methods provide the easiest access for all non-duplicate records in the database. 71 These methods are described in this section. 72 </p> 73 </li> 74 <li> 75 <p>Cursors provide several methods for putting and getting database 76 records. Cursors and their database access methods are described in 77 <a href="Cursors.html">Using Cursors</a>.</p> 78 </li> 79 </ul> 80 </div> 81 <div class="sect2" lang="en" xml:lang="en"> 82 <div class="titlepage"> 83 <div> 84 <div> 85 <h3 class="title"><a id="databaseWrite"></a>Writing Records to the Database</h3> 86 </div> 87 </div> 88 <div></div> 89 </div> 90 <p> 91 Records are stored in the database using whatever organization is 92 required by the access method that you have selected. In some cases (such as 93 BTree), records are stored in a sort order that you may want to define 94 (see <a href="btree.html#comparators">Setting Comparison Functions</a> for more information). 95 </p> 96 <p> 97 In any case, the mechanics of putting and getting database records do not 98 change once you have selected your access method, configured your 99 sorting routines (if any), and opened your database. From your 100 code's perspective, a simple database put and get is largely the 101 same no matter what access method you are using. 102 </p> 103 <p>You can use the following methods to put database records:</p> 104 <div class="itemizedlist"> 105 <ul type="disc"> 106 <li> 107 <p> 108 <tt class="methodname">Database.put()</tt> 109 </p> 110 <p> 111 Puts a database record into the database. If your database does not 112 support duplicate records, and if the provided key already exists in 113 the database, then the currently existing record is replaced with 114 the new data. 115 </p> 116 </li> 117 <li> 118 <p> 119 <tt class="methodname">Database.putNoOverwrite()</tt> 120 </p> 121 <p> 122 Disallows overwriting (replacing) an existing record in the 123 database. If the provided key already exists in the database, 124 then this method returns 125 <tt class="literal">OperationStatus.KEYEXIST</tt> even if 126 the database supports duplicates. 127 </p> 128 </li> 129 <li> 130 <p> 131 <tt class="methodname">Database.putNoDupData()</tt> 132 </p> 133 <p> 134 Puts a database record into the database. If the provided key 135 and data already exists in the database (that is, if you are 136 attempting to put a record that compares equally to an existing 137 record), then this returns 138 <tt class="literal">OperationStatus.KEYEXIST</tt>. 139 </p> 140 </li> 141 </ul> 142 </div> 143 <p> 144 When you put database records, you provide both the key and the data as 145 <tt class="classname">DatabaseEntry</tt> objects. This means you must 146 convert your key and data into a Java <tt class="literal">byte</tt> array. For 147 example: 148 </p> 149 <a id="java_dbt3"></a> 150 <pre class="programlisting">package db.GettingStarted; 151 152import com.sleepycat.db.DatabaseEntry; 153import com.sleepycat.db.Database; 154 155... 156 157// Database opens omitted for clarity. 158// Databases must NOT be opened read-only. 159 160String aKey = "myFirstKey"; 161String aData = "myFirstData"; 162 163try { 164 DatabaseEntry theKey = new DatabaseEntry(aKey.getBytes("UTF-8")); 165 DatabaseEntry theData = new DatabaseEntry(aData.getBytes("UTF-8")); 166 myDatabase.put(null, theKey, theData); 167} catch (Exception e) { 168 // Exception handling goes here 169} </pre> 170 </div> 171 <div class="sect2" lang="en" xml:lang="en"> 172 <div class="titlepage"> 173 <div> 174 <div> 175 <h3 class="title"><a id="databaseRead"></a>Getting Records from the Database</h3> 176 </div> 177 </div> 178 <div></div> 179 </div> 180 <p> 181 The <tt class="classname">Database</tt> class provides several 182 methods that you can use to retrieve database records. Note that if your 183 database supports duplicate records, then these methods will only ever 184 return the first record in a duplicate set. For this reason, if your 185 database supports duplicates, you should use a cursor to retrieve 186 records from it. Cursors are described in <a href="Cursors.html">Using Cursors</a>. 187 </p> 188 <p> 189 You can use either of the following methods to retrieve records from the database: 190 </p> 191 <div class="itemizedlist"> 192 <ul type="disc"> 193 <li> 194 <p> 195 <tt class="methodname">Database.get()</tt> 196 </p> 197 <p>Retrieves the record whose key matches the key provided to the 198 method. If no records exists that uses the provided key, then 199 <tt class="literal">OperationStatus.NOTFOUND</tt> is returned.</p> 200 </li> 201 <li> 202 <p> 203 <tt class="methodname">Database.getSearchBoth()</tt> 204 </p> 205 <p>Retrieve the record whose key matches both the key and the data 206 provided to the method. If no record exists that uses the provided 207 key and data, then <tt class="literal">OperationStatus.NOTFOUND</tt> is 208 returned.</p> 209 </li> 210 </ul> 211 </div> 212 <p>Both the key and data for a database record are returned as 213 byte arrays in <tt class="classname">DatabaseEntry</tt> objects. These objects are 214 passed as parameter values to the <tt class="methodname">Database.get()</tt> method. 215 </p> 216 <p>In order to retrieve your data once <tt class="classname">Database.get()</tt> 217 has completed, you must retrieve the <tt class="literal">byte</tt> array stored 218 in the <tt class="classname">DatabaseEntry</tt> and then convert that 219 <tt class="literal">byte</tt> array back to the 220 appropriate datatype. For example:</p> 221 <a id="java_dbt4"></a> 222 <pre class="programlisting">package db.GettingStarted; 223 224import com.sleepycat.db.DatabaseEntry; 225import com.sleepycat.db.Database; 226import com.sleepycat.db.LockMode; 227import com.sleepycat.db.OperationStatus; 228 229... 230 231Database myDatabase = null; 232// Database opens omitted for clarity. 233// Database may be opened read-only. 234 235String aKey = "myFirstKey"; 236 237try { 238 // Create a pair of DatabaseEntry objects. theKey 239 // is used to perform the search. theData is used 240 // to store the data returned by the get() operation. 241 DatabaseEntry theKey = new DatabaseEntry(aKey.getBytes("UTF-8")); 242 DatabaseEntry theData = new DatabaseEntry(); 243 244 // Perform the get. 245 if (myDatabase.get(null, theKey, theData, LockMode.DEFAULT) == 246 OperationStatus.SUCCESS) { 247 248 // Recreate the data String. 249 byte[] retData = theData.getData(); 250 String foundData = new String(retData, "UTF-8"); 251 System.out.println("For key: '" + aKey + "' found data: '" + 252 foundData + "'."); 253 } else { 254 System.out.println("No record found for key '" + aKey + "'."); 255 } 256} catch (Exception e) { 257 // Exception handling goes here 258}</pre> 259 </div> 260 <div class="sect2" lang="en" xml:lang="en"> 261 <div class="titlepage"> 262 <div> 263 <div> 264 <h3 class="title"><a id="recordDelete"></a>Deleting Records</h3> 265 </div> 266 </div> 267 <div></div> 268 </div> 269 <p> 270 271 You can use the 272 <tt class="methodname">Database.delete()</tt> 273 274 275 method to delete a record from the database. If your database supports 276 duplicate records, then all records associated with the provided key are 277 deleted. To delete just one record from a list of duplicates, use a 278 cursor. Cursors are described in <a href="Cursors.html">Using Cursors</a>. 279 280 </p> 281 <p> 282 You can also delete every record in the database by using 283 <tt class="methodname">Environment.truncateDatabase().</tt> 284 285 286 </p> 287 <p>For example:</p> 288 <a id="java_dbt5"></a> 289 <pre class="programlisting">package db.GettingStarted; 290 291import com.sleepycat.db.DatabaseEntry; 292import com.sleepycat.db.Database; 293 294... 295 296Database myDatabase = null; 297// Database opens omitted for clarity. 298// Database can NOT be opened read-only. 299 300try { 301 String aKey = "myFirstKey"; 302 DatabaseEntry theKey = new DatabaseEntry(aKey.getBytes("UTF-8")); 303 304 // Perform the deletion. All records that use this key are 305 // deleted. 306 myDatabase.delete(null, theKey); 307} catch (Exception e) { 308 // Exception handling goes here 309}</pre> 310 </div> 311 <div class="sect2" lang="en" xml:lang="en"> 312 <div class="titlepage"> 313 <div> 314 <div> 315 <h3 class="title"><a id="datapersist"></a>Data Persistence</h3> 316 </div> 317 </div> 318 <div></div> 319 </div> 320 <p> 321 When you perform a database modification, your modification is made 322 in the in-memory cache. This means that your data modifications 323 are not necessarily flushed to disk, and so your data may not appear 324 in the database after an application restart. 325 </p> 326 <p> 327 Note that as a normal part of closing a database, its cache is 328 written to disk. However, in the event of an application or system 329 failure, there is no guarantee that your databases will close 330 cleanly. In this event, it is possible for you to lose data. Under 331 extremely rare circumstances, it is also possible for you to 332 experience database corruption. 333 </p> 334 <p> 335 Therefore, if you care if your data is durable across system 336 failures, and to guard against the rare possibility of 337 database corruption, you should use transactions to protect your 338 database modifications. Every time you commit a transaction, DB 339 ensures that the data will not be lost due to application or 340 system failure. Transaction usage is described in the 341 342 343 344 345 <span> 346 <i class="citetitle">Berkeley DB Getting Started with Transaction Processing</i> guide. 347 </span> 348 </p> 349 <p> 350 If you do not want to use transactions, then the assumption is that 351 your data is of a nature that it need not exist the next time your 352 application starts. You may want this if, for example, you are using 353 DB to cache data relevant only to the current application 354 runtime. 355 </p> 356 <p> 357 If, however, you are not using transactions for some reason and you 358 still want some guarantee that your database modifications are 359 persistent, then you should periodically 360 <span>run environment syncs.</span> 361 362 363 Syncs cause any dirty entries in the in-memory cache and the 364 operating system's file cache to be written to disk. As 365 such, they are quite expensive and you should use them sparingly. 366 </p> 367 <p> 368 Remember that by default a sync is performed any time a non-transactional 369 database is closed cleanly. (You can override this behavior by 370 specifying 371 372 <tt class="literal">true</tt> 373 on the call to 374 375 376 <span><tt class="methodname">Database.close()</tt>.)</span> 377 378 That said, you can manually run a sync by calling 379 380 381 382 <tt class="methodname">Database.sync().</tt> 383 384 </p> 385 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 386 <h3 class="title">Note</h3> 387 <p> 388 If your application or system crashes and you are not using 389 transactions, then you should either discard and recreate your 390 databases, or verify them. You can verify a database using 391 392 393 <span>Database.verify().</span> 394 If your databases do not verify cleanly, use the 395 <span><b class="command">db_dump</b></span> command to salvage as much of the 396 database as is possible. Use either the <tt class="literal">-R</tt> or 397 <tt class="literal">-r</tt> command line options to control how 398 aggressive <span><b class="command">db_dump</b></span> should be when salvaging 399 your databases. 400 </p> 401 </div> 402 </div> 403 </div> 404 <div class="navfooter"> 405 <hr /> 406 <table width="100%" summary="Navigation footer"> 407 <tr> 408 <td width="40%" align="left"><a accesskey="p" href="DBEntry.html">Prev</a>��</td> 409 <td width="20%" align="center"> 410 <a accesskey="u" href="DBEntry.html">Up</a> 411 </td> 412 <td width="40%" align="right">��<a accesskey="n" href="bindAPI.html">Next</a></td> 413 </tr> 414 <tr> 415 <td width="40%" align="left" valign="top">Chapter��8.��Database Records��</td> 416 <td width="20%" align="center"> 417 <a accesskey="h" href="index.html">Home</a> 418 </td> 419 <td width="40%" align="right" valign="top">��Using the BIND APIs</td> 420 </tr> 421 </table> 422 </div> 423 </body> 424</html> 425