mirror of
https://github.com/berkeleydb/je.git
synced 2024-08-03 21:09:28 +00:00
662 lines
30 KiB
HTML
662 lines
30 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||
<title>Using Stored Collections</title>
|
||
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
||
<link rel="start" href="index.html" title="Berkeley DB Java Edition Collections Tutorial" />
|
||
<link rel="up" href="collectionOverview.html" title="Appendix A. API Notes and Details" />
|
||
<link rel="prev" href="UsingCollectionsAPI.html" title="Using the JE JE Collections API" />
|
||
<link rel="next" href="SerializedObjectStorage.html" title="Serialized Object Storage" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 12.2.7.5</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">
|
||
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 class="toc">
|
||
<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 Java Edition
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
</dl>
|
||
</div>
|
||
<p>
|
||
When a stored collection is created it is based on either a
|
||
<a class="ulink" href="../../java/com/sleepycat/je/Database.html" target="_top">Database</a>
|
||
|
||
|
||
or a
|
||
<span>
|
||
<a class="ulink" href="../../java/com/sleepycat/je/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>
|
||
<p>
|
||
The use of stored collections is constrained in certain respects as
|
||
described below.
|
||
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>
|
||
All iterators for stored collections implement the
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html" target="_top">ListIterator</a>
|
||
|
||
interface as well as the
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Iterator.html" target="_top">Iterator</a>
|
||
|
||
interface.
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#hasPrevious()" target="_top">ListIterator.hasPrevious()</a>
|
||
|
||
and
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#previous()" target="_top">ListIterator.previous()</a>
|
||
|
||
work in all cases.
|
||
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#add()" target="_top">ListIterator.add()</a>
|
||
|
||
throws
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>
|
||
|
||
if duplicates are not allowed.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#add()" target="_top">ListIterator.add()</a>
|
||
|
||
inserts a duplicate in sorted order if sorted duplicates are configured.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#set()" target="_top">ListIterator.set()</a>
|
||
|
||
throws
|
||
<a class="ulink" href="http://download.oracle.com/javase/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>
|
||
<li>
|
||
<p>
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#nextIndex()" target="_top">ListIterator.nextIndex()</a>
|
||
|
||
and
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#previousIndex()" target="_top">ListIterator.previousIndex()</a>
|
||
|
||
always throw
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.Entry.html#setValue()" target="_top">Map.Entry.setValue()</a>
|
||
|
||
throws
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>
|
||
|
||
if duplicates are sorted.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
When duplicates are allowed the
|
||
<a class="ulink" href="http://download.oracle.com/javase/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>
|
||
<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 class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.html#entrySet()" target="_top">Map.entrySet()</a>
|
||
|
||
may contain multiple
|
||
<a class="ulink" href="http://download.oracle.com/javase/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 class="ulink" href="http://download.oracle.com/javase/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 class="ulink" href="http://download.oracle.com/javase/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 class="ulink" href="http://download.oracle.com/javase/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 class="ulink" href="http://download.oracle.com/javase/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 class="ulink" href="http://download.oracle.com/javase/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 class="ulink" href="../../java/com/sleepycat/collections/StoredMap.html#duplicates(java.lang.Object)" target="_top">StoredSortedMap.duplicates()</a>
|
||
|
||
is an additional method for returning the values for a given key as a
|
||
<a class="ulink" href="http://download.oracle.com/javase/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 class="ulink" href="http://download.oracle.com/javase/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.
|
||
<code class="literal">storedCollection.addAll(standardCollection)</code> is allowed
|
||
while <code class="literal">standardCollection.addAll(storedCollection)</code> 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>
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Comparator.html" target="_top">Comparator</a>
|
||
|
||
objects cannot be used and the
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedMap.html#comparator()" target="_top">SortedMap.comparator()</a>
|
||
|
||
and
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedSet.html#comparator()" target="_top">SortedSet.comparator()</a>
|
||
|
||
methods always return null. The
|
||
<a class="ulink" href="http://download.oracle.com/javase/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 class="ulink" href="../../java/com/sleepycat/je/DatabaseConfig.html#setBtreeComparator(java.util.Comparator)" target="_top">DatabaseConfig.setBtreeComparator</a>.
|
||
</span>
|
||
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
The
|
||
<a class="ulink" href="http://download.oracle.com/javase/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>
|
||
<p>
|
||
The following characteristics of stored collections are
|
||
extensions of the definitions in the
|
||
<a class="ulink" href="http://download.oracle.com/javase/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>.</span>
|
||
|
||
Locking is handled by the Berkeley DB Java Edition
|
||
environment. To access a collection from multiple threads, creation
|
||
of synchronized collections using the
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Collections.html" target="_top">Collections</a>
|
||
|
||
class is not necessary<span>.</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 class="ulink" href="http://download.oracle.com/javase/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 class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>
|
||
|
||
when an index is used:
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Collection.html#add()" target="_top">Collection.add()</a>,
|
||
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#set()" target="_top">ListIterator.set()</a>
|
||
|
||
and
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.Entry.html#setValue()" target="_top">Map.Entry.setValue()</a>.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedMap.html#entrySet()" target="_top">SortedMap.entrySet()</a>
|
||
|
||
and
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedMap.html#keySet()" target="_top">SortedMap.keySet()</a>
|
||
|
||
return a
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>,
|
||
not just a
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Set.html" target="_top">Set</a>
|
||
|
||
as specified in Java collections interface. This allows using the
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>
|
||
|
||
methods on the returned collection.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedMap.html#values()" target="_top">SortedMap.values()</a>
|
||
|
||
returns a
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>,
|
||
not just a
|
||
<a class="ulink" href="http://download.oracle.com/javase/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 class="ulink" href="http://download.oracle.com/javase/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 class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>
|
||
|
||
and
|
||
<a class="ulink" href="http://download.oracle.com/javase/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 class="ulink" href="../../java/com/sleepycat/util/RuntimeExceptionWrapper.html" target="_top">RuntimeExceptionWrapper</a>,
|
||
is thrown whenever database exceptions occur which are not runtime
|
||
exceptions. The
|
||
<a class="ulink" 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 class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html" target="_top">ListIterator</a>
|
||
|
||
interface as well as the
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Iterator.html" target="_top">Iterator</a>
|
||
|
||
interface. This is to allow use of the
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#hasPrevious()" target="_top">ListIterator.hasPrevious()</a>
|
||
|
||
and
|
||
<a class="ulink" href="http://download.oracle.com/javase/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 class="ulink" 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 class="ulink" href="http://download.oracle.com/javase/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.
|
||
|
||
|
||
</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 class="ulink" href="http://download.oracle.com/javase/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 class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.html#put()" target="_top">Map.put()</a>,
|
||
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#set()" target="_top">ListIterator.set()</a>,
|
||
and
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.Entry.html#setValue()" target="_top">Map.Entry.setValue()</a>
|
||
|
||
will throw
|
||
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/IllegalArgumentException.html" target="_top">IllegalArgumentException</a>
|
||
|
||
in this situation.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
The
|
||
|
||
|
||
|
||
<a class="ulink" href="../../java/com/sleepycat/collections/StoredMap.html#append(java.lang.Object)" target="_top">StoredSortedMap.append(java.lang.Object)</a>
|
||
|
||
extension method allows
|
||
adding a new record with an automatically assigned key.
|
||
|
||
An application-defined
|
||
<a class="ulink" 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 Java Edition
|
||
</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
The Java collections interface was chosen as the best Java API
|
||
for JE 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 Java Edition storage system.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Compared to the JE 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
|
||
JE.
|
||
</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
<p>
|
||
Admittedly there are several things about the Java Collections
|
||
API that don't quite fit with JE 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 JE 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 JE
|
||
API.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
The ODMG API or another object persistence API could have been
|
||
implemented on top of JE. 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 JE JE 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>
|