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.�� 7 Using Tuples 8 </title> 9 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 10 <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" /> 11 <link rel="home" href="index.html" title="Berkeley DB Collections Tutorial" /> 12 <link rel="up" href="index.html" title="Berkeley DB Collections Tutorial" /> 13 <link rel="previous" href="entitieswithcollections.html" title=" 		Using Entities with Collections 	" /> 14 <link rel="next" href="tupleswithkeycreators.html" title=" 		Using Tuples with Key Creators 	" /> 15 </head> 16 <body> 17 <div class="navheader"> 18 <table width="100%" summary="Navigation header"> 19 <tr> 20 <th colspan="3" align="center">Chapter��5.�� 21 Using Tuples 22 </th> 23 </tr> 24 <tr> 25 <td width="20%" align="left"><a accesskey="p" href="entitieswithcollections.html">Prev</a>��</td> 26 <th width="60%" align="center">��</th> 27 <td width="20%" align="right">��<a accesskey="n" href="tupleswithkeycreators.html">Next</a></td> 28 </tr> 29 </table> 30 <hr /> 31 </div> 32 <div class="chapter" lang="en" xml:lang="en"> 33 <div class="titlepage"> 34 <div> 35 <div> 36 <h2 class="title"><a id="Tuple"></a>Chapter��5.�� 37 Using Tuples 38 </h2> 39 </div> 40 </div> 41 <div></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"> 72Creating 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 <tt class="classname">Sample</tt> 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></div> 139 </div> 140 <p> 141 Tuples are sequences of primitive Java values that can be 142 written to, and read from, the raw data bytes of a stored record. 143 The primitive values are written or read one at a time in sequence, 144 using the DB Java Collections API 145 <a href="../../java/com/sleepycat/bind/tuple/TupleInput.html" target="_top">TupleInput</a> 146 147 and 148 <a href="../../java/com/sleepycat/bind/tuple/TupleOutput.html" target="_top">TupleOutput</a> 149 150 classes. These classes are very similar to the standard Java 151 <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/io/DataInput.html" target="_top">DataInput</a> 152 153 and 154 <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/io/DataOutput.html" target="_top">DataOutput</a> 155 156 interfaces. The primary difference is the binary format of the 157 data, which is designed for sorting in the case of tuples. 158</p> 159 <p> 160 For example, to read and write a tuple containing two string 161 values, the following code snippets could be used. 162</p> 163 <a id="tuple_tuplefragment"></a> 164 <pre class="programlisting"><b class="userinput"><tt>import com.sleepycat.bind.tuple.TupleInput; 165import com.sleepycat.bind.tuple.TupleOutput; 166... 167TupleInput input; 168TupleOutput output; 169... 170String partNumber = input.readString(); 171String supplierNumber = input.readString(); 172... 173output.writeString(partNumber); 174output.writeString(supplierNumber); </tt></b> </pre> 175 <p> 176 Since a tuple is defined as an ordered sequence, reading and 177 writing order must match. If the wrong data type is read (an 178 integer instead of string, for example), an exception may be thrown 179 or at minimum invalid data will be read. 180</p> 181 <p> 182 When the tuple format is used, bindings and key creators must 183 read and write tuples using the tuple API as shown above. This will 184 be illustrated in the next two sections. 185</p> 186 </div> 187 </div> 188 <div class="navfooter"> 189 <hr /> 190 <table width="100%" summary="Navigation footer"> 191 <tr> 192 <td width="40%" align="left"><a accesskey="p" href="entitieswithcollections.html">Prev</a>��</td> 193 <td width="20%" align="center"> 194 <a accesskey="u" href="index.html">Up</a> 195 </td> 196 <td width="40%" align="right">��<a accesskey="n" href="tupleswithkeycreators.html">Next</a></td> 197 </tr> 198 <tr> 199 <td width="40%" align="left" valign="top"> 200 Using Entities with Collections 201 ��</td> 202 <td width="20%" align="center"> 203 <a accesskey="h" href="index.html">Home</a> 204 </td> 205 <td width="40%" align="right" valign="top">�� 206 Using Tuples with Key Creators 207 </td> 208 </tr> 209 </table> 210 </div> 211 </body> 212</html> 213