mirror of
https://github.com/berkeleydb/je.git
synced 2024-11-15 01:46:24 +00:00
451 lines
18 KiB
HTML
451 lines
18 KiB
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.73.2" />
|
||
<link rel="start" href="index.html" title="Berkeley DB Java Edition Collections Tutorial" />
|
||
<link rel="up" href="index.html" title="Berkeley DB Java Edition Collections Tutorial" />
|
||
<link rel="prev" href="Summary.html" title="Chapter 7. Summary" />
|
||
<link rel="next" href="UsingCollectionsAPI.html" title="Using the JE JE Collections API" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 12.2.7.5</p>
|
||
</div>
|
||
<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>
|
||
<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 class="xref" href="collectionOverview.html#UsingDataBindings" title="Using Data Bindings">
|
||
Using Data Bindings
|
||
</a>
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<a class="xref" href="UsingCollectionsAPI.html" title="Using the JE JE Collections API">
|
||
Using the JE JE Collections API
|
||
</a>
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<a class="xref" href="UsingStoredCollections.html" title="Using Stored Collections">
|
||
Using Stored Collections
|
||
</a>
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<a class="xref" href="SerializedObjectStorage.html" title="Serialized Object Storage">
|
||
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 class="toc">
|
||
<dl>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="collectionOverview.html#SelectingBindingFormats">
|
||
Selecting Binding Formats
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="collectionOverview.html#SelectingDataBindings">
|
||
Selecting Data Bindings
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="collectionOverview.html#ImplementingBindings">
|
||
Implementing Bindings
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="collectionOverview.html#UsingBindings">
|
||
Using Bindings
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="collectionOverview.html#SecondaryKeyCreators">
|
||
Secondary Key Creators
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
</dl>
|
||
</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
|
||
|
||
collection views. In other
|
||
words, any binding can be used with any
|
||
|
||
collection.
|
||
|
||
</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>
|
||
<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 class="ulink" 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 class="ulink" 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>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
|
||
<code class="methodname">DatabaseConfig.setBtreeComparator()</code>. 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="SelectingDataBindings"></a>
|
||
Selecting Data Bindings
|
||
</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
There are two types of binding interfaces. Simple entry bindings
|
||
implement the
|
||
<a class="ulink" 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 class="ulink" 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 class="ulink" 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 class="ulink" 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 class="ulink" href="http://download.oracle.com/javase/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>
|
||
<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 class="ulink" href="../../java/com/sleepycat/bind/EntryBinding.html" target="_top">EntryBinding</a>
|
||
|
||
or
|
||
<a class="ulink" 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 class="ulink" 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 class="ulink" 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 class="ulink" href="../../java/com/sleepycat/bind/tuple/TupleMarshalledBinding.html" target="_top">TupleMarshalledBinding</a>
|
||
|
||
along with key or value classes that implement the
|
||
<a class="ulink" 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>
|
||
<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>
|
||
<p>
|
||
Secondary Key Creators are needed whenever database indices are
|
||
used. For each secondary index
|
||
<span>
|
||
(<a class="ulink" href="../../java/com/sleepycat/je/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 class="ulink" href="../../java/com/sleepycat/je/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"> </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 JE JE Collections API
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|