docs/collections/tutorial/collectionOverview.html

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