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