Edit File: collectionOverview.html
<?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>Appendix A. API Notes and Details </title> <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" /> <link rel="home" href="index.html" title="Berkeley DB Collections Tutorial" /> <link rel="up" href="index.html" title="Berkeley DB Collections Tutorial" /> <link rel="previous" href="Summary.html" title="Chapter 7. 		Summary 	" /> <link rel="next" href="UsingCollectionsAPI.html" title=" Using the DB Java Collections API " /> </head> <body> <div class="navheader"> <table width="100%" summary="Navigation header"> <tr> <th colspan="3" align="center">Appendix A. API Notes and Details </th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="Summary.html">Prev</a> </td> <th width="60%" align="center"> </th> <td width="20%" align="right"> <a accesskey="n" href="UsingCollectionsAPI.html">Next</a></td> </tr> </table> <hr /> </div> <div class="appendix" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h2 class="title"><a id="collectionOverview"></a>Appendix A. API Notes and Details </h2> </div> </div> <div></div> </div> <p> This appendix contains information useful to the collections programmer that is too detailed to easily fit into the format of a tutorial. Specifically, this appendix contains the following information: </p> <div class="itemizedlist"> <ul type="disc"> <li> <p> <a href="collectionOverview.html#UsingDataBindings"> Using Data Bindings </a> </p> </li> <li> <p> <a href="UsingCollectionsAPI.html"> Using the DB Java Collections API </a> </p> </li> <li> <p> <a href="UsingStoredCollections.html"> Using Stored Collections </a> </p> </li> <li> <p> <a href="SerializedObjectStorage.html"> Serialized Object Storage </a> </p> </li> </ul> </div> <div class="sect1" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"><a id="UsingDataBindings"></a> Using Data Bindings </h2> </div> </div> <div></div> </div> <p> Data bindings determine how keys and values are represented as stored data (byte arrays) in the database, and how stored data is converted to and from Java objects. </p> <p> The selection of data bindings is, in general, independent of the selection of <span> access methods and </span> collection views. In other words, any binding can be used with any <span> access method or </span> collection. <span> One exception to this rule is described under <a href="collectionOverview.html#RecordNumberBindings">Record Number Bindings</a> below. </span> </p> <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> <h3 class="title">Note</h3> <p> In this document, bindings are described in the context of their use for stored data in a database. However, bindings may also be used independently of a database to operate on an arbitrary byte array. This allows using bindings when data is to be written to a file or sent over a network, for example. </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="SelectingBindingFormats"></a> Selecting Binding Formats </h3> </div> </div> <div></div> </div> <p> For the key and value of each stored collection, you may select one of the following types of bindings. </p> <div class="informaltable"> <table border="1" width="80%"> <colgroup> <col /> <col /> <col /> </colgroup> <thead> <tr> <th>Binding Format</th> <th>Ordered</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td> <a href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a> </td> <td>No</td> <td> The data is stored using a compact form of Java serialization, where the class descriptions are stored separately in a catalog database. Arbitrary Java objects are supported. </td> </tr> <tr> <td> <a href="../../java/com/sleepycat/bind/tuple/TupleBinding.html" target="_top">TupleBinding</a> </td> <td>Yes</td> <td> The data is stored using a series of fixed length primitive values or zero terminated character arrays (strings). Class/type evolution is not supported. </td> </tr> <tr> <td> <a href="../../java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a> </td> <td>Yes</td> <td> The data is a 32-bit integer stored in a platform-dependent format. </td> </tr> <tr> <td>Custom binding format</td> <td>User-defined</td> <td> The data storage format and ordering is determined by the custom binding implementation. </td> </tr> </tbody> </table> </div> <p> As shown in the table above, the tuple format supports built-in ordering (without specifying a custom comparator), while the serial format does not. This means that when a specific key order is needed, tuples should be used instead of serial data. Alternatively, a custom Btree comparator should be specified using <tt class="methodname">DatabaseConfig.setBtreeComparator()</tt>. Note that a custom Btree comparator will usually execute more slowly than the default byte-by-byte comparison. This makes using tuples an attractive option, since they provide ordering along with optimal performance. </p> <p> The tuple binding uses less space and executes faster than the serial binding. But once a tuple is written to a database, the order of fields in the tuple may not be changed and fields may not be deleted. The only type evolution allowed is the addition of fields at the end of the tuple, and this must be explicitly supported by the custom binding implementation. </p> <p> The serial binding supports the full generality of Java serialization including type evolution. But serialized data can only be accessed by Java applications, its size is larger, and its bindings are slower to execute. </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="RecordNumberBindings"></a>Record Number Bindings</h3> </div> </div> <div></div> </div> <p> Any use of an access method with record number keys, and therefore any use of a stored list view, requires using <a href="../../java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a> as the key binding. Since Berkeley DB stores record number keys using a platform-dependent byte order, <a href="../../java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a> is needed to store record numbers properly. See <span class="html"><a href="../../ref/am_conf/logrec.html" target="_top">logical record numbers</a> in</span> the <i class="citetitle">Berkeley DB Programmer's Reference Guide</i> for more information on storing DB record numbers. </p> <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> <h3 class="title">Note</h3> <p> You may not use <a href="../../java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a> except with record number keys, as determined by the access method. Using <a href="../../java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a> in other cases will create a database that is not portable between platforms. When constructing the stored collection, the DB Java Collections API will throw an <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/IllegalArgumentException.html" target="_top">IllegalArgumentException</a> in such cases. </p> </div> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="SelectingDataBindings"></a> Selecting Data Bindings </h3> </div> </div> <div></div> </div> <p> There are two types of binding interfaces. Simple entry bindings implement the <a href="../../java/com/sleepycat/bind/EntryBinding.html" target="_top">EntryBinding</a> interface and can be used for key or value objects. Entity bindings implement the <a href="../../java/com/sleepycat/bind/EntityBinding.html" target="_top">EntityBinding</a> interface and are used for combined key and value objects called entities. </p> <p> Simple entry bindings map between the key or value data stored by Berkeley DB and a key or value object. This is a simple one-to-one mapping. </p> <p> Simple entry bindings are easy to implement and in some cases require no coding. For example, a <a href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a> can be used for keys or values without writing any additional code. A tuple binding for a single-item tuple can also be used without writing any code; see the <a href="../../java/com/sleepycat/bind/tuple/TupleBinding.html#getPrimitiveBinding(java.lang.Class)" target="_top">TupleBinding.getPrimitiveBinding</a> method. </p> <p> Entity bindings must divide an entity object into its key and value data, and then combine the key and value data to re-create the entity object. This is a two-to-one mapping. </p> <p> Entity bindings are useful when a stored application object naturally has its primary key as a property, which is very common. For example, an Employee object would naturally have an EmployeeNumber property (its primary key) and an entity binding would then be needed. Of course, entity bindings are more complex to implement, especially if their key and data formats are different. </p> <p> Note that even when an entity binding is used a key binding is also usually needed. For example, a key binding is used to create key objects that are passed to the <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#get" target="_top">Map.get()</a> method. A key object is passed to this method even though it may return an entity that also contains the key. </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="ImplementingBindings"></a> Implementing Bindings </h3> </div> </div> <div></div> </div> <p> There are two ways to implement bindings. The first way is to create a binding class that implements one of the two binding interfaces, <a href="../../java/com/sleepycat/bind/EntryBinding.html" target="_top">EntryBinding</a> or <a href="../../java/com/sleepycat/bind/EntityBinding.html" target="_top">EntityBinding</a>. For tuple bindings and serial bindings there are a number of abstract classes that make this easier. For example, you can extend <a href="../../java/com/sleepycat/bind/tuple/TupleBinding.html" target="_top">TupleBinding</a> to implement a simple binding for a tuple key or value. Abstract classes are also provided for entity bindings and are named after the format names of the key and value. For example, you can extend <a href="../../java/com/sleepycat/bind/serial/TupleSerialBinding.html" target="_top">TupleSerialBinding</a> to implement an entity binding with a tuple key and serial value. </p> <p> Another way to implement bindings is with marshalling interfaces. These are interfaces which perform the binding operations and are implemented by the key, value or entity classes themselves. With marshalling you use a binding which calls the marshalling interface and you implement the marshalling interface for each key, value or entity class. For example, you can use <a href="../../java/com/sleepycat/bind/tuple/TupleMarshalledBinding.html" target="_top">TupleMarshalledBinding</a> along with key or value classes that implement the <a href="../../java/com/sleepycat/bind/tuple/MarshalledTupleEntry.html" target="_top">MarshalledTupleEntry</a> interface. </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="UsingBindings"></a> Using Bindings </h3> </div> </div> <div></div> </div> <p> Bindings are specified whenever a stored collection is created. A key binding must be specified for map, key set and entry set views. A value binding or entity binding must be specified for map, value set and entry set views. </p> <p> Any number of bindings may be created for the same stored data. This allows multiple views over the same data. For example, a tuple might be bound to an array of values or to a class with properties for each object. </p> <p> It is important to be careful of bindings that only use a subset of the stored data. This can be useful to simplify a view or to hide information that should not be accessible. However, if you write records using these bindings you may create stored data that is invalid from the application's point of view. It is up to the application to guard against this by creating a read-only collection when such bindings are used. </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="SecondaryKeyCreators"></a> Secondary Key Creators </h3> </div> </div> <div></div> </div> <p> Secondary Key Creators are needed whenever database indices are used. For each secondary index <span> (<a href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>) </span> a key creator is used to derive index key data from key/value data. Key creators are objects whose classes implement the <a href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a> interface. </p> <p> Like bindings, key creators may be implemented using a separate key creator class or using a marshalling interface. Abstract key creator classes and marshalling interfaces are provided in the com.sleepycat.bind.tuple and com.sleepycat.bind.serial packages. </p> <p> Unlike bindings, key creators fundamentally operate on key and value data, not necessarily on the objects derived from the data by bindings. In this sense key creators are a part of a database definition, and may be independent of the various bindings that may be used to view data in a database. However, key creators are not prohibited from using higher level objects produced by bindings, and doing so may be convenient for some applications. For example, marshalling interfaces, which are defined for objects produced by bindings, are a convenient way to define key creators. </p> </div> </div> </div> <div class="navfooter"> <hr /> <table width="100%" summary="Navigation footer"> <tr> <td width="40%" align="left"><a accesskey="p" href="Summary.html">Prev</a> </td> <td width="20%" align="center"> <a accesskey="u" href="index.html">Up</a> </td> <td width="40%" align="right"> <a accesskey="n" href="UsingCollectionsAPI.html">Next</a></td> </tr> <tr> <td width="40%" align="left" valign="top">Chapter 7. Summary </td> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> <td width="40%" align="right" valign="top"> Using the DB Java Collections API </td> </tr> </table> </div> </body> </html>
Back to File Manager