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
|
<?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 5. Using Tuples</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="Berkeley DB Collections Tutorial" />
<link rel="up" href="index.html" title="Berkeley DB Collections Tutorial" />
<link rel="prev" href="entitieswithcollections.html" title="Using Entities with Collections" />
<link rel="next" href="tupleswithkeycreators.html" title="Using Tuples with Key Creators" />
</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 5.
Using Tuples
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="entitieswithcollections.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="tupleswithkeycreators.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="Tuple"></a>Chapter 5.
Using Tuples
</h2>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="sect1">
<a href="Tuple.html#tupleformat">
Using the Tuple Format
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="tupleswithkeycreators.html">
Using Tuples with Key Creators
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="tuplekeybindings.html">
Creating Tuple Key Bindings
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="tuple-serialentitybindings.html">
Creating Tuple-Serial Entity Bindings
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="sortedcollections.html">
Using Sorted Collections
</a>
</span>
</dt>
</dl>
</div>
<p>
DB Java Collections API <span class="emphasis"><em>tuples</em></span> are sequences of
primitive Java data types, for example, integers and strings. The
<span class="emphasis"><em>tuple format</em></span> is a binary format for tuples that can be used
to store keys and/or values.
</p>
<p>
Tuples are useful as keys because they have a meaningful sort
order, while serialized objects do not. This is because the binary
data for a tuple is written in such a way that its raw byte
ordering provides a useful sort order. For example, strings in
tuples are written with a null terminator rather than with a
leading length.
</p>
<p>
Tuples are useful as keys <span class="emphasis"><em>or</em></span> values when reducing the
record size to a minimum is important. A tuple is significantly
smaller than an equivalent serialized object. However, unlike
serialized objects, tuples cannot contain complex data types and
are not easily extended except by adding fields at the end of the
tuple.
</p>
<p>
Whenever a tuple format is used, except when the key or value
class is a Java primitive wrapper class, a <span class="emphasis"><em>tuple binding</em></span> class must
be implemented to map between the Java object and the tuple fields.
Because of this extra requirement, and because tuples are not
easily extended, a useful technique shown in this example is to use
tuples for keys and serialized objects for values. This provides
compact ordered keys but still allows arbitrary Java objects as
values, and avoids implementing a tuple binding for each value
class.
</p>
<p>
Compare this example to the prior Entity example and you'll see
that the <code class="classname">Sample</code> class has not changed. When changing a
database format, while new bindings are needed to map key and value
objects to the new format, the application using the objects often
does not need to be modified.
</p>
<p>
The complete source of the final version of the example program
is included in the Berkeley DB distribution.
</p>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="tupleformat"></a>
Using the Tuple Format
</h2>
</div>
</div>
</div>
<p>
Tuples are sequences of primitive Java values that can be
written to, and read from, the raw data bytes of a stored record.
The primitive values are written or read one at a time in sequence,
using the DB Java Collections API
<a class="ulink" href="../../java/com/sleepycat/bind/tuple/TupleInput.html" target="_top">TupleInput</a>
and
<a class="ulink" href="../../java/com/sleepycat/bind/tuple/TupleOutput.html" target="_top">TupleOutput</a>
classes. These classes are very similar to the standard Java
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/io/DataInput.html" target="_top">DataInput</a>
and
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/io/DataOutput.html" target="_top">DataOutput</a>
interfaces. The primary difference is the binary format of the
data, which is designed for sorting in the case of tuples.
</p>
<p>
For example, to read and write a tuple containing two string
values, the following code snippets could be used.
</p>
<a id="tuple_tuplefragment"></a>
<pre class="programlisting"><strong class="userinput"><code>import com.sleepycat.bind.tuple.TupleInput;
import com.sleepycat.bind.tuple.TupleOutput;
...
TupleInput input;
TupleOutput output;
...
String partNumber = input.readString();
String supplierNumber = input.readString();
...
output.writeString(partNumber);
output.writeString(supplierNumber); </code></strong> </pre>
<p>
Since a tuple is defined as an ordered sequence, reading and
writing order must match. If the wrong data type is read (an
integer instead of string, for example), an exception may be thrown
or at minimum invalid data will be read.
</p>
<p>
When the tuple format is used, bindings and key creators must
read and write tuples using the tuple API as shown above. This will
be illustrated in the next two sections.
</p>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="entitieswithcollections.html">Prev</a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="tupleswithkeycreators.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Using Entities with Collections
</td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top">
Using Tuples with Key Creators
</td>
</tr>
</table>
</div>
</body>
</html>
|
