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��8.��Database Records</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="CoreJavaUsage.html" title="Database Example" />
12    <link rel="next" href="usingDbt.html" title="Reading and Writing Database Records" />
13  </head>
14  <body>
15    <div class="navheader">
16      <table width="100%" summary="Navigation header">
17        <tr>
18          <th colspan="3" align="center">Chapter��8.��Database Records</th>
19        </tr>
20        <tr>
21          <td width="20%" align="left"><a accesskey="p" href="CoreJavaUsage.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="usingDbt.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="DBEntry"></a>Chapter��8.��Database Records</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="DBEntry.html#usingDbEntry">Using Database Records</a>
44            </span>
45          </dt>
46          <dt>
47            <span class="sect1">
48              <a href="usingDbt.html">Reading and Writing Database Records</a>
49            </span>
50          </dt>
51          <dd>
52            <dl>
53              <dt>
54                <span class="sect2">
55                  <a href="usingDbt.html#databaseWrite">Writing Records to the Database</a>
56                </span>
57              </dt>
58              <dt>
59                <span class="sect2">
60                  <a href="usingDbt.html#databaseRead">Getting Records from the Database</a>
61                </span>
62              </dt>
63              <dt>
64                <span class="sect2">
65                  <a href="usingDbt.html#recordDelete">Deleting Records</a>
66                </span>
67              </dt>
68              <dt>
69                <span class="sect2">
70                  <a href="usingDbt.html#datapersist">Data Persistence</a>
71                </span>
72              </dt>
73            </dl>
74          </dd>
75          <dt>
76            <span class="sect1">
77              <a href="bindAPI.html">Using the BIND APIs</a>
78            </span>
79          </dt>
80          <dd>
81            <dl>
82              <dt>
83                <span class="sect2">
84                  <a href="bindAPI.html#bindPrimitive">Numerical and String Objects</a>
85                </span>
86              </dt>
87              <dt>
88                <span class="sect2">
89                  <a href="bindAPI.html#object2dbt">Serializable Complex Objects</a>
90                </span>
91              </dt>
92              <dt>
93                <span class="sect2">
94                  <a href="bindAPI.html#customTuple">Custom Tuple Bindings</a>
95                </span>
96              </dt>
97            </dl>
98          </dd>
99          <dt>
100            <span class="sect1">
101              <a href="dbtJavaUsage.html">Database Usage Example</a>
102            </span>
103          </dt>
104        </dl>
105      </div>
106      <p>
107      DB records contain two parts ��� a key and some data. Both the key
108    and its corresponding data are 
109      encapsulated in
110          <span><code class="classname">DatabaseEntry</code> class objects.</span> 
111           
112           
113    Therefore, to access a DB record, you need two such
114        
115        <span>objects,</span> one for the key and
116        one for the data.
117  </p>
118      <p>
119    <code class="classname">DatabaseEntry</code> can hold any kind of data from simple
120    Java primitive types to complex Java objects so long as that data can be
121    represented as a Java <code class="literal">byte</code> array. Note that due to
122    performance considerations, you should not use Java serialization to convert
123    a Java object to a <code class="literal">byte</code> array. Instead, use the Bind APIs
124    to perform this conversion (see 
125    <a class="xref" href="bindAPI.html" title="Using the BIND APIs">Using the BIND APIs</a> for more
126    information).
127  </p>
128      <p>
129    This chapter describes how you can convert both Java primitives and Java
130    class objects into and out of <code class="literal">byte</code> arrays. It also
131    introduces storing and retrieving key/value pairs from a database. In
132    addition, this chapter describes how you can use comparators to influence
133    how DB sorts its database records.
134  </p>
135      <div class="sect1" lang="en" xml:lang="en">
136        <div class="titlepage">
137          <div>
138            <div>
139              <h2 class="title" style="clear: both"><a id="usingDbEntry"></a>Using Database Records</h2>
140            </div>
141          </div>
142        </div>
143        <p>
144        Each database record is comprised of two 
145        <span><code class="classname">DatabaseEntry</code> objects</span>
146        
147        
148        ��� one for the key and another for the data. 
149
150        <span>The key and data information are passed to-
151        and returned from DB using
152        <code class="classname">DatabaseEntry</code> objects as <code class="literal">byte</code>
153        arrays. Using <code class="classname">DatabaseEntry</code>s allows DB to
154        change the underlying byte array as well as return multiple values (that
155        is, key and data).  Therefore, using <code class="classname">DatabaseEntry</code> instances
156        is mostly an exercise in efficiently moving your keys and your data in
157        and out of <code class="literal">byte</code> arrays.</span>
158    </p>
159        <p>
160        For example, to store a database record where both the key and the
161        data are Java <code class="classname">String</code> objects, you instantiate a
162        pair of <code class="classname">DatabaseEntry</code> objects:
163    </p>
164        <a id="java_dbt1"></a>
165        <pre class="programlisting">package db.GettingStarted;
166
167import com.sleepycat.db.DatabaseEntry;
168
169...
170
171String aKey = "key";
172String aData = "data";
173
174try {
175    DatabaseEntry theKey = new DatabaseEntry(aKey.getBytes("UTF-8"));
176    DatabaseEntry theData = new DatabaseEntry(aData.getBytes("UTF-8"));
177} catch (Exception e) {
178    // Exception handling goes here
179}
180
181    // Storing the record is described later in this chapter </pre>
182        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
183          <h3 class="title">Note</h3>
184          <p>
185            Notice that we specify <code class="literal">UTF-8</code> when we retrieve the
186            <code class="literal">byte</code> array from our <code class="classname">String</code>
187            object. Without parameters, <code class="methodname">String.getBytes()</code> uses the
188            Java system's default encoding. You should never use a system's default
189            encoding when storing data in a database because the encoding can change.
190        </p>
191        </div>
192        <p>
193        When the record is retrieved from the database, the method that you
194        use to perform this operation populates two <code class="classname">DatabaseEntry</code>
195        instances for you, one for the key and another for the data. Assuming Java
196        <code class="classname">String</code> objects, you retrieve your data from the
197        <code class="classname">DatabaseEntry</code> as follows:
198    </p>
199        <a id="java_dbt2"></a>
200        <pre class="programlisting">package db.GettingStarted;
201
202import com.sleepycat.db.DatabaseEntry;
203
204...
205
206// theKey and theData are DatabaseEntry objects. Database
207// retrieval is described later in this chapter. For now, 
208// we assume some database get method has populated these
209// objects for us.
210
211// Use DatabaseEntry.getData() to retrieve the encapsulated Java
212// byte array.
213
214byte[] myKey = theKey.getData();
215byte[] myData = theData.getData();
216
217String key = new String(myKey, "UTF-8");
218String data = new String(myData, "UTF-8"); </pre>
219        <p>
220        There are a large number of mechanisms that you can use to move data in
221        and out of <code class="literal">byte</code> arrays. To help you with this
222        activity, DB provides the bind APIs. These APIs allow you to
223        efficiently store both primitive data types and complex objects in
224        <code class="literal">byte</code> arrays.
225    </p>
226        <p>
227        The next section describes basic database put and get operations. A
228        basic understanding of database access is useful when describing database
229        storage of more complex data such as is supported by the bind APIs. Basic
230        bind API usage is then described in <a class="xref" href="bindAPI.html" title="Using the BIND APIs">Using the BIND APIs</a>.
231    </p>
232      </div>
233    </div>
234    <div class="navfooter">
235      <hr />
236      <table width="100%" summary="Navigation footer">
237        <tr>
238          <td width="40%" align="left"><a accesskey="p" href="CoreJavaUsage.html">Prev</a>��</td>
239          <td width="20%" align="center">
240            <a accesskey="u" href="baseapi.html">Up</a>
241          </td>
242          <td width="40%" align="right">��<a accesskey="n" href="usingDbt.html">Next</a></td>
243        </tr>
244        <tr>
245          <td width="40%" align="left" valign="top">Database Example��</td>
246          <td width="20%" align="center">
247            <a accesskey="h" href="index.html">Home</a>
248          </td>
249          <td width="40%" align="right" valign="top">��Reading and Writing Database Records</td>
250        </tr>
251      </table>
252    </div>
253  </body>
254</html>
255