mirror of
https://github.com/berkeleydb/je.git
synced 2024-11-15 01:46:24 +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>
|