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