Import BSDDB 4.7.25 (as of svn r89086)
This commit is contained in:
Zachary Ware
256
docs/gsg/JAVA/DBEntry.html
Normal file
256
docs/gsg/JAVA/DBEntry.html
Normal file
@@ -0,0 +1,256 @@
|
||||
<?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.62.4" />
|
||||
<link rel="home" 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="previous" href="CoreJavaUsage.html" title="Database Example" />
|
||||
<link rel="next" href="usingDbt.html" title="Reading and Writing Database Records" />
|
||||
</head>
|
||||
<body>
|
||||
<div class="navheader">
|
||||
<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>
|
||||
</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><tt class="classname">DatabaseEntry</tt> 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>
|
||||
<tt class="classname">DatabaseEntry</tt> 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 <tt class="literal">byte</tt> array. Note that due to
|
||||
performance considerations, you should not use Java serialization to convert
|
||||
a Java object to a <tt class="literal">byte</tt> array. Instead, use the Bind APIs
|
||||
to perform this conversion (see
|
||||
<a href="bindAPI.html">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 <tt class="literal">byte</tt> 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></div>
|
||||
</div>
|
||||
<p>
|
||||
Each database record is comprised of two
|
||||
<span><tt class="classname">DatabaseEntry</tt> 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
|
||||
<tt class="classname">DatabaseEntry</tt> objects as <tt class="literal">byte</tt>
|
||||
arrays. Using <tt class="classname">DatabaseEntry</tt>s allows DB to
|
||||
change the underlying byte array as well as return multiple values (that
|
||||
is, key and data). Therefore, using <tt class="classname">DatabaseEntry</tt> instances
|
||||
is mostly an exercise in efficiently moving your keys and your data in
|
||||
and out of <tt class="literal">byte</tt> arrays.</span>
|
||||
</p>
|
||||
<p>
|
||||
For example, to store a database record where both the key and the
|
||||
data are Java <tt class="classname">String</tt> objects, you instantiate a
|
||||
pair of <tt class="classname">DatabaseEntry</tt> 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 <tt class="literal">UTF-8</tt> when we retrieve the
|
||||
<tt class="literal">byte</tt> array from our <tt class="classname">String</tt>
|
||||
object. Without parameters, <tt class="methodname">String.getBytes()</tt> 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 <tt class="classname">DatabaseEntry</tt>
|
||||
instances for you, one for the key and another for the data. Assuming Java
|
||||
<tt class="classname">String</tt> objects, you retrieve your data from the
|
||||
<tt class="classname">DatabaseEntry</tt> 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 <tt class="literal">byte</tt> 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
|
||||
<tt class="literal">byte</tt> 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 href="bindAPI.html">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>
|
||||
Reference in New Issue
Block a user