mirror of
https://github.com/berkeleydb/je.git
synced 2024-07-06 18:07:18 +00:00
359 lines
14 KiB
HTML
359 lines
14 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 the JE JE Collections API</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="collectionOverview.html" title="Appendix A. API Notes and Details" />
|
||
<link rel="next" href="UsingStoredCollections.html" title="Using Stored Collections" />
|
||
</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 the JE JE 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 JE JE Collections API
|
||
</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="toc">
|
||
<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#AccessMethodRestrictions">
|
||
Access Method Restrictions
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
</dl>
|
||
</div>
|
||
<p>
|
||
An
|
||
<a class="ulink" href="../../java/com/sleepycat/je/Environment.html" target="_top">Environment</a>
|
||
|
||
|
||
manages the resources for one or more data stores. A
|
||
<a class="ulink" href="../../java/com/sleepycat/je/Database.html" target="_top">Database</a>
|
||
|
||
|
||
object
|
||
represents a single database and is created via a method on the
|
||
environment object.
|
||
<a class="ulink" href="../../java/com/sleepycat/je/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>
|
||
|
||
|
||
objects represent an index associated with a primary database.
|
||
|
||
|
||
|
||
Primary and secondary databases are then used to create stored
|
||
collection objects, as described in
|
||
<a class="xref" href="UsingStoredCollections.html" title="Using Stored Collections">
|
||
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>
|
||
<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 JE JE Collections API provides several
|
||
ways of managing transactions.
|
||
</p>
|
||
<p>
|
||
The recommended technique is to use the
|
||
<a class="ulink" href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>
|
||
|
||
class along with your own implementation of the
|
||
<a class="ulink" href="../../java/com/sleepycat/collections/TransactionWorker.html" target="_top">TransactionWorker</a>
|
||
|
||
interface.
|
||
<a class="ulink" href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>
|
||
|
||
will call your
|
||
<a class="ulink" 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 class="ulink" href="../../java/com/sleepycat/collections/TransactionWorker.html#doWork()" target="_top">TransactionWorker.doWork()</a>
|
||
|
||
method returns normally, or will be
|
||
aborted if <code class="methodname">doWork()</code> throws an exception.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<code class="classname">TransactionRunner</code> 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 class="ulink" href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>,
|
||
the alternative is to use the
|
||
<a class="ulink" 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 class="ulink" 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 class="ulink" href="../../java/com/sleepycat/collections/CurrentTransaction.html#beginTransaction(com.sleepycat.db.TransactionConfig)" target="_top">CurrentTransaction.beginTransaction()</a>,
|
||
<a class="ulink" href="../../java/com/sleepycat/collections/CurrentTransaction.html#commitTransaction()" target="_top">CurrentTransaction.commitTransaction()</a>
|
||
|
||
and
|
||
<a class="ulink" 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 class="ulink" href="../../java/com/sleepycat/je/LockConflictException.html" target="_top">LockConflictException</a>
|
||
|
||
|
||
|
||
exception and perform retries yourself. Also note that
|
||
CurrentTransaction may only be used in a transactional
|
||
environment.
|
||
</p>
|
||
<p>
|
||
The JE JE 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 JE JE Collections API also supports transaction
|
||
dirty-read via the
|
||
<a class="ulink" 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 class="ulink" 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>
|
||
<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 JE JE Collections API
|
||
treats data by value, not by reference, neither the data
|
||
objects nor the JE JE 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="AccessMethodRestrictions"></a>
|
||
Access Method Restrictions
|
||
</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
The BTREE access method is always used for JE Databases. Sorted
|
||
duplicates — more then one record for a single key — are
|
||
optional.
|
||
</p>
|
||
<p>
|
||
The restrictions imposed by the access method on the database
|
||
model are:
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<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 class="xref" href="UsingStoredCollections.html" title="Using Stored Collections">
|
||
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>
|
||
With sorted duplicates, all values for the same key must be
|
||
distinct.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<p>
|
||
See
|
||
<a class="xref" href="UsingStoredCollections.html" title="Using Stored Collections">
|
||
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>
|