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