Debian Codegraph @

docs/collections/tutorial/Tuple.html

raw
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>