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

457
docs/collections/tutorial/BasicProgram.html Normal file
View File

@@ -0,0 +1,457 @@
<?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>Chapter 2. 
The Basic Program
</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="tutorialintroduction.html" title="Tutorial Introduction" />
<link rel="next" href="opendbenvironment.html" title="&#10;&#9;&#9;Opening and Closing the Database Environment&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 2. 
The Basic Program
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="tutorialintroduction.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="opendbenvironment.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="BasicProgram"></a>Chapter 2. 
The Basic Program
</h2>
</div>
</div>
<div></div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="sect1">
<a href="BasicProgram.html#keyandvalueclasses">
Defining Serialized Key and Value Classes
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="opendbenvironment.html">
Opening and Closing the Database Environment
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="openclasscatalog.html">
Opening and Closing the Class Catalog
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="opendatabases.html">
Opening and Closing Databases
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="createbindingscollections.html">
Creating Bindings and Collections
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="implementingmain.html">
Implementing the Main Program
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="usingtransactions.html">
Using Transactions
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="addingdatabaseitems.html">
Adding Database Items
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="retrievingdatabaseitems.html">
Retrieving Database Items
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="handlingexceptions.html">
Handling Exceptions
</a>
</span>
</dt>
</dl>
</div>
<p>
The Basic example is a minimal implementation of the shipment
program. It writes and reads the part, supplier and shipment
databases.
</p>
<p>
The complete source of the final version of the example program
is included in the Berkeley DB distribution.
</p>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="keyandvalueclasses"></a>
Defining Serialized Key and Value Classes
</h2>
</div>
</div>
<div></div>
</div>
<p>
The key and value classes for each type of shipment record —
Parts, Suppliers and Shipments — are defined as ordinary Java
classes. In this example the serialized form of the key and value
objects is stored directly in the database. Therefore these classes
must implement the standard Java java.io.Serializable interface. A
compact form of Java serialization is used that does not duplicate
the class description in each record. Instead the class
descriptions are stored in the class catalog store, which is
described in the next section. But in all other respects, standard
Java serialization is used.
</p>
<p>
An important point is that instances of these classes are passed
and returned by value, not by reference, when they are stored and
retrieved from the database. This means that changing a key or
value object does not automatically change the database. The object
must be explicitly stored in the database after changing it. To
emphasize this point the key and value classes defined here have no
field setter methods. Setter methods can be defined, but it is
important to remember that calling a setter method will not cause
the change to be stored in the database. How to store and retrieve
objects in the database will be described later.
</p>
<p>
Each key and value class contains a toString method that is used
to output the contents of the object in the example program. This
is meant for illustration only and is not required for database
objects in general.
</p>
<p>
Notice that the key and value classes defined below do not
contain any references to <tt class="literal">com.sleepycat</tt> packages. An
important characteristic of these classes is that they are
independent of the database. Therefore, they may be easily used in
other contexts and may be defined in a way that is compatible with
other tools and libraries.
</p>
<p>
The <tt class="classname">PartKey</tt> class contains only the Part's Number field.
</p>
<p>
Note that <tt class="classname">PartKey</tt> (as well as <tt class="classname">SupplierKey</tt> below)
contain only a single String field. Instead of defining a specific
class for each type of key, the String class by itself could have
been used. Specific key classes were used to illustrate strong
typing and for consistency in the example. The use of a plain
String as an index key is illustrated in the next example program.
It is up to the developer to use either primitive Java classes such
as String and Integer, or strongly typed classes. When
there is the possibility that fields will be added later to a key
or value, a specific class should be used.
</p>
<a id="cb_partkey"></a>
<pre class="programlisting"><b class="userinput"><tt>import java.io.Serializable;
public class PartKey implements Serializable
{
private String number;
public PartKey(String number) {
this.number = number;
}
public final String getNumber() {
return number;
}
public String toString() {
return "[PartKey: number=" + number + ']';
}
}</tt></b> </pre>
<p>
The <tt class="classname">PartData</tt> class contains the Part's Name, Color,
Weight and City fields.
</p>
<a id="cb_partdata"></a>
<pre class="programlisting"><b class="userinput"><tt>import java.io.Serializable;
public class PartData implements Serializable
{
private String name;
private String color;
private Weight weight;
private String city;
public PartData(String name, String color, Weight weight, String city)
{
this.name = name;
this.color = color;
this.weight = weight;
this.city = city;
}
public final String getName()
{
return name;
}
public final String getColor()
{
return color;
}
public final Weight getWeight()
{
return weight;
}
public final String getCity()
{
return city;
}
public String toString()
{
return "[PartData: name=" + name +
" color=" + color +
" weight=" + weight +
" city=" + city + ']';
}
}</tt></b> </pre>
<p>
The <tt class="classname">Weight</tt> class is also defined here, and is used as the
type of the Part's Weight field. Just as in standard Java
serialization, nothing special is needed to store nested objects as
long as they are all Serializable.
</p>
<a id="cb_weight"></a>
<pre class="programlisting"><b class="userinput"><tt>import java.io.Serializable;
public class Weight implements Serializable
{
public final static String GRAMS = "grams";
public final static String OUNCES = "ounces";
private double amount;
private String units;
public Weight(double amount, String units)
{
this.amount = amount;
this.units = units;
}
public final double getAmount()
{
return amount;
}
public final String getUnits()
{
return units;
}
public String toString()
{
return "[" + amount + ' ' + units + ']';
}
}</tt></b> </pre>
<p>
The <tt class="classname">SupplierKey</tt> class contains the Supplier's Number
field.
</p>
<a id="cb_supplierkey"></a>
<pre class="programlisting"><b class="userinput"><tt>import java.io.Serializable;
public class SupplierKey implements Serializable
{
private String number;
public SupplierKey(String number)
{
this.number = number;
}
public final String getNumber()
{
return number;
}
public String toString()
{
return "[SupplierKey: number=" + number + ']';
}
}</tt></b> </pre>
<p>
The <tt class="classname">SupplierData</tt> class contains the Supplier's Name,
Status and City fields.
</p>
<a id="cb_supplierdata"></a>
<pre class="programlisting"><b class="userinput"><tt>import java.io.Serializable;
public class SupplierData implements Serializable
{
private String name;
private int status;
private String city;
public SupplierData(String name, int status, String city)
{
this.name = name;
this.status = status;
this.city = city;
}
public final String getName()
{
return name;
}
public final int getStatus()
{
return status;
}
public final String getCity()
{
return city;
}
public String toString()
{
return "[SupplierData: name=" + name +
" status=" + status +
" city=" + city + ']';
}
}</tt></b>
</pre>
<p>
The <tt class="classname">ShipmentKey</tt> class contains the keys of both the Part
and Supplier.
</p>
<a id="cb_shipmentkey"></a>
<pre class="programlisting"><b class="userinput"><tt>import java.io.Serializable;
public class ShipmentKey implements Serializable
{
private String partNumber;
private String supplierNumber;
public ShipmentKey(String partNumber, String supplierNumber)
{
this.partNumber = partNumber;
this.supplierNumber = supplierNumber;
}
public final String getPartNumber()
{
return partNumber;
}
public final String getSupplierNumber()
{
return supplierNumber;
}
public String toString()
{
return "[ShipmentKey: supplier=" + supplierNumber +
" part=" + partNumber + ']';
}
}</tt></b> </pre>
<p>
The <tt class="classname">ShipmentData</tt> class contains only the Shipment's
Quantity field. Like <tt class="classname">PartKey</tt> and <tt class="classname">SupplierKey</tt>,
<tt class="classname">ShipmentData</tt> contains only a single primitive field.
Therefore the Integer class could have been used instead of
defining a specific value class.
</p>
<a id="cb_shipmentdata"></a>
<pre class="programlisting"><b class="userinput"><tt>import java.io.Serializable;
public class ShipmentData implements Serializable
{
private int quantity;
public ShipmentData(int quantity)
{
this.quantity = quantity;
}
public final int getQuantity()
{
return quantity;
}
public String toString()
{
return "[ShipmentData: quantity=" + quantity + ']';
}
}</tt></b> </pre>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="tutorialintroduction.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="opendbenvironment.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Tutorial Introduction </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Opening and Closing the Database Environment
</td>
</tr>
</table>
</div>
</body>
</html>

BIN
docs/collections/tutorial/BerkeleyDB-Java-Collections.pdf Normal file
View File

Binary file not shown.

359
docs/collections/tutorial/Entity.html Normal file
View File

@@ -0,0 +1,359 @@
<?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>Chapter 4. 
Using Entity Classes
</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="retrievingbyindexkey.html" title="&#10;&#9;&#9;Retrieving Items by Index Key&#10;&#9;" />
<link rel="next" href="creatingentitybindings.html" title="&#10;&#9;&#9;Creating Entity Bindings&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 4. 
Using Entity Classes
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="retrievingbyindexkey.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="creatingentitybindings.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="Entity"></a>Chapter 4. 
Using Entity Classes
</h2>
</div>
</div>
<div></div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="sect1">
<a href="Entity.html#definingentityclasses">
Defining Entity Classes
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="creatingentitybindings.html">
Creating Entity Bindings
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="collectionswithentities.html">
Creating Collections with Entity Bindings
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="entitieswithcollections.html">
Using Entities with Collections
</a>
</span>
</dt>
</dl>
</div>
<p>
In the prior examples, the keys and values of each store were
represented using separate classes. For example, a <tt class="classname">PartKey</tt>
and a <tt class="classname">PartData</tt> class were used. Many times it is desirable
to have a single class representing both the key and the value, for
example, a <tt class="classname">Part</tt> class.
</p>
<p>
Such a combined key and value class is called an <span class="emphasis"><em>entity
class</em></span> and is used along with an <span class="emphasis"><em>entity binding</em></span>. Entity
bindings combine a key and a value into an entity when reading a
record from a collection, and split an entity into a key and a
value when writing a record to a collection. Entity bindings are
used in place of value bindings, and entity objects are used with
collections in place of value objects.
</p>
<p>
Some reasons for using entities are:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
When the key is a property of an entity object representing the
record as a whole, the object's identity and concept are often
clearer than with key and value objects that are disjoint.
</p>
</li>
<li>
<p>
A single entity object per record is often more convenient to
use than two objects.
</p>
</li>
</ul>
</div>
<p>
Of course, instead of using an entity binding, you could simply
create the entity yourself after reading the key and value from a
collection, and split the entity into a key and value yourself
before writing it to a collection. But this would detract from the
convenience of the using the Java collections API. It is convenient
to obtain a <tt class="classname">Part</tt> object directly from
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#get" target="_top">Map.get</a>
and to add a <tt class="classname">Part</tt> object using
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html#add" target="_top">Set.add</a>.
Collections having entity bindings can be used naturally without
combining and splitting objects each time a collection method is
called; however, an entity binding class must be defined by the
application.
</p>
<p>
In addition to showing how to use entity bindings, this example
illustrates a key feature of all bindings: Bindings are independent
of database storage parameters and formats. Compare this example to
the prior Index example and you'll see that the <tt class="classname">Sample</tt> and
<tt class="classname">SampleViews</tt> classes have been changed to use entity
bindings, but the <tt class="classname">SampleDatabase</tt> class was not changed at
all. In fact, the Entity program and the Index program can be used
interchangeably to access the same physical database files. This
demonstrates that bindings are only a "view" onto the physical
stored data.
</p>
<p>
<tt class="classname">Warning:</tt> When using multiple bindings for the same
database, it is the application's responsibility to ensure that the
same format is used for all bindings. For example, a serial binding
and a tuple binding cannot be used to access the same records.
</p>
<p>
The complete source of the final version of the example program
is included in the Berkeley DB distribution.
</p>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="definingentityclasses"></a>
Defining Entity Classes
</h2>
</div>
</div>
<div></div>
</div>
<p>
As described in the prior section, <span class="emphasis"><em>entity classes</em></span> are
combined key/value classes that are managed by entity bindings. In
this example the <tt class="classname">Part</tt>, <tt class="classname">Supplier</tt> and <tt class="classname">Shipment</tt>
classes are entity classes. These classes contain fields that are a
union of the fields of the key and value classes that were defined
earlier for each store.
</p>
<p>
In general, entity classes may be defined in any way desired by
the application. The entity binding, which is also defined by the
application, is responsible for mapping between key/value objects
and entity objects.
</p>
<p>
The <tt class="classname">Part</tt>, <tt class="classname">Supplier</tt> and <tt class="classname">Shipment</tt>
entity classes are
defined below.
</p>
<p>
An important difference between the entity classes defined here
and the key and value classes defined earlier is that the entity
classes are not serializable (do not implement the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/io/Serializable.html" target="_top">Serializable</a>
interface). This is because the entity classes are not directly
stored. The entity binding decomposes an entity object into key and
value objects, and only the key and value objects are serialized
for storage.
</p>
<p>
One advantage of using entities can already be seen in the
<tt class="methodname">toString()</tt> method of the classes below. These return debugging
output for the combined key and value, and will be used later to
create a listing of the database that is more readable than in the
prior examples.
</p>
<a id="entity_part"></a>
<pre class="programlisting"><b class="userinput"><tt>public class Part
{
private String number;
private String name;
private String color;
private Weight weight;
private String city;
public Part(String number, String name, String color, Weight weight,
String city)
{
this.number = number;
this.name = name;
this.color = color;
this.weight = weight;
this.city = city;
}
public final String getNumber()
{
return number;
}
public final String getName()
{
return name;
}
public final String getColor()
{
return color;
}
public final Weight getWeight()
{
return weight;
}
public final String getCity()
{
return city;
}
public String toString()
{
return "Part: number=" + number +
" name=" + name +
" color=" + color +
" weight=" + weight +
" city=" + city + '.';
}
}</tt></b> </pre>
<a id="entity_supplier"></a>
<pre class="programlisting"><b class="userinput"><tt>public class Supplier
{
private String number;
private String name;
private int status;
private String city;
public Supplier(String number, String name, int status, String city)
{
this.number = number;
this.name = name;
this.status = status;
this.city = city;
}
public final String getNumber()
{
return number;
}
public final String getName()
{
return name;
}
public final int getStatus()
{
return status;
}
public final String getCity()
{
return city;
}
public String toString()
{
return "Supplier: number=" + number +
" name=" + name +
" status=" + status +
" city=" + city + '.';
}
} </tt></b> </pre>
<a id="entity_shipment"></a>
<pre class="programlisting"><b class="userinput"><tt>public class Shipment
{
private String partNumber;
private String supplierNumber;
private int quantity;
public Shipment(String partNumber, String supplierNumber, int quantity)
{
this.partNumber = partNumber;
this.supplierNumber = supplierNumber;
this.quantity = quantity;
}
public final String getPartNumber()
{
return partNumber;
}
public final String getSupplierNumber()
{
return supplierNumber;
}
public final int getQuantity()
{
return quantity;
}
public String toString()
{
return "Shipment: part=" + partNumber +
" supplier=" + supplierNumber +
" quantity=" + quantity + '.';
}
} </tt></b> </pre>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="retrievingbyindexkey.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="creatingentitybindings.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Retrieving Items by Index Key
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Creating Entity Bindings
</td>
</tr>
</table>
</div>
</body>
</html>

348
docs/collections/tutorial/SerializableEntity.html Normal file
View File

@@ -0,0 +1,348 @@
<?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>Chapter 6. 
Using Serializable Entities
</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="sortedcollections.html" title="&#10;&#9;&#9;Using Sorted Collections&#10;&#9;" />
<link rel="next" href="transientfieldsinbinding.html" title="&#10;&#9;&#9;Using Transient Fields in an Entity Binding&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 6. 
Using Serializable Entities
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="sortedcollections.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="transientfieldsinbinding.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="SerializableEntity"></a>Chapter 6. 
Using Serializable Entities
</h2>
</div>
</div>
<div></div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="sect1">
<a href="SerializableEntity.html#transientfieldsinclass">
Using Transient Fields in an Entity Class
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="transientfieldsinbinding.html">
Using Transient Fields in an Entity Binding
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="removingredundantvalueclasses.html">
Removing the Redundant Value Classes
</a>
</span>
</dt>
</dl>
</div>
<p>
In the prior examples that used entities (the Entity and Tuple examples) you
may have noticed the redundancy between the serializable value
classes and the entity classes. An entity class by definition
contains all properties of the value class as well as all
properties of the key class.
</p>
<p>
When using serializable values it is possible to remove this
redundancy by changing the entity class in two ways:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
Make the entity class serializable, so it can be used in place
of the value class.
</p>
</li>
<li>
<p>
Make the key fields transient, so they are not redundantly
stored in the record.
</p>
</li>
</ul>
</div>
<p>
The modified entity class can then serve double-duty: It can be
serialized and stored as the record value, and it can be used as
the entity class as usual along with the Java collections API. The
<tt class="classname">PartData</tt>, <tt class="classname">SupplierData</tt> and <tt class="classname">ShipmentData</tt>
classes can then be removed.
</p>
<p>
Transient fields are defined in Java as fields that are not
stored in the serialized form of an object. Therefore, when an
object is deserialized the transient fields must be explicitly
initialized. Since the entity binding is responsible for creating
entity objects, it is the natural place to initialize the transient
key fields.
</p>
<p>
Note that it is not strictly necessary to make the key fields of
a serializable entity class transient. If this is not done, the key
will simply be stored redundantly in the record's value. This extra
storage may or may not be acceptable to an application. But since
we are using tuple keys and an entity binding class must be
implemented anyway to extract the key from the entity, it is
sensible to use transient key fields to reduce the record size. Of
course there may be a reason that transient fields are not desired;
for example, if an application wants to serialize the entity
objects for other purposes, then using transient fields should be
avoided.
</p>
<p>
The complete source of the final version of the example program
is included in the Berkeley DB distribution.
</p>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="transientfieldsinclass"></a>
Using Transient Fields in an Entity Class
</h2>
</div>
</div>
<div></div>
</div>
<p>
The entity classes in this example are redefined such that they
can be used both as serializable value classes and as entity
classes. Compared to the prior example there are three changes to
the <tt class="classname">Part</tt>, <tt class="classname">Supplier</tt> and <tt class="classname">Shipment</tt> entity
classes:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
Each class now implements the <tt class="classname">Serializable</tt>
interface.
</p>
</li>
<li>
<p>
The key fields in each class are declared as <tt class="literal">transient</tt>.
</p>
</li>
<li>
<p>
A package-private <tt class="methodname">setKey()</tt> method is added to each class
for initializing the transient key fields. This method will be
called from the entity bindings.
</p>
</li>
</ul>
</div>
<a id="sentity_part"></a>
<pre class="programlisting"><b class="userinput"><tt>import java.io.Serializable;</tt></b>
...
public class Part <b class="userinput"><tt>implements Serializable</tt></b>
{
private <b class="userinput"><tt>transient</tt></b> String number;
private String name;
private String color;
private Weight weight;
private String city;
public Part(String number, String name, String color, Weight weight,
String city)
{
this.number = number;
this.name = name;
this.color = color;
this.weight = weight;
this.city = city;
}
<b class="userinput"><tt> final void setKey(String number)
{
this.number = number;
}</tt></b>
public final String getNumber()
{
return number;
}
public final String getName()
{
return name;
}
public final String getColor()
{
return color;
}
public final Weight getWeight()
{
return weight;
}
public final String getCity()
{
return city;
}
public String toString()
{
return "Part: number=" + number +
" name=" + name +
" color=" + color +
" weight=" + weight +
" city=" + city + '.';
}
}
...
public class Supplier <b class="userinput"><tt>implements Serializable</tt></b>
{
private <b class="userinput"><tt>transient</tt></b> String number;
private String name;
private int status;
private String city;
public Supplier(String number, String name, int status, String city)
{
this.number = number;
this.name = name;
this.status = status;
this.city = city;
}
<b class="userinput"><tt> void setKey(String number)
{
this.number = number;
}</tt></b>
public final String getNumber()
{
return number;
}
public final String getName()
{
return name;
}
public final int getStatus()
{
return status;
}
public final String getCity()
{
return city;
}
public String toString()
{
return "Supplier: number=" + number +
" name=" + name +
" status=" + status +
" city=" + city + '.';
}
}
...
public class Shipment <b class="userinput"><tt>implements Serializable</tt></b>
{
private <b class="userinput"><tt>transient</tt></b> String partNumber;
private <b class="userinput"><tt>transient</tt></b> String supplierNumber;
private int quantity;
public Shipment(String partNumber, String supplierNumber, int quantity)
{
this.partNumber = partNumber;
this.supplierNumber = supplierNumber;
this.quantity = quantity;
}
<b class="userinput"><tt> void setKey(String partNumber, String supplierNumber)
{
this.partNumber = partNumber;
this.supplierNumber = supplierNumber;
} </tt></b>
public final String getPartNumber()
{
return partNumber;
}
public final String getSupplierNumber()
{
return supplierNumber;
}
public final int getQuantity()
{
return quantity;
}
public String toString()
{
return "Shipment: part=" + partNumber +
" supplier=" + supplierNumber +
" quantity=" + quantity + '.';
}
}
</pre>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="sortedcollections.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="transientfieldsinbinding.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Using Sorted Collections
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Using Transient Fields in an Entity Binding
</td>
</tr>
</table>
</div>
</body>
</html>

84
docs/collections/tutorial/SerializedObjectStorage.html Normal file
View File

@@ -0,0 +1,84 @@
<?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>
Serialized Object Storage
</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="collectionOverview.html" title="Appendix A. &#10; API Notes and Details&#10; " />
<link rel="previous" href="UsingStoredCollections.html" title="&#10; Using Stored Collections&#10; " />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Serialized Object Storage
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="UsingStoredCollections.html">Prev</a> </td>
<th width="60%" align="center">Appendix A. 
API Notes and Details
</th>
<td width="20%" align="right"> </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="SerializedObjectStorage"></a>
Serialized Object Storage
</h2>
</div>
</div>
<div></div>
</div>
<p>
Serialization of an object graph includes class information as
well as instance information. If more than one instance of the same
class is serialized as separate serialization operations then the
class information exists more than once. To eliminate this
inefficiency the
<a href="../../java/com/sleepycat/bind/serial/StoredClassCatalog.html" target="_top">StoredClassCatalog</a>
class will store the class format for all database records stored
using a
<a href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a>.
Refer to the
<tt class="literal">ship</tt> sample code for examples (the class
<tt class="literal">SampleDatabase</tt> in
<tt class="filename">examples_java/src/com/sleepycat/examples/collections/ship/basic/SampleDatabase.java</tt>
is a good place to start).
</p>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="UsingStoredCollections.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="collectionOverview.html">Up</a>
</td>
<td width="40%" align="right"> </td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Using Stored Collections
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> </td>
</tr>
</table>
</div>
</body>
</html>

193
docs/collections/tutorial/Summary.html Normal file
View File

@@ -0,0 +1,193 @@
<?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>Chapter 7. 
Summary
</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="removingredundantvalueclasses.html" title="&#10;&#9;&#9;Removing the Redundant Value Classes&#10;&#9;" />
<link rel="next" href="collectionOverview.html" title="Appendix A. &#10; API Notes and Details&#10; " />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 7. 
Summary
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="removingredundantvalueclasses.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="collectionOverview.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="Summary"></a>Chapter 7. 
Summary
</h2>
</div>
</div>
<div></div>
</div>
<p>
In summary, the DB Java Collections API tutorial has
demonstrated how to create different types of bindings, as well as
how to use the basic facilities of the DB Java Collections API:
the environment, databases, secondary indices, collections, and
transactions. The final approach illustrated by the last example
program, Serializable Entity, uses tuple keys and serial entity
values. Hopefully it is clear that any type of object-to-data
binding may be implemented by an application and used along with
standard Java collections.
</p>
<p>
The following table summarizes the differences between the
examples in the tutorial.
</p>
<div class="informaltable">
<table border="1" width="80%">
<colgroup>
<col />
<col />
<col />
<col />
<col />
</colgroup>
<thead>
<tr>
<th>Example</th>
<th>Key</th>
<th>Value</th>
<th>Entity</th>
<th>Comments</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<a href="BasicProgram.html">
The Basic Program
</a>
</td>
<td>Serial</td>
<td>Serial</td>
<td>No</td>
<td>The shipment program</td>
</tr>
<tr>
<td>
<a href="UsingSecondaries.html">
Using Secondary Indices
</a>
</td>
<td>Serial</td>
<td>Serial</td>
<td>No</td>
<td>Secondary indices</td>
</tr>
<tr>
<td>
<a href="Entity.html">
Using Entity Classes
</a>
</td>
<td>Serial</td>
<td>Serial</td>
<td>Yes</td>
<td>Combining the key and value in a single object</td>
</tr>
<tr>
<td>
<a href="Tuple.html">
Using Tuples
</a>
</td>
<td>Tuple</td>
<td>Serial</td>
<td>Yes</td>
<td>Compact ordered keys</td>
</tr>
<tr>
<td>
<a href="SerializableEntity.html">
Using Serializable Entities
</a>
</td>
<td>Tuple</td>
<td>Serial</td>
<td>Yes</td>
<td>One serializable class for entities and values</td>
</tr>
</tbody>
</table>
</div>
<p>
Having completed this tutorial, you may want to explore how other types of
bindings can be implemented. The bindings shown in this tutorial
are all <span class="emphasis"><em>external bindings</em></span>, meaning that the data classes
themselves contain none of the binding implementation. It is also
possible to implement <span class="emphasis"><em>internal bindings</em></span>, where the data
classes implement the binding.
</p>
<p>
Internal bindings are called <span class="emphasis"><em>marshalled bindings</em></span> in the
DB Java Collections API, and in this model each data class
implements a marshalling interface. A single external binding class
that understands the marshalling interface is used to call the
internal bindings of each data object, and therefore the overall
model and API is unchanged. To learn about marshalled bindings, see
the
<span class="pdf;html">
<tt class="literal">marshal</tt> and <tt class="literal">factory</tt> examples that
came with your DB distribution (you can find them in
<tt class="filename">&lt;INSTALL_DIR&gt;/examples_java/src/com/sleepycat/examples/collections/ship</tt>
where <tt class="literal">&lt;INSTALL_DIR&gt;</tt> is the location where you
unpacked your DB distribution).
</span>
These examples continue building on
the example programs used in the tutorial. The Marshal program is
the next program following the Serializable Entity program, and the
Factory program follows the Marshal program. The source code
comments in these examples explain their differences.
</p>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="removingredundantvalueclasses.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="collectionOverview.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Removing the Redundant Value Classes
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Appendix A. 
API Notes and Details
</td>
</tr>
</table>
</div>
</body>
</html>

212
docs/collections/tutorial/Tuple.html Normal file
View File

@@ -0,0 +1,212 @@
<?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>Chapter 5. 
Using Tuples
</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="entitieswithcollections.html" title="&#10;&#9;&#9;Using Entities with Collections&#10;&#9;" />
<link rel="next" href="tupleswithkeycreators.html" title="&#10;&#9;&#9;Using Tuples with Key Creators&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 5. 
Using Tuples
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="entitieswithcollections.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="tupleswithkeycreators.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="Tuple"></a>Chapter 5. 
Using Tuples
</h2>
</div>
</div>
<div></div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="sect1">
<a href="Tuple.html#tupleformat">
Using the Tuple Format
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="tupleswithkeycreators.html">
Using Tuples with Key Creators
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="tuplekeybindings.html">
Creating Tuple Key Bindings
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="tuple-serialentitybindings.html">
Creating Tuple-Serial Entity Bindings
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="sortedcollections.html">
Using Sorted Collections
</a>
</span>
</dt>
</dl>
</div>
<p>
DB Java Collections API <span class="emphasis"><em>tuples</em></span> are sequences of
primitive Java data types, for example, integers and strings. The
<span class="emphasis"><em>tuple format</em></span> is a binary format for tuples that can be used
to store keys and/or values.
</p>
<p>
Tuples are useful as keys because they have a meaningful sort
order, while serialized objects do not. This is because the binary
data for a tuple is written in such a way that its raw byte
ordering provides a useful sort order. For example, strings in
tuples are written with a null terminator rather than with a
leading length.
</p>
<p>
Tuples are useful as keys <span class="emphasis"><em>or</em></span> values when reducing the
record size to a minimum is important. A tuple is significantly
smaller than an equivalent serialized object. However, unlike
serialized objects, tuples cannot contain complex data types and
are not easily extended except by adding fields at the end of the
tuple.
</p>
<p>
Whenever a tuple format is used, except when the key or value
class is a Java primitive wrapper class, a <span class="emphasis"><em>tuple binding</em></span> class must
be implemented to map between the Java object and the tuple fields.
Because of this extra requirement, and because tuples are not
easily extended, a useful technique shown in this example is to use
tuples for keys and serialized objects for values. This provides
compact ordered keys but still allows arbitrary Java objects as
values, and avoids implementing a tuple binding for each value
class.
</p>
<p>
Compare this example to the prior Entity example and you'll see
that the <tt class="classname">Sample</tt> class has not changed. When changing a
database format, while new bindings are needed to map key and value
objects to the new format, the application using the objects often
does not need to be modified.
</p>
<p>
The complete source of the final version of the example program
is included in the Berkeley DB distribution.
</p>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="tupleformat"></a>
Using the Tuple Format
</h2>
</div>
</div>
<div></div>
</div>
<p>
Tuples are sequences of primitive Java values that can be
written to, and read from, the raw data bytes of a stored record.
The primitive values are written or read one at a time in sequence,
using the DB Java Collections API
<a href="../../java/com/sleepycat/bind/tuple/TupleInput.html" target="_top">TupleInput</a>
and
<a href="../../java/com/sleepycat/bind/tuple/TupleOutput.html" target="_top">TupleOutput</a>
classes. These classes are very similar to the standard Java
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/io/DataInput.html" target="_top">DataInput</a>
and
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/io/DataOutput.html" target="_top">DataOutput</a>
interfaces. The primary difference is the binary format of the
data, which is designed for sorting in the case of tuples.
</p>
<p>
For example, to read and write a tuple containing two string
values, the following code snippets could be used.
</p>
<a id="tuple_tuplefragment"></a>
<pre class="programlisting"><b class="userinput"><tt>import com.sleepycat.bind.tuple.TupleInput;
import com.sleepycat.bind.tuple.TupleOutput;
...
TupleInput input;
TupleOutput output;
...
String partNumber = input.readString();
String supplierNumber = input.readString();
...
output.writeString(partNumber);
output.writeString(supplierNumber); </tt></b> </pre>
<p>
Since a tuple is defined as an ordered sequence, reading and
writing order must match. If the wrong data type is read (an
integer instead of string, for example), an exception may be thrown
or at minimum invalid data will be read.
</p>
<p>
When the tuple format is used, bindings and key creators must
read and write tuples using the tuple API as shown above. This will
be illustrated in the next two sections.
</p>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="entitieswithcollections.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="tupleswithkeycreators.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Using Entities with Collections
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Using Tuples with Key Creators
</td>
</tr>
</table>
</div>
</body>
</html>

636
docs/collections/tutorial/UsingCollectionsAPI.html Normal file
View File

@@ -0,0 +1,636 @@
<?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>
Using the DB Java Collections API
</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="collectionOverview.html" title="Appendix A. &#10; API Notes and Details&#10; " />
<link rel="previous" href="collectionOverview.html" title="Appendix A. &#10; API Notes and Details&#10; " />
<link rel="next" href="UsingStoredCollections.html" title="&#10; Using Stored Collections&#10; " />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Using the DB Java Collections API
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="collectionOverview.html">Prev</a> </td>
<th width="60%" align="center">Appendix A. 
API Notes and Details
</th>
<td width="20%" align="right"> <a accesskey="n" href="UsingStoredCollections.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="UsingCollectionsAPI"></a>
Using the DB Java Collections API
</h2>
</div>
</div>
<div></div>
</div>
<p>
An
<a href="../../java/com/sleepycat/db/Environment.html" target="_top">Environment</a>
manages the resources for one or more data stores. A
<a href="../../java/com/sleepycat/db/Database.html" target="_top">Database</a>
object
represents a single database and is created via a method on the
environment object.
<a href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>
objects represent an index associated with a primary database.
<span>
An access method must be chosen for each database and secondary
database.
</span>
Primary and secondary databases are then used to create stored
collection objects, as described in
<a href="UsingStoredCollections.html">
Using Stored Collections
</a>.
</p>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="UsingTransactions"></a>
Using Transactions
</h3>
</div>
</div>
<div></div>
</div>
<p>
Once you have an environment, one or more databases, and one or
more stored collections, you are ready to access (read and write)
stored data. For a transactional environment, a transaction must be
started before accessing data, and must be committed or aborted
after access is complete. The DB Java Collections API provides several
ways of managing transactions.
</p>
<p>
The recommended technique is to use the
<a href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>
class along with your own implementation of the
<a href="../../java/com/sleepycat/collections/TransactionWorker.html" target="_top">TransactionWorker</a>
interface.
<a href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>
will call your
<a href="../../java/com/sleepycat/collections/TransactionWorker.html" target="_top">TransactionWorker</a>
implementation class to perform the data access or work of the
transaction. This technique has the following benefits:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
Transaction exceptions will be handled transparently and
retries will be performed when deadlocks are detected.
</p>
</li>
<li>
<p>
The transaction will automatically be committed if your
<a href="../../java/com/sleepycat/collections/TransactionWorker.html#doWork()" target="_top">TransactionWorker.doWork()</a>
method returns normally, or will be
aborted if <tt class="methodname">doWork()</tt> throws an exception.
</p>
</li>
<li>
<p>
<tt class="classname">TransactionRunner</tt> can be used for non-transactional
environments as well, allowing you to write your application
independently of the environment.
</p>
</li>
</ul>
</div>
<p>
If you don't want to use
<a href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>,
the alternative is to use the
<a href="../../java/com/sleepycat/collections/CurrentTransaction.html" target="_top">CurrentTransaction</a>
class.
</p>
<div class="orderedlist">
<ol type="1">
<li>
<p>
Obtain a CurrentTransaction instance by calling the
<a href="../../java/com/sleepycat/collections/CurrentTransaction.html#getInstance(com.sleepycat.db.Environment)" target="_top">CurrentTransaction.getInstance</a>
method. The instance returned
can be used by all threads in a program.
</p>
</li>
<li>
<p>
Use
<a href="../../java/com/sleepycat/collections/CurrentTransaction.html#beginTransaction(com.sleepycat.db.TransactionConfig)" target="_top">CurrentTransaction.beginTransaction()</a>,
<a href="../../java/com/sleepycat/collections/CurrentTransaction.html#commitTransaction()" target="_top">CurrentTransaction.commitTransaction()</a>
and
<a href="../../java/com/sleepycat/collections/CurrentTransaction.html#abortTransaction()" target="_top">CurrentTransaction.abortTransaction()</a>
to directly begin, commit and abort transactions.
</p>
</li>
</ol>
</div>
<p>
If you choose to use CurrentTransaction directly you must handle
the
<a href="../../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a>
exception and perform retries yourself. Also note that
CurrentTransaction may only be used in a transactional
environment.
</p>
<p>
The DB Java Collections API supports nested transactions. If
<a href="../../java/com/sleepycat/collections/TransactionRunner.html#run(com.sleepycat.collections.TransactionWorker)" target="_top">TransactionRunner.run(com.sleepycat.collections.TransactionWorker)</a>
or
<a href="../../java/com/sleepycat/collections/CurrentTransaction.html#beginTransaction(com.sleepycat.db.TransactionConfig)" target="_top">CurrentTransaction.beginTransaction()</a>
,
is called while another transaction is active, a child transaction
is created. When
<a href="../../java/com/sleepycat/collections/TransactionRunner.html#run(com.sleepycat.collections.TransactionWorker)" target="_top">TransactionRunner.run(com.sleepycat.collections.TransactionWorker)</a>
returns, or when
<a href="../../java/com/sleepycat/collections/CurrentTransaction.html#commitTransaction()" target="_top">CurrentTransaction.commitTransaction()</a>
or
<a href="../../java/com/sleepycat/collections/CurrentTransaction.html#abortTransaction()" target="_top">CurrentTransaction.abortTransaction()</a>
is called, the parent transaction becomes active again. Note that
because only one transaction is active per-thread, it is impossible
to accidentally use a parent transaction while a child transaction
is active.
</p>
<p>
The DB Java Collections API supports transaction auto-commit.
If no transaction is active and a write operation is requested for
a transactional database, auto-commit is used automatically.
</p>
<p>
The DB Java Collections API also supports transaction
dirty-read via the
<a href="../../java/com/sleepycat/collections/StoredCollections.html" target="_top">StoredCollections</a>
class. When dirty-read is enabled for a collection, data will be
read that has been modified by another transaction but not
committed. Using dirty-read can improve concurrency since reading
will not wait for other transactions to complete. For a
non-transactional container, dirty-read has no effect. See
<a href="../../java/com/sleepycat/collections/StoredCollections.html" target="_top">StoredCollections</a>
for how to create a dirty-read collection.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="TransactionRollback"></a>
Transaction Rollback
</h3>
</div>
</div>
<div></div>
</div>
<p>
When a transaction is aborted (or rolled back) the application
is responsible for discarding references to any data objects that
were modified during the transaction. Since the DB Java Collections API
treats data by value, not by reference, neither the data
objects nor the DB Java Collections API objects contain status
information indicating whether the data objects are 1- in sync with
the database, 2- dirty (contain changes that have not been written
to the database), 3- stale (were read previously but have become
out of sync with changes made to the database), or 4- contain
changes that cannot be committed because of an aborted
transaction.
</p>
<p>
For example, a given data object will reflect the current state
of the database after reading it within a transaction. If the
object is then modified it will be out of sync with the database.
When the modified object is written to the database it will then be
in sync again. But if the transaction is aborted the object will
then be out of sync with the database. References to objects for aborted
transactions
should no longer be used. When these objects are needed later they
should be read fresh from the database.
</p>
<p>
When an existing stored object is to be updated, special care
should be taken to read the data, then modify it, and then write it
to the database, all within a single transaction. If a stale data
object (an object that was read previously but has since been
changed in the database) is modified and then written to the
database, database changes may be overwritten unintentionally.
</p>
<p>
When an application enforces rules about concurrent access to
specific data objects or all data objects, the rules described here
can be relaxed. For example, if the application knows that a
certain object is only modified in one place, it may be able to
reliably keep a current copy of that object. In that case, it is
not necessary to reread the object before updating it. That said,
if arbitrary concurrent access is to be supported, the safest
approach is to always read data before modifying it within a single
transaction.
</p>
<p>
Similar concerns apply to using data that may have become stale.
If the application depends on current data, it should be read fresh
from the database just before it is used.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="SelectingAccessMethods"></a>Selecting Access Methods</h3>
</div>
</div>
<div></div>
</div>
<p>
For each data store and secondary index, you must choose from one of the
access methods in the table below.
The access method determines not only whether sorted keys or duplicate
keys are supported, but also what types of collection views may be used
and what restrictions are imposed on the collection views.
</p>
<div class="informaltable">
<table border="1" width="80%">
<colgroup>
<col />
<col />
<col />
<col />
<col />
<col />
</colgroup>
<thead>
<tr>
<th>Access Method</th>
<th>Ordered</th>
<th>Duplicates</th>
<th>Record Numbers</th>
<th>Database Type</th>
<th><tt class="classname">DatabaseConfig</tt> Method</th>
</tr>
</thead>
<tbody>
<tr>
<td>
BTREE-UNIQUE
</td>
<td>
Yes
</td>
<td>
No
</td>
<td>
No
</td>
<td>
<a href="../../java/com/sleepycat/db/DatabaseType.html#BTREE" target="_top">BTREE</a>
</td>
<td>
None
</td>
</tr>
<tr>
<td>
BTREE-DUP
</td>
<td>
Yes
</td>
<td>
Yes, Unsorted
</td>
<td>
No
</td>
<td>
<a href="../../java/com/sleepycat/db/DatabaseType.html#BTREE" target="_top">BTREE</a>
</td>
<td>
<a href="../../java/com/sleepycat/db/DatabaseConfig.html#setUnsortedDuplicates(boolean)" target="_top">setUnsortedDuplicates</a>
</td>
</tr>
<tr>
<td>
BTREE-DUPSORT
</td>
<td>
Yes
</td>
<td>
Yes, Sorted
</td>
<td>
No
</td>
<td>
<a href="../../java/com/sleepycat/db/DatabaseType.html#BTREE" target="_top">BTREE</a>
</td>
<td>
<a href="../../java/com/sleepycat/db/DatabaseConfig.html#setSortedDuplicates(boolean)" target="_top">setSortedDuplicates</a>
</td>
</tr>
<tr>
<td>
BTREE-RECNUM
</td>
<td>
Yes
</td>
<td>
No
</td>
<td>
Yes, Renumbered
</td>
<td>
<a href="../../java/com/sleepycat/db/DatabaseType.html#BTREE" target="_top">BTREE</a>
</td>
<td>
<a href="../../java/com/sleepycat/db/DatabaseConfig.html#setBtreeRecordNumbers(boolean)" target="_top">setBtreeRecordNumbers</a>
</td>
</tr>
<tr>
<td>
HASH-UNIQUE
</td>
<td>
No
</td>
<td>
No
</td>
<td>
No
</td>
<td>
<a href="../../java/com/sleepycat/db/DatabaseType.html#HASH" target="_top">HASH</a>
</td>
<td>
None
</td>
</tr>
<tr>
<td>
HASH-DUP
</td>
<td>
No
</td>
<td>
Yes, Unsorted
</td>
<td>
No
</td>
<td>
<a href="../../java/com/sleepycat/db/DatabaseType.html#HASH" target="_top">HASH</a>
</td>
<td>
<a href="../../java/com/sleepycat/db/DatabaseConfig.html#setUnsortedDuplicates(boolean)" target="_top">setUnsortedDuplicates</a>
</td>
</tr>
<tr>
<td>
HASH-DUPSORT
</td>
<td>
No
</td>
<td>
Yes, Sorted
</td>
<td>
No
</td>
<td>
<a href="../../java/com/sleepycat/db/DatabaseType.html#HASH" target="_top">HASH</a>
</td>
<td>
<a href="../../java/com/sleepycat/db/DatabaseConfig.html#setSortedDuplicates(boolean)" target="_top">setSortedDuplicates</a>
</td>
</tr>
<tr>
<td>
QUEUE
</td>
<td>
Yes
</td>
<td>
No
</td>
<td>
Yes, Fixed
</td>
<td>
<a href="../../java/com/sleepycat/db/DatabaseType.html#QUEUE" target="_top">QUEUE</a>
</td>
<td>
None
</td>
</tr>
<tr>
<td>
RECNO
</td>
<td>
Yes
</td>
<td>
No
</td>
<td>
Yes, Fixed
</td>
<td>
<a href="../../java/com/sleepycat/db/DatabaseType.html#RECNO" target="_top">RECNO</a>
</td>
<td>
None
</td>
</tr>
<tr>
<td>
RECNO-RENUMBER
</td>
<td>
Yes
</td>
<td>
No
</td>
<td>
Yes, Renumbered
</td>
<td>
<a href="../../java/com/sleepycat/db/DatabaseType.html#RECNO" target="_top">RECNO</a>
</td>
<td>
<a href="../../java/com/sleepycat/db/DatabaseConfig.html#setRenumbering(boolean)" target="_top">setRenumbering</a>
</td>
</tr>
</tbody>
</table>
</div>
<p>
Please see
<span class="html"><a href="../../ref/am_conf/intro.html" target="_top">Available Access Methods</a> in</span>
the <i class="citetitle">Berkeley DB Programmer's Reference Guide</i>
for more information on access method configuration.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="AccessMethodRestrictions"></a>
Access Method Restrictions
</h3>
</div>
</div>
<div></div>
</div>
<p>
The restrictions imposed by the access method on the database
model are:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
If keys are ordered then data may be enumerated in key order and
key ranges may be used to form subsets of a data store. The
<tt class="classname">SortedMap</tt> and <tt class="classname">SortedSet</tt>
interfaces are supported for collections with ordered keys.
</p>
</li>
<li>
<p>
If duplicates are allowed then more than one value may be
associated with the same key. This means that the data store cannot
be strictly considered a map — it is really a multi-map. See
<a href="UsingStoredCollections.html">
Using Stored Collections
</a>
for implications on the use of the collection interfaces.
</p>
</li>
<li>
<p>
If duplicate keys are allowed for a data store then the data
store may not have secondary indices.
</p>
</li>
<li>
<p>
For secondary indices with duplicates, the duplicates must be
sorted. This restriction is imposed by the DB Java Collections API.
</p>
</li>
<li>
<p>
With sorted duplicates, all values for the same key must be
distinct.
</p>
</li>
<li>
<p>
If duplicates are unsorted, then values for the same key must be
distinct.
</p>
</li>
<li>
<p>
If record number keys are used, the the number of records is
limited to the maximum value of an unsigned 32-bit integer.
</p>
</li>
<li>
<p>
If record number keys are renumbered, then standard List
add/remove behavior is supported but concurrency/performance is
reduced.
</p>
</li>
</ul>
</div>
<p>
See
<a href="UsingStoredCollections.html">
Using Stored Collections
</a>
for more information on how access methods impact the use of stored
collections.
</p>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="collectionOverview.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="collectionOverview.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="UsingStoredCollections.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Appendix A. 
API Notes and Details
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Using Stored Collections
</td>
</tr>
</table>
</div>
</body>
</html>

457
docs/collections/tutorial/UsingSecondaries.html Normal file
View File

@@ -0,0 +1,457 @@
<?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>Chapter 3. 
Using Secondary Indices
</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="handlingexceptions.html" title="&#10;&#9;&#9;Handling Exceptions&#10;&#9;" />
<link rel="next" href="openingforeignkeys.html" title="&#10;&#9;&#9;&#10;&#9;&#9;More Secondary Key Indices&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 3. 
Using Secondary Indices
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="handlingexceptions.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="openingforeignkeys.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="UsingSecondaries"></a>Chapter 3. 
Using Secondary Indices
</h2>
</div>
</div>
<div></div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="sect1">
<a href="UsingSecondaries.html#opensecondaryindices">
Opening Secondary Key Indices
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="openingforeignkeys.html">
More Secondary Key Indices
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="indexedcollections.html">
Creating Indexed Collections
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="retrievingbyindexkey.html">
Retrieving Items by Index Key
</a>
</span>
</dt>
</dl>
</div>
<p>
In the Basic example, each store has a single <span class="emphasis"><em>primary
key</em></span>. The Index example extends the Basic example to add the use of
<span class="emphasis"><em>secondary keys</em></span>.
</p>
<p>
The complete source of the final version of the example program
is included in the Berkeley DB distribution.
</p>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="opensecondaryindices"></a>
Opening Secondary Key Indices
</h2>
</div>
</div>
<div></div>
</div>
<p>
<span class="emphasis"><em>Secondary indices</em></span> or <span class="emphasis"><em>secondary databases</em></span> are used
to access a primary database by a key other than the primary key.
Recall that the Supplier Number field is the primary key of the
Supplier database. In this section, the Supplier City field will be
used as a secondary lookup key. Given a city value, we would like
to be able to find the Suppliers in that city. Note that more than
one Supplier may be in the same city.
</p>
<p>
Both primary and secondary databases contain key-value records.
The key of an index record is the secondary key, and its value is
the key of the associated record in the primary database. When lookups by
secondary key are performed, the associated record in the primary
database is transparently retrieved by its primary key and returned
to the caller.
</p>
<p>
Secondary indices are maintained automatically when index key
fields (the City field in this case) are added, modified or removed
in the records of the primary database. However, the application
must implement a
<a href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>
that extracts the index key from the database record.
</p>
<p>
It is useful to contrast opening an secondary index with opening
a primary database (as described earlier in
<a href="opendatabases.html">
Opening and Closing Databases
</a>.
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
A primary database may be associated with one or more secondary
indices. A secondary index is always associated with exactly one
primary database.
</p>
</li>
<li>
<p>
For a secondary index, a
<a href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>
must be implemented by the application to extract the index key
from the record of its associated primary database.
</p>
</li>
<li>
<p>
A primary database is represented by a
<a href="../../java/com/sleepycat/db/Database.html" target="_top">Database</a>
object and a secondary index is represented by a
<a href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>
object. The
<a href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>
class extends the
<a href="../../java/com/sleepycat/db/Database.html" target="_top">Database</a>
class.
</p>
</li>
<li>
<p>
When a
<a href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>
is created it is associated with a primary
<a href="../../java/com/sleepycat/db/Database.html" target="_top">Database</a>
object and a
<span>
<a href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>.
</span>
</p>
</li>
</ul>
</div>
<p>
The <tt class="classname">SampleDatabase</tt> class is extended to open the
Supplier-by-City secondary key index.
</p>
<a id="index_java_sampledatabase"></a>
<pre class="programlisting"><b class="userinput"><tt>import com.sleepycat.bind.serial.SerialSerialKeyCreator;
import com.sleepycat.db.SecondaryConfig;
import com.sleepycat.db.SecondaryDatabase;</tt></b>
...
public class SampleDatabase
{
...
<b class="userinput"><tt> private static final String SUPPLIER_CITY_INDEX = "supplier_city_index";
...
private SecondaryDatabase supplierByCityDb;
...</tt></b>
public SampleDatabase(String homeDirectory)
throws DatabaseException, FileNotFoundException
{
...
<b class="userinput"><tt> SecondaryConfig secConfig = new SecondaryConfig();
secConfig.setTransactional(true);
secConfig.setAllowCreate(true);
secConfig.setType(DatabaseType.BTREE);
secConfig.setSortedDuplicates(true);
secConfig.setKeyCreator(
new SupplierByCityKeyCreator(javaCatalog,
SupplierKey.class,
SupplierData.class,
String.class));
supplierByCityDb = env.openSecondaryDatabase(null,
SUPPLIER_CITY_INDEX,
null,
supplierDb,
secConfig);</tt></b>
...
}
} </pre>
<p>
A
<a href="../../java/com/sleepycat/db/SecondaryConfig.html" target="_top">SecondaryConfig</a>
object is used to configure the secondary database. The
<a href="../../java/com/sleepycat/db/SecondaryConfig.html" target="_top">SecondaryConfig</a>
class extends the
<a href="../../java/com/sleepycat/db/DatabaseConfig.html" target="_top">DatabaseConfig</a>
class, and most steps for configuring a secondary database are the
same as for configuring a primary database. The main difference in
the example above is that the
<tt class="methodname">SecondaryConfig.setSortedDuplicates()</tt> method is called to
allow duplicate index keys. This is how more than one Supplier may
be in the same City. If this property is not specified, the default is
that the index keys of all records must be unique.
</p>
<p>
For a primary database, duplicate keys are not normally used
since a primary database with duplicate keys may not have any
associated secondary indices. If primary database keys are not
unique, there is no way for a secondary key to reference a specific
record in the primary database.
</p>
<p>
Note that <tt class="methodname">setSortedDuplicates()</tt> and not
<tt class="methodname">setUnsortedDuplicates()</tt> was called. Sorted
duplicates are always used for indices rather than unsorted duplicates,
since sorting enables optimized equality joins.
</p>
<p>
Opening a secondary key index requires creating a
<span>
<a href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>.
</span>
The <tt class="classname">SupplierByCityKeyCreator</tt> class implements the
<a href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>
interface and will be defined below.
</p>
<p>
The
<a href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>
object is opened last. If you compare the
<tt class="methodname">openSecondaryDatabase()</tt> and <tt class="methodname">openDatabase()</tt> methods you'll
notice only two differences:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<tt class="methodname">openSecondaryDatabase()</tt> has an extra parameter for
specifying the associated primary database. The primary database is
<tt class="literal">supplierDb</tt> in this case.
</p>
</li>
<li>
<p>
The last parameter of <tt class="methodname">openSecondaryDatabase()</tt> is a
<tt class="literal">SecondaryConfig</tt> instead of a <tt class="literal">DatabaseConfig</tt>.
</p>
</li>
</ul>
</div>
<p>
How to use the secondary index to access records will be shown
in a later section.
</p>
<p>
The application-defined <tt class="classname">SupplierByCityKeyCreator</tt> class is
shown below. It was used above to configure the secondary
database.
</p>
<a id="index_supplierbycitykeycreator"></a>
<pre class="programlisting">public class SampleDatabase
{
...
<b class="userinput"><tt> private static class SupplierByCityKeyCreator
extends SerialSerialKeyCreator
{
private SupplierByCityKeyCreator(StoredClassCatalog catalog,
Class primaryKeyClass,
Class valueClass,
Class indexKeyClass)
{
super(catalog, primaryKeyClass, valueClass, indexKeyClass);
}
public Object createSecondaryKey(Object primaryKeyInput,
Object valueInput)
{
SupplierData supplierData = (SupplierData) valueInput;
return supplierData.getCity();
}
}</tt></b>
...
} </pre>
<p>
In general, a key creator class must implement the
<a href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>
interface. This interface has methods that operate on the record
data as raw bytes. In practice, it is easiest to use an abstract
base class that performs the conversion of record data to and from
the format defined for the database's key and value. The base class
implements the
<a href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>
interface and has abstract methods that must be implemented in turn
by the application.
</p>
<p>
In this example the
<a href="../../java/com/sleepycat/bind/serial/SerialSerialKeyCreator.html" target="_top">SerialSerialKeyCreator</a>
base class is used because the database record uses the serial
format for both its key and its value. The abstract methods of this
class have key and value parameters of type
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Object.html" target="_top">Object</a>
which are automatically converted to and from the raw record data
by the base class.
</p>
<p>
To perform the conversions properly, the key creator must be
aware of all three formats involved: the key format of the primary
database record, the value format of the primary database record,
and the key format of the index record. The
<a href="../../java/com/sleepycat/bind/serial/SerialSerialKeyCreator.html" target="_top">SerialSerialKeyCreator</a>
constructor is given the base classes for these three formats as
parameters.
</p>
<p>
The <tt class="methodname">SerialSerialKeyCreator.createSecondaryKey</tt> method is
given the key and value of the primary database record as
parameters, and it returns the key of the index record. In this
example, the index key is a field in the primary database record
value. Since the record value is known to be a <tt class="classname">SupplierData</tt>
object, it is cast to that class and the city field is
returned.
</p>
<p>
Note that the <tt class="literal">primaryKeyInput</tt> parameter is not used in
the example. This parameter is needed only when an index key is
derived from the key of the primary database record. Normally an
index key is derived only from the primary database record value,
but it may be derived from the key, value or both.
</p>
<p>
The following getter methods return the secondary database
object for use by other classes in the example program. The
secondary database object is used to create Java collections for
accessing records via their secondary keys.
</p>
<a id="index_getsupplierbycitydatabase"></a>
<pre class="programlisting">public class SampleDatabase
{
...
<b class="userinput"><tt> public final SecondaryDatabase getSupplierByCityDatabase()
{
return supplierByCityDb;
}</tt></b>
...
} </pre>
<p>
The following statement closes the secondary database.
</p>
<a id="index_close"></a>
<pre class="programlisting">public class SampleDatabase
{
...
public void close()
throws DatabaseException {
<b class="userinput"><tt> supplierByCityDb.close();</tt></b>
partDb.close();
supplierDb.close();
shipmentDb.close();
javaCatalog.close();
env.close();
}
...
} </pre>
<p>
Secondary databases must be closed before closing their
associated primary database.
</p>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="handlingexceptions.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="openingforeignkeys.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Handling Exceptions
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
More Secondary Key Indices
</td>
</tr>
</table>
</div>
</body>
</html>

790
docs/collections/tutorial/UsingStoredCollections.html Normal file
View File

@@ -0,0 +1,790 @@
<?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>
Using Stored Collections
</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="collectionOverview.html" title="Appendix A. &#10; API Notes and Details&#10; " />
<link rel="previous" href="UsingCollectionsAPI.html" title="&#10; Using the DB Java Collections API&#10; " />
<link rel="next" href="SerializedObjectStorage.html" title="&#10; Serialized Object Storage&#10; " />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Using Stored Collections
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="UsingCollectionsAPI.html">Prev</a> </td>
<th width="60%" align="center">Appendix A. 
API Notes and Details
</th>
<td width="20%" align="right"> <a accesskey="n" href="SerializedObjectStorage.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="UsingStoredCollections"></a>
Using Stored Collections
</h2>
</div>
</div>
<div></div>
</div>
<p>
When a stored collection is created it is based on either a
<a href="../../java/com/sleepycat/db/Database.html" target="_top">Database</a>
or a
<span>
<a href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>.
</span>
When a database is used, the primary key of the database is used as
the collection key. When a secondary database is used, the index
key is used as the collection key. Indexed collections can be used
for reading elements and removing elements but not for adding or
updating elements.
</p>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="StoredCollectionAccessMethods"></a>
Stored Collection and Access Methods
</h3>
</div>
</div>
<div></div>
</div>
<p>
The use of stored collections is constrained in certain respects as
described below.
<span>
Most of these restrictions have to do with
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/List.html" target="_top">List</a>
interfaces; for
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html" target="_top">Map</a>
interfaces, most all access modes are fully supported since the
Berkeley DB model is map-like.
</span>
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>
and
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedMap.html" target="_top">SortedMap</a>
interfaces may only be used if keys are ordered. This means ordered keys are required for creating a
<a href="../../java/com/sleepycat/collections/StoredSortedEntrySet.html" target="_top">StoredSortedEntrySet</a>,
<a href="../../java/com/sleepycat/collections/StoredSortedKeySet.html" target="_top">StoredSortedKeySet</a>,
<a href="../../java/com/sleepycat/collections/StoredSortedMap.html" target="_top">StoredSortedMap</a>, or
<a href="../../java/com/sleepycat/collections/StoredSortedValueSet.html" target="_top">StoredSortedValueSet</a>.
</p>
</li>
<li>
<p>
All iterators for stored collections implement the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html" target="_top">ListIterator</a>
interface as well as the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Iterator.html" target="_top">Iterator</a>
interface.
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#hasPrevious()" target="_top">ListIterator.hasPrevious()</a>
and
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#previous()" target="_top">ListIterator.previous()</a>
work in all cases.
<span>
However, the following
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html" target="_top">ListIterator</a>
method behavior is dependent on the access method.
</span>
</p>
<div class="itemizedlist">
<ul type="circle">
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#nextIndex()" target="_top">ListIterator.nextIndex()</a>
and
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#previousIndex()" target="_top">ListIterator.previousIndex()</a>
only work when record number keys are used, and throw
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>
otherwise.
</p>
</li>
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#add()" target="_top">ListIterator.add()</a>
inserts before the current position and renumbers following keys if the RECNO-RENUMBER
access method is used.
</p>
</li>
<li>
<p>
For all access methods other than RECNO-RENUMBER:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#add()" target="_top">ListIterator.add()</a>
throws
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>
if duplicates are not allowed.
</p>
</li>
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#add()" target="_top">ListIterator.add()</a>
inserts a duplicate before the current position
if duplicates are unsorted.
</p>
</li>
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#add()" target="_top">ListIterator.add()</a>
inserts a duplicate in sorted order if
duplicates are sorted.
</p>
</li>
</ul>
</div>
</li>
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#set()" target="_top">ListIterator.set()</a>
throws
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>
if sorted duplicates are configured, since updating with sorted duplicates would change the
iterator position.
</p>
</li>
</ul>
</div>
</li>
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.Entry.html#setValue()" target="_top">Map.Entry.setValue()</a>
throws
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>
if duplicates are sorted.
</p>
</li>
<li>
<p>
Only the access methods that use a record number key may be used
with a
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/List.html" target="_top">List</a>
<tt class="classname">List</tt>
view.
</p>
</li>
<li>
<p>
To create a stored List that supports the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/List.html#add()" target="_top">List.add()</a>
<tt class="methodname">List.add()</tt>
method, only the RECNO-RENUMBER access method may be used.
</p>
</li>
<li>
<p>
For List access methods that do not support
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/List.html#add()" target="_top">List.add()</a>
<tt class="methodname">List.add()</tt>
(RECNO, QUEUE, and BTREE-RECNUM):
</p>
<div class="itemizedlist">
<ul type="circle">
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/List.html#add()" target="_top">List.add()</a>
<tt class="methodname">List.add()</tt>
and
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#add()" target="_top">ListIterator.add()</a>
<tt class="methodname">ListIterator.add()</tt>
always throw
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a> .
</p>
</li>
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/List.html#remove()" target="_top">List.remove()</a>
<tt class="methodname">List.remove()</tt>
and
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#remove()" target="_top">ListIterator.remove()</a>
<tt class="methodname">ListIterator.remove()</tt>
do not cause list indices to be renumbered. However, iterators will skip
the removed values.
</p>
</li>
</ul>
</div>
<p>
For these access methods, stored Lists are most useful as
read-only collections where indices are not required to be
sequential.
</p>
</li>
<li>
<p>
When duplicates are allowed the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collection.html" target="_top">Collection</a>
interfaces are modified in several ways as described in the next
section.
</p>
</li>
</ul>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="StoredVersusStandardCollections"></a>
Stored Collections Versus Standard Java Collections
</h3>
</div>
</div>
<div></div>
</div>
<p>
Stored collections have the following differences with the
standard Java collection interfaces. Some of these are interface
contract violations.
</p>
<p>
The Java collections interface does not support duplicate keys
(multi-maps or multi-sets). When the access method allows duplicate
keys, the collection interfaces are defined as follows.
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#entrySet()" target="_top">Map.entrySet()</a>
may contain multiple
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.Entry.html" target="_top">Map.Entry</a>
objects with the same key.
</p>
</li>
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#keySet()" target="_top">Map.keySet()</a>
always contains unique keys, it does not contain duplicates.
</p>
</li>
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#values()" target="_top">Map.values()</a>
contains all values including the values
associated with duplicate keys.
</p>
</li>
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#put()" target="_top">Map.put()</a>
appends a duplicate if the key already exists rather than replacing
the existing value, and always returns null.
</p>
</li>
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#remove()" target="_top">Map.remove()</a>
removes all duplicates for the specified key.
</p>
</li>
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#get()" target="_top">Map.get()</a>
returns the first duplicate for the specified key.
</p>
</li>
<li>
<p>
<a href="../../java/com/sleepycat/collections/StoredMap.html#duplicates(java.lang.Object)" target="_top">StoredMap.duplicates()</a>
is an additional method for returning the values for a given key as a
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collection.html" target="_top">Collection</a>.
</p>
</li>
</ul>
</div>
<p>
Other differences are:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
Collection.size() and Map.size() always throws
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>.
This is because the number of
records in a database cannot be determined reliably or
cheaply.
</p>
</li>
<li>
<p>
Because the size() method cannot be used, the bulk operation
methods of standard Java collections cannot be passed stored
collections as parameters, since the implementations rely on
size(). However, the bulk operation methods of stored collections
can be passed standard Java collections as parameters.
<tt class="literal">storedCollection.addAll(standardCollection)</tt> is allowed
while <tt class="literal">standardCollection.addAll(storedCollection)</tt> is
<span class="emphasis"><em>not</em></span> allowed. This restriction applies to the standard
collection constructors that take a Collection parameter (copy
constructors), the Map.putAll() method, and the following
Collection methods: addAll(), containsAll(), removeAll() and
retainAll().
</p>
</li>
<li>
<p>
The <tt class="methodname">ListIterator.nextIndex()</tt> method
returns <tt class="literal">Integer.MAX_VALUE</tt>
for stored lists when positioned at the end of the list, rather
than returning the list size as specified by the ListIterator
interface. Again, this is because the database size is not
available.
</p>
</li>
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Comparator.html" target="_top">Comparator</a>
objects cannot be used and the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedMap.html#comparator()" target="_top">SortedMap.comparator()</a>
and
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedSet.html#comparator()" target="_top">SortedSet.comparator()</a>
methods always return null. The
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Comparable.html" target="_top">Comparable</a>
interface is not supported. However, Comparators that operate on
byte arrays may be specified using
<span>
<a href="../../java/com/sleepycat/db/DatabaseConfig.html#setBtreeComparator(java.util.Comparator)" target="_top">DatabaseConfig.setBtreeComparator</a>.
</span>
</p>
</li>
<li>
<p>
The
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Object.html#equals()" target="_top">Object.equals()</a>
method is not used to determine whether a key
or value is contained in a collection, to locate a value by key,
etc. Instead the byte array representation of the keys and values
are used. However, the equals() method <span class="emphasis"><em>is</em></span> called for each
key and value when comparing two collections for equality. It is
the responsibility of the application to make sure that the
equals() method returns true if and only if the byte array
representations of the two objects are equal. Normally this occurs
naturally since the byte array representation is derived from the
object's fields.
</p>
</li>
</ul>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="StoredCollectionCharacteristics"></a>
Other Stored Collection Characteristics
</h3>
</div>
</div>
<div></div>
</div>
<p>
The following characteristics of stored collections are
extensions of the definitions in the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/package-summary.html" target="_top">java.util</a>
package. These differences do not violate the Java
collections interface contract.
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
All stored collections are thread safe (can be used by multiple
threads concurrently)
<span>
whenever the Berkeley DB Concurrent Data Store or
Transactional Data Store environment is used.
</span>
Locking is handled by the Berkeley DB
environment. To access a collection from multiple threads, creation
of synchronized collections using the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collections.html" target="_top">Collections</a>
class is not necessary
<span>
except when using the Data Store environment.
</span>
Iterators, however, should always be used only by a single thread.
</p>
</li>
<li>
<p>
All stored collections may be read-only if desired by passing
false for the writeAllowed parameter of their constructor. Creation
of immutable collections using the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collections.html" target="_top">Collections</a>
class is not necessary.
</p>
</li>
<li>
<p>
A stored collection is partially read-only if a secondary
index is used. Specifically, values may be removed but may not be
added or updated. The following methods will throw
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>
when an index is used:
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collection.html#add()" target="_top">Collection.add()</a>,
<span><a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/List.html#set()" target="_top">List.set()</a>,</span>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#set()" target="_top">ListIterator.set()</a>
and
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.Entry.html#setValue()" target="_top">Map.Entry.setValue()</a>.
</p>
</li>
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedMap.html#entrySet()" target="_top">SortedMap.entrySet()</a>
and
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedMap.html#keySet()" target="_top">SortedMap.keySet()</a>
return a
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>,
not just a
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html" target="_top">Set</a>
as specified in Java collections interface. This allows using the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>
methods on the returned collection.
</p>
</li>
<li>
<p>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedMap.html#values()" target="_top">SortedMap.values()</a>
returns a
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>,
not just a
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collection.html" target="_top">Collection</a>,
whenever the keys of the map can be derived from the values using
an entity binding. Note that the sorted set returned is not really
a set if duplicates are allowed, since it is technically a
collection; however, the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>
methods (for example, subSet()), can still be used.
</p>
</li>
<li>
<p>
For
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>
and
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedMap.html" target="_top">SortedMap</a>
views, additional subSet() and subMap() methods are provided that
allow control over whether keys are treated as inclusive or
exclusive values in the key range.
</p>
</li>
<li>
<p>
Keys and values are stored by value, not by reference. This is
because objects that are added to collections are converted to byte
arrays (by bindings) and stored in the database. When they are
retrieved from the collection they are read from the database and
converted from byte arrays to objects. Therefore, the object
reference added to a collection will not be the same as the
reference later retrieved from the collection.
</p>
</li>
<li>
<p>
A runtime exception,
<a href="../../java/com/sleepycat/util/RuntimeExceptionWrapper.html" target="_top">RuntimeExceptionWrapper</a>,
is thrown whenever database exceptions occur which are not runtime
exceptions. The
<a href="../../java/com/sleepycat/util/RuntimeExceptionWrapper.html#getCause()" target="_top">RuntimeExceptionWrapper.getCause()</a>
method can be called to get the underlying exception.
</p>
</li>
<li>
<p>
All iterators for stored collections implement the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html" target="_top">ListIterator</a>
interface as well as the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Iterator.html" target="_top">Iterator</a>
interface. This is to allow use of the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#hasPrevious()" target="_top">ListIterator.hasPrevious()</a>
and
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#previous()" target="_top">ListIterator.previous()</a>
methods, which work for all collections
since Berkeley DB provides bidirectional cursors.
</p>
</li>
<li>
<p>
All stored collections have a
<a href="../../java/com/sleepycat/collections/StoredCollection.html#iterator(boolean)" target="_top">StoredCollection.iterator(boolean)</a>
method that allows creating
a read-only iterator for a writable collection. For the standard
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collection.html#iterator()" target="_top">Collection.iterator()</a>
method, the iterator is read-only only
when the collection is read-only.
<span>Read-only iterators are important
for using the Berkeley DB Concurrent Data Store environment, since
only one write cursors may be open at one time.</span>
</p>
</li>
<li>
<p>
Iterator stability for stored collections is greater than the
iterator stability defined by the Java collections interfaces.
Stored iterator stability is the same as the cursor stability
defined by Berkeley DB.
</p>
</li>
<li>
<p>
When an entity binding is used, updating (setting) a value is
not allowed if the key in the entity is not equal to the original
key. For example, calling
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#put()" target="_top">Map.put()</a>
is not allowed when the key parameter is not equal to the key of
the entity parameter.
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#put()" target="_top">Map.put()</a>,
<span><a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/List.html#set()" target="_top">List.set()</a>,</span>
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#set()" target="_top">ListIterator.set()</a>,
and
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.Entry.html#setValue()" target="_top">Map.Entry.setValue()</a>
will throw
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/IllegalArgumentException.html" target="_top">IllegalArgumentException</a>
in this situation.
</p>
</li>
<li>
<p>
Adding and removing items from stored lists is not allowed for
sublists. This is simply an unimplemented feature and may be
changed in the future. Currently for sublists the following
methods throw
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>:
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/List.html#add()" target="_top">List.add()</a><tt class="methodname">List.add()</tt>,
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/List.html#remove()" target="_top">List.remove()</a><tt class="methodname">List.remove()</tt>,
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#add()" target="_top">ListIterator.add()</a>
and
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/ListIterator.html#remove()" target="_top">ListIterator.remove()</a><tt class="methodname">ListIterator.remove()</tt>.
</p>
</li>
<li>
<p>
The
<span>
<a href="../../java/com/sleepycat/collections/StoredList.html#append(java.lang.Object)" target="_top">StoredList.append(java.lang.Object)</a>
and
</span>
<a href="../../java/com/sleepycat/collections/StoredMap.html#append(java.lang.Object)" target="_top">StoredMap.append(java.lang.Object)</a>
extension method<span>s</span> allows
adding a new record with an automatically assigned key.
<span>
Record number assignment by the database itself is supported
for QUEUE, RECNO and RECNO-RENUMBER databases.
</span>
An application-defined
<a href="../../java/com/sleepycat/collections/PrimaryKeyAssigner.html" target="_top">PrimaryKeyAssigner</a>
is used to assign the key value.
</p>
</li>
</ul>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="WhyJavaCollections"></a>
Why Java Collections for Berkeley DB
</h3>
</div>
</div>
<div></div>
</div>
<p>
The Java collections interface was chosen as the best Java API
for DB given these requirements:
</p>
<div class="orderedlist">
<ol type="1">
<li>
<p>
Provide the Java developer with an API that is as familiar and
easy to use as possible.
</p>
</li>
<li>
<p>
Provide access to all, or a large majority, of the features of
the underlying Berkeley DB storage system.
</p>
</li>
<li>
<p>
Compared to the DB API, provide a higher-level API
that is oriented toward Java developers.
</p>
</li>
<li>
<p>
For ease of use, support object-to-data bindings, per-thread
transactions, and some traditional database features such as
foreign keys.
</p>
</li>
<li>
<p>
Provide a thin layer that can be thoroughly tested and which
does not significantly impact the reliability and performance of
DB.
</p>
</li>
</ol>
</div>
<p>
Admittedly there are several things about the Java Collections
API that don't quite fit with DB or with any transactional
database, and therefore there are some new rules for applying the
Java Collections API. However, these disadvantages are considered
to be smaller than the disadvantages of the alternatives:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
A new API not based on the Java Collections API could have been
designed that maps well to DB but is higher-level.
However, this would require designing an entirely new model. The
exceptions for using the Java Collections API are considered easier
to learn than a whole new model. A new model would also require a
long design stabilization period before being as complete and
understandable as either the Java Collections API or the DB
API.
</p>
</li>
<li>
<p>
The ODMG API or another object persistence API could have been
implemented on top of DB. However, an object persistence
implementation would add much code and require a long stabilization
period. And while it may work well for applications that require
object persistence, it would probably never perform well enough for
many other applications.
</p>
</li>
</ul>
</div>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="UsingCollectionsAPI.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="collectionOverview.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="SerializedObjectStorage.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Using the DB Java Collections API
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Serialized Object Storage
</td>
</tr>
</table>
</div>
</body>
</html>

229
docs/collections/tutorial/addingdatabaseitems.html Normal file
View File

@@ -0,0 +1,229 @@
<?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>
Adding Database Items
</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="BasicProgram.html" title="Chapter 2. &#10;&#9;&#9;The Basic Program&#10;&#9;" />
<link rel="previous" href="usingtransactions.html" title="&#10;&#9;&#9;Using Transactions&#10;&#9;" />
<link rel="next" href="retrievingdatabaseitems.html" title="&#10;&#9;&#9;Retrieving Database Items&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Adding Database Items
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="usingtransactions.html">Prev</a> </td>
<th width="60%" align="center">Chapter 2. 
The Basic Program
</th>
<td width="20%" align="right"> <a accesskey="n" href="retrievingdatabaseitems.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="addingdatabaseitems"></a>
Adding Database Items
</h2>
</div>
</div>
<div></div>
</div>
<p>
Adding (as well as updating, removing, and deleting) information
in the database is accomplished via the standard Java collections
API. In the example, the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#put" target="_top">Map.put</a>
method is used to add objects. All standard Java methods for
modifying a collection may be used with the DB Java Collections API.
</p>
<p>
The <tt class="methodname">PopulateDatabase.doWork()</tt> method calls private methods
for adding objects to each of the three database stores. It is
called via the
<a href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>
class and was outlined in the previous section.
</p>
<a id="cb_populatedatabase"></a>
<pre class="programlisting">import java.util.Map;
import com.sleepycat.collections.TransactionWorker;
...
public class Sample
{
...
private SampleViews views;
...
private class PopulateDatabase implements TransactionWorker
{
public void doWork()
throws Exception
{
<b class="userinput"><tt> addSuppliers();
addParts();
addShipments();</tt></b>
}
}
...
<b class="userinput"><tt> private void addSuppliers()
{
}
private void addParts()
{
}
private void addShipments()
{
}</tt></b>
} </pre>
<p>
The <tt class="methodname">addSuppliers()</tt>, <tt class="methodname">addParts()</tt> and <tt class="methodname">addShipments()</tt>
methods add objects to the Suppliers, Parts and Shipments stores.
The
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html" target="_top">Map</a>
for each store is obtained from the <tt class="classname">SampleViews</tt> object.
</p>
<a id="cb_addsuppliers"></a>
<pre class="programlisting"> private void addSuppliers()
{
<b class="userinput"><tt> Map suppliers = views.getSupplierMap();
if (suppliers.isEmpty())
{
System.out.println("Adding Suppliers");
suppliers.put(new SupplierKey("S1"),
new SupplierData("Smith", 20, "London"));
suppliers.put(new SupplierKey("S2"),
new SupplierData("Jones", 10, "Paris"));
suppliers.put(new SupplierKey("S3"),
new SupplierData("Blake", 30, "Paris"));
suppliers.put(new SupplierKey("S4"),
new SupplierData("Clark", 20, "London"));
suppliers.put(new SupplierKey("S5"),
new SupplierData("Adams", 30, "Athens"));
}</tt></b>
}
private void addParts()
{
<b class="userinput"><tt> Map parts = views.getPartMap();
if (parts.isEmpty())
{
System.out.println("Adding Parts");
parts.put(new PartKey("P1"),
new PartData("Nut", "Red",
new Weight(12.0, Weight.GRAMS),
"London"));
parts.put(new PartKey("P2"),
new PartData("Bolt", "Green",
new Weight(17.0, Weight.GRAMS),
"Paris"));
parts.put(new PartKey("P3"),
new PartData("Screw", "Blue",
new Weight(17.0, Weight.GRAMS),
"Rome"));
parts.put(new PartKey("P4"),
new PartData("Screw", "Red",
new Weight(14.0, Weight.GRAMS),
"London"));
parts.put(new PartKey("P5"),
new PartData("Cam", "Blue",
new Weight(12.0, Weight.GRAMS),
"Paris"));
parts.put(new PartKey("P6"),
new PartData("Cog", "Red",
new Weight(19.0, Weight.GRAMS),
"London"));
}</tt></b>
}
private void addShipments()
{
<b class="userinput"><tt> Map shipments = views.getShipmentMap();
if (shipments.isEmpty())
{
System.out.println("Adding Shipments");
shipments.put(new ShipmentKey("P1", "S1"),
new ShipmentData(300));
shipments.put(new ShipmentKey("P2", "S1"),
new ShipmentData(200));
shipments.put(new ShipmentKey("P3", "S1"),
new ShipmentData(400));
shipments.put(new ShipmentKey("P4", "S1"),
new ShipmentData(200));
shipments.put(new ShipmentKey("P5", "S1"),
new ShipmentData(100));
shipments.put(new ShipmentKey("P6", "S1"),
new ShipmentData(100));
shipments.put(new ShipmentKey("P1", "S2"),
new ShipmentData(300));
shipments.put(new ShipmentKey("P2", "S2"),
new ShipmentData(400));
shipments.put(new ShipmentKey("P2", "S3"),
new ShipmentData(200));
shipments.put(new ShipmentKey("P2", "S4"),
new ShipmentData(200));
shipments.put(new ShipmentKey("P4", "S4"),
new ShipmentData(300));
shipments.put(new ShipmentKey("P5", "S4"),
new ShipmentData(400));
}</tt></b>
}
}</pre>
<p>
The key and value classes used above were defined in the
<a href="BasicProgram.html#keyandvalueclasses">
Defining Serialized Key and Value Classes
</a>.
</p>
<p>
In each method above, objects are added only if the map is not
empty. This is a simple way of allowing the example program to be
run repeatedly. In real-life applications another technique —
checking the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#containsKey" target="_top">Map.containsKey</a>
method, for example — might be used.
</p>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="usingtransactions.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="retrievingdatabaseitems.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Using Transactions
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Retrieving Database Items
</td>
</tr>
</table>
</div>
</body>
</html>

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>

164
docs/collections/tutorial/collectionswithentities.html Normal file
View File

@@ -0,0 +1,164 @@
<?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 Collections with Entity Bindings
</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="Entity.html" title="Chapter 4. &#10; Using Entity Classes&#9;&#10;&#9;" />
<link rel="previous" href="creatingentitybindings.html" title="&#10;&#9;&#9;Creating Entity Bindings&#10;&#9;" />
<link rel="next" href="entitieswithcollections.html" title="&#10;&#9;&#9;Using Entities with Collections&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Creating Collections with Entity Bindings
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="creatingentitybindings.html">Prev</a> </td>
<th width="60%" align="center">Chapter 4. 
Using Entity Classes
</th>
<td width="20%" align="right"> <a accesskey="n" href="entitieswithcollections.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="collectionswithentities"></a>
Creating Collections with Entity Bindings
</h2>
</div>
</div>
<div></div>
</div>
<p>
Stored map objects are created in this example in the same way
as in prior examples, but using entity bindings in place of value
bindings. All value objects passed and returned to the Java
collections API are then actually entity objects (<tt class="classname">Part</tt>,
<tt class="classname">Supplier</tt> and <tt class="classname">Shipment</tt>). The application no longer
deals directly with plain value objects (<tt class="classname">PartData</tt>,
<tt class="classname">SupplierData</tt> and <tt class="classname">ShipmentData</tt>).
</p>
<p>
Since the <tt class="literal">partValueBinding</tt>, <tt class="literal">supplierValueBinding</tt>
and <tt class="literal">shipmentValueBinding</tt> were defined as entity bindings in
the prior section, there are no source code changes necessary for
creating the stored map objects.
</p>
<a id="entity_sampleviews2"></a>
<pre class="programlisting">public class SampleViews
{
...
public SampleViews(SampleDatabase db)
{
...
partMap =
new StoredMap(db.getPartDatabase(),
partKeyBinding, partValueBinding, true);
supplierMap =
new StoredMap(db.getSupplierDatabase(),
supplierKeyBinding, supplierValueBinding, true);
shipmentMap =
new StoredMap(db.getShipmentDatabase(),
shipmentKeyBinding, shipmentValueBinding, true);
...
} </pre>
<p>
Specifying an
<a href="../../java/com/sleepycat/bind/EntityBinding.html" target="_top">EntityBinding</a>
will select a different
<a href="../../java/com/sleepycat/collections/StoredMap.html" target="_top">StoredMap</a>
constructor, but the syntax is the same. In general, an entity
binding may be used anywhere that a value binding is used.
</p>
<p>
The following getter methods are defined for use by other
classes in the example program. Instead of returning the map's
entry set
(<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#entrySet" target="_top">Map.entrySet</a>),
the map's value set
(<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#values" target="_top">Map.values</a>)
is returned. The entry set was convenient in prior examples because
it allowed enumerating all key/value pairs in the collection. Since
an entity contains the key and the value, enumerating the value set
can now be used more conveniently for the same purpose.
</p>
<a id="entity_sampleviews3"></a>
<pre class="programlisting"><b class="userinput"><tt>import com.sleepycat.collections.StoredValueSet;</tt></b>
...
public class SampleViews
{
...
<b class="userinput"><tt> public StoredValueSet getPartSet()
{
return (StoredValueSet) partMap.values();
}
public StoredValueSet getSupplierSet()
{
return (StoredValueSet) supplierMap.values();
}
public StoredValueSet getShipmentSet()
{
return (StoredValueSet) shipmentMap.values();
}</tt></b>
...
} </pre>
<p>
Notice that the collection returned by the
<a href="../../java/com/sleepycat/collections/StoredMap.html#values()" target="_top">StoredMap.values</a>
method is actually a
<a href="../../java/com/sleepycat/collections/StoredValueSet.html" target="_top">StoredValueSet</a>
and not just a
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collection.html" target="_top">Collection</a>
as defined by the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#values" target="_top">Map.values</a>
interface. As long as duplicate keys are not allowed, this
collection will behave as a true set and will disallow the addition
of duplicates, etc.
</p>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="creatingentitybindings.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="Entity.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="entitieswithcollections.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Creating Entity Bindings
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Using Entities with Collections
</td>
</tr>
</table>
</div>
</body>
</html>

283
docs/collections/tutorial/createbindingscollections.html Normal file
View File

@@ -0,0 +1,283 @@
<?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.62.4" />
<link rel="home" href="index.html" title="Berkeley DB Collections Tutorial" />
<link rel="up" href="BasicProgram.html" title="Chapter 2. &#10;&#9;&#9;The Basic Program&#10;&#9;" />
<link rel="previous" href="opendatabases.html" title="&#10;&#9;&#9;Opening and Closing Databases&#10;&#9;" />
<link rel="next" href="implementingmain.html" title="&#10;&#9;&#9;Implementing the Main Program&#10;&#9;" />
</head>
<body>
<div class="navheader">
<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></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 <tt class="classname">SampleViews</tt> class is used to create the bindings and
collections. This class is separate from the <tt class="classname">SampleDatabase</tt>
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 <tt class="classname">SampleViews</tt> class follows.
</p>
<a id="cb_sampleviews"></a>
<pre class="programlisting"><b class="userinput"><tt>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)
{
}
}</tt></b> </pre>
<p>
A
<a 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 href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html" target="_top">Map</a>
interface, which has methods for obtaining a
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html" target="_top">Set</a>
of keys, a
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collection.html" target="_top">Collection</a>
of values, or a
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html" target="_top">Set</a>
of
<a href="http://java.sun.com/j2se/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 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)
{
<b class="userinput"><tt> 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);</tt></b>
...
} </pre>
<p>
The first parameter of the
<a 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
<tt class="literal">null</tt> or <tt class="literal">Object.class</tt> 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 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)
{
...
<b class="userinput"><tt> partMap =
new StoredMap(db.getPartDatabase(),
partKeyBinding, partValueBinding, true);
supplierMap =
new StoredMap(db.getSupplierDatabase(),
supplierKeyBinding, supplierValueBinding, true);
shipmentMap =
new StoredMap(db.getShipmentDatabase(),
shipmentKeyBinding, shipmentValueBinding, true);</tt></b>
...
} </pre>
<p>
The first parameter of the
<a 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
{
...
<b class="userinput"><tt> 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();
}</tt></b>
...
} </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>
<tt class="classname">StoredMap</tt>, <tt class="classname">StoredEntrySet</tt>,
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"><b class="userinput"><tt> SampleDatabase sd = new SampleDatabase(new String("/home"));
SampleViews views = new SampleViews(sd);
Map partMap = views.getPartMap();
Set supplierEntries = views.getSupplierEntrySet();</tt></b> </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>

268
docs/collections/tutorial/creatingentitybindings.html Normal file
View File

@@ -0,0 +1,268 @@
<?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 Entity Bindings
</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="Entity.html" title="Chapter 4. &#10; Using Entity Classes&#9;&#10;&#9;" />
<link rel="previous" href="Entity.html" title="Chapter 4. &#10; Using Entity Classes&#9;&#10;&#9;" />
<link rel="next" href="collectionswithentities.html" title="&#10;&#9;&#9;Creating Collections with Entity Bindings&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Creating Entity Bindings
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="Entity.html">Prev</a> </td>
<th width="60%" align="center">Chapter 4. 
Using Entity Classes
</th>
<td width="20%" align="right"> <a accesskey="n" href="collectionswithentities.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="creatingentitybindings"></a>
Creating Entity Bindings
</h2>
</div>
</div>
<div></div>
</div>
<p>
<span class="emphasis"><em>Entity bindings</em></span> are similar to ordinary bindings in that
they convert between Java objects and the stored data format of
keys and values. In addition, entity bindings map between key/value
pairs and entity objects. An ordinary binding is a one-to-one
mapping, while an entity binding is a two-to-one mapping.
</p>
<p>
The <tt class="literal">partValueBinding</tt>, <tt class="literal">supplierValueBinding</tt> and
<tt class="literal">shipmentValueBinding</tt> bindings are created below as entity
bindings rather than (in the prior examples) serial bindings.
</p>
<a id="entity_sampleviews"></a>
<pre class="programlisting">import com.sleepycat.bind.EntryBinding;
<b class="userinput"><tt>import com.sleepycat.bind.EntityBinding;</tt></b>
import com.sleepycat.bind.serial.SerialBinding;
<b class="userinput"><tt>import com.sleepycat.bind.serial.SerialSerialBinding;</tt></b>
...
public class SampleViews
{
...
public SampleViews(SampleDatabase db)
{
ClassCatalog catalog = db.getClassCatalog();
SerialBinding partKeyBinding =
new SerialBinding(catalog, PartKey.class);
<b class="userinput"><tt> EntityBinding partValueBinding =
new PartBinding(catalog, PartKey.class, PartData.class);</tt></b>
SerialBinding supplierKeyBinding =
new SerialBinding(catalog, SupplierKey.class);
<b class="userinput"><tt> EntityBinding supplierValueBinding =
new SupplierBinding(catalog, SupplierKey.class,
SupplierData.class);</tt></b>
SerialBinding shipmentKeyBinding =
new SerialBinding(catalog, ShipmentKey.class);
<b class="userinput"><tt> EntityBinding shipmentValueBinding =
new ShipmentBinding(catalog, ShipmentKey.class,
ShipmentData.class);</tt></b>
SerialBinding cityKeyBinding =
new SerialBinding(catalog, String.class);
...
}
} </pre>
<p>
The entity bindings will be used in the next section to
construct stored map objects.
</p>
<p>
The <tt class="classname">PartBinding</tt> class is defined below.
</p>
<a id="entity_partbinding"></a>
<pre class="programlisting">public class SampleViews
{
...
<b class="userinput"><tt> private static class PartBinding extends SerialSerialBinding {
private PartBinding(ClassCatalog classCatalog,
Class keyClass,
Class dataClass)
{
super(classCatalog, keyClass, dataClass);
}
public Object entryToObject(Object keyInput, Object dataInput)
{
PartKey key = (PartKey) keyInput;
PartData data = (PartData) dataInput;
return new Part(key.getNumber(), data.getName(), data.getColor(),
data.getWeight(), data.getCity());
}
public Object objectToKey(Object object)
{
Part part = (Part) object;
return new PartKey(part.getNumber());
}
public Object objectToData(Object object)
{
Part part = (Part) object;
return new PartData(part.getName(), part.getColor(),
part.getWeight(), part.getCity());
}
}</tt></b>
...
} </pre>
<p>
In general, an entity binding is any class that implements the
<a href="../../java/com/sleepycat/bind/EntityBinding.html" target="_top">EntityBinding</a>
interface, just as an ordinary binding is any class that implements
the
<a href="../../java/com/sleepycat/bind/EntryBinding.html" target="_top">EntryBinding</a>
interface. In the prior examples the built-in
<a href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a>
class (which implements
<a href="../../java/com/sleepycat/bind/EntryBinding.html" target="_top">EntryBinding</a>)
was used and no application-defined binding classes were needed.
</p>
<p>
In this example, application-defined binding classes are used
that extend the
<a href="../../java/com/sleepycat/bind/serial/SerialSerialBinding.html" target="_top">SerialSerialBinding</a>
abstract base class. This base class implements
<a href="../../java/com/sleepycat/bind/EntityBinding.html" target="_top">EntityBinding</a>
and provides the conversions between key/value bytes and key/value
objects, just as the
<a href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a>
class does. The application-defined entity class implements the
abstract methods defined in the base class that map between
key/value objects and entity objects.
</p>
<p>
Three abstract methods are implemented for each entity binding.
The <tt class="methodname">entryToObject()</tt> method takes as input the key and data
objects, which have been deserialized automatically by the base
class. As output, it returns the combined <tt class="classname">Part</tt> entity.
</p>
<p>
The <tt class="methodname">objectToKey()</tt> and <tt class="methodname">objectToData()</tt> methods take an
entity object as input. As output they return the part key or data
object that is extracted from the entity object. The key or data
will then be serialized automatically by the base class.
</p>
<p>
The <tt class="classname">SupplierBinding</tt> and <tt class="classname">ShipmentBinding</tt> classes
are very similar to the <tt class="classname">PartBinding</tt> class.
</p>
<a id="entity_supplierbinding"></a>
<pre class="programlisting">public class SampleViews
{
...
<b class="userinput"><tt> private static class SupplierBinding extends SerialSerialBinding {
private SupplierBinding(ClassCatalog classCatalog,
Class keyClass,
Class dataClass)
{
super(classCatalog, keyClass, dataClass);
}
public Object entryToObject(Object keyInput, Object dataInput)
{
SupplierKey key = (SupplierKey) keyInput;
SupplierData data = (SupplierData) dataInput;
return new Supplier(key.getNumber(), data.getName(),
data.getStatus(), data.getCity());
}
public Object objectToKey(Object object)
{
Supplier supplier = (Supplier) object;
return new SupplierKey(supplier.getNumber());
}
public Object objectToData(Object object)
{
Supplier supplier = (Supplier) object;
return new SupplierData(supplier.getName(), supplier.getStatus(),
supplier.getCity());
}
}
private static class ShipmentBinding extends SerialSerialBinding {
private ShipmentBinding(ClassCatalog classCatalog,
Class keyClass,
Class dataClass)
{
super(classCatalog, keyClass, dataClass);
}
public Object entryToObject(Object keyInput, Object dataInput)
{
ShipmentKey key = (ShipmentKey) keyInput;
ShipmentData data = (ShipmentData) dataInput;
return new Shipment(key.getPartNumber(), key.getSupplierNumber(),
data.getQuantity());
}
public Object objectToKey(Object object)
{
Shipment shipment = (Shipment) object;
return new ShipmentKey(shipment.getPartNumber(),
shipment.getSupplierNumber());
}
public Object objectToData(Object object)
{
Shipment shipment = (Shipment) object;
return new ShipmentData(shipment.getQuantity());
}
}</tt></b>
...
} </pre>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="Entity.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="Entity.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="collectionswithentities.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 4. 
Using Entity Classes
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Creating Collections with Entity Bindings
</td>
</tr>
</table>
</div>
</body>
</html>

216
docs/collections/tutorial/developing.html Normal file
View File

@@ -0,0 +1,216 @@
<?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>Developing a DB Collections Application</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="intro.html" title="Chapter 1. &#10; Introduction&#10; " />
<link rel="previous" href="intro.html" title="Chapter 1. &#10; Introduction&#10; " />
<link rel="next" href="tutorialintroduction.html" title="Tutorial Introduction" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Developing a DB Collections Application</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="intro.html">Prev</a> </td>
<th width="60%" align="center">Chapter 1. 
Introduction
</th>
<td width="20%" align="right"> <a accesskey="n" href="tutorialintroduction.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="developing"></a>Developing a DB Collections Application</h2>
</div>
</div>
<div></div>
</div>
<p>
There are several important choices to make when developing an
application using the DB Java Collections API.
</p>
<div class="orderedlist">
<ol type="1">
<li>
<p>
Choose the Berkeley DB Environment
</p>
<p>
Depending on your application's concurrency and transactional
requirements, you may choose one of the three Berkeley DB
Environments: Data Store, Concurrent Data Store, or
Transactional Data Store. For details on creating and
configuring the environment, see the
<i class="citetitle">Berkeley DB Programmer's Reference Guide</i>
</p>
</li>
<li>
<p>
Choose the Berkeley DB Access Method
</p>
<p>
For each Berkeley DB datastore, you may choose from any of the
four Berkeley DB access methods — BTREE, HASH, RECNO, or
QUEUE
<span class="html">
(<a href="../../java/com/sleepycat/db/DatabaseType.html#BTREE" target="_top">DatabaseType.BTREE</a>,
<a href="../../java/com/sleepycat/db/DatabaseType.html#HASH" target="_top">DatabaseType.HASH</a>,
<a href="../../java/com/sleepycat/db/DatabaseType.html#RECNO" target="_top">DatabaseType.RECNO</a>,
or
<a href="../../java/com/sleepycat/db/DatabaseType.html#QUEUE" target="_top">DatabaseType.QUEUE</a>.)
</span>
— and a number of other database options. Your choice
depends on several factors such as whether you need ordered
keys, unique keys, record number access, and so forth. For more
information on access methods, see the
<i class="citetitle">Berkeley DB Programmer's Reference Guide</i>.
</p>
</li>
<li>
<p>
Choose the Format for Keys and Values
</p>
<p>
For each database you may choose a binding format for the keys
and values. For example, the tuple format is useful for keys
because it has a deterministic sort order. The serial format is
useful for values if you want to store arbitrary Java objects. In
some cases a custom format may be appropriate. For details on
choosing a binding format see
<a href="collectionOverview.html#UsingDataBindings">
Using Data Bindings
</a>.
</p>
</li>
<li>
<p>
Choose the Binding for Keys and Values
</p>
<p>
With the serial data format you do not have to create a binding
for each Java class that is stored since Java serialization is
used. But for other formats a binding must be defined that
translates between stored byte arrays and Java objects. For details
see
<a href="collectionOverview.html#UsingDataBindings">
Using Data Bindings
</a>.
</p>
</li>
<li>
<p>
Choose Secondary Indices
</p>
<p>
Any database that has unique keys may have any number of
secondary indices. A secondary index has keys that are derived from
data values in the primary database. This allows lookup and
iteration of objects in the database by its index keys.
For each index you must define how the index keys are derived from the data
values using a
<span>
<a href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>.
</span>
For details see the
<span>
<a href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>,
</span>
<a href="../../java/com/sleepycat/db/SecondaryConfig.html" target="_top">SecondaryConfig</a>
and
<a href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>
classes.
</p>
</li>
<li>
<p>
Choose the Collection Interface for each Database
</p>
<p>
The standard Java Collection interfaces are used for accessing
databases and secondary indices. The Map and Set interfaces may be
used for any type of database. The Iterator interface is used
through the Set interfaces. For more information on the collection
interfaces see
<a href="UsingStoredCollections.html">
Using Stored Collections
</a>.
</p>
</li>
</ol>
</div>
<p>
Any number of bindings and collections may be created for the
same database. This allows multiple views of the same stored data.
For example, a data store may be viewed as a Map of keys to values,
a Set of keys, or a Collection of values. String values, for
example, may be used with the built-in binding to the String class,
or with a custom binding to another class that represents the
string values differently.
</p>
<p>
It is sometimes desirable to use a Java class that encapsulates
both a data key and a data value. For example, a Part object might
contain both the part number (key) and the part name (value). Using
the DB Java Collections API this type of object is called an
"entity". An entity binding is used to translate between the Java
object and the stored data key and value. Entity bindings may be
used with all Collection types.
</p>
<p>
Please be aware that the provided DB Java Collections API collection classes
do not conform completely to the interface contracts
defined in the <tt class="literal">java.util</tt> package. For example, all
iterators must be explicitly closed and the <tt class="methodname">size()</tt>
method is not available. The differences between the DB Java Collections API
collections and the standard Java collections are
documented in
<a href="UsingStoredCollections.html#StoredVersusStandardCollections">
Stored Collections Versus Standard Java Collections
</a>.
</p>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="intro.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="intro.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="tutorialintroduction.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 1. 
Introduction
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Tutorial Introduction</td>
</tr>
</table>
</div>
</body>
</html>

251
docs/collections/tutorial/entitieswithcollections.html Normal file
View File

@@ -0,0 +1,251 @@
<?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>
Using Entities with Collections
</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="Entity.html" title="Chapter 4. &#10; Using Entity Classes&#9;&#10;&#9;" />
<link rel="previous" href="collectionswithentities.html" title="&#10;&#9;&#9;Creating Collections with Entity Bindings&#10;&#9;" />
<link rel="next" href="Tuple.html" title="Chapter 5. &#10;&#9;&#9;Using Tuples&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Using Entities with Collections
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="collectionswithentities.html">Prev</a> </td>
<th width="60%" align="center">Chapter 4. 
Using Entity Classes
</th>
<td width="20%" align="right"> <a accesskey="n" href="Tuple.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="entitieswithcollections"></a>
Using Entities with Collections
</h2>
</div>
</div>
<div></div>
</div>
<p>
In this example entity objects, rather than key and value
objects, are used for adding and enumerating the records in a
collection. Because fewer classes and objects are involved, adding
and enumerating is done more conveniently and more simply than in
the prior examples.
</p>
<p>
For adding and iterating entities, the collection of entities
returned by
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#values" target="_top">Map.values</a>
is used. In general, when using an entity binding, all Java
collection methods that are passed or returned a value object will
be passed or returned an entity object instead.
</p>
<p>
The <tt class="classname">Sample</tt> class has been changed in this example to add
objects using the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html#add" target="_top">Set.add</a>
method rather than the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#put" target="_top">Map.put</a>
method that was used in the prior examples. Entity objects are
constructed and passed to
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html#add" target="_top">Set.add</a>.
</p>
<a id="entity_addsuppliers"></a>
<pre class="programlisting">import java.util.Set;
...
public class Sample
{
...
private void addSuppliers()
{
<b class="userinput"><tt> Set suppliers = views.getSupplierSet();
if (suppliers.isEmpty())
{
System.out.println("Adding Suppliers");
suppliers.add(new Supplier("S1", "Smith", 20, "London"));
suppliers.add(new Supplier("S2", "Jones", 10, "Paris"));
suppliers.add(new Supplier("S3", "Blake", 30, "Paris"));
suppliers.add(new Supplier("S4", "Clark", 20, "London"));
suppliers.add(new Supplier("S5", "Adams", 30, "Athens"));
}</tt></b>
}
private void addParts()
{
<b class="userinput"><tt> Set parts = views.getPartSet();
if (parts.isEmpty())
{
System.out.println("Adding Parts");
parts.add(new Part("P1", "Nut", "Red",
new Weight(12.0, Weight.GRAMS), "London"));
parts.add(new Part("P2", "Bolt", "Green",
new Weight(17.0, Weight.GRAMS), "Paris"));
parts.add(new Part("P3", "Screw", "Blue",
new Weight(17.0, Weight.GRAMS), "Rome"));
parts.add(new Part("P4", "Screw", "Red",
new Weight(14.0, Weight.GRAMS), "London"));
parts.add(new Part("P5", "Cam", "Blue",
new Weight(12.0, Weight.GRAMS), "Paris"));
parts.add(new Part("P6", "Cog", "Red",
new Weight(19.0, Weight.GRAMS), "London"));
}</tt></b>
}
private void addShipments()
{
<b class="userinput"><tt> Set shipments = views.getShipmentSet();
if (shipments.isEmpty())
{
System.out.println("Adding Shipments");
shipments.add(new Shipment("P1", "S1", 300));
shipments.add(new Shipment("P2", "S1", 200));
shipments.add(new Shipment("P3", "S1", 400));
shipments.add(new Shipment("P4", "S1", 200));
shipments.add(new Shipment("P5", "S1", 100));
shipments.add(new Shipment("P6", "S1", 100));
shipments.add(new Shipment("P1", "S2", 300));
shipments.add(new Shipment("P2", "S2", 400));
shipments.add(new Shipment("P2", "S3", 200));
shipments.add(new Shipment("P2", "S4", 200));
shipments.add(new Shipment("P4", "S4", 300));
shipments.add(new Shipment("P5", "S4", 400));
}</tt></b>
} </pre>
<p>
Instead of printing the key/value pairs by iterating over the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#entrySet" target="_top">Map.entrySet</a>
as done in the prior example, this example
iterates over the entities in the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#values" target="_top">Map.values</a>
collection.
</p>
<a id="entity_printdatabase"></a>
<pre class="programlisting">import java.util.Iterator;
import java.util.Set;
...
public class Sample
{
...
private class PrintDatabase implements TransactionWorker
{
public void doWork()
throws Exception
{
<b class="userinput"><tt> printValues("Parts",
views.getPartSet().iterator());
printValues("Suppliers",
views.getSupplierSet().iterator());</tt></b>
printValues("Suppliers for City Paris",
views.getSupplierByCityMap().duplicates(
"Paris").iterator());
<b class="userinput"><tt> printValues("Shipments",
views.getShipmentSet().iterator());</tt></b>
printValues("Shipments for Part P1",
views.getShipmentByPartMap().duplicates(
new PartKey("P1")).iterator());
printValues("Shipments for Supplier S1",
views.getShipmentBySupplierMap().duplicates(
new SupplierKey("S1")).iterator());
}
}
...
} </pre>
<p>
The output of the example program is shown below.
</p>
<pre class="programlisting">Adding Suppliers
Adding Parts
Adding Shipments
--- Parts ---
Part: number=P1 name=Nut color=Red weight=[12.0 grams] city=London
Part: number=P2 name=Bolt color=Green weight=[17.0 grams] city=Paris
Part: number=P3 name=Screw color=Blue weight=[17.0 grams] city=Rome
Part: number=P4 name=Screw color=Red weight=[14.0 grams] city=London
Part: number=P5 name=Cam color=Blue weight=[12.0 grams] city=Paris
Part: number=P6 name=Cog color=Red weight=[19.0 grams] city=London
--- Suppliers ---
Supplier: number=S1 name=Smith status=20 city=London
Supplier: number=S2 name=Jones status=10 city=Paris
Supplier: number=S3 name=Blake status=30 city=Paris
Supplier: number=S4 name=Clark status=20 city=London
Supplier: number=S5 name=Adams status=30 city=Athens
--- Suppliers for City Paris ---
Supplier: number=S2 name=Jones status=10 city=Paris
Supplier: number=S3 name=Blake status=30 city=Paris
--- Shipments ---
Shipment: part=P1 supplier=S1 quantity=300
Shipment: part=P1 supplier=S2 quantity=300
Shipment: part=P2 supplier=S1 quantity=200
Shipment: part=P2 supplier=S2 quantity=400
Shipment: part=P2 supplier=S3 quantity=200
Shipment: part=P2 supplier=S4 quantity=200
Shipment: part=P3 supplier=S1 quantity=400
Shipment: part=P4 supplier=S1 quantity=200
Shipment: part=P4 supplier=S4 quantity=300
Shipment: part=P5 supplier=S1 quantity=100
Shipment: part=P5 supplier=S4 quantity=400
Shipment: part=P6 supplier=S1 quantity=100
--- Shipments for Part P1 ---
Shipment: part=P1 supplier=S1 quantity=300
Shipment: part=P1 supplier=S2 quantity=300
--- Shipments for Supplier S1 ---
Shipment: part=P1 supplier=S1 quantity=300
Shipment: part=P2 supplier=S1 quantity=200
Shipment: part=P3 supplier=S1 quantity=400
Shipment: part=P4 supplier=S1 quantity=200
Shipment: part=P5 supplier=S1 quantity=100
Shipment: part=P6 supplier=S1 quantity=100 </pre>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="collectionswithentities.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="Entity.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="Tuple.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Creating Collections with Entity Bindings
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Chapter 5. 
Using Tuples
</td>
</tr>
</table>
</div>
</body>
</html>

41
docs/collections/tutorial/gettingStarted.css Normal file
View File

@@ -0,0 +1,41 @@
body { width: 45em;
margin-left: 3em;
font-family: Arial, Helvetica, sans-serif;
font-size: 11pt;
}
h2.title { margin-left: -1em;
font-family: Verdana, serif;
font-size: 16pt;
}
h3.title { font-family: Verdana, serif;
font-size: 14pt;
}
pre.programlisting {
font-family: monospace;
background-color: #eae8e9;
}
div.navheader { font-size: 9pt;
width: 60em;
margin-left: -2em;
}
div.navheader table tr td { font-size: 9pt; }
div.navfooter { font-size: 9pt;
width: 60em;
margin-left: -2em;
}
div.navfooter table tr td { font-size: 9pt; }
span.emphasis { font-style: italic; font-size: 9pt;}
div.appendix div.informaltable { font-size: 9pt; }
div.appendix div.informaltable td { vertical-align: top; }
div.appendix div.informaltable p { margin-top: .25em; }
div.appendix div.informaltable p { margin-bottom: .25em; }

215
docs/collections/tutorial/handlingexceptions.html Normal file
View File

@@ -0,0 +1,215 @@
<?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>
Handling Exceptions
</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="BasicProgram.html" title="Chapter 2. &#10;&#9;&#9;The Basic Program&#10;&#9;" />
<link rel="previous" href="retrievingdatabaseitems.html" title="&#10;&#9;&#9;Retrieving Database Items&#10;&#9;" />
<link rel="next" href="UsingSecondaries.html" title="Chapter 3. &#10;&#9;&#9;Using Secondary Indices&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Handling Exceptions
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="retrievingdatabaseitems.html">Prev</a> </td>
<th width="60%" align="center">Chapter 2. 
The Basic Program
</th>
<td width="20%" align="right"> <a accesskey="n" href="UsingSecondaries.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="handlingexceptions"></a>
Handling Exceptions
</h2>
</div>
</div>
<div></div>
</div>
<p>
Exception handling was illustrated previously in
<a href="implementingmain.html">
Implementing the Main Program
</a>
and
<a href="usingtransactions.html">
Using Transactions
</a>
exception handling in a DB Java Collections API application in
more detail.
</p>
<p>
There are two exceptions that must be treated specially:
<a href="../../java/com/sleepycat/db/RunRecoveryException.html" target="_top">RunRecoveryException</a>
and
<span>
<a href="../../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a>.
</span>
</p>
<p>
<a href="../../java/com/sleepycat/db/RunRecoveryException.html" target="_top">RunRecoveryException</a>
is thrown when the only solution is to shut down the application
and run recovery. All applications must catch this exception and
follow the recovery procedure.
</p>
<p>
When
<a href="../../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a>
is thrown, the application should normally retry the operation. If
a deadlock continues to occur for some maximum number of retries,
the application should give up and try again later or take other
corrective actions. The DB Java Collections API provides two APIs
for transaction execution.
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
When using the
<a href="../../java/com/sleepycat/collections/CurrentTransaction.html" target="_top">CurrentTransaction</a>
class directly, the application must catch
<a href="../../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a>
and follow the procedure described previously.
</p>
</li>
<li>
<p>
When using the
<a href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>
class, retries are performed automatically and the application need
only handle the case where the maximum number of retries has been
reached. In that case,
<a href="../../java/com/sleepycat/collections/TransactionRunner.html#run(com.sleepycat.collections.TransactionWorker)" target="_top">TransactionRunner.run</a>
will throw
<span>
<a href="../../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a>.
</span>
</p>
</li>
</ul>
</div>
<p>
When using the
<a href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>
class there are two other considerations.
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
First, if the application-defined
<a href="../../java/com/sleepycat/collections/TransactionWorker.html#doWork()" target="_top">TransactionWorker.doWork</a>
method throws an exception the
transaction will automatically be aborted, and otherwise the
transaction will automatically be committed. Applications should
design their transaction processing with this in mind.
</p>
</li>
<li>
<p>
Second, please be aware that
<a href="../../java/com/sleepycat/collections/TransactionRunner.html#run(com.sleepycat.collections.TransactionWorker)" target="_top">TransactionRunner.run</a>
unwraps exceptions in order to discover whether a nested exception is a
<span>
<a href="../../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a>.
</span>
This is particularly important since all Berkeley DB exceptions
that occur while calling a stored collection method are wrapped
with a
<a href="../../java/com/sleepycat/util/RuntimeExceptionWrapper.html" target="_top">RuntimeExceptionWrapper</a>.
This wrapping is necessary because Berkeley DB exceptions are
checked exceptions, and the Java collections API does not allow
such exceptions to be thrown.
</p>
</li>
</ul>
</div>
<p>
When calling
<a href="../../java/com/sleepycat/collections/TransactionRunner.html#run(com.sleepycat.collections.TransactionWorker)" target="_top">TransactionRunner.run</a>,
the unwrapped (nested) exception will be unwrapped and thrown
automatically. If you are not using
<a href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>
or if you are handling exceptions directly for some other reason,
use the
<a href="../../java/com/sleepycat/util/ExceptionUnwrapper.html#unwrap(java.lang.Exception)" target="_top">ExceptionUnwrapper.unwrap</a>
method to get the nested exception. For example, this can be used
to discover that an exception is a
<a href="../../java/com/sleepycat/db/RunRecoveryException.html" target="_top">RunRecoveryException</a>
as shown below.
</p>
<a id="cb_java_manageexceptions"></a>
<pre class="programlisting"><b class="userinput"><tt>import com.sleepycat.db.RunRecoveryException;
import com.sleepycat.util.ExceptionUnwrapper;
...
catch (Exception e)
{
e = ExceptionUnwrapper.unwrap(e);
if (e instanceof RunRecoveryException)
{
// follow recovery procedure
}
}</tt></b> </pre>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="retrievingdatabaseitems.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="UsingSecondaries.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Retrieving Database Items
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Chapter 3. 
Using Secondary Indices
</td>
</tr>
</table>
</div>
</body>
</html>

253
docs/collections/tutorial/implementingmain.html Normal file
View File

@@ -0,0 +1,253 @@
<?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>
Implementing the Main Program
</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="BasicProgram.html" title="Chapter 2. &#10;&#9;&#9;The Basic Program&#10;&#9;" />
<link rel="previous" href="createbindingscollections.html" title="&#10;&#9;&#9;Creating Bindings and Collections&#10;&#9;" />
<link rel="next" href="usingtransactions.html" title="&#10;&#9;&#9;Using Transactions&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Implementing the Main Program
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="createbindingscollections.html">Prev</a> </td>
<th width="60%" align="center">Chapter 2. 
The Basic Program
</th>
<td width="20%" align="right"> <a accesskey="n" href="usingtransactions.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="implementingmain"></a>
Implementing the Main Program
</h2>
</div>
</div>
<div></div>
</div>
<p>
The main program opens the environment and databases, stores and retrieves
objects within a transaction, and finally closes the environment
databases. This section describes the main program shell, and the
next section describes how to run transactions for storing and
retrieving objects.
</p>
<p>
The <tt class="classname">Sample</tt> class contains the main program. The skeleton
for the <tt class="classname">Sample</tt> class follows.
</p>
<a id="cb_java_sample"></a>
<pre class="programlisting"><b class="userinput"><tt>import com.sleepycat.db.DatabaseException;
import java.io.FileNotFoundException;
public class Sample
{
private SampleDatabase db;
private SampleViews views;
public static void main(String args)
{
}
private Sample(String homeDir)
throws DatabaseException, FileNotFoundException
{
}
private void close()
throws DatabaseException
{
}
private void run()
throws Exception
{
}
}</tt></b> </pre>
<p>
The main program uses the <tt class="classname">SampleDatabase</tt> and
<tt class="classname">SampleViews</tt> classes that were described in the preceding
sections. The <tt class="methodname">main</tt> method will create an instance of the
<tt class="classname">Sample</tt> class, and call its <tt class="methodname">run()</tt> and <tt class="methodname">close()</tt>
methods.
</p>
<p>
The following statements parse the program's command line
arguments.
</p>
<a id="cb_main"></a>
<pre class="programlisting"> public static void main(String[] args)
{
<b class="userinput"><tt> System.out.println("\nRunning sample: " + Sample.class);
String homeDir = "./tmp";
for (int i = 0; i &lt; args.length; i += 1)
{
String arg = args[i];
if (args[i].equals("-h") &amp;&amp; i &lt; args.length - 1)
{
i += 1;
homeDir = args[i];
}
else
{
System.err.println("Usage:\n java " +
Sample.class.getName() +
"\n [-h &lt;home-directory&gt;]");
System.exit(2);
}
}</tt></b>
...
} </pre>
<p>
The usage command is:
</p>
<pre class="programlisting"><b class="userinput"><tt>java com.sleepycat.examples.bdb.shipment.basic.Sample
[-h &lt;home-directory&gt; ]</tt></b> </pre>
<p>
The <tt class="literal">-h</tt> command is used to set the <tt class="filename">homeDir</tt>
variable, which will later be passed to the <tt class="methodname">SampleDatabase()</tt>
constructor. Normally all Berkeley DB programs should provide a way
to configure their database environment home directory.
</p>
<p>
The default for the home directory is <tt class="filename">./tmp</tt> — the tmp
subdirectory of the current directory where the sample is run. The
home directory must exist before running the sample. To re-create
the sample database from scratch, delete all files in the home
directory before running the sample.
</p>
<p>
The home directory was described previously in
<a href="opendbenvironment.html">
Opening and Closing the Database Environment
</a>.
</p>
<p>
Of course, the command line arguments shown are only examples
and a real-life application may use different techniques for
configuring these options.
</p>
<p>
The following statements create an instance of the <tt class="classname">Sample</tt>
class and call its <tt class="methodname">run()</tt> and <tt class="methodname">close()</tt> methods.
</p>
<a id="cb_main2"></a>
<pre class="programlisting"> public static void main(String args)
{
...
<b class="userinput"><tt> Sample sample = null;
try
{
sample = new Sample(homeDir);
sample.run();
}
catch (Exception e)
{
e.printStackTrace();
}
finally
{
if (sample != null)
{
try
{
sample.close();
}
catch (Exception e)
{
System.err.println("Exception during database close:");
e.printStackTrace();
}
}
}</tt></b>
} </pre>
<p>
The <tt class="methodname">Sample()</tt> constructor will open the environment and
databases, and the <tt class="methodname">run()</tt> method will run transactions for
storing and retrieving objects. If either of these throws an
exception, then the program was unable to run and should normally
terminate. (Transaction retries are handled at a lower level and
will be described later.) The first <tt class="literal">catch</tt> statement handles
such exceptions.
</p>
<p>
The <tt class="literal">finally</tt> statement is used to call the <tt class="methodname">close()</tt>
method since an attempt should always be made to close the environment and
databases
cleanly. If an exception is thrown during close and a prior
exception occurred above, then the exception during close is likely
a side effect of the prior exception.
</p>
<p>
The <tt class="methodname">Sample()</tt> constructor creates the <tt class="literal">SampleDatabase</tt>
and <tt class="classname">SampleViews</tt> objects.
</p>
<a id="cb_sample"></a>
<pre class="programlisting"> private Sample(String homeDir)
throws DatabaseException, FileNotFoundException
{
<b class="userinput"><tt> db = new SampleDatabase(homeDir);
views = new SampleViews(db);</tt></b>
} </pre>
<p>
Recall that creating the <tt class="classname">SampleDatabase</tt> object will open
the environment and all databases.
</p>
<p>
To close the database the <tt class="methodname">Sample.close()</tt> method simply
calls <tt class="methodname">SampleDatabase.close()</tt>.
</p>
<a id="cb_sample-close"></a>
<pre class="programlisting"> private void close()
throws DatabaseException
{
<b class="userinput"><tt> db.close();</tt></b>
} </pre>
<p>
The <tt class="methodname">run()</tt> method is described in the next section.
</p>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="createbindingscollections.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="usingtransactions.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Creating Bindings and Collections
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Using Transactions
</td>
</tr>
</table>
</div>
</body>
</html>

534
docs/collections/tutorial/index.html Normal file
View File

@@ -0,0 +1,534 @@
<?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>Berkeley DB Collections Tutorial</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="next" href="preface.html" title="Preface" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Berkeley DB Collections Tutorial</th>
</tr>
<tr>
<td width="20%" align="left"> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="preface.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="book" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h1 class="title"><a id="id613728"></a>Berkeley DB Collections Tutorial</h1>
</div>
<div>
<div class="legalnotice">
<p class="legalnotice-title">
<b>Legal Notice</b>
</p>
<p>
This documentation is distributed under an open source license.
You may review the terms of this license at:
<a href="http://www.oracle.com/technology/software/products/berkeley-db/htdocs/oslicense.html" target="_top">http://www.oracle.com/technology/software/products/berkeley-db/htdocs/oslicense.html</a>
</p>
<p>
Oracle, Berkeley DB,
and
Sleepycat are trademarks or registered trademarks of
Oracle. All rights to these marks are reserved.
No third-party use is permitted without the
express prior written consent of Oracle.
</p>
<p>
<span class="trademark">Java</span>™ and all Java-based marks are a trademark
or registered trademark of Sun Microsystems,
Inc, in the United States and other countries.
</p>
<p>
To obtain a copy of this document's original source code, please
submit a request to the Oracle Technology Network forum at:
<a href="http://forums.oracle.com/forums/forum.jspa?forumID=271" target="_top">http://forums.oracle.com/forums/forum.jspa?forumID=271</a>
</p>
</div>
</div>
<div>
<p class="pubdate">4/25/2008</p>
</div>
</div>
<div></div>
<hr />
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="preface">
<a href="preface.html">Preface</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span class="sect1">
<a href="preface.html#conventions">Conventions Used in this Book</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="moreinfo.html">For More Information</a>
</span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter">
<a href="intro.html">1.
Introduction
</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span class="sect1">
<a href="intro.html#features">Features</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="developing.html">Developing a DB Collections Application</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="tutorialintroduction.html">Tutorial Introduction</a>
</span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter">
<a href="BasicProgram.html">2.
The Basic Program
</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span class="sect1">
<a href="BasicProgram.html#keyandvalueclasses">
Defining Serialized Key and Value Classes
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="opendbenvironment.html">
Opening and Closing the Database Environment
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="openclasscatalog.html">
Opening and Closing the Class Catalog
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="opendatabases.html">
Opening and Closing Databases
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="createbindingscollections.html">
Creating Bindings and Collections
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="implementingmain.html">
Implementing the Main Program
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="usingtransactions.html">
Using Transactions
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="addingdatabaseitems.html">
Adding Database Items
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="retrievingdatabaseitems.html">
Retrieving Database Items
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="handlingexceptions.html">
Handling Exceptions
</a>
</span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter">
<a href="UsingSecondaries.html">3.
Using Secondary Indices
</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span class="sect1">
<a href="UsingSecondaries.html#opensecondaryindices">
Opening Secondary Key Indices
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="openingforeignkeys.html">
More Secondary Key Indices
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="indexedcollections.html">
Creating Indexed Collections
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="retrievingbyindexkey.html">
Retrieving Items by Index Key
</a>
</span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter">
<a href="Entity.html">4.
Using Entity Classes
</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span class="sect1">
<a href="Entity.html#definingentityclasses">
Defining Entity Classes
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="creatingentitybindings.html">
Creating Entity Bindings
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="collectionswithentities.html">
Creating Collections with Entity Bindings
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="entitieswithcollections.html">
Using Entities with Collections
</a>
</span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter">
<a href="Tuple.html">5.
Using Tuples
</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span class="sect1">
<a href="Tuple.html#tupleformat">
Using the Tuple Format
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="tupleswithkeycreators.html">
Using Tuples with Key Creators
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="tuplekeybindings.html">
Creating Tuple Key Bindings
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="tuple-serialentitybindings.html">
Creating Tuple-Serial Entity Bindings
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="sortedcollections.html">
Using Sorted Collections
</a>
</span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter">
<a href="SerializableEntity.html">6.
Using Serializable Entities
</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span class="sect1">
<a href="SerializableEntity.html#transientfieldsinclass">
Using Transient Fields in an Entity Class
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="transientfieldsinbinding.html">
Using Transient Fields in an Entity Binding
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="removingredundantvalueclasses.html">
Removing the Redundant Value Classes
</a>
</span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter">
<a href="Summary.html">7.
Summary
</a>
</span>
</dt>
<dt>
<span class="appendix">
<a href="collectionOverview.html">A.
API Notes and Details
</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span class="sect1">
<a href="collectionOverview.html#UsingDataBindings">
Using Data Bindings
</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span class="sect2">
<a href="collectionOverview.html#SelectingBindingFormats">
Selecting Binding Formats
</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="collectionOverview.html#RecordNumberBindings">Record Number Bindings</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>
</dd>
<dt>
<span class="sect1">
<a href="UsingCollectionsAPI.html">
Using the DB Java Collections API
</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span class="sect2">
<a href="UsingCollectionsAPI.html#UsingTransactions">
Using Transactions
</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="UsingCollectionsAPI.html#TransactionRollback">
Transaction Rollback
</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="UsingCollectionsAPI.html#SelectingAccessMethods">Selecting Access Methods</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="UsingCollectionsAPI.html#AccessMethodRestrictions">
Access Method Restrictions
</a>
</span>
</dt>
</dl>
</dd>
<dt>
<span class="sect1">
<a href="UsingStoredCollections.html">
Using Stored Collections
</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span class="sect2">
<a href="UsingStoredCollections.html#StoredCollectionAccessMethods">
Stored Collection and Access Methods
</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="UsingStoredCollections.html#StoredVersusStandardCollections">
Stored Collections Versus Standard Java Collections
</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="UsingStoredCollections.html#StoredCollectionCharacteristics">
Other Stored Collection Characteristics
</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="UsingStoredCollections.html#WhyJavaCollections">
Why Java Collections for Berkeley DB
</a>
</span>
</dt>
</dl>
</dd>
<dt>
<span class="sect1">
<a href="SerializedObjectStorage.html">
Serialized Object Storage
</a>
</span>
</dt>
</dl>
</dd>
</dl>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="preface.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top"> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right" valign="top"> Preface</td>
</tr>
</table>
</div>
</body>
</html>

248
docs/collections/tutorial/indexedcollections.html Normal file
View File

@@ -0,0 +1,248 @@
<?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 Indexed Collections
</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="UsingSecondaries.html" title="Chapter 3. &#10;&#9;&#9;Using Secondary Indices&#10;&#9;" />
<link rel="previous" href="openingforeignkeys.html" title="&#10;&#9;&#9;&#10;&#9;&#9;More Secondary Key Indices&#10;&#9;" />
<link rel="next" href="retrievingbyindexkey.html" title="&#10;&#9;&#9;Retrieving Items by Index Key&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Creating Indexed Collections
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="openingforeignkeys.html">Prev</a> </td>
<th width="60%" align="center">Chapter 3. 
Using Secondary Indices
</th>
<td width="20%" align="right"> <a accesskey="n" href="retrievingbyindexkey.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="indexedcollections"></a>
Creating Indexed Collections
</h2>
</div>
</div>
<div></div>
</div>
<p>
In the prior Basic example, bindings and Java collections were
created for accessing databases via their primary keys. In this
example, bindings and collections are added for accessing the same
databases via their index keys. As in the prior example, serial
bindings and the Java
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html" target="_top">Map</a>
class are used.
</p>
<p>
When a map is created from a
<span>
<a href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>,
</span>
the keys of the map will be the index keys. However, the values of
the map will be the values of the primary database associated with
the index. This is how index keys can be used to access the values
in a primary database.
</p>
<p>
For example, the Supplier's City field is an index key that can
be used to access the Supplier database. When a map is created
using the <tt class="methodname">supplierByCityDb()</tt> method, the key to the map will be the
City field, a
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/String.html" target="_top">String</a>
object. When
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#get" target="_top">Map.get</a>
is called passing the City as the key parameter, a
<tt class="classname">SupplierData</tt>
object will be returned.
</p>
<p>
The <tt class="classname">SampleViews</tt> class is extended to create an index key
binding for the Supplier's City field and three Java maps based on
the three indices created in the prior section.
</p>
<a id="index_sampleviews"></a>
<pre class="programlisting">import com.sleepycat.bind.EntryBinding;
import com.sleepycat.bind.serial.SerialBinding;
import com.sleepycat.collections.StoredEntrySet;
import com.sleepycat.collections.StoredMap;
...
public class SampleViews
{
...
<b class="userinput"><tt> private StoredMap supplierByCityMap;
private StoredMap shipmentByPartMap;
private StoredMap shipmentBySupplierMap;</tt></b>
...
public SampleViews(SampleDatabase db)
{
ClassCatalog catalog = db.getClassCatalog();
...
<b class="userinput"><tt> EntryBinding cityKeyBinding =
new SerialBinding(catalog, String.class);
...
supplierByCityMap =
new StoredMap(db.getSupplierByCityDatabase(),
cityKeyBinding, supplierValueBinding, true);
shipmentByPartMap =
new StoredMap(db.getShipmentByPartDatabase(),
partKeyBinding, shipmentValueBinding, true);
shipmentBySupplierMap =
new StoredMap(db.getShipmentBySupplierDatabase(),
supplierKeyBinding, shipmentValueBinding, true); </tt></b>
...
}
} </pre>
<p>
In general, the indexed maps are created here in the same way as
the unindexed maps were created in the Basic example. The
differences are:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
The first parameter of the
<a href="../../java/com/sleepycat/collections/StoredMap.html" target="_top">StoredMap</a>
constructor is a
<a href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>
rather than a
<span>
<a href="../../java/com/sleepycat/db/Database.html" target="_top">Database</a>.
</span>
</p>
</li>
<li>
<p>
The second parameter is the index key binding rather than the
primary key binding.
</p>
</li>
</ul>
</div>
<p>
For the <tt class="literal">supplierByCityMap</tt>, the <tt class="literal">cityKeyBinding</tt> must
first be created. This binding was not created in the Basic example
because the City field is not a primary key.
</p>
<p>
Like the bindings created earlier for keys and values, the
<tt class="literal">cityKeyBinding</tt> is a
<a href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a>.
Unlike the bindings created earlier, it is an example of creating a
binding for a built-in Java class,
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/String.html" target="_top">String</a>,
instead of an application-defined class. Any serializable class may
be used.
</p>
<p>
For the <tt class="literal">shipmentByPartMap</tt> and
<tt class="literal">shipmentBySupplierMap</tt>, the <tt class="literal">partKeyBinding</tt> and
<tt class="literal">supplierKeyBinding</tt> are used. These were created in the Basic
example and used as the primary key bindings for the <tt class="literal">partMap</tt>
and <tt class="literal">supplierMap</tt>.
</p>
<p>
The value bindings — <tt class="literal">supplierValueBinding</tt> and
<tt class="literal">shipmentValueBinding</tt> — were also created in the Basic
example.
</p>
<p>
This illustrates that bindings and formats may and should be
reused where appropriate for creating maps and other
collections.
</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="index_sampleviewsgetters"></a>
<pre class="programlisting">public class SampleViews
{
...
<b class="userinput"><tt> public final StoredMap getShipmentByPartMap()
{
return shipmentByPartMap;
}
public final StoredMap getShipmentBySupplierMap()
{
return shipmentBySupplierMap;
}
public final StoredMap getSupplierByCityMap()
{
return supplierByCityMap;
}
public final StoredEntrySet getShipmentByPartEntrySet()
{
return (StoredEntrySet) shipmentByPartMap.entrySet();
}
public final StoredEntrySet getShipmentBySupplierEntrySet()
{
return (StoredEntrySet) shipmentBySupplierMap.entrySet();
}
public final StoredEntrySet getSupplierByCityEntrySet()
{
return (StoredEntrySet) supplierByCityMap.entrySet();
}</tt></b>
...
} </pre>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="openingforeignkeys.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="UsingSecondaries.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="retrievingbyindexkey.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
More Secondary Key Indices
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Retrieving Items by Index Key
</td>
</tr>
</table>
</div>
</body>
</html>

220
docs/collections/tutorial/intro.html Normal file
View File

@@ -0,0 +1,220 @@
<?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>Chapter 1. 
Introduction
</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="moreinfo.html" title="For More Information" />
<link rel="next" href="developing.html" title="Developing a DB Collections Application" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 1. 
Introduction
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="moreinfo.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="developing.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="intro"></a>Chapter 1. 
Introduction
</h2>
</div>
</div>
<div></div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="sect1">
<a href="intro.html#features">Features</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="developing.html">Developing a DB Collections Application</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="tutorialintroduction.html">Tutorial Introduction</a>
</span>
</dt>
</dl>
</div>
<p>
The DB Java Collections API is a Java framework that extends
the well known
<a href="http://java.sun.com/j2se/1.5.0/docs/guide/collections/" target="_top">Java Collections</a>
design pattern such that collections can now be
stored, updated and queried in a transactional manner. The
DB Java Collections API is a layer on top of DB.
</p>
<p>
Together the DB Java Collections API and Berkeley DB provide an
embedded data management solution with all the benefits of a full
transactional storage and the simplicity of a well known Java API.
Java programmers who need fast, scalable, transactional data
management for their projects can quickly adopt and deploy the
DB Java Collections API with confidence.
</p>
<p>
This framework was first known as
<a href="http://greybird-db.sourceforge.net/" target="_top">Greybird DB</a>
written by Mark Hayes. Mark collaborated with us to
permanently incorporate his excellent work into our distribution
and to support it as an ongoing part of Berkeley DB and Berkeley DB Java
Edition. The repository of source code that remains at SourceForge at version 0.9.0 is
considered the last version before incorporation and will remain
intact but will not be updated to reflect changes made as part of
Berkeley DB or Berkeley DB Java Edition.
</p>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="features"></a>Features</h2>
</div>
</div>
<div></div>
</div>
<p>
<span>Berkeley DB has always provided a Java API which can be roughly
described as a map and cursor interface, where the keys and values
are represented as byte arrays. This API is a Java (JNI) interface
to the C API and it closely modeled the Berkeley DB C API's
interface.</span>
The DB Java Collections API is a layer on top of
<span>that
thin JNI mapping of the C API to Berkeley DB.</span>
It adds significant new functionality in several ways.
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
An implementation of the Java Collections interfaces (Map,
SortedMap, Set, SortedSet,
<span>List</span>
and Iterator) is provided.
</p>
</li>
<li>
<p>
Transactions are supported using the conventional Java
transaction-per-thread model, where the current transaction is
implicitly associated with the current thread.
</p>
</li>
<li>
<p>
Transaction runner utilities are provided that automatically
perform transaction retry and exception handling.
</p>
</li>
<li>
<p>
Keys and values are represented as Java objects rather than
byte arrays. Bindings are used to map between Java objects and the
stored byte arrays.
</p>
</li>
<li>
<p>
The tuple data format is provided as the simplest data
representation, and is useful for keys as well as simple compact
values.
</p>
</li>
<li>
<p>
The serial data format is provided for storing arbitrary Java
objects without writing custom binding code. Java serialization is
extended to store the class descriptions separately, making the
data records much more compact than with standard Java
serialization.
</p>
</li>
<li>
<p>
Custom data formats and bindings can be easily added. XML data
format and XML bindings could easily be created using this feature,
for example.
</p>
</li>
<li>
<p>
The DB Java Collections API insulates the application
from minor differences in the use of the Berkeley DB Data Store,
Concurrent Data Store, and Transactional Data Store products.
This allows for development with one and deployment with another
without significant changes to code.
</p>
</li>
</ul>
</div>
<p>
Note that the DB Java Collections API does not support caching
of programming language objects nor does it keep track of their stored
status. This is in contrast to "persistent object" approaches such
as those defined by
<a href="http://www.odmg.org/" target="_top">ODMG</a>
and JDO
(<a href="http://www.jcp.org/en/jsr/detail?id=12" target="_top">JSR 12</a>).
Such approaches have benefits but also require sophisticated object
caching. For simplicity the DB Java Collections API treats data
objects by value, not by reference, and does not perform object
caching of any kind. Since the DB Java Collections API is a thin
layer, its reliability and performance characteristics are roughly
equivalent to those of Berkeley DB, and database tuning is
accomplished in the same way as for any Berkeley DB database.
</p>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="moreinfo.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="developing.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">For More Information </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Developing a DB Collections Application</td>
</tr>
</table>
</div>
</body>
</html>

108
docs/collections/tutorial/moreinfo.html Normal file
View File

@@ -0,0 +1,108 @@
<?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>For More Information</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="preface.html" title="Preface" />
<link rel="previous" href="preface.html" title="Preface" />
<link rel="next" href="intro.html" title="Chapter 1. &#10; Introduction&#10; " />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">For More Information</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="preface.html">Prev</a> </td>
<th width="60%" align="center">Preface</th>
<td width="20%" align="right"> <a accesskey="n" href="intro.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="moreinfo"></a>For More Information</h2>
</div>
</div>
<div></div>
</div>
<p>
Beyond this manual, you may also find the following sources of information useful when building a
DB application:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<a href="http://www.oracle.com/technology/documentation/berkeley-db/db/gsg/JAVA/index.html" target="_top">
Getting Started with Berkeley DB for Java
</a>
</p>
</li>
<li>
<p>
<a href="http://www.oracle.com/technology/documentation/berkeley-db/db/gsg_txn/JAVA/index.html" target="_top">
Getting Started with Transaction Processing for Java
</a>
</p>
</li>
<li>
<p>
<a href="http://www.oracle.com/technology/documentation/berkeley-db/db/gsg_db_rep/JAVA/index.html" target="_top">
Berkeley DB Getting Started with Replicated Applications for Java
</a>
</p>
</li>
<li>
<p>
<a href="http://www.oracle.com/technology/documentation/berkeley-db/db/ref/toc.html" target="_top">
Berkeley DB Programmer's Reference Guide
</a>
</p>
</li>
<li>
<p>
<a href="http://www.oracle.com/technology/documentation/berkeley-db/db/java/index.html" target="_top">
Berkeley DB Javadoc
</a>
</p>
</li>
</ul>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="preface.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="preface.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="intro.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Preface </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Chapter 1. 
Introduction
</td>
</tr>
</table>
</div>
</body>
</html>

208
docs/collections/tutorial/openclasscatalog.html Normal file
View File

@@ -0,0 +1,208 @@
<?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>
Opening and Closing the Class Catalog
</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="BasicProgram.html" title="Chapter 2. &#10;&#9;&#9;The Basic Program&#10;&#9;" />
<link rel="previous" href="opendbenvironment.html" title="&#10;&#9;&#9;Opening and Closing the Database Environment&#10;&#9;" />
<link rel="next" href="opendatabases.html" title="&#10;&#9;&#9;Opening and Closing Databases&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Opening and Closing the Class Catalog
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="opendbenvironment.html">Prev</a> </td>
<th width="60%" align="center">Chapter 2. 
The Basic Program
</th>
<td width="20%" align="right"> <a accesskey="n" href="opendatabases.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="openclasscatalog"></a>
Opening and Closing the Class Catalog
</h2>
</div>
</div>
<div></div>
</div>
<p>
This section describes how to open and close the Java class
catalog. The class catalog is a specialized database store that
contains the Java class descriptions of the serialized objects that
are stored in the database. The class descriptions are stored in
the catalog rather than storing them redundantly in each database
record. A single class catalog per environment must be opened
whenever serialized objects will be stored in the database.
</p>
<p>
The <tt class="classname">SampleDatabase</tt> class is extended to open and close
the class catalog. The following additional imports and class
members are needed.
</p>
<a id="cb_java_sampledatabase1"></a>
<pre class="programlisting"><b class="userinput"><tt>import com.sleepycat.bind.serial.StoredClassCatalog;
import com.sleepycat.db.Database;
import com.sleepycat.db.DatabaseConfig;
import com.sleepycat.db.DatabaseType;</tt></b>
import com.sleepycat.db.DatabaseException;
import com.sleepycat.db.Environment;
import com.sleepycat.db.EnvironmentConfig;
import java.io.File;
import java.io.FileNotFoundException;
...
public class SampleDatabase
{
private Environment env;
<b class="userinput"><tt> private static final String CLASS_CATALOG = "java_class_catalog";</tt></b>
...
<b class="userinput"><tt> private StoredClassCatalog javaCatalog;</tt></b>
...
} </pre>
<p>
While the class catalog is itself a database, it contains
metadata for other databases and is therefore treated specially by
the DB Java Collections API. The
<a href="../../java/com/sleepycat/bind/serial/StoredClassCatalog.html" target="_top">StoredClassCatalog</a>
class encapsulates the catalog store and implements this special
behavior.
</p>
<p>
The following statements open the class catalog by creating a
<tt class="classname">Database</tt> and a <tt class="classname">StoredClassCatalog</tt> object. The catalog
database is created if it does not already exist.
</p>
<a id="cb_java_sampledatabase2"></a>
<pre class="programlisting"> public SampleDatabase(String homeDirectory)
throws DatabaseException, FileNotFoundException
{
...
<b class="userinput"><tt> DatabaseConfig dbConfig = new DatabaseConfig();
dbConfig.setTransactional(true);
dbConfig.setAllowCreate(true);
dbConfig.setType(DatabaseType.BTREE);
Database catalogDb = env.openDatabase(null, CLASS_CATALOG, null,
dbConfig);
javaCatalog = new StoredClassCatalog(catalogDb);</tt></b>
...
}
...
<b class="userinput"><tt> public final StoredClassCatalog getClassCatalog() {
return javaCatalog;
}</tt></b> </pre>
<p>
The
<a href="../../java/com/sleepycat/db/DatabaseConfig.html" target="_top">DatabaseConfig</a>
class is used to specify configuration parameters when opening a
database. The first configuration option specified —
<tt class="methodname">setTransactional()</tt> — is set to true to create a transactional
database. While non-transactional databases can also be created,
the examples in this tutorial use transactional databases.
</p>
<p>
<tt class="methodname">setAllowCreate()</tt> is set to true to specify
that the database will be created if it does not already exist. If
this parameter is not specified, an exception will be thrown if the
database does not already exist.
</p>
<p>
<tt class="methodname">setDatabaseType()</tt> identifies the database storage
type or access method. For opening a catalog database, the
<tt class="literal">BTREE</tt> type is required. <tt class="literal">BTREE</tt> is the
most commonly used database type and in this tutorial is used for all
databases.
</p>
<p>
The first parameter of the <tt class="methodname">openDatabase()</tt> method is an
optional transaction that is used for creating a new database. If
null is passed, auto-commit is used when creating a database.
</p>
<p>
The second and third parameters of <tt class="methodname">openDatabase()</tt>
specify the filename and database (sub-file) name of the database. The
database name is optional and is <tt class="literal">null</tt> in this example.
</p>
<p>
The last parameter of <tt class="methodname">openDatabase()</tt> specifies the database
configuration object.
</p>
<p>
Lastly, the <tt class="classname">StoredClassCatalog</tt> object is created to manage the
information in the class catalog database. The
<tt class="classname">StoredClassCatalog</tt> object will be used in the sections
following for creating serial bindings.
</p>
<p>
The <tt class="methodname">getClassCatalog</tt> method returns the catalog object for
use by other classes in the example program.
</p>
<p>
When the environment is closed, the class catalog is closed
also.
</p>
<a id="cb_close1"></a>
<pre class="programlisting"> public void close()
throws DatabaseException
{
<b class="userinput"><tt> javaCatalog.close();</tt></b>
env.close();
} </pre>
<p>
The <tt class="methodname">StoredClassCatalog.close()</tt> method simply closes the
underlying class catalog database and in fact the
<a href="../../java/com/sleepycat/db/Database.html#close()" target="_top">Database.close()</a>
method may be called instead, if desired. The catalog database, and
all other databases, must be closed before closing the
environment.
</p>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="opendbenvironment.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="opendatabases.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Opening and Closing the Database Environment
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Opening and Closing Databases
</td>
</tr>
</table>
</div>
</body>
</html>

168
docs/collections/tutorial/opendatabases.html Normal file
View File

@@ -0,0 +1,168 @@
<?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>
Opening and Closing Databases
</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="BasicProgram.html" title="Chapter 2. &#10;&#9;&#9;The Basic Program&#10;&#9;" />
<link rel="previous" href="openclasscatalog.html" title="&#10;&#9;&#9;Opening and Closing the Class Catalog&#10;&#9;" />
<link rel="next" href="createbindingscollections.html" title="&#10;&#9;&#9;Creating Bindings and Collections&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Opening and Closing Databases
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="openclasscatalog.html">Prev</a> </td>
<th width="60%" align="center">Chapter 2. 
The Basic Program
</th>
<td width="20%" align="right"> <a accesskey="n" href="createbindingscollections.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="opendatabases"></a>
Opening and Closing Databases
</h2>
</div>
</div>
<div></div>
</div>
<p>
This section describes how to open and close the Part, Supplier
and Shipment databases. A <span class="emphasis"><em>database</em></span> is a collection of
records, each of which has a key and a value. The keys and values
are stored in a selected format, which defines the syntax of the
stored data. Two examples of formats are Java serialization format
and tuple format. In a given database, all keys have the same
format and all values have the same format.
</p>
<p>
The <tt class="classname">SampleDatabase</tt> class is extended to open and close
the three databases. The following additional class members are
needed.
</p>
<a id="cb_sampledatabase3"></a>
<pre class="programlisting">public class SampleDatabase
{
...
<b class="userinput"><tt> private static final String SUPPLIER_STORE = "supplier_store";
private static final String PART_STORE = "part_store";
private static final String SHIPMENT_STORE = "shipment_store";</tt></b>
...
<b class="userinput"><tt> private Database supplierDb;
private Database partDb;
private Database shipmentDb;</tt></b>
...
} </pre>
<p>
For each database there is a database name constant and a
<tt class="classname">Database</tt> object.
</p>
<p>
The following statements open the three databases by
constructing a Database object.
</p>
<a id="cb_java_sampledatabase4"></a>
<pre class="programlisting"> public SampleDatabase(String homeDirectory)
throws DatabaseException, FileNotFoundException
{
...
DatabaseConfig dbConfig = new DatabaseConfig();
dbConfig.setTransactional(true);
dbConfig.setAllowCreate(true);
dbConfig.setType(DatabaseType.BTREE);
...
<b class="userinput"><tt> partDb = env.openDatabase(null, PART_STORE, null, dbConfig);
supplierDb = env.openDatabase(null, SUPPLIER_STORE, null, dbConfig);
shipmentDb = env.openDatabase(null, SHIPMENT_STORE, null, dbConfig);</tt></b>
...
} </pre>
<p>
The database configuration object that was used previously for
opening the catalog database is reused for opening the three
databases above. The databases are created if they don't already
exist. The parameters of the <tt class="methodname">openDatabase()</tt> method were
described earlier when the class catalog database was opened.
</p>
<p>
The following statements close the three databases.
</p>
<a id="cb_close2"></a>
<pre class="programlisting"> public void close()
throws DatabaseException
{
<b class="userinput"><tt> partDb.close();
supplierDb.close();
shipmentDb.close();</tt></b>
javaCatalog.close();
env.close();
} </pre>
<p>
All databases, including the catalog database, must be closed
before closing the environment.
</p>
<p>
The following getter methods return the databases for use by
other classes in the example program.
</p>
<a id="cb_sampledatabase_getters"></a>
<pre class="programlisting">public class SampleDatabase
{
...
<b class="userinput"><tt> public final Database getPartDatabase()
{
return partDb;
}
public final Database getSupplierDatabase()
{
return supplierDb;
}
public final Database getShipmentDatabase()
{
return shipmentDb;
}</tt></b>
...
}</pre>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="openclasscatalog.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="createbindingscollections.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Opening and Closing the Class Catalog
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Creating Bindings and Collections
</td>
</tr>
</table>
</div>
</body>
</html>

200
docs/collections/tutorial/opendbenvironment.html Normal file
View File

@@ -0,0 +1,200 @@
<?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>
Opening and Closing the Database Environment
</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="BasicProgram.html" title="Chapter 2. &#10;&#9;&#9;The Basic Program&#10;&#9;" />
<link rel="previous" href="BasicProgram.html" title="Chapter 2. &#10;&#9;&#9;The Basic Program&#10;&#9;" />
<link rel="next" href="openclasscatalog.html" title="&#10;&#9;&#9;Opening and Closing the Class Catalog&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Opening and Closing the Database Environment
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="BasicProgram.html">Prev</a> </td>
<th width="60%" align="center">Chapter 2. 
The Basic Program
</th>
<td width="20%" align="right"> <a accesskey="n" href="openclasscatalog.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="opendbenvironment"></a>
Opening and Closing the Database Environment
</h2>
</div>
</div>
<div></div>
</div>
<p>
This section of the tutorial describes how to open and close the
database environment. The database environment manages resources
(for example, memory, locks and transactions) for any number of
databases. A single environment instance is normally used for all
databases.
</p>
<p>
The <tt class="classname">SampleDatabase</tt> class is used to open and close the
environment. It will also be used in following sections to open and
close the class catalog and other databases. Its constructor is
used to open the environment and its <tt class="classname">close()</tt> method is used
to close the environment. The skeleton for the
<tt class="classname">SampleDatabase</tt> class follows.
</p>
<a id="cb_java_sampledatabase"></a>
<pre class="programlisting"><b class="userinput"><tt>import com.sleepycat.db.DatabaseException;
import com.sleepycat.db.Environment;
import com.sleepycat.db.EnvironmentConfig;
import java.io.File;
import java.io.FileNotFoundException;
public class SampleDatabase
{
private Environment env;
public SampleDatabase(String homeDirectory)
throws DatabaseException, FileNotFoundException
{
}
public void close()
throws DatabaseException
{
}
}</tt></b> </pre>
<p>
The first thing to notice is that the Environment class is in
the
<span>com.sleepycat.db</span>
package, not the com.sleepycat.collections
package. The
<span>com.sleepycat.db</span>
package contains all core Berkeley DB
functionality. The com.sleepycat.collections package contains
extended functionality that is based on the Java Collections API.
The collections package is layered on top of the
<span>com.sleepycat.db</span>
package. Both packages are needed to create a complete application
based on the DB Java Collections API.
</p>
<p>
The following statements create an
<a href="../../java/com/sleepycat/db/Environment.html" target="_top">Environment</a>
object.
</p>
<a id="cb_java_sampledatabaseconstructor"></a>
<pre class="programlisting">public SampleDatabase(String homeDirectory)
throws DatabaseException, FileNotFoundException
{
<b class="userinput"><tt> System.out.println("Opening environment in: " + homeDirectory);
EnvironmentConfig envConfig = new EnvironmentConfig();
envConfig.setTransactional(true);
envConfig.setAllowCreate(true);
envConfig.setInitializeCache(true);
envConfig.setInitializeLocking(true);
env = new Environment(new File(homeDirectory), envConfig);</tt></b>
} </pre>
<p>
The
<a href="../../java/com/sleepycat/db/EnvironmentConfig.html" target="_top">EnvironmentConfig</a>
class is used to specify environment configuration parameters. The
first configuration option specified — <tt class="methodname">setTransactional()</tt> —
is set to true to create an environment where transactional (and
non-transactional) databases may be opened. While non-transactional
environments can also be created, the examples in this tutorial use
a transactional environment.
</p>
<p>
<tt class="methodname">setAllowCreate()</tt> is set to true to specify
that the environment's files will be created if they don't already
exist. If this parameter is not specified, an exception will be
thrown if the environment does not already exist. A similar
parameter will be used later to cause databases to be created if
they don't exist.
</p>
<p>
When an <tt class="classname">Environment</tt> object is constructed, a home
directory and the environment configuration object are specified.
The home directory is the location of the environment's log files
that store all database information.
</p>
<p>
The following statement closes the environment. The environment
should always be closed when database work is completed to free
allocated resources and to avoid having to run recovery later.
Closing the environment does not automatically close databases, so
databases should be closed explicitly before closing the
environment.
</p>
<a id="cb_close"></a>
<pre class="programlisting"> public void close()
throws DatabaseException
{
<b class="userinput"><tt> env.close();</tt></b>
} </pre>
<p>
The following getter method returns the environment for use by
other classes in the example program. The environment is used for
opening databases and running transactions.
</p>
<a id="cb_getenvironment"></a>
<pre class="programlisting">public class SampleDatabase
{
...
<b class="userinput"><tt> public final Environment getEnvironment()
{
return env;
}</tt></b>
...
} </pre>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="BasicProgram.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="openclasscatalog.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 2. 
The Basic Program
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Opening and Closing the Class Catalog
</td>
</tr>
</table>
</div>
</body>
</html>

237
docs/collections/tutorial/openingforeignkeys.html Normal file
View File

@@ -0,0 +1,237 @@
<?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>
More Secondary Key Indices
</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="UsingSecondaries.html" title="Chapter 3. &#10;&#9;&#9;Using Secondary Indices&#10;&#9;" />
<link rel="previous" href="UsingSecondaries.html" title="Chapter 3. &#10;&#9;&#9;Using Secondary Indices&#10;&#9;" />
<link rel="next" href="indexedcollections.html" title="&#10;&#9;&#9;Creating Indexed Collections&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
More Secondary Key Indices
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="UsingSecondaries.html">Prev</a> </td>
<th width="60%" align="center">Chapter 3. 
Using Secondary Indices
</th>
<td width="20%" align="right"> <a accesskey="n" href="indexedcollections.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="openingforeignkeys"></a>
<span>More Secondary Key Indices</span>
</h2>
</div>
</div>
<div></div>
</div>
<p>
This section builds on the prior section describing secondary key indices.
Two more secondary key indices are defined for indexing the Shipment record
by PartNumber and by SupplierNumber.
</p>
<p>
The <tt class="classname">SampleDatabase</tt> class is extended to open the
Shipment-by-Part and Shipment-by-Supplier secondary key
indices.
</p>
<a id="index_java_sampledatabase1"></a>
<pre class="programlisting"><b class="userinput"><tt>import com.sleepycat.bind.serial.SerialSerialKeyCreator;
import com.sleepycat.db.SecondaryConfig;
import com.sleepycat.db.SecondaryDatabase;</tt></b>
...
public class SampleDatabase
{
...
<b class="userinput"><tt> private static final String SHIPMENT_PART_INDEX = "shipment_part_index";
private static final String SHIPMENT_SUPPLIER_INDEX =
"shipment_supplier_index";
...
private SecondaryDatabase shipmentByPartDb;
private SecondaryDatabase shipmentBySupplierDb;
...</tt></b>
public SampleDatabase(String homeDirectory)
throws DatabaseException, FileNotFoundException
{
...
SecondaryConfig secConfig = new SecondaryConfig();
secConfig.setTransactional(true);
secConfig.setAllowCreate(true);
secConfig.setType(DatabaseType.BTREE);
secConfig.setSortedDuplicates(true);
...
<b class="userinput"><tt> secConfig.setKeyCreator(
new ShipmentByPartKeyCreator(javaCatalog,
ShipmentKey.class,
ShipmentData.class,
PartKey.class));
shipmentByPartDb = env.openSecondaryDatabase(null,
SHIPMENT_PART_INDEX,
null,
shipmentDb,
secConfig);
secConfig.setKeyCreator(
new ShipmentBySupplierKeyCreator(javaCatalog,
ShipmentKey.class,
ShipmentData.class,
SupplierKey.class));
shipmentBySupplierDb = env.openSecondaryDatabase(null,
SHIPMENT_SUPPLIER_INDEX,
null,
shipmentDb,
secConfig);</tt></b>
...
}
} </pre>
<p>
The statements in this example are very similar to the statements used in
the previous section for opening a secondary index.
</p>
<p>
The application-defined <tt class="classname">ShipmentByPartKeyCreator</tt>
and <tt class="classname">ShipmentBySupplierKeyCreator</tt> classes are shown below. They
were used above to configure the secondary database objects.
</p>
<a id="index_shipmentbypartkeycreator"></a>
<pre class="programlisting">public class SampleDatabase
{
...
<b class="userinput"><tt> private static class ShipmentByPartKeyCreator
extends SerialSerialKeyCreator
{
private ShipmentByPartKeyCreator(StoredClassCatalog catalog,
Class primaryKeyClass,
Class valueClass,
Class indexKeyClass)
{
super(catalog, primaryKeyClass, valueClass, indexKeyClass);
}
public Object createSecondaryKey(Object primaryKeyInput,
Object valueInput)
{
ShipmentKey shipmentKey = (ShipmentKey) primaryKeyInput;
return new PartKey(shipmentKey.getPartNumber());
}
}
private static class ShipmentBySupplierKeyCreator
extends SerialSerialKeyCreator
{
private ShipmentBySupplierKeyCreator(StoredClassCatalog catalog,
Class primaryKeyClass,
Class valueClass,
Class indexKeyClass)
{
super(catalog, primaryKeyClass, valueClass, indexKeyClass);
}
public Object createSecondaryKey(Object primaryKeyInput,
Object valueInput)
{
ShipmentKey shipmentKey = (ShipmentKey) primaryKeyInput;
return new SupplierKey(shipmentKey.getSupplierNumber());
}
}</tt></b>
...
} </pre>
<p>
The key creator classes above are almost identical to the one
defined in the previous section for use with a secondary index. The
index key fields are different, of course, but the interesting
difference is that the index keys are extracted from the key, not
the value, of the Shipment record. This illustrates that an index
key may be derived from the primary database record key, value, or
both.
</p>
<p>
The following getter methods return the secondary database
objects for use by other classes in the example program.
</p>
<a id="index_sampledatabasegetters"></a>
<pre class="programlisting">public class SampleDatabase
{
...
<b class="userinput"><tt> public final SecondaryDatabase getShipmentByPartDatabase()
{
return shipmentByPartDb;
}
public final SecondaryDatabase getShipmentBySupplierDatabase()
{
return shipmentBySupplierDb;
}</tt></b>
...
} </pre>
<p>
The following statements close the secondary databases.
</p>
<a id="index_close2"></a>
<pre class="programlisting">public class SampleDatabase
{
...
public void close()
throws DatabaseException {
supplierByCityDb.close();
<b class="userinput"><tt> shipmentByPartDb.close();
shipmentBySupplierDb.close();</tt></b>
partDb.close();
supplierDb.close();
shipmentDb.close();
javaCatalog.close();
env.close();
}
...
} </pre>
<p>
Secondary databases must be closed before closing their
associated primary database.
</p>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="UsingSecondaries.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="UsingSecondaries.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="indexedcollections.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 3. 
Using Secondary Indices
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Creating Indexed Collections
</td>
</tr>
</table>
</div>
</body>
</html>

132
docs/collections/tutorial/preface.html Normal file
View File

@@ -0,0 +1,132 @@
<?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>Preface</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="index.html" title="Berkeley DB Collections Tutorial" />
<link rel="next" href="moreinfo.html" title="For More Information" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Preface</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="moreinfo.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="preface" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="preface"></a>Preface</h2>
</div>
</div>
<div></div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="sect1">
<a href="preface.html#conventions">Conventions Used in this Book</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="moreinfo.html">For More Information</a>
</span>
</dt>
</dl>
</div>
<p>
Welcome to the Berkeley DB (DB) Collections API. This document
provides a tutorial that introduces the collections API.
The goal of this document is to provide you with an efficient mechanism
with which you can quickly become efficient with this API. As such, this document is
intended for Java developers and senior software architects who are
looking for transactionally-protected backing of their Java collections.
No prior experience with DB technologies is expected or required.
</p>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="conventions"></a>Conventions Used in this Book</h2>
</div>
</div>
<div></div>
</div>
<p>
The following typographical conventions are used within in this manual:
</p>
<p>
Class names are represented in <tt class="classname">monospaced font</tt>, as are <tt class="methodname">method
names</tt>. For example: "The <tt class="methodname">Environment.openDatabase()</tt> method
returns a <tt class="classname">Database</tt> class object."
</p>
<p>
Variable or non-literal text is presented in <span class="emphasis"><em>italics</em></span>. For example: "Go to your
<span class="emphasis"><em>DB_INSTALLATION_HOME</em></span> directory."
</p>
<p>
Program examples are displayed in a monospaced font on a shaded background. For example:
</p>
<pre class="programlisting">import com.sleepycat.db.Environment;
import com.sleepycat.db.EnvironmentConfig;
import java.io.File;
...
// Open the environment. Allow it to be created if it does not already exist.
Environment myDbEnvironment;</pre>
<p>
In situations in this book, programming examples are updated from one chapter to the next in this book. When
this occurs, the new code is presented in <b class="userinput"><tt>monospaced bold</tt></b> font. For example:
</p>
<pre class="programlisting">import com.sleepycat.db.Environment;
import com.sleepycat.db.EnvironmentConfig;
import java.io.File;
...
// Open the environment. Allow it to be created if it does not already exist.
<b class="userinput"><tt>Environment myDbEnv;
EnvironmentConfig envConfig = new EnvironmentConfig();
envConfig.setAllowCreate(true);
myDbEnv = new Environment(new File("/export/dbEnv"), envConfig);</tt></b> </pre>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="index.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="moreinfo.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Berkeley DB Collections Tutorial </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> For More Information</td>
</tr>
</table>
</div>
</body>
</html>

130
docs/collections/tutorial/removingredundantvalueclasses.html Normal file
View File

@@ -0,0 +1,130 @@
<?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>
Removing the Redundant Value Classes
</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="SerializableEntity.html" title="Chapter 6. &#10;&#9;&#9;Using Serializable Entities&#10;&#9;" />
<link rel="previous" href="transientfieldsinbinding.html" title="&#10;&#9;&#9;Using Transient Fields in an Entity Binding&#10;&#9;" />
<link rel="next" href="Summary.html" title="Chapter 7. &#10;&#9;&#9;Summary&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Removing the Redundant Value Classes
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="transientfieldsinbinding.html">Prev</a> </td>
<th width="60%" align="center">Chapter 6. 
Using Serializable Entities
</th>
<td width="20%" align="right"> <a accesskey="n" href="Summary.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="removingredundantvalueclasses"></a>
Removing the Redundant Value Classes
</h2>
</div>
</div>
<div></div>
</div>
<p>
The <tt class="classname">PartData</tt>, <tt class="classname">SupplierData</tt> and <tt class="classname">ShipmentData</tt>
classes have been removed in this example, and the <tt class="classname">Part</tt>,
<tt class="classname">Supplier</tt> and <tt class="classname">Shipment</tt> entity classes are used in
their place.
</p>
<p>
The serial formats are created with the entity classes.
</p>
<a id="sentity_sampledatabase"></a>
<pre class="programlisting">public class SampleDatabase
{
...
public SampleDatabase(String homeDirectory)
throws DatabaseException, FileNotFoundException
{
...
secConfig.setKeyCreator(new SupplierByCityKeyCreator(javaCatalog,
<b class="userinput"><tt>Supplier</tt></b>.class));
...
secConfig.setKeyCreator(new ShipmentByPartKeyCreator(javaCatalog,
<b class="userinput"><tt>Shipment</tt></b>.class));
...
secConfig.setKeyCreator(new ShipmentBySupplierKeyCreator(javaCatalog,
<b class="userinput"><tt>Shipment</tt></b>.class));
...
}
} </pre>
<p>
The index key creator uses the entity class as well.
</p>
<a id="sentity_supplierbycitykeycreator"></a>
<pre class="programlisting">public class SampleDatabase
{
...
private static class SupplierByCityKeyCreator
extends TupleSerialKeyCreator
{
private SupplierByCityKeyCreator(ClassCatalog catalog,
Class valueClass)
{
super(catalog, valueClass);
}
public boolean createSecondaryKey(TupleInput primaryKeyInput,
Object valueInput,
TupleOutput indexKeyOutput)
{
<b class="userinput"><tt>Supplier</tt></b> supplier = (<b class="userinput"><tt>Supplier</tt></b>) valueInput;
String city = supplier.getCity();
if (city != null) {
indexKeyOutput.writeString(supplier.getCity());
return true;
} else {
return false;
}
}
}
} </pre>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="transientfieldsinbinding.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="SerializableEntity.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="Summary.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Using Transient Fields in an Entity Binding
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Chapter 7. 
Summary
</td>
</tr>
</table>
</div>
</body>
</html>

279
docs/collections/tutorial/retrievingbyindexkey.html Normal file
View File

@@ -0,0 +1,279 @@
<?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>
Retrieving Items by Index Key
</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="UsingSecondaries.html" title="Chapter 3. &#10;&#9;&#9;Using Secondary Indices&#10;&#9;" />
<link rel="previous" href="indexedcollections.html" title="&#10;&#9;&#9;Creating Indexed Collections&#10;&#9;" />
<link rel="next" href="Entity.html" title="Chapter 4. &#10; Using Entity Classes&#9;&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Retrieving Items by Index Key
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="indexedcollections.html">Prev</a> </td>
<th width="60%" align="center">Chapter 3. 
Using Secondary Indices
</th>
<td width="20%" align="right"> <a accesskey="n" href="Entity.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="retrievingbyindexkey"></a>
Retrieving Items by Index Key
</h2>
</div>
</div>
<div></div>
</div>
<p>
Retrieving information via database index keys can be
accomplished using the standard Java collections API, using a
collection created from a
<a href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>
rather than a
<span>
<a href="../../java/com/sleepycat/db/Database.html" target="_top">Database</a>.
</span>
However, the standard Java API does not support <span class="emphasis"><em>duplicate keys</em></span>: more
than one element in a collection having the same key. All three
indices created in the prior section have duplicate keys because of
the nature of the city, part number and supplier number index keys.
More than one supplier may be in the same city, and more than one
shipment may have the same part number or supplier number. This
section describes how to use extended methods for stored
collections to return all values for a given key.
</p>
<p>
Using the standard Java collections API, the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#get" target="_top">Map.get</a>
method for a stored collection with duplicate keys will return only
the first value for a given key. To obtain all values for a given
key, the
<a href="../../java/com/sleepycat/collections/StoredMap.html#duplicates(java.lang.Object)" target="_top">StoredMap.duplicates</a>
method may be called. This returns a
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collection.html" target="_top">Collection</a>
of values for the given key. If duplicate keys are not allowed, the
returned collection will have at most one value. If the key is not
present in the map, an empty collection is returned.
</p>
<p>
The <tt class="classname">Sample</tt> class is extended to retrieve duplicates for
specific index keys that are present in the database.
</p>
<a id="index_sampleviewsprintdatabase"></a>
<pre class="programlisting">import java.util.Iterator;
...
public class Sample
{
...
private SampleViews views;
...
private class PrintDatabase implements TransactionWorker
{
public void doWork()
throws Exception
{
printEntries("Parts",
views.getPartEntrySet().iterator());
printEntries("Suppliers",
views.getSupplierEntrySet().iterator());
<b class="userinput"><tt> printValues("Suppliers for City Paris",
views.getSupplierByCityMap().duplicates(
"Paris").iterator());</tt></b>
printEntries("Shipments",
views.getShipmentEntrySet().iterator());
<b class="userinput"><tt> printValues("Shipments for Part P1",
views.getShipmentByPartMap().duplicates(
new PartKey("P1")).iterator());
printValues("Shipments for Supplier S1",
views.getShipmentBySupplierMap().duplicates(
new
SupplierKey("S1")).iterator());</tt></b>
}
}
<b class="userinput"><tt> private void printValues(String label, Iterator iterator)
{
System.out.println("\n--- " + label + " ---");
while (iterator.hasNext())
{
System.out.println(iterator.next().toString());
}
} </tt></b>
...
} </pre>
<p>
The
<a href="../../java/com/sleepycat/collections/StoredMap.html#duplicates(java.lang.Object)" target="_top">StoredMap.duplicates</a>
method is called passing the desired key. The returned value is a
standard Java
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collection.html" target="_top">Collection</a>
containing the values for the specified key. A standard Java
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Iterator.html" target="_top">Iterator</a>
is then obtained for this collection and all values returned by
that iterator are printed.
</p>
<p>
Another technique for retrieving duplicates is to use the
collection returned by
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#entrySet" target="_top">Map.entrySet</a>.
When duplicate keys are present, a
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.Entry.html" target="_top">Map.Entry</a>
object will be present in this collection for each duplicate. This
collection can then be iterated or a subset can be created from it,
all using the standard Java collection API.
</p>
<p>
Note that we did not discuss how duplicates keys can be
explicitly added or removed in a collection. For index keys, the
addition and deletion of duplicate keys happens automatically when
records containing the index key are added, updated, or
removed.
</p>
<p>
While not shown in the example program, it is also possible to
create a store with duplicate keys in the same way as an index with
duplicate keys — by calling
<tt class="methodname">DatabaseConfig.setSortedDuplicates()</tt> method. In that case,
calling
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#put" target="_top">Map.put</a>
will add duplicate keys. To remove all duplicate keys, call
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#remove" target="_top">Map.remove</a>.
To remove a specific duplicate key, call
<a href="../../java/com/sleepycat/collections/StoredMap.html#duplicates(java.lang.Object)" target="_top">StoredMap.duplicates</a>
and then call
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collection.html#remove" target="_top">Collection.remove</a>
using the returned collection. Duplicate
values may also be added to this collection using
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collection.html#add" target="_top"> Collection.add</a>.
</p>
<p>
The output of the example program is shown below.
</p>
<pre class="programlisting">Adding Suppliers
Adding Parts
Adding Shipments
--- Parts ---
PartKey: number=P1
PartData: name=Nut color=Red weight=[12.0 grams] city=London
PartKey: number=P2
PartData: name=Bolt color=Green weight=[17.0 grams] city=Paris
PartKey: number=P3
PartData: name=Screw color=Blue weight=[17.0 grams] city=Rome
PartKey: number=P4
PartData: name=Screw color=Red weight=[14.0 grams] city=London
PartKey: number=P5
PartData: name=Cam color=Blue weight=[12.0 grams] city=Paris
PartKey: number=P6
PartData: name=Cog color=Red weight=[19.0 grams] city=London
--- Suppliers ---
SupplierKey: number=S1
SupplierData: name=Smith status=20 city=London
SupplierKey: number=S2
SupplierData: name=Jones status=10 city=Paris
SupplierKey: number=S3
SupplierData: name=Blake status=30 city=Paris
SupplierKey: number=S4
SupplierData: name=Clark status=20 city=London
SupplierKey: number=S5
SupplierData: name=Adams status=30 city=Athens
<b class="userinput"><tt>--- Suppliers for City Paris ---
SupplierData: name=Jones status=10 city=Paris
SupplierData: name=Blake status=30 city=Paris</tt></b>
--- Shipments ---
ShipmentKey: supplier=S1 part=P1
ShipmentData: quantity=300
ShipmentKey: supplier=S2 part=P1
ShipmentData: quantity=300
ShipmentKey: supplier=S1 part=P2
ShipmentData: quantity=200
ShipmentKey: supplier=S2 part=P2
ShipmentData: quantity=400
ShipmentKey: supplier=S3 part=P2
ShipmentData: quantity=200
ShipmentKey: supplier=S4 part=P2
ShipmentData: quantity=200
ShipmentKey: supplier=S1 part=P3
ShipmentData: quantity=400
ShipmentKey: supplier=S1 part=P4
ShipmentData: quantity=200
ShipmentKey: supplier=S4 part=P4
ShipmentData: quantity=300
ShipmentKey: supplier=S1 part=P5
ShipmentData: quantity=100
ShipmentKey: supplier=S4 part=P5
ShipmentData: quantity=400
ShipmentKey: supplier=S1 part=P6
ShipmentData: quantity=100 <b class="userinput"><tt>
--- Shipments for Part P1 ---
ShipmentData: quantity=300
ShipmentData: quantity=300
--- Shipments for Supplier S1 ---
ShipmentData: quantity=300
ShipmentData: quantity=200
ShipmentData: quantity=400
ShipmentData: quantity=200
ShipmentData: quantity=100
ShipmentData: quantity=100</tt></b> </pre>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="indexedcollections.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="UsingSecondaries.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="Entity.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Creating Indexed Collections
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Chapter 4. 
Using Entity Classes
</td>
</tr>
</table>
</div>
</body>
</html>

216
docs/collections/tutorial/retrievingdatabaseitems.html Normal file
View File

@@ -0,0 +1,216 @@
<?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>
Retrieving Database Items
</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="BasicProgram.html" title="Chapter 2. &#10;&#9;&#9;The Basic Program&#10;&#9;" />
<link rel="previous" href="addingdatabaseitems.html" title="&#10;&#9;&#9;Adding Database Items&#10;&#9;" />
<link rel="next" href="handlingexceptions.html" title="&#10;&#9;&#9;Handling Exceptions&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Retrieving Database Items
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="addingdatabaseitems.html">Prev</a> </td>
<th width="60%" align="center">Chapter 2. 
The Basic Program
</th>
<td width="20%" align="right"> <a accesskey="n" href="handlingexceptions.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="retrievingdatabaseitems"></a>
Retrieving Database Items
</h2>
</div>
</div>
<div></div>
</div>
<p>
Retrieving information from the database is accomplished via the
standard Java collections API. In the example, the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html#iterator" target="_top">Set.iterator</a>
method is used to iterate all
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.Entry.html" target="_top">Map.Entry</a>
objects for each store. All standard Java methods for retrieving
objects from a collection may be used with the DB Java Collections API.
</p>
<p>
The <tt class="methodname">PrintDatabase.doWork()</tt> method calls
<tt class="methodname">printEntries()</tt>
to print the map entries for each database store. It is called via
the
<a href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>
class and was outlined in the previous section.
</p>
<a id="cb_printdatabase"></a>
<pre class="programlisting">import java.util.Iterator;
...
public class Sample
{
...
private SampleViews views;
...
private class PrintDatabase implements TransactionWorker
{
public void doWork()
throws Exception
{
<b class="userinput"><tt> printEntries("Parts",
views.getPartEntrySet().iterator());
printEntries("Suppliers",
views.getSupplierEntrySet().iterator());
printEntries("Shipments",
views.getShipmentEntrySet().iterator());</tt></b>
}
}
...
<b class="userinput"><tt> private void printEntries(String label, Iterator iterator)
{
}</tt></b>
...
} </pre>
<p>
The
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Set.html" target="_top">Set</a>
of
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.Entry.html" target="_top">Map.Entry</a>
objects for each store is obtained from the <tt class="classname">SampleViews</tt>
object. This set can also be obtained by calling the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#entrySet" target="_top">Map.entrySet</a>
method of a stored map.
</p>
<p>
The <tt class="methodname">printEntries()</tt> prints the map entries for any stored
map. The
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Object.html#toString" target="_top">Object.toString</a>
method of each key and value is called to
obtain a printable representation of each object.
</p>
<a id="cb_printentries"></a>
<pre class="programlisting"> private void printEntries(String label, Iterator iterator)
{
<b class="userinput"><tt> System.out.println("\n--- " + label + " ---");
while (iterator.hasNext())
{
Map.Entry entry = (Map.Entry) iterator.next();
System.out.println(entry.getKey().toString());
System.out.println(entry.getValue().toString());
}</tt></b>
} </pre>
<p>
This is one of a small number of behavioral differences between
standard Java collections and stored collections. For a complete
list see
<a href="UsingStoredCollections.html">
Using Stored Collections
</a>.
</p>
<p>
The output of the example program is shown below.
</p>
<pre class="programlisting">Adding Suppliers
Adding Parts
Adding Shipments
--- Parts ---
PartKey: number=P1
PartData: name=Nut color=Red weight=[12.0 grams] city=London
PartKey: number=P2
PartData: name=Bolt color=Green weight=[17.0 grams] city=Paris
PartKey: number=P3
PartData: name=Screw color=Blue weight=[17.0 grams] city=Rome
PartKey: number=P4
PartData: name=Screw color=Red weight=[14.0 grams] city=London
PartKey: number=P5
PartData: name=Cam color=Blue weight=[12.0 grams] city=Paris
PartKey: number=P6
PartData: name=Cog color=Red weight=[19.0 grams] city=London
--- Suppliers ---
SupplierKey: number=S1
SupplierData: name=Smith status=20 city=London
SupplierKey: number=S2
SupplierData: name=Jones status=10 city=Paris
SupplierKey: number=S3
SupplierData: name=Blake status=30 city=Paris
SupplierKey: number=S4
SupplierData: name=Clark status=20 city=London
SupplierKey: number=S5
SupplierData: name=Adams status=30 city=Athens
--- Shipments ---
ShipmentKey: supplier=S1 part=P1
ShipmentData: quantity=300
ShipmentKey: supplier=S2 part=P1
ShipmentData: quantity=300
ShipmentKey: supplier=S1 part=P2
ShipmentData: quantity=200
ShipmentKey: supplier=S2 part=P2
ShipmentData: quantity=400
ShipmentKey: supplier=S3 part=P2
ShipmentData: quantity=200
ShipmentKey: supplier=S4 part=P2
ShipmentData: quantity=200
ShipmentKey: supplier=S1 part=P3
ShipmentData: quantity=400
ShipmentKey: supplier=S1 part=P4
ShipmentData: quantity=200
ShipmentKey: supplier=S4 part=P4
ShipmentData: quantity=300
ShipmentKey: supplier=S1 part=P5
ShipmentData: quantity=100
ShipmentKey: supplier=S4 part=P5
ShipmentData: quantity=400
ShipmentKey: supplier=S1 part=P6
ShipmentData: quantity=100 </pre>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="addingdatabaseitems.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="handlingexceptions.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Adding Database Items
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Handling Exceptions
</td>
</tr>
</table>
</div>
</body>
</html>

149
docs/collections/tutorial/sortedcollections.html Normal file
View File

@@ -0,0 +1,149 @@
<?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>
Using Sorted Collections
</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="Tuple.html" title="Chapter 5. &#10;&#9;&#9;Using Tuples&#10;&#9;" />
<link rel="previous" href="tuple-serialentitybindings.html" title="&#10;Creating Tuple-Serial Entity Bindings&#10;" />
<link rel="next" href="SerializableEntity.html" title="Chapter 6. &#10;&#9;&#9;Using Serializable Entities&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Using Sorted Collections
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="tuple-serialentitybindings.html">Prev</a> </td>
<th width="60%" align="center">Chapter 5. 
Using Tuples
</th>
<td width="20%" align="right"> <a accesskey="n" href="SerializableEntity.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="sortedcollections"></a>
Using Sorted Collections
</h2>
</div>
</div>
<div></div>
</div>
<p>
In general, no changes to the prior example are necessary to use
collections having tuple keys. Iteration of elements in a stored
collection will be ordered by the sort order of the tuples.
</p>
<p>
In addition to using the tuple format, the
<a href="../../java/com/sleepycat/db/DatabaseType.html#BTREE" target="_top">DatabaseType.BTREE</a>
access method must be used when creating the database.
<a href="../../java/com/sleepycat/db/DatabaseType.html#BTREE" target="_top">DatabaseType.BTREE</a>
is used for the databases in all examples. The
<a href="../../java/com/sleepycat/db/DatabaseType.html#HASH" target="_top">DatabaseType.HASH</a>
access method does not support sorted keys.
</p>
<p>
Although not shown in the example, all methods of the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedMap.html" target="_top">SortedMap</a>
and
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>
interfaces may be used with sorted collections. For example,
submaps and subsets may be created.
</p>
<p>
The output of the example program shows that records are sorted
by key value.
</p>
<pre class="programlisting">Adding Suppliers
Adding Parts
Adding Shipments
--- Parts ---
Part: number=P1 name=Nut color=Red weight=[12.0 grams] city=London
Part: number=P2 name=Bolt color=Green weight=[17.0 grams] city=Paris
Part: number=P3 name=Screw color=Blue weight=[17.0 grams] city=Rome
Part: number=P4 name=Screw color=Red weight=[14.0 grams] city=London
Part: number=P5 name=Cam color=Blue weight=[12.0 grams] city=Paris
Part: number=P6 name=Cog color=Red weight=[19.0 grams] city=London
--- Suppliers ---
Supplier: number=S1 name=Smith status=20 city=London
Supplier: number=S2 name=Jones status=10 city=Paris
Supplier: number=S3 name=Blake status=30 city=Paris
Supplier: number=S4 name=Clark status=20 city=London
Supplier: number=S5 name=Adams status=30 city=Athens
--- Suppliers for City Paris ---
Supplier: number=S2 name=Jones status=10 city=Paris
Supplier: number=S3 name=Blake status=30 city=Paris
--- Shipments ---
Shipment: part=P1 supplier=S1 quantity=300
Shipment: part=P1 supplier=S2 quantity=300
Shipment: part=P2 supplier=S1 quantity=200
Shipment: part=P2 supplier=S2 quantity=400
Shipment: part=P2 supplier=S3 quantity=200
Shipment: part=P2 supplier=S4 quantity=200
Shipment: part=P3 supplier=S1 quantity=400
Shipment: part=P4 supplier=S1 quantity=200
Shipment: part=P4 supplier=S4 quantity=300
Shipment: part=P5 supplier=S1 quantity=100
Shipment: part=P5 supplier=S4 quantity=400
Shipment: part=P6 supplier=S1 quantity=100
--- Shipments for Part P1 ---
Shipment: part=P1 supplier=S1 quantity=300
Shipment: part=P1 supplier=S2 quantity=300
--- Shipments for Supplier S1 ---
Shipment: part=P1 supplier=S1 quantity=300
Shipment: part=P2 supplier=S1 quantity=200
Shipment: part=P3 supplier=S1 quantity=400
Shipment: part=P4 supplier=S1 quantity=200
Shipment: part=P5 supplier=S1 quantity=100
Shipment: part=P6 supplier=S1 quantity=100 </pre>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="tuple-serialentitybindings.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="Tuple.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="SerializableEntity.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Creating Tuple-Serial Entity Bindings
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Chapter 6. 
Using Serializable Entities
</td>
</tr>
</table>
</div>
</body>
</html>

177
docs/collections/tutorial/transientfieldsinbinding.html Normal file
View File

@@ -0,0 +1,177 @@
<?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>
Using Transient Fields in an Entity Binding
</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="SerializableEntity.html" title="Chapter 6. &#10;&#9;&#9;Using Serializable Entities&#10;&#9;" />
<link rel="previous" href="SerializableEntity.html" title="Chapter 6. &#10;&#9;&#9;Using Serializable Entities&#10;&#9;" />
<link rel="next" href="removingredundantvalueclasses.html" title="&#10;&#9;&#9;Removing the Redundant Value Classes&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Using Transient Fields in an Entity Binding
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="SerializableEntity.html">Prev</a> </td>
<th width="60%" align="center">Chapter 6. 
Using Serializable Entities
</th>
<td width="20%" align="right"> <a accesskey="n" href="removingredundantvalueclasses.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="transientfieldsinbinding"></a>
Using Transient Fields in an Entity Binding
</h2>
</div>
</div>
<div></div>
</div>
<p>
The entity bindings from the prior example have been changed in
this example to use the entity object both as a value object and an
entity object.
</p>
<p>
Before, the <tt class="methodname">entryToObject()</tt> method combined the
deserialized value object with the key fields to create a new
entity object. Now, this method uses the deserialized object
directly as an entity, and initializes its key using the fields
read from the key tuple.
</p>
<p>
Before, the <tt class="methodname">objectToData()</tt> method constructed a new value
object using information in the entity. Now it simply returns the
entity. Nothing needs to be changed in the entity, since the
transient key fields won't be serialized.
</p>
<a id="sentity_partbinding"></a>
<pre class="programlisting">import com.sleepycat.bind.serial.ClassCatalog;
...
public class SampleViews
{
...
private static class PartBinding extends TupleSerialBinding
{
private PartBinding(ClassCatalog classCatalog, Class dataClass)
{
super(classCatalog, dataClass);
}
public Object entryToObject(TupleInput keyInput, Object dataInput)
{
String number = keyInput.readString();
<b class="userinput"><tt> Part part = (Part) dataInput;
part.setKey(number);
return part;</tt></b>
}
public void objectToKey(Object object, TupleOutput output)
{
Part part = (Part) object;
output.writeString(part.getNumber());
}
public Object objectToData(Object object)
{
<b class="userinput"><tt> return object;</tt></b>
}
}
private static class SupplierBinding extends TupleSerialBinding
{
private SupplierBinding(ClassCatalog classCatalog, Class dataClass)
{
super(classCatalog, dataClass);
}
public Object entryToObject(TupleInput keyInput, Object dataInput)
{
String number = keyInput.readString();
<b class="userinput"><tt> Supplier supplier = (Supplier) dataInput;
supplier.setKey(number);
return supplier;</tt></b>
}
public void objectToKey(Object object, TupleOutput output)
{
Supplier supplier = (Supplier) object;
output.writeString(supplier.getNumber());
}
public Object objectToData(Object object)
{
<b class="userinput"><tt> return object;</tt></b>
}
}
private static class ShipmentBinding extends TupleSerialBinding
{
private ShipmentBinding(ClassCatalog classCatalog, Class dataClass)
{
super(classCatalog, dataClass);
}
public Object entryToObject(TupleInput keyInput, Object dataInput)
{
String partNumber = keyInput.readString();
String supplierNumber = keyInput.readString();
<b class="userinput"><tt> Shipment shipment = (Shipment) dataInput;
shipment.setKey(partNumber, supplierNumber);
return shipment;</tt></b>
}
public void objectToKey(Object object, TupleOutput output)
{
Shipment shipment = (Shipment) object;
output.writeString(shipment.getPartNumber());
output.writeString(shipment.getSupplierNumber());
}
public Object objectToData(Object object)
{
<b class="userinput"><tt> return object;</tt></b>
}
}
} </pre>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="SerializableEntity.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="SerializableEntity.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="removingredundantvalueclasses.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 6. 
Using Serializable Entities
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Removing the Redundant Value Classes
</td>
</tr>
</table>
</div>
</body>
</html>

197
docs/collections/tutorial/tuple-serialentitybindings.html Normal file
View File

@@ -0,0 +1,197 @@
<?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 Tuple-Serial Entity Bindings
</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="Tuple.html" title="Chapter 5. &#10;&#9;&#9;Using Tuples&#10;&#9;" />
<link rel="previous" href="tuplekeybindings.html" title="&#10;&#9;&#9;Creating Tuple Key Bindings&#10;&#9;" />
<link rel="next" href="sortedcollections.html" title="&#10;&#9;&#9;Using Sorted Collections&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Creating Tuple-Serial Entity Bindings
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="tuplekeybindings.html">Prev</a> </td>
<th width="60%" align="center">Chapter 5. 
Using Tuples
</th>
<td width="20%" align="right"> <a accesskey="n" href="sortedcollections.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="tuple-serialentitybindings"></a>
Creating Tuple-Serial Entity Bindings
</h2>
</div>
</div>
<div></div>
</div>
<p>
In the prior example serial keys and serial values were used,
and the
<a href="../../java/com/sleepycat/bind/serial/SerialSerialBinding.html" target="_top">SerialSerialBinding</a>
base class was used for entity bindings. In this example, tuple
keys and serial values are used and therefore the
<a href="../../java/com/sleepycat/bind/serial/TupleSerialBinding.html" target="_top">TupleSerialBinding</a>
base class is used for entity bindings.
</p>
<p>
As with any entity binding, a key and value is converted to an
entity in the
<a href="../../java/com/sleepycat/bind/serial/TupleSerialBinding.html#entryToObject(com.sleepycat.bind.tuple.TupleInput,%20java.lang.Object)" target="_top">TupleSerialBinding.entryToObject</a>
method, and from an entity to
a key and value in the
<a href="../../java/com/sleepycat/bind/serial/TupleSerialBinding.html#objectToKey(java.lang.Object,%20com.sleepycat.db.DatabaseEntry)" target="_top">TupleSerialBinding.objectToKey</a>
and
<a href="../../java/com/sleepycat/bind/serial/TupleSerialBinding.html#objectToData(java.lang.Object)" target="_top">TupleSerialBinding.objectToData</a>
methods. But since keys are
stored as tuples, not as serialized objects, key fields are read
and written using the
<a href="../../java/com/sleepycat/bind/tuple/TupleInput.html" target="_top">TupleInput</a>
and
<a href="../../java/com/sleepycat/bind/tuple/TupleOutput.html" target="_top">TupleOutput</a>
parameters.
</p>
<p>
The <tt class="classname">SampleViews</tt> class contains the modified entity
binding classes that were defined in the prior example:
<tt class="classname">PartBinding</tt>, <tt class="classname">SupplierBinding</tt> and
<tt class="classname">ShipmentBinding</tt>.
</p>
<a id="tuple_partbinding"></a>
<pre class="programlisting"><b class="userinput"><tt>import com.sleepycat.bind.serial.TupleSerialBinding;
import com.sleepycat.bind.tuple.TupleInput;
import com.sleepycat.bind.tuple.TupleOutput;
...</tt></b>
public class SampleViews
{
...
private static class PartBinding extends <b class="userinput"><tt>TupleSerialBinding</tt></b>
{
private PartBinding(ClassCatalog classCatalog, <b class="userinput"><tt>Class dataClass</tt></b>)
{
super(classCatalog, dataClass);
}
public Object entryToObject(<b class="userinput"><tt>TupleInput</tt></b> keyInput, Object dataInput)
{
<b class="userinput"><tt> String number = keyInput.readString();</tt></b>
PartData data = (PartData) dataInput;
return new Part(<b class="userinput"><tt>number</tt></b>, data.getName(), data.getColor(),
data.getWeight(), data.getCity());
}
public void objectToKey(Object object, TupleOutput output)
{
Part part = (Part) object;
<b class="userinput"><tt> output.writeString(part.getNumber());</tt></b>
}
public Object objectToData(Object object)
{
Part part = (Part) object;
return new PartData(part.getName(), part.getColor(),
part.getWeight(), part.getCity());
}
}
...
private static class SupplierBinding extends <b class="userinput"><tt>TupleSerialBinding</tt></b>
{
private SupplierBinding(ClassCatalog classCatalog, <b class="userinput"><tt>Class dataClass</tt></b>)
{
super(classCatalog, dataClass);
}
public Object entryToObject(<b class="userinput"><tt>TupleInput</tt></b> keyInput, Object dataInput)
{
<b class="userinput"><tt> String number = keyInput.readString();</tt></b>
SupplierData data = (SupplierData) dataInput;
return new Supplier(<b class="userinput"><tt>number</tt></b>, data.getName(),
data.getStatus(), data.getCity());
}
public void objectToKey(Object object, TupleOutput output)
{
Supplier supplier = (Supplier) object;
<b class="userinput"><tt> output.writeString(supplier.getNumber());</tt></b>
}
public Object objectToData(Object object)
{
Supplier supplier = (Supplier) object;
return new SupplierData(supplier.getName(), supplier.getStatus(),
supplier.getCity());
}
}
...
private static class ShipmentBinding extends <b class="userinput"><tt>TupleSerialBinding</tt></b>
{
private ShipmentBinding(ClassCatalog classCatalog, <b class="userinput"><tt>Class dataClass</tt></b>)
{
super(classCatalog, dataClass);
}
public Object entryToObject(<b class="userinput"><tt>TupleInput</tt></b> keyInput, Object dataInput)
{
<b class="userinput"><tt> String partNumber = keyInput.readString();
String supplierNumber = keyInput.readString();</tt></b>
ShipmentData data = (ShipmentData) dataInput;
return new Shipment(<b class="userinput"><tt>partNumber, supplierNumber</tt></b>,
data.getQuantity());
}
public void objectToKey(Object object, TupleOutput output)
{
Shipment shipment = (Shipment) object;
<b class="userinput"><tt> output.writeString(shipment.getPartNumber());
output.writeString(shipment.getSupplierNumber());</tt></b>
}
public Object objectToData(Object object)
{
Shipment shipment = (Shipment) object;
return new ShipmentData(shipment.getQuantity());
}
}
...
} </pre>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="tuplekeybindings.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="Tuple.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="sortedcollections.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Creating Tuple Key Bindings
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Using Sorted Collections
</td>
</tr>
</table>
</div>
</body>
</html>

220
docs/collections/tutorial/tuplekeybindings.html Normal file
View File

@@ -0,0 +1,220 @@
<?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 Tuple Key Bindings
</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="Tuple.html" title="Chapter 5. &#10;&#9;&#9;Using Tuples&#10;&#9;" />
<link rel="previous" href="tupleswithkeycreators.html" title="&#10;&#9;&#9;Using Tuples with Key Creators&#10;&#9;" />
<link rel="next" href="tuple-serialentitybindings.html" title="&#10;Creating Tuple-Serial Entity Bindings&#10;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Creating Tuple Key Bindings
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="tupleswithkeycreators.html">Prev</a> </td>
<th width="60%" align="center">Chapter 5. 
Using Tuples
</th>
<td width="20%" align="right"> <a accesskey="n" href="tuple-serialentitybindings.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="tuplekeybindings"></a>
Creating Tuple Key Bindings
</h2>
</div>
</div>
<div></div>
</div>
<p>
Serial bindings were used in prior examples as key bindings, and
keys were stored as serialized objects. In this example, a tuple
binding is used for each key since keys will be stored as tuples.
Because keys are no longer stored as serialized objects, the
<tt class="classname">PartKey</tt>, <tt class="classname">SupplierKey</tt> and <tt class="classname">ShipmentKey</tt> classes
no longer implement the
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/io/Serializable.html" target="_top">Serializable</a>
interface (this is the only change to these classes and is not
shown below).
</p>
<p>
For the <tt class="classname">Part</tt> key, <tt class="classname">Supplier</tt> key,
and <tt class="classname">Shipment</tt> key, the
<tt class="classname">SampleViews</tt> class was changed in this example to create a
custom
<a href="../../java/com/sleepycat/bind/tuple/TupleBinding.html" target="_top">TupleBinding</a>
instead of a
<a href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a>.
The custom tuple key binding classes are defined further below.
</p>
<a id="tuple_sampleviews"></a>
<pre class="programlisting"><b class="userinput"><tt>import com.sleepycat.bind.tuple.TupleBinding;
...</tt></b>
public class SampleViews
{
...
public SampleViews(SampleDatabase db)
{
...
ClassCatalog catalog = db.getClassCatalog();
<b class="userinput"><tt> EntryBinding partKeyBinding =
new PartKeyBinding();
EntityBinding partDataBinding =
new PartBinding(catalog, PartData.class);
EntryBinding supplierKeyBinding =
new SupplierKeyBinding();
EntityBinding supplierDataBinding =
new SupplierBinding(catalog, SupplierData.class);
EntryBinding shipmentKeyBinding =
new ShipmentKeyBinding();
EntityBinding shipmentDataBinding =
new ShipmentBinding(catalog, ShipmentData.class);
EntryBinding cityKeyBinding =
TupleBinding.getPrimitiveBinding(String.class);</tt></b>
...
}
} </pre>
<p>
For the City key, however, a custom binding class is not needed
because the key class is a primitive Java type,
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/String.html" target="_top">String</a>.
For any primitive Java type, a tuple binding may be created using the
<a href="../../java/com/sleepycat/bind/tuple/TupleBinding.html#getPrimitiveBinding(java.lang.Class)" target="_top">TupleBinding.getPrimitiveBinding</a>
static method.
</p>
<p>
The custom key binding classes, <tt class="classname">PartKeyBinding</tt>,
<tt class="classname">SupplierKeyBinding</tt> and <tt class="classname">ShipmentKeyBinding</tt>, are
defined by extending the
<a href="../../java/com/sleepycat/bind/tuple/TupleBinding.html" target="_top">TupleBinding</a>
class. The
<a href="../../java/com/sleepycat/bind/tuple/TupleBinding.html" target="_top">TupleBinding</a>
abstract class implements the
<a href="../../java/com/sleepycat/bind/EntryBinding.html" target="_top">EntryBinding</a>
interface, and is used for one-to-one bindings between tuples and
objects. Each binding class implements two methods for converting
between tuples and objects. Tuple fields are read using the
<a href="../../java/com/sleepycat/bind/tuple/TupleInput.html" target="_top">TupleInput</a>
parameter and written using the
<a href="../../java/com/sleepycat/bind/tuple/TupleOutput.html" target="_top">TupleOutput</a>
parameter.
</p>
<a id="tuple_partkeybinding"></a>
<pre class="programlisting"><b class="userinput"><tt>import com.sleepycat.bind.tuple.TupleBinding;
import com.sleepycat.bind.tuple.TupleInput;
import com.sleepycat.bind.tuple.TupleOutput;
...</tt></b>
public class SampleViews
{
...
<b class="userinput"><tt>private static class PartKeyBinding extends TupleBinding
{
private PartKeyBinding()
{
}
public Object entryToObject(TupleInput input)
{
String number = input.readString();
return new PartKey(number);
}
public void objectToEntry(Object object, TupleOutput output)
{
PartKey key = (PartKey) object;
output.writeString(key.getNumber());
}
}
...
private static class SupplierKeyBinding extends TupleBinding
{
private SupplierKeyBinding()
{
}
public Object entryToObject(TupleInput input)
{
String number = input.readString();
return new SupplierKey(number);
}
public void objectToEntry(Object object, TupleOutput output)
{
SupplierKey key = (SupplierKey) object;
output.writeString(key.getNumber());
}
}
...
private static class ShipmentKeyBinding extends TupleBinding
{
private ShipmentKeyBinding()
{
}
public Object entryToObject(TupleInput input)
{
String partNumber = input.readString();
String supplierNumber = input.readString();
return new ShipmentKey(partNumber, supplierNumber);
}
public void objectToEntry(Object object, TupleOutput output)
{
ShipmentKey key = (ShipmentKey) object;
output.writeString(key.getPartNumber());
output.writeString(key.getSupplierNumber());
}
}</tt></b>
...
} </pre>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="tupleswithkeycreators.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="Tuple.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="tuple-serialentitybindings.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Using Tuples with Key Creators
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Creating Tuple-Serial Entity Bindings
</td>
</tr>
</table>
</div>
</body>
</html>

206
docs/collections/tutorial/tupleswithkeycreators.html Normal file
View File

@@ -0,0 +1,206 @@
<?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>
Using Tuples with Key Creators
</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="Tuple.html" title="Chapter 5. &#10;&#9;&#9;Using Tuples&#10;&#9;" />
<link rel="previous" href="Tuple.html" title="Chapter 5. &#10;&#9;&#9;Using Tuples&#10;&#9;" />
<link rel="next" href="tuplekeybindings.html" title="&#10;&#9;&#9;Creating Tuple Key Bindings&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Using Tuples with Key Creators
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="Tuple.html">Prev</a> </td>
<th width="60%" align="center">Chapter 5. 
Using Tuples
</th>
<td width="20%" align="right"> <a accesskey="n" href="tuplekeybindings.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="tupleswithkeycreators"></a>
Using Tuples with Key Creators
</h2>
</div>
</div>
<div></div>
</div>
<p>
Key creators were used in prior examples to extract index keys
from value objects. The keys were returned as deserialized key
objects, since the serial format was used for keys. In this
example, the tuple format is used for keys and the key creators
return keys by writing information to a tuple. The differences
between this example and the prior example are:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
The
<a href="../../java/com/sleepycat/bind/serial/TupleSerialKeyCreator.html" target="_top">TupleSerialKeyCreator</a>
base class is used instead of the
<a href="../../java/com/sleepycat/bind/serial/SerialSerialKeyCreator.html" target="_top">SerialSerialKeyCreator</a>
base class.
</p>
</li>
<li>
<p>
For all key input and output parameters, the
<a href="../../java/com/sleepycat/bind/tuple/TupleInput.html" target="_top">TupleInput</a>
and
<a href="../../java/com/sleepycat/bind/tuple/TupleOutput.html" target="_top">TupleOutput</a>
classes are used instead of
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Object.html" target="_top">Object</a>
(representing a deserialized object).
</p>
</li>
<li>
<p>
Instead of returning a key output object, these methods call
tuple write methods such as
<a href="../../java/com/sleepycat/bind/tuple/TupleOutput.html#writeString(java.lang.String)" target="_top">TupleOutput.writeString</a>.
</p>
</li>
</ul>
</div>
<p>
In addition to writing key tuples, the
<tt class="classname">ShipmentByPartKeyCreator</tt> and
<tt class="classname">ShipmentBySupplierKeyCreator</tt> classes also read the key tuple
of the primary key. This is because they extract the index key from
fields in the Shipment's primary key. Instead of calling getter
methods on the <tt class="classname">ShipmentKey</tt> object, as in prior examples,
these methods call
<a href="../../java/com/sleepycat/bind/tuple/TupleInput.html#readString()" target="_top">TupleInput.readString</a>.
The <tt class="classname">ShipmentKey</tt> consists of two string fields that are read
in sequence.
</p>
<p>
The modified key creators are shown below:
<tt class="classname">SupplierByCityKeyCreator</tt>,
<tt class="classname">ShipmentByPartKeyCreator</tt>
and <tt class="classname">ShipmentBySupplierKeyCreator</tt>.
</p>
<a id="tuple_SupplierByCityKeyCreator"></a>
<pre class="programlisting"><b class="userinput"><tt>import com.sleepycat.bind.serial.TupleSerialKeyCreator;
import com.sleepycat.bind.tuple.TupleInput;
import com.sleepycat.bind.tuple.TupleOutput;
...</tt></b>
public class SampleDatabase
{
...
private static class SupplierByCityKeyCreator
<b class="userinput"><tt> extends TupleSerialKeyCreator</tt></b>
{
private SupplierByCityKeyCreator(StoredClassCatalog catalog,
<b class="userinput"><tt>Class valueClass</tt></b>)
{
super(catalog, valueClass);
}
<b class="userinput"><tt> public boolean createSecondaryKey(TupleInput primaryKeyInput,
Object valueInput,
TupleOutput indexKeyOutput)
{
SupplierData supplierData = (SupplierData) valueInput;
String city = supplierData.getCity();
if (city != null) {
indexKeyOutput.writeString(supplierData.getCity());
return true;
} else {
return false;
}
}</tt></b>
}
private static class ShipmentByPartKeyCreator
<b class="userinput"><tt>extends TupleSerialKeyCreator</tt></b>
{
private ShipmentByPartKeyCreator(StoredClassCatalog catalog,
<b class="userinput"><tt>Class valueClass</tt></b>)
{
super(catalog, valueClass);
}
<b class="userinput"><tt>public boolean createSecondaryKey(TupleInput primaryKeyInput,
Object valueInput,
TupleOutput indexKeyOutput)
{
String partNumber = primaryKeyInput.readString();
// don't bother reading the supplierNumber
indexKeyOutput.writeString(partNumber);
return true;
}</tt></b>
}
private static class ShipmentBySupplierKeyCreator
<b class="userinput"><tt>extends TupleSerialKeyCreator</tt></b>
{
private ShipmentBySupplierKeyCreator(StoredClassCatalog catalog,
<b class="userinput"><tt>Class valueClass</tt></b>)
{
super(catalog, valueClass);
}
<b class="userinput"><tt>public boolean createSecondaryKey(TupleInput primaryKeyInput,
Object valueInput,
TupleOutput indexKeyOutput)
{
primaryKeyInput.readString(); // skip the partNumber
String supplierNumber = primaryKeyInput.readString();
indexKeyOutput.writeString(supplierNumber);
return true;
}</tt></b>
}
...
}
</pre>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="Tuple.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="Tuple.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="tuplekeybindings.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 5. 
Using Tuples
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Creating Tuple Key Bindings
</td>
</tr>
</table>
</div>
</body>
</html>

408
docs/collections/tutorial/tutorialintroduction.html Normal file
View File

@@ -0,0 +1,408 @@
<?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>Tutorial Introduction</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="intro.html" title="Chapter 1. &#10; Introduction&#10; " />
<link rel="previous" href="developing.html" title="Developing a DB Collections Application" />
<link rel="next" href="BasicProgram.html" title="Chapter 2. &#10;&#9;&#9;The Basic Program&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Tutorial Introduction</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="developing.html">Prev</a> </td>
<th width="60%" align="center">Chapter 1. 
Introduction
</th>
<td width="20%" align="right"> <a accesskey="n" href="BasicProgram.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="tutorialintroduction"></a>Tutorial Introduction</h2>
</div>
</div>
<div></div>
</div>
<p>
Most of the remainder of this document illustrates the use of the
DB Java Collections API by presenting a tutorial that describes usage of the API.
This tutorial builds a shipment database, a familiar example from classic
database texts.
</p>
<p>
The examples illustrate the following concepts of the DB Java Collections API:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
Object-to-data <span class="emphasis"><em>bindings</em></span>
</p>
</li>
<li>
<p>
The database <span class="emphasis"><em>environment</em></span>
</p>
</li>
<li>
<p>
<span class="emphasis"><em>Databases</em></span> that contain key/value records
</p>
</li>
<li>
<p>
<span class="emphasis"><em>Secondary index</em></span> databases that contain index keys
</p>
</li>
<li>
<p>
Java <span class="emphasis"><em>collections</em></span> for accessing databases and
indices
</p>
</li>
<li>
<p>
<span class="emphasis"><em>Transactions</em></span> used to commit or undo database
changes
</p>
</li>
</ul>
</div>
<p>
The examples build on each other, but at the same time the
source code for each example stands alone.
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<a href="BasicProgram.html">
The Basic Program
</a>
</p>
</li>
<li>
<p>
<a href="UsingSecondaries.html">
Using Secondary Indices
</a>
</p>
</li>
<li>
<p>
<a href="Entity.html">
Using Entity Classes
</a>
</p>
</li>
<li>
<p>
<a href="Tuple.html">
Using Tuples
</a>
</p>
</li>
<li>
<p>
<a href="SerializableEntity.html">
Using Serializable Entities
</a>
</p>
</li>
</ul>
</div>
<p>
The shipment database consists of three database stores: the
part store, the supplier store, and the shipment store. Each store
contains a number of records, and each record consists of a key and
a value.
</p>
<div class="informaltable">
<table border="1" width="80%">
<colgroup>
<col />
<col />
<col />
</colgroup>
<thead>
<tr>
<th>Store</th>
<th>Key</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr>
<td>Part</td>
<td>Part Number</td>
<td>Name, Color, Weight, City</td>
</tr>
<tr>
<td>Supplier</td>
<td>Supplier Number</td>
<td>Name, Status, City</td>
</tr>
<tr>
<td>Shipment</td>
<td>Part Number, Supplier Number</td>
<td>Quantity</td>
</tr>
</tbody>
</table>
</div>
<p>
In the example programs, Java classes containing the fields
above are defined for the key and value of each store:
<tt class="classname">PartKey</tt>,
<tt class="classname">PartData</tt>,
<tt class="classname">SupplierKey</tt>,
<tt class="classname">SupplierData</tt>,
<tt class="classname">ShipmentKey</tt> and <tt class="classname">ShipmentData</tt>. In
addition, because the Part's Weight field is itself composed of two
fields — the weight value and the unit of measure — it is
represented by a separate <tt class="classname">Weight</tt> class. These classes will
be defined in the first example program.
</p>
<p>
In general the DB Java Collections API uses bindings to
describe how Java objects are stored. A binding defines the stored
data syntax and the mapping between a Java object and the stored
data. The example programs show how to create different types of
bindings, and explains the characteristics of each type.
</p>
<p>
The following tables show the record values that are used in
all the example programs in the tutorial.
<span>
</span>
</p>
<div class="informaltable">
<table border="1" width="80%">
<colgroup>
<col />
<col />
<col />
<col />
<col />
</colgroup>
<thead>
<tr>
<th>Number</th>
<th>Name</th>
<th>Color</th>
<th>Weight</th>
<th>City</th>
</tr>
</thead>
<tbody>
<tr>
<td>P1</td>
<td>Nut</td>
<td>Red</td>
<td>12.0 grams</td>
<td>London</td>
</tr>
<tr>
<td>P2</td>
<td>Bolt</td>
<td>Green</td>
<td>17.0 grams</td>
<td>Paris</td>
</tr>
<tr>
<td>P3</td>
<td>Screw</td>
<td>Blue</td>
<td>17.0 grams</td>
<td>Rome</td>
</tr>
<tr>
<td>P4</td>
<td>Screw</td>
<td>Red</td>
<td>14.0 grams</td>
<td>London</td>
</tr>
<tr>
<td>P5</td>
<td>Cam</td>
<td>Blue</td>
<td>12.0 grams</td>
<td>Paris</td>
</tr>
<tr>
<td>P6</td>
<td>Cog</td>
<td>Red</td>
<td>19.0 grams</td>
<td>London</td>
</tr>
</tbody>
</table>
</div>
<div class="informaltable">
<table border="1" width="80%">
<colgroup>
<col />
<col />
<col />
<col />
</colgroup>
<thead>
<tr>
<th>Number</th>
<th>Name</th>
<th>Status</th>
<th>City</th>
</tr>
</thead>
<tbody>
<tr>
<td>S1</td>
<td>Smith</td>
<td>20</td>
<td>London</td>
</tr>
<tr>
<td>S2</td>
<td>Jones</td>
<td>10</td>
<td>Paris</td>
</tr>
<tr>
<td>S3</td>
<td>Blake</td>
<td>30</td>
<td>Paris</td>
</tr>
<tr>
<td>S4</td>
<td>Clark</td>
<td>20</td>
<td>London</td>
</tr>
<tr>
<td>S5</td>
<td>Adams</td>
<td>30</td>
<td>Athens</td>
</tr>
</tbody>
</table>
</div>
<div class="informaltable">
<table border="1" width="80%">
<colgroup>
<col />
<col />
<col />
</colgroup>
<thead>
<tr>
<th>Part Number</th>
<th>Supplier Number</th>
<th>Quantity</th>
</tr>
</thead>
<tbody>
<tr>
<td>P1</td>
<td>S1</td>
<td>300</td>
</tr>
<tr>
<td>P1</td>
<td>S2</td>
<td>300</td>
</tr>
<tr>
<td>P2</td>
<td>S1</td>
<td>200</td>
</tr>
<tr>
<td>P2</td>
<td>S2</td>
<td>400</td>
</tr>
<tr>
<td>P2</td>
<td>S3</td>
<td>200</td>
</tr>
<tr>
<td>P2</td>
<td>S4</td>
<td>200</td>
</tr>
<tr>
<td>P3</td>
<td>S1</td>
<td>400</td>
</tr>
<tr>
<td>P4</td>
<td>S1</td>
<td>200</td>
</tr>
<tr>
<td>P4</td>
<td>S4</td>
<td>300</td>
</tr>
<tr>
<td>P5</td>
<td>S1</td>
<td>100</td>
</tr>
<tr>
<td>P5</td>
<td>S4</td>
<td>400</td>
</tr>
<tr>
<td>P6</td>
<td>S1</td>
<td>100</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="developing.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="intro.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="BasicProgram.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Developing a DB Collections Application </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Chapter 2. 
The Basic Program
</td>
</tr>
</table>
</div>
</body>
</html>

221
docs/collections/tutorial/usingtransactions.html Normal file
View File

@@ -0,0 +1,221 @@
<?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>
Using Transactions
</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="BasicProgram.html" title="Chapter 2. &#10;&#9;&#9;The Basic Program&#10;&#9;" />
<link rel="previous" href="implementingmain.html" title="&#10;&#9;&#9;Implementing the Main Program&#10;&#9;" />
<link rel="next" href="addingdatabaseitems.html" title="&#10;&#9;&#9;Adding Database Items&#10;&#9;" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Using Transactions
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="implementingmain.html">Prev</a> </td>
<th width="60%" align="center">Chapter 2. 
The Basic Program
</th>
<td width="20%" align="right"> <a accesskey="n" href="addingdatabaseitems.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="usingtransactions"></a>
Using Transactions
</h2>
</div>
</div>
<div></div>
</div>
<p>
DB transactional applications have standard
transactional characteristics: recoverability, atomicity and
integrity (this is sometimes also referred to generically as <span class="emphasis"><em>ACID
properties</em></span>). The DB Java Collections API provides these
transactional capabilities using a <span class="emphasis"><em>transaction-per-thread</em></span>
model. Once a transaction is begun, it is implicitly associated
with the current thread until it is committed or aborted. This
model is used for the following reasons.
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
The transaction-per-thread model is commonly used in other Java
APIs such as J2EE.
</p>
</li>
<li>
<p>
Since the Java collections API is used for data access, there
is no way to pass a transaction object to methods such
as
<a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Map.html#put" target="_top">Map.put</a>.
</p>
</li>
</ul>
</div>
<p>
The DB Java Collections API provides two transaction APIs. The
lower-level API is the
<a href="../../java/com/sleepycat/collections/CurrentTransaction.html" target="_top">CurrentTransaction</a>
class. It provides a way to get the transaction for the current
thread, and to begin, commit and abort transactions. It also
provides access to the Berkeley DB core API
<a href="../../java/com/sleepycat/db/Transaction.html" target="_top">Transaction</a>
object. With
<a href="../../java/com/sleepycat/collections/CurrentTransaction.html" target="_top">CurrentTransaction</a>,
just as in the
<span>com.sleepycat.db</span>
API, the application is responsible
for beginning, committing and aborting transactions, and for
handling deadlock exceptions and retrying operations. This API may
be needed for some applications, but it is not used in the
example.
</p>
<p>
The example uses the higher-level
<a href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>
and
<a href="../../java/com/sleepycat/collections/TransactionWorker.html" target="_top">TransactionWorker</a>
APIs, which are build on top of
<a href="../../java/com/sleepycat/collections/CurrentTransaction.html" target="_top">CurrentTransaction</a>.
<tt class="methodname">TransactionRunner.run()</tt> automatically begins a transaction and
then calls the <tt class="methodname">TransactionWorker.doWork()</tt> method, which is
implemented by the application.
</p>
<p>
The <tt class="methodname">TransactionRunner.run()</tt> method automatically detects
deadlock exceptions and performs retries by repeatedly calling the
<tt class="methodname">TransactionWorker.doWork()</tt> method until the operation succeeds
or the maximum retry count is reached. If the maximum retry count
is reached or if another exception (other than
<span>
<a href="../../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a>)
</span>
is thrown by <tt class="methodname">TransactionWorker.doWork()</tt>, then the transaction
will be automatically aborted. Otherwise, the transaction will be
automatically committed.
</p>
<p>
Using this high-level API, if <tt class="methodname">TransactionRunner.run()</tt>
throws an exception, the application can assume that the operation
failed and the transaction was aborted; otherwise, when an
exception is not thrown, the application can assume the operation
succeeded and the transaction was committed.
</p>
<p>
The <tt class="methodname">Sample.run()</tt> method creates a <tt class="classname">TransactionRunner</tt>
object and calls its <tt class="methodname">run()</tt> method.
</p>
<a id="cb_sample1"></a>
<pre class="programlisting"><b class="userinput"><tt>import com.sleepycat.collections.TransactionRunner;
import com.sleepycat.collections.TransactionWorker;</tt></b>
...
public class Sample
{
private SampleDatabase db;
...
<b class="userinput"><tt> private void run()
throws Exception
{
TransactionRunner runner = new TransactionRunner(db.getEnvironment());
runner.run(new PopulateDatabase());
runner.run(new PrintDatabase());
}
...
private class PopulateDatabase implements TransactionWorker
{
public void doWork()
throws Exception
{
}
}
private class PrintDatabase implements TransactionWorker
{
public void doWork()
throws Exception
{
}
}</tt></b>
} </pre>
<p>
The <tt class="methodname">run()</tt> method is called by <tt class="methodname">main()</tt> and was outlined
in the previous section. It first creates a
<tt class="classname">TransactionRunner</tt>, passing the database environment to its
constructor.
</p>
<p>
It then calls <tt class="methodname">TransactionRunner.run()</tt> to execute two
transactions, passing instances of the application-defined
<tt class="classname">PopulateDatabase</tt> and
<tt class="classname">PrintDatabase</tt> nested classes.
These classes implement the <tt class="methodname">TransactionWorker.doWork()</tt> method
and will be fully described in the next two sections.
</p>
<p>
For each call to <tt class="methodname">TransactionRunner.run()</tt>, a separate
transaction will be performed. The use of two transactions in the
example — one for populating the database and another for printing
its contents — is arbitrary. A real-life application should be
designed to create transactions for each group of operations that
should have ACID properties, while also
taking into account the impact of transactions on performance.
</p>
<p>
The advantage of using <tt class="classname">TransactionRunner</tt> is that deadlock
retries and transaction begin, commit and abort are handled
automatically. However, a <tt class="classname">TransactionWorker</tt> class must be
implemented for each type of transaction. If desired, anonymous
inner classes can be used to implement the <tt class="classname">TransactionWorker</tt>
interface.
</p>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="implementingmain.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="addingdatabaseitems.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Implementing the Main Program
 </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 
Adding Database Items
</td>
</tr>
</table>
</div>
</body>
</html>