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