ag/cpython-source-deps
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Import BSDDB 4.7.25 (as of svn r89086)

Browse Source
This commit is contained in:
Zachary Ware
2017-09-04 13:40:25 -05:00
parent 4b29e0458f
commit 8f590873d0
4781 changed files with 2241032 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

473
docs/collections/tutorial/collectionOverview.html Normal file
View File

@@ -0,0 +1,473 @@
<?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. &#10;&#9;&#9;Summary&#10;&#9;" />
<link rel="next" href="UsingCollectionsAPI.html" title="&#10; Using the DB Java Collections API&#10; " />
</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>