mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-17 09:36:24 +00:00
284 lines
11 KiB
HTML
284 lines
11 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>Creating Bindings and Collections</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 Collections Tutorial" />
|
|||
|
|
<link rel="up" href="BasicProgram.html" title="Chapter 2. The Basic Program" />
|
|||
|
|
<link rel="prev" href="opendatabases.html" title="Opening and Closing Databases" />
|
|||
|
|
<link rel="next" href="implementingmain.html" title="Implementing the Main Program" />
|
|||
|
|
</head>
|
|||
|
|
<body>
|
|||
|
|
<div xmlns="" class="navheader">
|
|||
|
|
<div class="libver">
|
|||
|
|
<p>Library Version 11.2.5.2</p>
|
|||
|
|
</div>
|
|||
|
|
<table width="100%" summary="Navigation header">
|
|||
|
|
<tr>
|
|||
|
|
<th colspan="3" align="center">
|
|||
|
|
Creating Bindings and Collections
|
|||
|
|
</th>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td width="20%" align="left"><a accesskey="p" href="opendatabases.html">Prev</a> </td>
|
|||
|
|
<th width="60%" align="center">Chapter 2.
|
|||
|
|
The Basic Program
|
|||
|
|
</th>
|
|||
|
|
<td width="20%" align="right"> <a accesskey="n" href="implementingmain.html">Next</a></td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
<hr />
|
|||
|
|
</div>
|
|||
|
|
<div class="sect1" lang="en" xml:lang="en">
|
|||
|
|
<div class="titlepage">
|
|||
|
|
<div>
|
|||
|
|
<div>
|
|||
|
|
<h2 class="title" style="clear: both"><a id="createbindingscollections"></a>
|
|||
|
|
Creating Bindings and Collections
|
|||
|
|
</h2>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<p>
|
|||
|
|
<span class="emphasis"><em>Bindings</em></span> translate between stored records and Java objects.
|
|||
|
|
In this example, Java serialization bindings are used. Serial
|
|||
|
|
bindings are the simplest type of bindings because no mapping of
|
|||
|
|
fields or type conversion is needed. Tuple bindings — which are
|
|||
|
|
more difficult to create than serial bindings but have some
|
|||
|
|
advantages — will be introduced later in the Tuple example
|
|||
|
|
program.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Standard Java <span class="emphasis"><em>collections</em></span> are used to access records in a
|
|||
|
|
database. Stored collections use bindings transparently to convert
|
|||
|
|
the records to objects when they are retrieved from the collection,
|
|||
|
|
and to convert the objects to records when they are stored in the
|
|||
|
|
collection.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
An important characteristic of stored collections is that they
|
|||
|
|
do <span class="emphasis"><em>not</em></span> perform object caching. Every time an object is
|
|||
|
|
accessed via a collection it will be added to or retrieved from the
|
|||
|
|
database, and the bindings will be invoked to convert the data.
|
|||
|
|
Objects are therefore always passed and returned by value, not by
|
|||
|
|
reference. Because Berkeley DB is an embedded database, efficient
|
|||
|
|
caching of stored raw record data is performed by the database library.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The <code class="classname">SampleViews</code> class is used to create the bindings and
|
|||
|
|
collections. This class is separate from the <code class="classname">SampleDatabase</code>
|
|||
|
|
class to illustrate the idea that a single set of stored data can
|
|||
|
|
be accessed via multiple bindings and collections, or <span class="emphasis"><em>views</em></span>.
|
|||
|
|
The skeleton for the <code class="classname">SampleViews</code> class follows.
|
|||
|
|
</p>
|
|||
|
|
<a id="cb_sampleviews"></a>
|
|||
|
|
<pre class="programlisting"><strong class="userinput"><code>import com.sleepycat.bind.EntryBinding;
|
|||
|
|
import com.sleepycat.bind.serial.ClassCatalog;
|
|||
|
|
import com.sleepycat.bind.serial.SerialBinding;
|
|||
|
|
import com.sleepycat.collections.StoredEntrySet;
|
|||
|
|
import com.sleepycat.collections.StoredMap;
|
|||
|
|
...
|
|||
|
|
|
|||
|
|
public class SampleViews
|
|||
|
|
{
|
|||
|
|
private StoredMap partMap;
|
|||
|
|
private StoredMap supplierMap;
|
|||
|
|
private StoredMap shipmentMap;
|
|||
|
|
|
|||
|
|
...
|
|||
|
|
public SampleViews(SampleDatabase db)
|
|||
|
|
{
|
|||
|
|
}
|
|||
|
|
}</code></strong> </pre>
|
|||
|
|
<p>
|
|||
|
|
A
|
|||
|
|
<a class="ulink" href="../../java/com/sleepycat/collections/StoredMap.html" target="_top">StoredMap</a>
|
|||
|
|
|
|||
|
|
field is used for each database. The StoredMap class implements the
|
|||
|
|
standard Java
|
|||
|
|
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.html" target="_top">Map</a>
|
|||
|
|
|
|||
|
|
interface, which has methods for obtaining a
|
|||
|
|
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Set.html" target="_top">Set</a>
|
|||
|
|
|
|||
|
|
of keys, a
|
|||
|
|
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Collection.html" target="_top">Collection</a>
|
|||
|
|
|
|||
|
|
of values, or a
|
|||
|
|
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Set.html" target="_top">Set</a>
|
|||
|
|
|
|||
|
|
of
|
|||
|
|
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.Entry.html" target="_top">Map.Entry</a>
|
|||
|
|
|
|||
|
|
key/value pairs. Because databases contain key/value pairs, any
|
|||
|
|
Berkeley DB database may be represented as a Java map.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The following statements create the key and data bindings using
|
|||
|
|
the
|
|||
|
|
<a class="ulink" href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a>
|
|||
|
|
|
|||
|
|
class.
|
|||
|
|
</p>
|
|||
|
|
<a id="cb_sampleviews1"></a>
|
|||
|
|
<pre class="programlisting"> public SampleViews(SampleDatabase db)
|
|||
|
|
{
|
|||
|
|
<strong class="userinput"><code> ClassCatalog catalog = db.getClassCatalog();
|
|||
|
|
EntryBinding partKeyBinding =
|
|||
|
|
new SerialBinding(catalog, PartKey.class);
|
|||
|
|
EntryBinding partValueBinding =
|
|||
|
|
new SerialBinding(catalog, PartData.class);
|
|||
|
|
EntryBinding supplierKeyBinding =
|
|||
|
|
new SerialBinding(catalog, SupplierKey.class);
|
|||
|
|
EntryBinding supplierValueBinding =
|
|||
|
|
new SerialBinding(catalog, SupplierData.class);
|
|||
|
|
EntryBinding shipmentKeyBinding =
|
|||
|
|
new SerialBinding(catalog, ShipmentKey.class);
|
|||
|
|
EntryBinding shipmentValueBinding =
|
|||
|
|
new SerialBinding(catalog, ShipmentData.class);</code></strong>
|
|||
|
|
...
|
|||
|
|
} </pre>
|
|||
|
|
<p>
|
|||
|
|
The first parameter of the
|
|||
|
|
<a class="ulink" href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a>
|
|||
|
|
|
|||
|
|
constructor is the class catalog, and is used to store the class
|
|||
|
|
descriptions of the serialized objects.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The second parameter is the base class for the serialized
|
|||
|
|
objects and is used for type checking of the stored objects. If
|
|||
|
|
<code class="literal">null</code> or <code class="literal">Object.class</code> is specified, then any Java
|
|||
|
|
class is allowed. Otherwise, all objects stored in that format must
|
|||
|
|
be instances of the specified class or derived from the specified
|
|||
|
|
class. In the example, specific classes are used to enable strong
|
|||
|
|
type checking.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The following statements create standard Java maps using the
|
|||
|
|
<a class="ulink" href="../../java/com/sleepycat/collections/StoredMap.html" target="_top">StoredMap</a>
|
|||
|
|
|
|||
|
|
class.
|
|||
|
|
</p>
|
|||
|
|
<a id="cb_sampleviews2"></a>
|
|||
|
|
<pre class="programlisting"> public SampleViews(SampleDatabase db)
|
|||
|
|
{
|
|||
|
|
...
|
|||
|
|
<strong class="userinput"><code> partMap =
|
|||
|
|
new StoredMap(db.getPartDatabase(),
|
|||
|
|
partKeyBinding, partValueBinding, true);
|
|||
|
|
supplierMap =
|
|||
|
|
new StoredMap(db.getSupplierDatabase(),
|
|||
|
|
supplierKeyBinding, supplierValueBinding, true);
|
|||
|
|
shipmentMap =
|
|||
|
|
new StoredMap(db.getShipmentDatabase(),
|
|||
|
|
shipmentKeyBinding, shipmentValueBinding, true);</code></strong>
|
|||
|
|
...
|
|||
|
|
} </pre>
|
|||
|
|
<p>
|
|||
|
|
The first parameter of the
|
|||
|
|
<a class="ulink" href="../../java/com/sleepycat/collections/StoredMap.html" target="_top">StoredMap</a>
|
|||
|
|
|
|||
|
|
constructor is the database. In a StoredMap, the database keys (the primary
|
|||
|
|
keys) are used as the map keys. The Index
|
|||
|
|
example shows how to use secondary index keys as map keys.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The second and third parameters are the key and value bindings
|
|||
|
|
to use when storing and retrieving objects via the map.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The fourth and last parameter specifies whether changes will be
|
|||
|
|
allowed via the collection. If false is passed, the collection will
|
|||
|
|
be read-only.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
The following getter methods return the stored maps for use by
|
|||
|
|
other classes in the example program. Convenience methods for
|
|||
|
|
returning entry sets are also included.
|
|||
|
|
</p>
|
|||
|
|
<a id="cb_sampleviewsgetters"></a>
|
|||
|
|
<pre class="programlisting">public class SampleViews
|
|||
|
|
{
|
|||
|
|
...
|
|||
|
|
<strong class="userinput"><code> public final StoredMap getPartMap()
|
|||
|
|
{
|
|||
|
|
return partMap;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
public final StoredMap getSupplierMap()
|
|||
|
|
{
|
|||
|
|
return supplierMap;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
public final StoredMap getShipmentMap()
|
|||
|
|
{
|
|||
|
|
return shipmentMap;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
public final StoredEntrySet getPartEntrySet()
|
|||
|
|
{
|
|||
|
|
return (StoredEntrySet) partMap.entrySet();
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
public final StoredEntrySet getSupplierEntrySet()
|
|||
|
|
{
|
|||
|
|
return (StoredEntrySet) supplierMap.entrySet();
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
public final StoredEntrySet getShipmentEntrySet()
|
|||
|
|
{
|
|||
|
|
return (StoredEntrySet) shipmentMap.entrySet();
|
|||
|
|
}</code></strong>
|
|||
|
|
...
|
|||
|
|
} </pre>
|
|||
|
|
<p>
|
|||
|
|
Note that StoredMap and StoredEntrySet are returned rather than
|
|||
|
|
just returning Map and Set. Since StoredMap implements the Map
|
|||
|
|
interface and StoredEntrySet implements the Set interface, you may
|
|||
|
|
ask why Map and Set were not returned directly.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
<code class="classname">StoredMap</code>, <code class="classname">StoredEntrySet</code>,
|
|||
|
|
and other stored collection classes
|
|||
|
|
have a small number of extra methods beyond those in the Java
|
|||
|
|
collection interfaces. The stored collection types are therefore
|
|||
|
|
returned to avoid casting when using the extended methods.
|
|||
|
|
Normally, however, only a Map or Set is needed, and may be used as
|
|||
|
|
follows.
|
|||
|
|
</p>
|
|||
|
|
<a id="cb_sampleviews_usage"></a>
|
|||
|
|
<pre class="programlisting"><strong class="userinput"><code> SampleDatabase sd = new SampleDatabase(new String("/home"));
|
|||
|
|
SampleViews views = new SampleViews(sd);
|
|||
|
|
Map partMap = views.getPartMap();
|
|||
|
|
Set supplierEntries = views.getSupplierEntrySet();</code></strong> </pre>
|
|||
|
|
</div>
|
|||
|
|
<div class="navfooter">
|
|||
|
|
<hr />
|
|||
|
|
<table width="100%" summary="Navigation footer">
|
|||
|
|
<tr>
|
|||
|
|
<td width="40%" align="left"><a accesskey="p" href="opendatabases.html">Prev</a> </td>
|
|||
|
|
<td width="20%" align="center">
|
|||
|
|
<a accesskey="u" href="BasicProgram.html">Up</a>
|
|||
|
|
</td>
|
|||
|
|
<td width="40%" align="right"> <a accesskey="n" href="implementingmain.html">Next</a></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td width="40%" align="left" valign="top">
|
|||
|
|
Opening and Closing Databases
|
|||
|
|
</td>
|
|||
|
|
<td width="20%" align="center">
|
|||
|
|
<a accesskey="h" href="index.html">Home</a>
|
|||
|
|
</td>
|
|||
|
|
<td width="40%" align="right" valign="top">
|
|||
|
|
Implementing the Main Program
|
|||
|
|
</td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
</div>
|
|||
|
|
</body>
|
|||
|
|
</html>
|