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>Appendix A. 7 API Notes and Details 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="Summary.html" title="Chapter 7. 		Summary 	" /> 14 <link rel="next" href="UsingCollectionsAPI.html" title=" Using the DB Java Collections API " /> 15 </head> 16 <body> 17 <div class="navheader"> 18 <table width="100%" summary="Navigation header"> 19 <tr> 20 <th colspan="3" align="center">Appendix A. 21 API Notes and Details 22 </th> 23 </tr> 24 <tr> 25 <td width="20%" align="left"><a accesskey="p" href="Summary.html">Prev</a> </td> 26 <th width="60%" align="center"> </th> 27 <td width="20%" align="right"> <a accesskey="n" href="UsingCollectionsAPI.html">Next</a></td> 28 </tr> 29 </table> 30 <hr /> 31 </div> 32 <div class="appendix" lang="en" xml:lang="en"> 33 <div class="titlepage"> 34 <div> 35 <div> 36 <h2 class="title"><a id="collectionOverview"></a>Appendix A. 37 API Notes and Details 38 </h2> 39 </div> 40 </div> 41 <div></div> 42 </div> 43 <p> 44 This appendix contains information useful to the collections programmer 45 that is too detailed to easily fit into the format of a tutorial. 46 Specifically, this appendix contains the following information: 47 </p> 48 <div class="itemizedlist"> 49 <ul type="disc"> 50 <li> 51 <p> 52 <a href="collectionOverview.html#UsingDataBindings"> 53 Using Data Bindings 54 </a> 55 </p> 56 </li> 57 <li> 58 <p> 59 <a href="UsingCollectionsAPI.html"> 60 Using the DB Java Collections API 61 </a> 62 </p> 63 </li> 64 <li> 65 <p> 66 <a href="UsingStoredCollections.html"> 67 Using Stored Collections 68 </a> 69 </p> 70 </li> 71 <li> 72 <p> 73 <a href="SerializedObjectStorage.html"> 74 Serialized Object Storage 75 </a> 76 </p> 77 </li> 78 </ul> 79 </div> 80 <div class="sect1" lang="en" xml:lang="en"> 81 <div class="titlepage"> 82 <div> 83 <div> 84 <h2 class="title" style="clear: both"><a id="UsingDataBindings"></a> 85 Using Data Bindings 86 </h2> 87 </div> 88 </div> 89 <div></div> 90 </div> 91 <p> 92 Data bindings determine how keys and values are represented as 93 stored data (byte arrays) in the database, and how stored data is 94 converted to and from Java objects. 95 </p> 96 <p> 97 The selection of data bindings is, in general, independent of 98 the selection of 99 <span> access methods and </span> 100 collection views. In other 101 words, any binding can be used with any 102 <span> access method or </span> 103 collection. 104 <span> 105 One exception to this rule is described under 106 <a href="collectionOverview.html#RecordNumberBindings">Record Number Bindings</a> 107 below. 108 </span> 109 </p> 110 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 111 <h3 class="title">Note</h3> 112 <p> 113 In this document, bindings are described in the 114 context of their use for stored data in a database. However, 115 bindings may also be used independently of a database to operate on 116 an arbitrary byte array. This allows using bindings when data is to 117 be written to a file or sent over a network, for example. 118 </p> 119 </div> 120 <div class="sect2" lang="en" xml:lang="en"> 121 <div class="titlepage"> 122 <div> 123 <div> 124 <h3 class="title"><a id="SelectingBindingFormats"></a> 125 Selecting Binding Formats 126 </h3> 127 </div> 128 </div> 129 <div></div> 130 </div> 131 <p> 132 For the key and value of each stored collection, you may select 133 one of the following types of bindings. 134 </p> 135 <div class="informaltable"> 136 <table border="1" width="80%"> 137 <colgroup> 138 <col /> 139 <col /> 140 <col /> 141 </colgroup> 142 <thead> 143 <tr> 144 <th>Binding Format</th> 145 <th>Ordered</th> 146 <th>Description</th> 147 </tr> 148 </thead> 149 <tbody> 150 <tr> 151 <td> 152 <a href="/java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a> 153 </td> 154 <td>No</td> 155 <td> 156 The data is stored using a compact form of Java serialization, 157 where the class descriptions are stored separately in a catalog 158 database. Arbitrary Java objects are supported. 159 </td> 160 </tr> 161 <tr> 162 <td> 163 <a href="/java/com/sleepycat/bind/tuple/TupleBinding.html" target="_top">TupleBinding</a> 164 </td> 165 <td>Yes</td> 166 <td> 167 The data is stored using a series of fixed length primitive 168 values or zero terminated character arrays (strings). Class/type 169 evolution is not supported. 170 </td> 171 </tr> 172 <tr> 173 <td> 174 <a href="/java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a> 175 </td> 176 <td>Yes</td> 177 <td> 178 The data is a 32-bit integer stored in a platform-dependent format. 179 </td> 180 </tr> 181 <tr> 182 <td>Custom binding format</td> 183 <td>User-defined</td> 184 <td> 185 The data storage format and ordering is determined by the 186 custom binding implementation. 187 </td> 188 </tr> 189 </tbody> 190 </table> 191 </div> 192 <p> 193 As shown in the table above, the tuple format supports built-in ordering 194 (without specifying a custom comparator), while the serial format does 195 not. This means that when a specific key order is needed, tuples should 196 be used instead of serial data. Alternatively, a custom Btree comparator should be 197 specified using 198 <tt class="methodname">DatabaseConfig.setBtreeComparator()</tt>. Note that 199 a custom Btree comparator will usually execute more slowly than the 200 default byte-by-byte comparison. This makes using tuples an attractive 201 option, since they provide ordering along with optimal performance. 202 </p> 203 <p> 204 The tuple binding uses less space and executes faster than the 205 serial binding. But once a tuple is written to a database, the 206 order of fields in the tuple may not be changed and fields may not 207 be deleted. The only type evolution allowed is the addition of 208 fields at the end of the tuple, and this must be explicitly 209 supported by the custom binding implementation. 210 </p> 211 <p> 212 The serial binding supports the full generality of Java 213 serialization including type evolution. But serialized data can 214 only be accessed by Java applications, its size is larger, and its 215 bindings are slower to execute. 216 </p> 217 </div> 218 <div class="sect2" lang="en" xml:lang="en"> 219 <div class="titlepage"> 220 <div> 221 <div> 222 <h3 class="title"><a id="RecordNumberBindings"></a>Record Number Bindings</h3> 223 </div> 224 </div> 225 <div></div> 226 </div> 227 <p> 228 Any use of an access method with record number keys, and therefore any 229 use of a stored list view, requires using 230 <a href="/java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a> 231 232 as the key binding. Since Berkeley DB stores record number keys using 233 a platform-dependent byte order, 234 <a href="/java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a> 235 236 is needed to store record numbers properly. See 237 <span class="html"><a href="/ref/am_conf/logrec.html" target="_top">logical record numbers</a> in</span> 238 the <i class="citetitle">Berkeley DB Programmer's Reference Guide</i> 239 for more information on storing DB record numbers. 240 </p> 241 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 242 <h3 class="title">Note</h3> 243 <p> 244 You may not use 245 <a href="/java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a> 246 247 except with record number keys, as determined by the access 248 method. Using 249 <a href="/java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a> 250 251 in other cases will create a database that is not portable 252 between platforms. When constructing the stored collection, 253 the DB Java Collections API will throw an 254 <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/IllegalArgumentException.html" target="_top">IllegalArgumentException</a> 255 256 in such cases. 257 </p> 258 </div> 259 </div> 260 <div class="sect2" lang="en" xml:lang="en"> 261 <div class="titlepage"> 262 <div> 263 <div> 264 <h3 class="title"><a id="SelectingDataBindings"></a> 265 Selecting Data Bindings 266 </h3> 267 </div> 268 </div> 269 <div></div> 270 </div> 271 <p> 272 There are two types of binding interfaces. Simple entry bindings 273 implement the 274 <a href="/java/com/sleepycat/bind/EntryBinding.html" target="_top">EntryBinding</a> 275 276 interface and can be used for key or value objects. Entity bindings 277 implement the 278 <a href="/java/com/sleepycat/bind/EntityBinding.html" target="_top">EntityBinding</a> 279 280 interface and are used for combined key and value objects called 281 entities. 282 </p> 283 <p> 284 Simple entry bindings map between the key or value data stored 285 by Berkeley DB and a key or value object. This is a simple 286 one-to-one mapping. 287 </p> 288 <p> 289 Simple entry bindings are easy to implement and in some cases 290 require no coding. For example, a 291 <a href="/java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a> 292 293 can be used for keys or values without writing any additional 294 code. A tuple binding for a single-item tuple can also be used without 295 writing any code; see the 296 <a href="/java/com/sleepycat/bind/tuple/TupleBinding.html#getPrimitiveBinding(java.lang.Class)" target="_top">TupleBinding.getPrimitiveBinding</a> 297 298 method. 299 </p> 300 <p> 301 Entity bindings must divide an entity object into its key and 302 value data, and then combine the key and value data to re-create 303 the entity object. This is a two-to-one mapping. 304 </p> 305 <p> 306 Entity bindings are useful when a stored application object 307 naturally has its primary key as a property, which is very common. 308 For example, an Employee object would naturally have an 309 EmployeeNumber property (its primary key) and an entity binding 310 would then be needed. Of course, entity bindings are more complex 311 to implement, especially if their key and data formats are 312 different. 313 </p> 314 <p> 315 Note that even when an entity binding is used a key binding is 316 also usually needed. For example, a key binding is used to create 317 key objects that are passed to the 318 <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#get" target="_top">Map.get()</a> 319 320 method. A key object is passed to this method even though it may 321 return an entity that also contains the key. 322 </p> 323 </div> 324 <div class="sect2" lang="en" xml:lang="en"> 325 <div class="titlepage"> 326 <div> 327 <div> 328 <h3 class="title"><a id="ImplementingBindings"></a> 329 Implementing Bindings 330 </h3> 331 </div> 332 </div> 333 <div></div> 334 </div> 335 <p> 336 There are two ways to implement bindings. The first way is to 337 create a binding class that implements one of the two binding 338 interfaces, 339 <a href="/java/com/sleepycat/bind/EntryBinding.html" target="_top">EntryBinding</a> 340 341 or 342 <a href="/java/com/sleepycat/bind/EntityBinding.html" target="_top">EntityBinding</a>. 343 For tuple bindings and serial bindings there are a number of 344 abstract classes that make this easier. For example, you can extend 345 <a href="/java/com/sleepycat/bind/tuple/TupleBinding.html" target="_top">TupleBinding</a> 346 347 to implement a simple binding for a tuple key or value. Abstract 348 classes are also provided for entity bindings and are named after 349 the format names of the key and value. For example, you can extend 350 <a href="/java/com/sleepycat/bind/serial/TupleSerialBinding.html" target="_top">TupleSerialBinding</a> 351 352 to implement an entity binding with a tuple key and serial 353 value. 354 </p> 355 <p> 356 Another way to implement bindings is with marshalling 357 interfaces. These are interfaces which perform the binding 358 operations and are implemented by the key, value or entity classes 359 themselves. With marshalling you use a binding which calls the 360 marshalling interface and you implement the marshalling interface 361 for each key, value or entity class. For example, you can use 362 <a href="/java/com/sleepycat/bind/tuple/TupleMarshalledBinding.html" target="_top">TupleMarshalledBinding</a> 363 364 along with key or value classes that implement the 365 <a href="/java/com/sleepycat/bind/tuple/MarshalledTupleEntry.html" target="_top">MarshalledTupleEntry</a> 366 367 interface. 368 </p> 369 </div> 370 <div class="sect2" lang="en" xml:lang="en"> 371 <div class="titlepage"> 372 <div> 373 <div> 374 <h3 class="title"><a id="UsingBindings"></a> 375 Using Bindings 376 </h3> 377 </div> 378 </div> 379 <div></div> 380 </div> 381 <p> 382 Bindings are specified whenever a stored collection is created. 383 A key binding must be specified for map, key set and entry set 384 views. A value binding or entity binding must be specified for map, 385 value set and entry set views. 386 </p> 387 <p> 388 Any number of bindings may be created for the same stored data. 389 This allows multiple views over the same data. For example, a tuple 390 might be bound to an array of values or to a class with properties 391 for each object. 392 </p> 393 <p> 394 It is important to be careful of bindings that only use a subset 395 of the stored data. This can be useful to simplify a view or to 396 hide information that should not be accessible. However, if you 397 write records using these bindings you may create stored data that 398 is invalid from the application's point of view. It is up to the 399 application to guard against this by creating a read-only 400 collection when such bindings are used. 401 </p> 402 </div> 403 <div class="sect2" lang="en" xml:lang="en"> 404 <div class="titlepage"> 405 <div> 406 <div> 407 <h3 class="title"><a id="SecondaryKeyCreators"></a> 408 Secondary Key Creators 409 </h3> 410 </div> 411 </div> 412 <div></div> 413 </div> 414 <p> 415 Secondary Key Creators are needed whenever database indices are 416 used. For each secondary index 417 418 <span> 419 (<a href="/java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>) 420 </span> 421 a key creator is used to derive index key data from key/value data. 422 Key creators are objects whose classes implement the 423 424 <a href="/java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a> 425 426 interface. 427 </p> 428 <p> 429 Like bindings, key creators may be implemented using a separate 430 key creator class or using a marshalling interface. Abstract key 431 creator classes and marshalling interfaces are provided in the 432 com.sleepycat.bind.tuple and com.sleepycat.bind.serial 433 packages. 434 </p> 435 <p> 436 Unlike bindings, key creators fundamentally operate on key and 437 value data, not necessarily on the objects derived from the data by 438 bindings. In this sense key creators are a part of a database 439 definition, and may be independent of the various bindings that may 440 be used to view data in a database. However, key creators are not 441 prohibited from using higher level objects produced by bindings, 442 and doing so may be convenient for some applications. For example, 443 marshalling interfaces, which are defined for objects produced by 444 bindings, are a convenient way to define key creators. 445 </p> 446 </div> 447 </div> 448 </div> 449 <div class="navfooter"> 450 <hr /> 451 <table width="100%" summary="Navigation footer"> 452 <tr> 453 <td width="40%" align="left"><a accesskey="p" href="Summary.html">Prev</a> </td> 454 <td width="20%" align="center"> 455 <a accesskey="u" href="index.html">Up</a> 456 </td> 457 <td width="40%" align="right"> <a accesskey="n" href="UsingCollectionsAPI.html">Next</a></td> 458 </tr> 459 <tr> 460 <td width="40%" align="left" valign="top">Chapter 7. 461 Summary 462 </td> 463 <td width="20%" align="center"> 464 <a accesskey="h" href="index.html">Home</a> 465 </td> 466 <td width="40%" align="right" valign="top"> 467 Using the DB Java Collections API 468 </td> 469 </tr> 470 </table> 471 </div> 472 </body> 473</html> 474