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