mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-17 01:26:25 +00:00
283 lines
11 KiB
HTML
283 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>
|