| 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 5. Using Tuples</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="Berkeley DB Collections Tutorial" /> |
| 10 |
<link rel="up" href="index.html" title="Berkeley DB Collections Tutorial" /> |
| 11 |
<link rel="prev" href="entitieswithcollections.html" title="Using Entities with Collections" /> |
| 12 |
<link rel="next" href="tupleswithkeycreators.html" title="Using Tuples with Key Creators" /> |
| 13 |
</head> |
| 14 |
<body> |
| 15 |
<div xmlns="" class="navheader"> |
| 16 |
<div class="libver"> |
| 17 |
<p>Library Version 11.2.5.3</p> |
| 18 |
</div> |
| 19 |
<table width="100%" summary="Navigation header"> |
| 20 |
<tr> |
| 21 |
<th colspan="3" align="center">Chapter 5. |
| 22 |
Using Tuples |
| 23 |
</th> |
| 24 |
</tr> |
| 25 |
<tr> |
| 26 |
<td width="20%" align="left"><a accesskey="p" href="entitieswithcollections.html">Prev</a> </td> |
| 27 |
<th width="60%" align="center"> </th> |
| 28 |
<td width="20%" align="right"> <a accesskey="n" href="tupleswithkeycreators.html">Next</a></td> |
| 29 |
</tr> |
| 30 |
</table> |
| 31 |
<hr /> |
| 32 |
</div> |
| 33 |
<div class="chapter" lang="en" xml:lang="en"> |
| 34 |
<div class="titlepage"> |
| 35 |
<div> |
| 36 |
<div> |
| 37 |
<h2 class="title"><a id="Tuple"></a>Chapter 5. |
| 38 |
Using Tuples |
| 39 |
</h2> |
| 40 |
</div> |
| 41 |
</div> |
| 42 |
</div> |
| 43 |
<div class="toc"> |
| 44 |
<p> |
| 45 |
<b>Table of Contents</b> |
| 46 |
</p> |
| 47 |
<dl> |
| 48 |
<dt> |
| 49 |
<span class="sect1"> |
| 50 |
<a href="Tuple.html#tupleformat"> |
| 51 |
Using the Tuple Format |
| 52 |
</a> |
| 53 |
</span> |
| 54 |
</dt> |
| 55 |
<dt> |
| 56 |
<span class="sect1"> |
| 57 |
<a href="tupleswithkeycreators.html"> |
| 58 |
Using Tuples with Key Creators |
| 59 |
</a> |
| 60 |
</span> |
| 61 |
</dt> |
| 62 |
<dt> |
| 63 |
<span class="sect1"> |
| 64 |
<a href="tuplekeybindings.html"> |
| 65 |
Creating Tuple Key Bindings |
| 66 |
</a> |
| 67 |
</span> |
| 68 |
</dt> |
| 69 |
<dt> |
| 70 |
<span class="sect1"> |
| 71 |
<a href="tuple-serialentitybindings.html"> |
| 72 |
Creating Tuple-Serial Entity Bindings |
| 73 |
</a> |
| 74 |
</span> |
| 75 |
</dt> |
| 76 |
<dt> |
| 77 |
<span class="sect1"> |
| 78 |
<a href="sortedcollections.html"> |
| 79 |
Using Sorted Collections |
| 80 |
</a> |
| 81 |
</span> |
| 82 |
</dt> |
| 83 |
</dl> |
| 84 |
</div> |
| 85 |
<p> |
| 86 |
DB Java Collections API <span class="emphasis"><em>tuples</em></span> are sequences of |
| 87 |
primitive Java data types, for example, integers and strings. The |
| 88 |
<span class="emphasis"><em>tuple format</em></span> is a binary format for tuples that can be used |
| 89 |
to store keys and/or values. |
| 90 |
</p> |
| 91 |
<p> |
| 92 |
Tuples are useful as keys because they have a meaningful sort |
| 93 |
order, while serialized objects do not. This is because the binary |
| 94 |
data for a tuple is written in such a way that its raw byte |
| 95 |
ordering provides a useful sort order. For example, strings in |
| 96 |
tuples are written with a null terminator rather than with a |
| 97 |
leading length. |
| 98 |
</p> |
| 99 |
<p> |
| 100 |
Tuples are useful as keys <span class="emphasis"><em>or</em></span> values when reducing the |
| 101 |
record size to a minimum is important. A tuple is significantly |
| 102 |
smaller than an equivalent serialized object. However, unlike |
| 103 |
serialized objects, tuples cannot contain complex data types and |
| 104 |
are not easily extended except by adding fields at the end of the |
| 105 |
tuple. |
| 106 |
</p> |
| 107 |
<p> |
| 108 |
Whenever a tuple format is used, except when the key or value |
| 109 |
class is a Java primitive wrapper class, a <span class="emphasis"><em>tuple binding</em></span> class must |
| 110 |
be implemented to map between the Java object and the tuple fields. |
| 111 |
Because of this extra requirement, and because tuples are not |
| 112 |
easily extended, a useful technique shown in this example is to use |
| 113 |
tuples for keys and serialized objects for values. This provides |
| 114 |
compact ordered keys but still allows arbitrary Java objects as |
| 115 |
values, and avoids implementing a tuple binding for each value |
| 116 |
class. |
| 117 |
</p> |
| 118 |
<p> |
| 119 |
Compare this example to the prior Entity example and you'll see |
| 120 |
that the <code class="classname">Sample</code> class has not changed. When changing a |
| 121 |
database format, while new bindings are needed to map key and value |
| 122 |
objects to the new format, the application using the objects often |
| 123 |
does not need to be modified. |
| 124 |
</p> |
| 125 |
<p> |
| 126 |
The complete source of the final version of the example program |
| 127 |
is included in the Berkeley DB distribution. |
| 128 |
</p> |
| 129 |
<div class="sect1" lang="en" xml:lang="en"> |
| 130 |
<div class="titlepage"> |
| 131 |
<div> |
| 132 |
<div> |
| 133 |
<h2 class="title" style="clear: both"><a id="tupleformat"></a> |
| 134 |
Using the Tuple Format |
| 135 |
</h2> |
| 136 |
</div> |
| 137 |
</div> |
| 138 |
</div> |
| 139 |
<p> |
| 140 |
Tuples are sequences of primitive Java values that can be |
| 141 |
written to, and read from, the raw data bytes of a stored record. |
| 142 |
The primitive values are written or read one at a time in sequence, |
| 143 |
using the DB Java Collections API |
| 144 |
<a class="ulink" href="../../java/com/sleepycat/bind/tuple/TupleInput.html" target="_top">TupleInput</a> |
| 145 |
|
| 146 |
and |
| 147 |
<a class="ulink" href="../../java/com/sleepycat/bind/tuple/TupleOutput.html" target="_top">TupleOutput</a> |
| 148 |
|
| 149 |
classes. These classes are very similar to the standard Java |
| 150 |
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/io/DataInput.html" target="_top">DataInput</a> |
| 151 |
|
| 152 |
and |
| 153 |
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/io/DataOutput.html" target="_top">DataOutput</a> |
| 154 |
|
| 155 |
interfaces. The primary difference is the binary format of the |
| 156 |
data, which is designed for sorting in the case of tuples. |
| 157 |
</p> |
| 158 |
<p> |
| 159 |
For example, to read and write a tuple containing two string |
| 160 |
values, the following code snippets could be used. |
| 161 |
</p> |
| 162 |
<a id="tuple_tuplefragment"></a> |
| 163 |
<pre class="programlisting"><strong class="userinput"><code>import com.sleepycat.bind.tuple.TupleInput; |
| 164 |
import com.sleepycat.bind.tuple.TupleOutput; |
| 165 |
... |
| 166 |
TupleInput input; |
| 167 |
TupleOutput output; |
| 168 |
... |
| 169 |
String partNumber = input.readString(); |
| 170 |
String supplierNumber = input.readString(); |
| 171 |
... |
| 172 |
output.writeString(partNumber); |
| 173 |
output.writeString(supplierNumber); </code></strong> </pre> |
| 174 |
<p> |
| 175 |
Since a tuple is defined as an ordered sequence, reading and |
| 176 |
writing order must match. If the wrong data type is read (an |
| 177 |
integer instead of string, for example), an exception may be thrown |
| 178 |
or at minimum invalid data will be read. |
| 179 |
</p> |
| 180 |
<p> |
| 181 |
When the tuple format is used, bindings and key creators must |
| 182 |
read and write tuples using the tuple API as shown above. This will |
| 183 |
be illustrated in the next two sections. |
| 184 |
</p> |
| 185 |
</div> |
| 186 |
</div> |
| 187 |
<div class="navfooter"> |
| 188 |
<hr /> |
| 189 |
<table width="100%" summary="Navigation footer"> |
| 190 |
<tr> |
| 191 |
<td width="40%" align="left"><a accesskey="p" href="entitieswithcollections.html">Prev</a> </td> |
| 192 |
<td width="20%" align="center"> </td> |
| 193 |
<td width="40%" align="right"> <a accesskey="n" href="tupleswithkeycreators.html">Next</a></td> |
| 194 |
</tr> |
| 195 |
<tr> |
| 196 |
<td width="40%" align="left" valign="top"> |
| 197 |
Using Entities with Collections |
| 198 |
</td> |
| 199 |
<td width="20%" align="center"> |
| 200 |
<a accesskey="h" href="index.html">Home</a> |
| 201 |
</td> |
| 202 |
<td width="40%" align="right" valign="top"> |
| 203 |
Using Tuples with Key Creators |
| 204 |
</td> |
| 205 |
</tr> |
| 206 |
</table> |
| 207 |
</div> |
| 208 |
</body> |
| 209 |
</html> |