greg/je
1
0
Fork 0
mirror of https://github.com/berkeleydb/je.git synced 2024-11-15 01:46:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
je/docs/java/com/sleepycat/persist/EntityIndex.html
Greg Burd 10c9f34f67 Initial import.
2021-06-06 13:46:45 -04:00

1653 lines
91 KiB
HTML
Raw Permalink Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc (1.8.0_151) on Tue Oct 31 17:36:46 EDT 2017 -->
<title>EntityIndex (Oracle - Berkeley DB Java Edition API)</title>
<meta name="date" content="2017-10-31">
<link rel="stylesheet" type="text/css" href="../../../style.css" title="Style">
<script type="text/javascript" src="../../../script.js"></script>
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="EntityIndex (Oracle - Berkeley DB Java Edition API)";
}
}
catch(err) {
}
//-->
var methods = {"i0":6,"i1":6,"i2":6,"i3":6,"i4":6,"i5":6,"i6":6,"i7":6,"i8":6,"i9":6,"i10":6,"i11":6,"i12":6,"i13":6,"i14":6,"i15":6,"i16":6,"i17":6,"i18":6,"i19":6,"i20":6};
var tabs = {65535:["t0","All Methods"],2:["t2","Instance Methods"],4:["t3","Abstract Methods"]};
var altColor = "altColor";
var rowColor = "rowColor";
var tableTab = "tableTab";
var activeTableTab = "activeTableTab";
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/EntityIndex.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../index-all.html">Index</a></li>
<li><a href="../../../help-doc.html">Help</a></li>
</ul>
<div class="aboutLanguage"><b>Berkeley DB Java Edition</b><br><font size=\"-1\"> version 7.5.11</font>
</div>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../com/sleepycat/persist/EntityJoin.html" title="class in com.sleepycat.persist"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../index.html?com/sleepycat/persist/EntityIndex.html" target="_top">Frames</a></li>
<li><a href="EntityIndex.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.detail">Method</a></li>
</ul>
</div>
<a name="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="subTitle">com.sleepycat.persist</div>
<h2 title="Interface EntityIndex" class="title">Interface EntityIndex&lt;K,V&gt;</h2>
</div>
<div class="contentContainer">
<div class="description">
<ul class="blockList">
<li class="blockList">
<dl>
<dt>All Known Implementing Classes:</dt>
<dd><a href="../../../com/sleepycat/persist/PrimaryIndex.html" title="class in com.sleepycat.persist">PrimaryIndex</a>, <a href="../../../com/sleepycat/persist/SecondaryIndex.html" title="class in com.sleepycat.persist">SecondaryIndex</a></dd>
</dl>
<hr>
<br>
<pre>public interface <span class="typeNameLabel">EntityIndex&lt;K,V&gt;</span></pre>
<div class="block">The interface for accessing keys and entities via a primary or secondary
index.
<p><code>EntityIndex</code> objects are thread-safe. Multiple threads may safely
call the methods of a shared <code>EntityIndex</code> object.</p>
<p>An index is conceptually a <em>map</em>. {key:value} mappings are
stored in the index and accessed by key. In fact, for interoperability with
other libraries that use the standard Java <code>Map</code> or <code>SortedMap</code>
interfaces, an <code>EntityIndex</code> may be accessed via these standard
interfaces by calling the <a href="../../../com/sleepycat/persist/EntityIndex.html#map--"><code>map()</code></a> or <a href="../../../com/sleepycat/persist/EntityIndex.html#sortedMap--"><code>sortedMap()</code></a> methods.</p>
<p><code>EntityIndex</code> is an interface that is implemented by several
classes in this package for different purposes. Depending on the context,
the key type (K) and value type (V) of the index take on different meanings.
The different classes that implement <code>EntityIndex</code> are:</p>
<ul>
<li><a href="../../../com/sleepycat/persist/PrimaryIndex.html" title="class in com.sleepycat.persist"><code>PrimaryIndex</code></a> maps primary keys to entities.</li>
<li><a href="../../../com/sleepycat/persist/SecondaryIndex.html" title="class in com.sleepycat.persist"><code>SecondaryIndex</code></a> maps secondary keys to entities.</li>
<li><a href="../../../com/sleepycat/persist/SecondaryIndex.html#keysIndex"><code>SecondaryIndex.keysIndex</code></a> maps secondary keys to primary
keys.</li>
<li><a href="../../../com/sleepycat/persist/SecondaryIndex.html#subIndex-SK-"><code>SecondaryIndex.subIndex(SK)</code></a> maps primary keys to entities, for the
subset of entities having a specified secondary key.</li>
</ul>
<p>In all cases, the index key type (K) is a primary or secondary key class.
The index value type (V) is an entity class in all cases except for a <a href="../../../com/sleepycat/persist/SecondaryIndex.html#keysIndex"><code>SecondaryIndex.keysIndex</code></a>, when it is a primary key class.</p>
<p>In the following example, a <code>Employee</code> entity with a <code>MANY_TO_ONE</code> secondary key is defined.</p>
<pre class="code">
@Entity
class Employee {
@PrimaryKey
long id;
@SecondaryKey(relate=MANY_TO_ONE)
String department;
String name;
private Employee() {}
}</pre>
<p>Consider that we have stored the entities below:</p>
<div><table class="code" border="1" summary="">
<tr><th colspan="3">Entities</th></tr>
<tr><th>ID</th><th>Department</th><th>Name</th></tr>
<tr><td>1</td><td>Engineering</td><td>Jane Smith</td></tr>
<tr><td>2</td><td>Sales</td><td>Joan Smith</td></tr>
<tr><td>3</td><td>Engineering</td><td>John Smith</td></tr>
<tr><td>4</td><td>Sales</td><td>Jim Smith</td></tr>
</table></div>
<p><a href="../../../com/sleepycat/persist/PrimaryIndex.html" title="class in com.sleepycat.persist"><code>PrimaryIndex</code></a> maps primary keys to entities:</p>
<pre class="code">
<code>PrimaryIndex&lt;Long, Employee&gt;</code> primaryIndex =
store.getPrimaryIndex(Long.class, Employee.class);</pre>
<div><table class="code" border="1" summary="">
<tr><th colspan="4">primaryIndex</th></tr>
<tr><th>Primary Key</th><th colspan="3">Entity</th></tr>
<tr><td>1</td><td>1</td><td>Engineering</td><td>Jane Smith</td></tr>
<tr><td>2</td><td>2</td><td>Sales</td><td>Joan Smith</td></tr>
<tr><td>3</td><td>3</td><td>Engineering</td><td>John Smith</td></tr>
<tr><td>4</td><td>4</td><td>Sales</td><td>Jim Smith</td></tr>
</table></div>
<p><a href="../../../com/sleepycat/persist/SecondaryIndex.html" title="class in com.sleepycat.persist"><code>SecondaryIndex</code></a> maps secondary keys to entities:</p>
<pre class="code">
<code>SecondaryIndex&lt;String, Long, Employee&gt;</code> secondaryIndex =
store.getSecondaryIndex(primaryIndex, String.class, "department");</pre>
<div><table class="code" border="1" summary="">
<tr><th colspan="4">secondaryIndex</th></tr>
<tr><th>Secondary Key</th><th colspan="3">Entity</th></tr>
<tr><td>Engineering</td><td>1</td><td>Engineering</td><td>Jane Smith</td></tr>
<tr><td>Engineering</td><td>3</td><td>Engineering</td><td>John Smith</td></tr>
<tr><td>Sales</td><td>2</td><td>Sales</td><td>Joan Smith</td></tr>
<tr><td>Sales</td><td>4</td><td>Sales</td><td>Jim Smith</td></tr>
</table></div>
<p><a href="../../../com/sleepycat/persist/SecondaryIndex.html#keysIndex"><code>SecondaryIndex.keysIndex</code></a> maps secondary keys to primary
keys:</p>
<pre class="code">
<code>EntityIndex&lt;String, Long&gt;</code> keysIndex = secondaryIndex.keysIndex();</pre>
<div><table class="code" border="1" summary="">
<tr><th colspan="4">keysIndex</th></tr>
<tr><th>Secondary Key</th><th colspan="3">Primary Key</th></tr>
<tr><td>Engineering</td><td>1</td></tr>
<tr><td>Engineering</td><td>3</td></tr>
<tr><td>Sales</td><td>2</td></tr>
<tr><td>Sales</td><td>4</td></tr>
</table></div>
<p><a href="../../../com/sleepycat/persist/SecondaryIndex.html#subIndex-SK-"><code>SecondaryIndex.subIndex(SK)</code></a> maps primary keys to entities, for the
subset of entities having a specified secondary key:</p>
<pre class="code">
<code>EntityIndex&lt;Long, Entity&gt;</code> subIndex = secondaryIndex.subIndex("Engineering");</pre>
<div><table class="code" border="1" summary="">
<tr><th colspan="4">subIndex</th></tr>
<tr><th>Primary Key</th><th colspan="3">Entity</th></tr>
<tr><td>1</td><td>1</td><td>Engineering</td><td>Jane Smith</td></tr>
<tr><td>3</td><td>3</td><td>Engineering</td><td>John Smith</td></tr>
</table></div>
<h3>Accessing the Index</h3>
<p>An <code>EntityIndex</code> provides a variety of methods for retrieving
entities from an index. It also provides methods for deleting entities.
However, it does not provide methods for inserting and updating. To insert
and update entities, use the <a href="../../../com/sleepycat/persist/PrimaryIndex.html#put-E-"><code>PrimaryIndex.put(E)</code></a> family of methods in
the <a href="../../../com/sleepycat/persist/PrimaryIndex.html" title="class in com.sleepycat.persist"><code>PrimaryIndex</code></a> class.</p>
<p>An <code>EntityIndex</code> supports two mechanisms for retrieving
entities:</p>
<ol>
<li>The <a href="../../../com/sleepycat/persist/EntityIndex.html#get-K-"><code>get(K)</code></a> method returns a single value for a given key. If there
are multiple values with the same secondary key (duplicates), it returns the
first entity in the duplicate set.</li>
<li>An <a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist"><code>EntityCursor</code></a> can be obtained using the <a href="../../../com/sleepycat/persist/EntityIndex.html#keys--"><code>keys()</code></a> and
<a href="../../../com/sleepycat/persist/EntityIndex.html#entities--"><code>entities()</code></a> family of methods. A cursor can be used to return all
values in the index, including duplicates. A cursor can also be used to
return values within a specified range of keys.</li>
</ol>
<p>Using the example entities above, calling <a href="../../../com/sleepycat/persist/EntityIndex.html#get-K-"><code>get(K)</code></a> on the primary
index will always return the employee with the given ID, or null if no such
ID exists. But calling <a href="../../../com/sleepycat/persist/EntityIndex.html#get-K-"><code>get(K)</code></a> on the secondary index will retrieve
the first employee in the given department, which may not be very
useful:</p>
<pre class="code">
Employee emp = primaryIndex.get(1); // Returns by unique ID
emp = secondaryIndex.get("Engineering"); // Returns first in department</pre>
<p>Using a cursor, you can iterate through all duplicates in the secondary
index:</p>
<pre class="code">
<code>EntityCursor&lt;Employee&gt;</code> cursor = secondaryIndex.entities();
try {
for (Employee entity : cursor) {
if (entity.department.equals("Engineering")) {
// Do something with the entity...
}
}
} finally {
cursor.close();
}</pre>
<p>But for a large database it is much more efficient to iterate over only
those entities with the secondary key you're searching for. This could be
done by restricting a cursor to a range of keys:</p>
<pre class="code">
<code>EntityCursor&lt;Employee&gt;</code> cursor =
secondaryIndex.entities("Engineering", true, "Engineering", true);
try {
for (Employee entity : cursor) {
// Do something with the entity...
}
} finally {
cursor.close();
}</pre>
<p>However, when you are interested only in the entities with a particular
secondary key value, it is more convenient to use a sub-index:</p>
<pre class="code">
<code>EntityIndex&lt;Long, Entity&gt;</code> subIndex = secondaryIndex.subIndex("Engineering");
<code>EntityCursor&lt;Employee&gt;</code> cursor = subIndex.entities();
try {
for (Employee entity : cursor) {
// Do something with the entity...
}
} finally {
cursor.close();
}</pre>
<p>In addition to being more convenient than a cursor range, a sub-index
allows retrieving by primary key:</p>
<pre class="code">
Employee emp = subIndex.get(1);</pre>
<p>When using a sub-index, all operations performed on the sub-index are
restricted to the single key that was specified when the sub-index was
created. For example, the following returns null because employee 2 is not
in the Engineering department and therefore is not part of the
sub-index:</p>
<pre class="code">
Employee emp = subIndex.get(2);</pre>
<p>For more information on using cursors and cursor ranges, see <a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist"><code>EntityCursor</code></a>.</p>
<p>Note that when using an index, keys and values are stored and retrieved
by value not by reference. In other words, if an entity object is stored
and then retrieved, or retrieved twice, each object will be a separate
instance. For example, in the code below the assertion will always
fail.</p>
<pre class="code">
MyKey key = ...;
MyEntity entity1 = index.get(key);
MyEntity entity2 = index.get(key);
assert entity1 == entity2; // always fails!
</pre>
<h3>Deleting from the Index</h3>
<p>Any type of index may be used to delete entities with a specified key by
calling <a href="../../../com/sleepycat/persist/EntityIndex.html#delete-K-"><code>delete(K)</code></a>. The important thing to keep in mind is that
<em>all entities</em> with the specified key are deleted. In a primary index,
at most a single entity is deleted:</p>
<pre class="code">
primaryIndex.delete(1); // Deletes a single employee by unique ID</pre>
<p>But in a secondary index, multiple entities may be deleted:</p>
<pre class="code">
secondaryIndex.delete("Engineering"); // Deletes all Engineering employees</pre>
<p>This begs this question: How can a single entity be deleted without
knowing its primary key? The answer is to use cursors. After locating an
entity using a cursor, the entity can be deleted by calling <a href="../../../com/sleepycat/persist/EntityCursor.html#delete--"><code>EntityCursor.delete()</code></a>.</p>
<h3>Transactions</h3>
<p>Transactions can be used to provide standard ACID (Atomicity,
Consistency, Integrity and Durability) guarantees when retrieving, storing
and deleting entities. This section provides a brief overview of how to use
transactions with the Direct Persistence Layer. For more information on
using transactions, see <a
href="../../../../TransactionGettingStarted/index.html">Writing
Transactional Applications</a>.</p>
<p>Transactions may be used only with a transactional <a href="../../../com/sleepycat/persist/EntityStore.html" title="class in com.sleepycat.persist"><code>EntityStore</code></a>,
which is one for which <a href="../../../com/sleepycat/persist/StoreConfig.html#setTransactional-boolean-"><code>StoreConfig.setTransactional(true)</code></a> has been called. Likewise, a
transactional store may only be used with a transactional <a href="../../../com/sleepycat/je/Environment.html" title="class in com.sleepycat.je"><code>Environment</code></a>, which is one for which <a href="../../../com/sleepycat/je/EnvironmentConfig.html#setTransactional-boolean-"><code>EnvironmentConfig.setTransactional(true)</code></a>
has been called. For example:</p>
<pre class="code">
EnvironmentConfig envConfig = new EnvironmentConfig();
envConfig.setTransactional(true);
envConfig.setAllowCreate(true);
Environment env = new Environment(new File("/my/data"), envConfig);
StoreConfig storeConfig = new StoreConfig();
storeConfig.setTransactional(true);
storeConfig.setAllowCreate(true);
EntityStore store = new EntityStore(env, "myStore", storeConfig);</pre>
<p>Transactions are represented by <a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je"><code>Transaction</code></a> objects, which are
part of the <a href="../../../com/sleepycat/je/package-summary.html"><code>Base API</code></a>. Transactions are created
using the <a href="../../../com/sleepycat/je/Environment.html#beginTransaction-com.sleepycat.je.Transaction-com.sleepycat.je.TransactionConfig-"><code>Environment.beginTransaction</code></a>
method.</p>
<p>A transaction will include all operations for which the transaction
object is passed as a method argument. All retrieval, storage and deletion
methods have an optional <a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je"><code>Transaction</code></a> parameter for this purpose.
When a transaction is passed to a method that opens a cursor, all retrieval,
storage and deletion operations performed using that cursor will be included
in the transaction.</p>
<p>A transaction may be committed by calling <a href="../../../com/sleepycat/je/Transaction.html#commit--"><code>Transaction.commit()</code></a> or
aborted by calling <a href="../../../com/sleepycat/je/Transaction.html#abort--"><code>Transaction.abort()</code></a>. For example, two employees
may be deleted atomically with a transaction; other words, either both are
deleted or neither is deleted:</p>
<pre class="code">
Transaction txn = env.beginTransaction(null, null);
try {
primaryIndex.delete(txn, 1);
primaryIndex.delete(txn, 2);
txn.commit();
txn = null;
} finally {
if (txn != null) {
txn.abort();
}
}</pre>
<p><em>WARNING:</em> Transactions must always be committed or aborted to
prevent resource leaks which could lead to the index becoming unusable or
cause an <code>OutOfMemoryError</code>. To ensure that a transaction is
aborted in the face of exceptions, call <a href="../../../com/sleepycat/je/Transaction.html#abort--"><code>Transaction.abort()</code></a> in a
finally block.</p>
<p>For a transactional store, storage and deletion operations are always
transaction protected, whether or not a transaction is explicitly used. A
null transaction argument means to perform the operation using auto-commit,
or the implied thread transaction if an XAEnvironment is being used. A
transaction is automatically started as part of the operation and is
automatically committed if the operation completes successfully. The
transaction is automatically aborted if an exception occurs during the
operation, and the exception is re-thrown to the caller. For example, each
employee is deleted using a an auto-commit transaction below, but it is
possible that employee 1 will be deleted and employee 2 will not be deleted,
if an error or crash occurs while deleting employee 2:</p>
<pre class="code">
primaryIndex.delete(null, 1);
primaryIndex.delete(null, 2);</pre>
<p>When retrieving entities, a null transaction argument means to perform
the operation non-transactionally. The operation is performed outside the
scope of any transaction, without providing transactional ACID guarantees.
If an implied thread transaction is present (i.e. if an XAEnvironment is
being used), that transaction is used. When a non-transactional store is
used, transactional ACID guarantees are also not provided.</p>
<p>For non-transactional and auto-commit usage, overloaded signatures for
retrieval, storage and deletion methods are provided to avoid having to pass
a null transaction argument. For example, <a href="../../../com/sleepycat/persist/EntityIndex.html#delete-K-"><code>delete(K)</code></a> may be called
instead of <a href="../../../com/sleepycat/persist/EntityIndex.html#delete-com.sleepycat.je.Transaction-K-"><code>delete(Transaction,Object)</code></a>. For example, the following
code is equivalent to the code above where null was passed for the
transaction:</p>
<pre class="code">
primaryIndex.delete(1);
primaryIndex.delete(2);</pre>
<p>For retrieval methods the overloaded signatures also include an optional
<a href="../../../com/sleepycat/je/LockMode.html" title="enum in com.sleepycat.je"><code>LockMode</code></a> parameter, and overloaded signatures for opening cursors
include an optional <a href="../../../com/sleepycat/je/CursorConfig.html" title="class in com.sleepycat.je"><code>CursorConfig</code></a> parameter. These parameters are
described further below in the Locking and Lock Modes section.</p>
<h3>Transactions and Cursors</h3>
<p>There are two special consideration when using cursors with transactions.
First, for a transactional store, a non-null transaction must be passed to
methods that open a cursor if that cursor will be used to delete or update
entities. Cursors do not perform auto-commit when a null transaction is
explicitly passed or implied by the method signature. For example, the
following code will throw <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je"><code>DatabaseException</code></a> when the <a href="../../../com/sleepycat/persist/EntityCursor.html#delete--"><code>EntityCursor.delete()</code></a> method is called:</p>
<pre class="code">
// <strong>Does not work with a transactional store!</strong>
<code>EntityCursor&lt;Employee&gt;</code> cursor = primaryIndex.entities();
try {
for (Employee entity : cursor) {
cursor.delete(); // <strong>Will throw DatabaseException.</strong>
}
} finally {
cursor.close();
}</pre>
<p>Instead, the <a href="../../../com/sleepycat/persist/EntityIndex.html#entities-com.sleepycat.je.Transaction-com.sleepycat.je.CursorConfig-"><code>entities(Transaction,CursorConfig)</code></a> signature must
be used and a non-null transaction must be passed:</p>
<pre class="code">
<code>EntityCursor&lt;Employee&gt;</code> cursor = primaryIndex.entities(txn, null);
try {
for (Employee entity : cursor) {
cursor.delete();
}
} finally {
cursor.close();
}</pre>
<p>The second consideration is that error handling is more complex when
using both transactions and cursors, for the following reasons:</p>
<ol>
<li>When an exception occurs, the transaction should be aborted.</li>
<li>Cursors must be closed whether or not an exception occurs.</li>
<li>Cursors must be closed before committing or aborting the
transaction.</li>
</ol>
<p>For example:</p>
<pre class="code">
Transaction txn = env.beginTransaction(null, null);
<code>EntityCursor&lt;Employee&gt;</code> cursor = null;
try {
cursor = primaryIndex.entities(txn, null);
for (Employee entity : cursor) {
cursor.delete();
}
cursor.close();
cursor = null;
txn.commit();
txn = null;
} finally {
if (cursor != null) {
cursor.close();
}
if (txn != null) {
txn.abort();
}
}</pre>
<h3>Locking and Lock Modes</h3>
<p>This section provides a brief overview of locking and describes how lock
modes are used with the Direct Persistence Layer. For more information on
locking, see <a
href="../../../../TransactionGettingStarted/index.html">Writing
Transactional Applications</a>.</p>
<p>When using transactions, locks are normally acquired on each entity that
is retrieved or stored. The locks are used to isolate one transaction from
another. Locks are normally released only when the transaction is committed
or aborted.</p>
<p>When not using transactions, locks are also normally acquired on each
entity that is retrieved or stored. However, these locks are released when
the operation is complete. When using cursors, in order to provide
<em>cursor stability</em> locks are held until the cursor is moved to a
different entity or closed.</p>
<p>This default locking behavior provides full transactional ACID guarantees
and cursor stability. However, application performance can sometimes be
improved by compromising these guarantees. As described in <a
href="../../../../TransactionGettingStarted/index.html">Writing
Transactional Applications</a>, the <a href="../../../com/sleepycat/je/LockMode.html" title="enum in com.sleepycat.je"><code>LockMode</code></a> and <a href="../../../com/sleepycat/je/CursorConfig.html" title="class in com.sleepycat.je"><code>CursorConfig</code></a> parameters are two of the mechanisms that can be used to make
compromises.</p>
<p>For example, imagine that you need an approximate count of all entities
matching certain criterion, and it is acceptable for entities to be changed
by other threads or other transactions while performing this query. <a href="../../../com/sleepycat/je/LockMode.html#READ_UNCOMMITTED"><code>LockMode.READ_UNCOMMITTED</code></a> can be used to perform the retrievals without
acquiring any locks. This reduces memory consumption, does less processing,
and improves concurrency.</p>
<pre class="code">
<code>EntityCursor&lt;Employee&gt;</code> cursor = primaryIndex.entities(txn, null);
try {
Employee entity;
while ((entity = cursor.next(LockMode.READ_UNCOMMITTED)) != null) {
// Examine the entity and accumulate totals...
}
} finally {
cursor.close();
}</pre>
<p>The <a href="../../../com/sleepycat/je/LockMode.html" title="enum in com.sleepycat.je"><code>LockMode</code></a> parameter specifies locking behavior on a
per-operation basis. If null or <a href="../../../com/sleepycat/je/LockMode.html#DEFAULT"><code>LockMode.DEFAULT</code></a> is specified, the
default lock mode is used.</p>
<p>It is also possible to specify the default locking behavior for a cursor
using <a href="../../../com/sleepycat/je/CursorConfig.html" title="class in com.sleepycat.je"><code>CursorConfig</code></a>. The example below is equivalent to the example
above:</p>
<pre class="code">
CursorConfig config = new CursorConfig();
config.setReadUncommitted(true);
<code>EntityCursor&lt;Employee&gt;</code> cursor = primaryIndex.entities(txn, config);
try {
Employee entity;
while ((entity = cursor.next()) != null) {
// Examine the entity and accumulate totals...
}
} finally {
cursor.close();
}</pre>
<!-- begin JE only -->
<p>Note that <code>READ_UNCOMMITTED</code> can be used with a key cursor to
reduce I/O, potentially providing significant performance benefits. See <a
href="#keyCursorReadUncommitted">Key Cursor Optimization with
READ_UNCOMMITTED</a></p>
<!-- end JE only -->
<p>The use of other lock modes, cursor configuration, and transaction
configuration are discussed in <a
href="../../../../TransactionGettingStarted/index.html">Writing
Transactional Applications</a>.</p>
<h3><a name="retries">Performing Transaction Retries</a></h3>
<p>Lock conflict handling is another important topic discussed in <a
href="../../../../TransactionGettingStarted/index.html">Writing
Transactional Applications</a>. To go along with that material, here we
show a lock conflict handling loop in the context of the Direct Persistence
Layer. The example below shows deleting all entities in a primary index in
a single transaction. If a lock conflict occurs, the transaction is aborted
and the operation is retried.</p>
<!-- begin JE only -->
<p>This is a DPL version of the <a
href="../je/LockConflictException.html#retries">equivalent example code</a>
for the base API.</p>
<p>The following example code illustrates the recommended approach. Note
that the <code>Environment.beginTransaction</code> and <code>Transaction.commit</code>
calls are intentially inside the <code>try</code> block. When using JE-HA, this
will make it easy to add a <code>catch</code> for other exceptions that can be
resolved by retrying the transaction, such as consistency exceptions.</p>
<!-- end JE only -->
<pre class="code">
void doTransaction(final Environment env,
final <code>PrimaryIndex&lt;Long, Employee&gt;</code> primaryIndex,
final int maxTries)
throws DatabaseException {
boolean success = false;
long sleepMillis = 0;
for (int i = 0; i &lt; maxTries; i++) {
// Sleep before retrying.
if (sleepMillis != 0) {
Thread.sleep(sleepMillis);
sleepMillis = 0;
}
Transaction txn = null;
try {
txn = env.beginTransaction(null, null);
final <code>EntityCursor&lt;Employee&gt;</code> cursor =
primaryIndex.entities(txn, null);
try {
// INSERT APP-SPECIFIC CODE HERE:
// Perform read and write operations, for example:
for (Employee entity : cursor) {
cursor.delete();
}
} finally {
cursor.close();
}
txn.commit();
success = true;
return;
} catch (LockConflictException e) {
sleepMillis = LOCK_CONFLICT_RETRY_SEC * 1000;
continue;
} finally {
if (!success) {
if (txn != null) {
txn.abort();
}
}
}
}
// INSERT APP-SPECIFIC CODE HERE:
// Transaction failed, despite retries.
// Take some app-specific course of action.
}</pre>
<h3>Low Level Access</h3>
<p>Each Direct Persistence Layer index is associated with an underlying
<a href="../../../com/sleepycat/je/Database.html" title="class in com.sleepycat.je"><code>Database</code></a> or <a href="../../../com/sleepycat/je/SecondaryDatabase.html" title="class in com.sleepycat.je"><code>SecondaryDatabase</code></a> defined in the <a href="../../../com/sleepycat/je/package-summary.html"><code>Base API</code></a>. At this level, an index is a Btree managed by
the Berkeley DB Java Edition transactional storage engine. Although you may
never need to work at the <code>Base API</code> level, keep in mind that some
types of performance tuning can be done by configuring the underlying
databases. See the <a href="../../../com/sleepycat/persist/EntityStore.html" title="class in com.sleepycat.persist"><code>EntityStore</code></a> class for more information on
database and sequence configuration.</p>
<p>If you wish to access an index using the <code>Base API</code>, you may call
the <code>BasicIndex.getDatabase()</code> or <a href="../../../com/sleepycat/persist/SecondaryIndex.html#getDatabase--"><code>SecondaryIndex.getDatabase()</code></a>
method to get the underlying database. To translate between entity or key
objects and <a href="../../../com/sleepycat/je/DatabaseEntry.html" title="class in com.sleepycat.je"><code>DatabaseEntry</code></a> objects at this level, use the bindings
returned by <a href="../../../com/sleepycat/persist/PrimaryIndex.html#getEntityBinding--"><code>PrimaryIndex.getEntityBinding()</code></a>, <a href="../../../com/sleepycat/persist/PrimaryIndex.html#getKeyBinding--"><code>PrimaryIndex.getKeyBinding()</code></a>, and <a href="../../../com/sleepycat/persist/SecondaryIndex.html#getKeyBinding--"><code>SecondaryIndex.getKeyBinding()</code></a>.</p></div>
<dl>
<dt><span class="simpleTagLabel">Author:</span></dt>
<dd>Mark Hayes</dd>
</dl>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- ========== METHOD SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="method.summary">
<!-- -->
</a>
<h3>Method Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation">
<caption><span id="t0" class="activeTableTab"><span>All Methods</span><span class="tabEnd">&nbsp;</span></span><span id="t2" class="tableTab"><span><a href="javascript:show(2);">Instance Methods</a></span><span class="tabEnd">&nbsp;</span></span><span id="t3" class="tableTab"><span><a href="javascript:show(4);">Abstract Methods</a></span><span class="tabEnd">&nbsp;</span></span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Method and Description</th>
</tr>
<tr id="i0" class="altColor">
<td class="colFirst"><code>boolean</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#contains-K-">contains</a></span>(<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;key)</code>
<div class="block">Checks for existence of a key in this index.</div>
</td>
</tr>
<tr id="i1" class="rowColor">
<td class="colFirst"><code>boolean</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#contains-com.sleepycat.je.Transaction-K-com.sleepycat.je.LockMode-">contains</a></span>(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;key,
<a href="../../../com/sleepycat/je/LockMode.html" title="enum in com.sleepycat.je">LockMode</a>&nbsp;lockMode)</code>
<div class="block">Checks for existence of a key in this index.</div>
</td>
</tr>
<tr id="i2" class="altColor">
<td class="colFirst"><code>long</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#count--">count</a></span>()</code>
<div class="block">Returns a non-transactional count of the entities in this index.</div>
</td>
</tr>
<tr id="i3" class="rowColor">
<td class="colFirst"><code>long</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#count-long-">count</a></span>(long&nbsp;memoryLimit)</code>
<div class="block">Returns a non-transactional count of the entities in this index.</div>
</td>
</tr>
<tr id="i4" class="altColor">
<td class="colFirst"><code>boolean</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#delete-K-">delete</a></span>(<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;key)</code>
<div class="block">Deletes all entities with a given index key.</div>
</td>
</tr>
<tr id="i5" class="rowColor">
<td class="colFirst"><code>boolean</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#delete-com.sleepycat.je.Transaction-K-">delete</a></span>(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;key)</code>
<div class="block">Deletes all entities with a given index key.</div>
</td>
</tr>
<tr id="i6" class="altColor">
<td class="colFirst"><code><a href="../../../com/sleepycat/je/OperationResult.html" title="class in com.sleepycat.je">OperationResult</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#delete-com.sleepycat.je.Transaction-K-com.sleepycat.je.WriteOptions-">delete</a></span>(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;key,
<a href="../../../com/sleepycat/je/WriteOptions.html" title="class in com.sleepycat.je">WriteOptions</a>&nbsp;options)</code>
<div class="block">Deletes all entities with a given index key, using a WriteOptions
parameter and returning an OperationResult.</div>
</td>
</tr>
<tr id="i7" class="rowColor">
<td class="colFirst"><code><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist">EntityCursor</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a>&gt;</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#entities--">entities</a></span>()</code>
<div class="block">Opens a cursor for traversing all entities in this index.</div>
</td>
</tr>
<tr id="i8" class="altColor">
<td class="colFirst"><code><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist">EntityCursor</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a>&gt;</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#entities-K-boolean-K-boolean-">entities</a></span>(<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;fromKey,
boolean&nbsp;fromInclusive,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;toKey,
boolean&nbsp;toInclusive)</code>
<div class="block">Opens a cursor for traversing entities in a key range.</div>
</td>
</tr>
<tr id="i9" class="rowColor">
<td class="colFirst"><code><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist">EntityCursor</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a>&gt;</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#entities-com.sleepycat.je.Transaction-com.sleepycat.je.CursorConfig-">entities</a></span>(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/je/CursorConfig.html" title="class in com.sleepycat.je">CursorConfig</a>&nbsp;config)</code>
<div class="block">Opens a cursor for traversing all entities in this index.</div>
</td>
</tr>
<tr id="i10" class="altColor">
<td class="colFirst"><code><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist">EntityCursor</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a>&gt;</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#entities-com.sleepycat.je.Transaction-K-boolean-K-boolean-com.sleepycat.je.CursorConfig-">entities</a></span>(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;fromKey,
boolean&nbsp;fromInclusive,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;toKey,
boolean&nbsp;toInclusive,
<a href="../../../com/sleepycat/je/CursorConfig.html" title="class in com.sleepycat.je">CursorConfig</a>&nbsp;config)</code>
<div class="block">Opens a cursor for traversing entities in a key range.</div>
</td>
</tr>
<tr id="i11" class="rowColor">
<td class="colFirst"><code><a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#get-K-">get</a></span>(<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;key)</code>
<div class="block">Gets an entity via a key of this index.</div>
</td>
</tr>
<tr id="i12" class="altColor">
<td class="colFirst"><code><a href="../../../com/sleepycat/persist/EntityResult.html" title="class in com.sleepycat.persist">EntityResult</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a>&gt;</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#get-com.sleepycat.je.Transaction-K-com.sleepycat.je.Get-com.sleepycat.je.ReadOptions-">get</a></span>(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;key,
<a href="../../../com/sleepycat/je/Get.html" title="enum in com.sleepycat.je">Get</a>&nbsp;getType,
<a href="../../../com/sleepycat/je/ReadOptions.html" title="class in com.sleepycat.je">ReadOptions</a>&nbsp;options)</code>
<div class="block">Gets an entity via a key of this index, using Get type and ReadOptions
parameters, and returning an EntityResult.</div>
</td>
</tr>
<tr id="i13" class="rowColor">
<td class="colFirst"><code><a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#get-com.sleepycat.je.Transaction-K-com.sleepycat.je.LockMode-">get</a></span>(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;key,
<a href="../../../com/sleepycat/je/LockMode.html" title="enum in com.sleepycat.je">LockMode</a>&nbsp;lockMode)</code>
<div class="block">Gets an entity via a key of this index.</div>
</td>
</tr>
<tr id="i14" class="altColor">
<td class="colFirst"><code><a href="../../../com/sleepycat/je/Database.html" title="class in com.sleepycat.je">Database</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#getDatabase--">getDatabase</a></span>()</code>
<div class="block">Returns the underlying database for this index.</div>
</td>
</tr>
<tr id="i15" class="rowColor">
<td class="colFirst"><code><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist">EntityCursor</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&gt;</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#keys--">keys</a></span>()</code>
<div class="block">Opens a cursor for traversing all keys in this index.</div>
</td>
</tr>
<tr id="i16" class="altColor">
<td class="colFirst"><code><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist">EntityCursor</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&gt;</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#keys-K-boolean-K-boolean-">keys</a></span>(<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;fromKey,
boolean&nbsp;fromInclusive,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;toKey,
boolean&nbsp;toInclusive)</code>
<div class="block">Opens a cursor for traversing keys in a key range.</div>
</td>
</tr>
<tr id="i17" class="rowColor">
<td class="colFirst"><code><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist">EntityCursor</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&gt;</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#keys-com.sleepycat.je.Transaction-com.sleepycat.je.CursorConfig-">keys</a></span>(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/je/CursorConfig.html" title="class in com.sleepycat.je">CursorConfig</a>&nbsp;config)</code>
<div class="block">Opens a cursor for traversing all keys in this index.</div>
</td>
</tr>
<tr id="i18" class="altColor">
<td class="colFirst"><code><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist">EntityCursor</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&gt;</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#keys-com.sleepycat.je.Transaction-K-boolean-K-boolean-com.sleepycat.je.CursorConfig-">keys</a></span>(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;fromKey,
boolean&nbsp;fromInclusive,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;toKey,
boolean&nbsp;toInclusive,
<a href="../../../com/sleepycat/je/CursorConfig.html" title="class in com.sleepycat.je">CursorConfig</a>&nbsp;config)</code>
<div class="block">Opens a cursor for traversing keys in a key range.</div>
</td>
</tr>
<tr id="i19" class="rowColor">
<td class="colFirst"><code>java.util.Map&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>,<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a>&gt;</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#map--">map</a></span>()</code>
<div class="block">Returns a standard Java map based on this entity index.</div>
</td>
</tr>
<tr id="i20" class="altColor">
<td class="colFirst"><code>java.util.SortedMap&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>,<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a>&gt;</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/sleepycat/persist/EntityIndex.html#sortedMap--">sortedMap</a></span>()</code>
<div class="block">Returns a standard Java sorted map based on this entity index.</div>
</td>
</tr>
</table>
</li>
</ul>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ METHOD DETAIL ========== -->
<ul class="blockList">
<li class="blockList"><a name="method.detail">
<!-- -->
</a>
<h3>Method Detail</h3>
<a name="getDatabase--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>getDatabase</h4>
<pre><a href="../../../com/sleepycat/je/Database.html" title="class in com.sleepycat.je">Database</a>&nbsp;getDatabase()</pre>
<div class="block">Returns the underlying database for this index.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the database.</dd>
</dl>
</li>
</ul>
<a name="contains-java.lang.Object-">
<!-- -->
</a><a name="contains-K-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>contains</h4>
<pre>boolean&nbsp;contains(<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;key)
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Checks for existence of a key in this index.
<p>The operation will not be transaction protected, and <a href="../../../com/sleepycat/je/LockMode.html#DEFAULT"><code>LockMode.DEFAULT</code></a> is used implicitly.</p>
<!-- begin JE only -->
<p><code>READ_UNCOMMITTED</code> can be used with this method to reduce I/O,
since the record data item will not be read. This is the same benefit
as described in <a href="#keyCursorReadUncommitted">Key Cursor
Optimization with READ_UNCOMMITTED</a></p>
<!-- end JE only --></div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>key</code> - the key to search for.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>whether the key exists in the index.
<!-- begin JE only --></dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/OperationFailureException.html" title="class in com.sleepycat.je">OperationFailureException</a></code> - if one of the <a
href="../je/OperationFailureException.html#readFailures">Read Operation
Failures</a> occurs.</dd>
<dd><code><a href="../../../com/sleepycat/je/EnvironmentFailureException.html" title="class in com.sleepycat.je">EnvironmentFailureException</a></code> - if an unexpected, internal or
environment-wide failure occurs.
<!-- end JE only --></dd>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
</dl>
</li>
</ul>
<a name="contains-com.sleepycat.je.Transaction-java.lang.Object-com.sleepycat.je.LockMode-">
<!-- -->
</a><a name="contains-com.sleepycat.je.Transaction-K-com.sleepycat.je.LockMode-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>contains</h4>
<pre>boolean&nbsp;contains(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;key,
<a href="../../../com/sleepycat/je/LockMode.html" title="enum in com.sleepycat.je">LockMode</a>&nbsp;lockMode)
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Checks for existence of a key in this index.
<!-- begin JE only -->
<p><code>READ_UNCOMMITTED</code> can be used with this method to reduce I/O,
since the record data item will not be read. This is the same benefit
as described in <a href="#keyCursorReadUncommitted">Key Cursor
Optimization with READ_UNCOMMITTED</a></p>
<!-- end JE only --></div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>txn</code> - the transaction used to protect this operation, or null
if the operation should not be transaction protected.</dd>
<dd><code>key</code> - the key to search for.</dd>
<dd><code>lockMode</code> - the lock mode to use for this operation, or null to
use <a href="../../../com/sleepycat/je/LockMode.html#DEFAULT"><code>LockMode.DEFAULT</code></a>.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>whether the key exists in the index.
<!-- begin JE only --></dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/OperationFailureException.html" title="class in com.sleepycat.je">OperationFailureException</a></code> - if one of the <a
href="../je/OperationFailureException.html#readFailures">Read Operation
Failures</a> occurs.</dd>
<dd><code><a href="../../../com/sleepycat/je/EnvironmentFailureException.html" title="class in com.sleepycat.je">EnvironmentFailureException</a></code> - if an unexpected, internal or
environment-wide failure occurs.
<!-- end JE only --></dd>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
</dl>
</li>
</ul>
<a name="get-java.lang.Object-">
<!-- -->
</a><a name="get-K-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>get</h4>
<pre><a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a>&nbsp;get(<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;key)
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Gets an entity via a key of this index.
<p>The operation will not be transaction protected, and <a href="../../../com/sleepycat/je/LockMode.html#DEFAULT"><code>LockMode.DEFAULT</code></a> is used implicitly.</p></div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>key</code> - the key to search for.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the value mapped to the given key, or null if the key is not
present in the index.
<!-- begin JE only --></dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/OperationFailureException.html" title="class in com.sleepycat.je">OperationFailureException</a></code> - if one of the <a
href="../je/OperationFailureException.html#readFailures">Read Operation
Failures</a> occurs.</dd>
<dd><code><a href="../../../com/sleepycat/je/EnvironmentFailureException.html" title="class in com.sleepycat.je">EnvironmentFailureException</a></code> - if an unexpected, internal or
environment-wide failure occurs.
<!-- end JE only --></dd>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
</dl>
</li>
</ul>
<a name="get-com.sleepycat.je.Transaction-java.lang.Object-com.sleepycat.je.LockMode-">
<!-- -->
</a><a name="get-com.sleepycat.je.Transaction-K-com.sleepycat.je.LockMode-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>get</h4>
<pre><a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a>&nbsp;get(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;key,
<a href="../../../com/sleepycat/je/LockMode.html" title="enum in com.sleepycat.je">LockMode</a>&nbsp;lockMode)
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Gets an entity via a key of this index.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>txn</code> - the transaction used to protect this operation, or null
if the operation should not be transaction protected.</dd>
<dd><code>key</code> - the key to search for.</dd>
<dd><code>lockMode</code> - the lock mode to use for this operation, or null to
use <a href="../../../com/sleepycat/je/LockMode.html#DEFAULT"><code>LockMode.DEFAULT</code></a>.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the value mapped to the given key, or null if the key is not
present in the index.
<!-- begin JE only --></dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/OperationFailureException.html" title="class in com.sleepycat.je">OperationFailureException</a></code> - if one of the <a
href="../je/OperationFailureException.html#readFailures">Read Operation
Failures</a> occurs.</dd>
<dd><code><a href="../../../com/sleepycat/je/EnvironmentFailureException.html" title="class in com.sleepycat.je">EnvironmentFailureException</a></code> - if an unexpected, internal or
environment-wide failure occurs.
<!-- end JE only --></dd>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
</dl>
</li>
</ul>
<a name="get-com.sleepycat.je.Transaction-java.lang.Object-com.sleepycat.je.Get-com.sleepycat.je.ReadOptions-">
<!-- -->
</a><a name="get-com.sleepycat.je.Transaction-K-com.sleepycat.je.Get-com.sleepycat.je.ReadOptions-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>get</h4>
<pre><a href="../../../com/sleepycat/persist/EntityResult.html" title="class in com.sleepycat.persist">EntityResult</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a>&gt;&nbsp;get(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;key,
<a href="../../../com/sleepycat/je/Get.html" title="enum in com.sleepycat.je">Get</a>&nbsp;getType,
<a href="../../../com/sleepycat/je/ReadOptions.html" title="class in com.sleepycat.je">ReadOptions</a>&nbsp;options)
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Gets an entity via a key of this index, using Get type and ReadOptions
parameters, and returning an EntityResult.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>txn</code> - the transaction used to protect this operation, or null
if the operation should not be transaction protected.</dd>
<dd><code>key</code> - the key to search for.</dd>
<dd><code>getType</code> - must be <a href="../../../com/sleepycat/je/Get.html#SEARCH"><code>Get.SEARCH</code></a>.</dd>
<dd><code>options</code> - the ReadOptions, or null to use default options.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the EntityResult, including the value mapped to the given key,
or null if the key is not present in the index.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/OperationFailureException.html" title="class in com.sleepycat.je">OperationFailureException</a></code> - if one of the <a
href="../je/OperationFailureException.html#readFailures">Read Operation
Failures</a> occurs.</dd>
<dd><code><a href="../../../com/sleepycat/je/EnvironmentFailureException.html" title="class in com.sleepycat.je">EnvironmentFailureException</a></code> - if an unexpected, internal or
environment-wide failure occurs.</dd>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
<dt><span class="simpleTagLabel">Since:</span></dt>
<dd>7.0</dd>
</dl>
</li>
</ul>
<a name="count--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>count</h4>
<pre>long&nbsp;count()
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Returns a non-transactional count of the entities in this index.
<!-- begin JE only -->
<p>This operation is faster than obtaining a count by scanning the index
manually, and will not perturb the current contents of the cache.
However, the count is not guaranteed to be accurate if there are
concurrent updates. Note that this method does scan a significant
portion of the index and should be considered a fairly expensive
operation.</p>
<p>This operation will disable deletion of log files by the JE log
cleaner during its execution and will consume a certain amount of
memory (but without affecting the memory that is available for the
JE cache). To avoid excessive memory consumption (and a potential
<code>OutOfMemoryError</code>) this method places an internal limit on
its memory consumption. If this limit is reached, the method will
still work properly, but its performance will degrade. To specify
a different memory limit than the one used by this method, use the
<a href="../../../com/sleepycat/persist/EntityIndex.html#count-long-"><code>count(long memoryLimit)</code></a> method.</p>
<!-- end JE only --></div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the number of entities in this index.
<!-- begin JE only --></dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/OperationFailureException.html" title="class in com.sleepycat.je">OperationFailureException</a></code> - if one of the <a
href="../je/OperationFailureException.html#readFailures">Read Operation
Failures</a> occurs.</dd>
<dd><code><a href="../../../com/sleepycat/je/EnvironmentFailureException.html" title="class in com.sleepycat.je">EnvironmentFailureException</a></code> - if an unexpected, internal or
environment-wide failure occurs.
<!-- end JE only --></dd>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
</dl>
</li>
</ul>
<a name="count-long-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>count</h4>
<pre>long&nbsp;count(long&nbsp;memoryLimit)
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Returns a non-transactional count of the entities in this index.
<p>This operation is faster than obtaining a count by scanning the index
manually, and will not perturb the current contents of the cache.
However, the count is not guaranteed to be accurate if there are
concurrent updates. Note that this method does scan a significant
portion of the index and should be considered a fairly expensive
operation.</p>
<p>This operation will disable deletion of log files by the JE log
cleaner during its execution and will consume a certain amount of
memory (but without affecting the memory that is available for the
JE cache). To avoid excessive memory consumption (and a potential
<code>OutOfMemoryError</code>) this method takes as input an upper bound
on the memory it may consume. If this limit is reached, the method
will still work properly, but its performance will degrade.</p></div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the number of entities in this index.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/OperationFailureException.html" title="class in com.sleepycat.je">OperationFailureException</a></code> - if one of the <a
href="../je/OperationFailureException.html#readFailures">Read Operation
Failures</a> occurs.</dd>
<dd><code><a href="../../../com/sleepycat/je/EnvironmentFailureException.html" title="class in com.sleepycat.je">EnvironmentFailureException</a></code> - if an unexpected, internal or
environment-wide failure occurs.</dd>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
</dl>
</li>
</ul>
<a name="delete-java.lang.Object-">
<!-- -->
</a><a name="delete-K-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>delete</h4>
<pre>boolean&nbsp;delete(<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;key)
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Deletes all entities with a given index key.
<p>Auto-commit is used implicitly if the store is transactional.</p></div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>key</code> - the key to search for.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>whether any entities were deleted.
<!-- begin JE only --></dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/OperationFailureException.html" title="class in com.sleepycat.je">OperationFailureException</a></code> - if one of the <a
href="../je/OperationFailureException.html#writeFailures">Write
Operation Failures</a> occurs.</dd>
<dd><code><a href="../../../com/sleepycat/je/EnvironmentFailureException.html" title="class in com.sleepycat.je">EnvironmentFailureException</a></code> - if an unexpected, internal or
environment-wide failure occurs.
<!-- end JE only --></dd>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
</dl>
</li>
</ul>
<a name="delete-com.sleepycat.je.Transaction-java.lang.Object-">
<!-- -->
</a><a name="delete-com.sleepycat.je.Transaction-K-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>delete</h4>
<pre>boolean&nbsp;delete(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;key)
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Deletes all entities with a given index key.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>txn</code> - the transaction used to protect this operation, null to use
auto-commit, or null if the store is non-transactional.</dd>
<dd><code>key</code> - the key to search for.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>whether any entities were deleted.
<!-- begin JE only --></dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/OperationFailureException.html" title="class in com.sleepycat.je">OperationFailureException</a></code> - if one of the <a
href="../je/OperationFailureException.html#writeFailures">Write
Operation Failures</a> occurs.</dd>
<dd><code><a href="../../../com/sleepycat/je/EnvironmentFailureException.html" title="class in com.sleepycat.je">EnvironmentFailureException</a></code> - if an unexpected, internal or
environment-wide failure occurs.
<!-- end JE only --></dd>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
</dl>
</li>
</ul>
<a name="delete-com.sleepycat.je.Transaction-java.lang.Object-com.sleepycat.je.WriteOptions-">
<!-- -->
</a><a name="delete-com.sleepycat.je.Transaction-K-com.sleepycat.je.WriteOptions-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>delete</h4>
<pre><a href="../../../com/sleepycat/je/OperationResult.html" title="class in com.sleepycat.je">OperationResult</a>&nbsp;delete(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;key,
<a href="../../../com/sleepycat/je/WriteOptions.html" title="class in com.sleepycat.je">WriteOptions</a>&nbsp;options)
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Deletes all entities with a given index key, using a WriteOptions
parameter and returning an OperationResult.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>txn</code> - the transaction used to protect this operation, null to use
auto-commit, or null if the store is non-transactional.</dd>
<dd><code>key</code> - the key to search for.</dd>
<dd><code>options</code> - the WriteOptions, or null to use default options.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the OperationResult if any entities were deleted, else null. If</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/OperationFailureException.html" title="class in com.sleepycat.je">OperationFailureException</a></code> - if one of the <a
href="../je/OperationFailureException.html#writeFailures">Write
Operation Failures</a> occurs.</dd>
<dd><code><a href="../../../com/sleepycat/je/EnvironmentFailureException.html" title="class in com.sleepycat.je">EnvironmentFailureException</a></code> - if an unexpected, internal or
environment-wide failure occurs.</dd>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
<dt><span class="simpleTagLabel">Since:</span></dt>
<dd>7.0</dd>
</dl>
</li>
</ul>
<a name="keys--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>keys</h4>
<pre><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist">EntityCursor</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&gt;&nbsp;keys()
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Opens a cursor for traversing all keys in this index.
<p>The operations performed with the cursor will not be transaction
protected, and <a href="../../../com/sleepycat/je/CursorConfig.html#DEFAULT"><code>CursorConfig.DEFAULT</code></a> is used implicitly. If the
store is transactional, the cursor may not be used to update or delete
entities.</p>
<!-- begin JE only -->
<p>Note that <code>READ_UNCOMMITTED</code> can be used with a key cursor to
reduce I/O, potentially providing significant performance benefits. See
<a href="#keyCursorReadUncommitted">Key Cursor Optimization with
READ_UNCOMMITTED</a></p>
<!-- end JE only --></div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the cursor.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
</dl>
</li>
</ul>
<a name="keys-com.sleepycat.je.Transaction-com.sleepycat.je.CursorConfig-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>keys</h4>
<pre><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist">EntityCursor</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&gt;&nbsp;keys(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/je/CursorConfig.html" title="class in com.sleepycat.je">CursorConfig</a>&nbsp;config)
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Opens a cursor for traversing all keys in this index.
<!-- begin JE only -->
<p>Note that <code>READ_UNCOMMITTED</code> can be used with a key cursor to
reduce I/O, potentially providing significant performance benefits. See
<a href="#keyCursorReadUncommitted">Key Cursor Optimization with
READ_UNCOMMITTED</a></p>
<!-- end JE only --></div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>txn</code> - the transaction used to protect all operations performed with
the cursor, or null if the operations should not be transaction
protected. If the store is non-transactional, null must be specified.
For a transactional store the transaction is optional for read-only
access and required for read-write access.</dd>
<dd><code>config</code> - the cursor configuration that determines the default lock
mode used for all cursor operations, or null to implicitly use <a href="../../../com/sleepycat/je/CursorConfig.html#DEFAULT"><code>CursorConfig.DEFAULT</code></a>.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the cursor.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
</dl>
</li>
</ul>
<a name="entities--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>entities</h4>
<pre><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist">EntityCursor</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a>&gt;&nbsp;entities()
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Opens a cursor for traversing all entities in this index.
<p>The operations performed with the cursor will not be transaction
protected, and <a href="../../../com/sleepycat/je/CursorConfig.html#DEFAULT"><code>CursorConfig.DEFAULT</code></a> is used implicitly. If the
store is transactional, the cursor may not be used to update or delete
entities.</p></div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the cursor.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
</dl>
</li>
</ul>
<a name="entities-com.sleepycat.je.Transaction-com.sleepycat.je.CursorConfig-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>entities</h4>
<pre><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist">EntityCursor</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a>&gt;&nbsp;entities(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/je/CursorConfig.html" title="class in com.sleepycat.je">CursorConfig</a>&nbsp;config)
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Opens a cursor for traversing all entities in this index.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>txn</code> - the transaction used to protect all operations performed with
the cursor, or null if the operations should not be transaction
protected. If the store is non-transactional, null must be specified.
For a transactional store the transaction is optional for read-only
access and required for read-write access.</dd>
<dd><code>config</code> - the cursor configuration that determines the default lock
mode used for all cursor operations, or null to implicitly use <a href="../../../com/sleepycat/je/CursorConfig.html#DEFAULT"><code>CursorConfig.DEFAULT</code></a>.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the cursor.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
</dl>
</li>
</ul>
<a name="keys-java.lang.Object-boolean-java.lang.Object-boolean-">
<!-- -->
</a><a name="keys-K-boolean-K-boolean-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>keys</h4>
<pre><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist">EntityCursor</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&gt;&nbsp;keys(<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;fromKey,
boolean&nbsp;fromInclusive,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;toKey,
boolean&nbsp;toInclusive)
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Opens a cursor for traversing keys in a key range.
<p>The operations performed with the cursor will not be transaction
protected, and <a href="../../../com/sleepycat/je/CursorConfig.html#DEFAULT"><code>CursorConfig.DEFAULT</code></a> is used implicitly. If the
store is transactional, the cursor may not be used to update or delete
entities.</p>
<!-- begin JE only -->
<p>Note that <code>READ_UNCOMMITTED</code> can be used with a key cursor to
reduce I/O, potentially providing significant performance benefits. See
<a href="#keyCursorReadUncommitted">Key Cursor Optimization with
READ_UNCOMMITTED</a></p>
<!-- end JE only --></div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>fromKey</code> - is the lower bound of the key range, or null if the range
has no lower bound.</dd>
<dd><code>fromInclusive</code> - is true if keys greater than or equal to fromKey
should be included in the key range, or false if only keys greater than
fromKey should be included.</dd>
<dd><code>toKey</code> - is the upper bound of the key range, or null if the range
has no upper bound.</dd>
<dd><code>toInclusive</code> - is true if keys less than or equal to toKey should be
included in the key range, or false if only keys less than toKey should
be included.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the cursor.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
</dl>
</li>
</ul>
<a name="keys-com.sleepycat.je.Transaction-java.lang.Object-boolean-java.lang.Object-boolean-com.sleepycat.je.CursorConfig-">
<!-- -->
</a><a name="keys-com.sleepycat.je.Transaction-K-boolean-K-boolean-com.sleepycat.je.CursorConfig-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>keys</h4>
<pre><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist">EntityCursor</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&gt;&nbsp;keys(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;fromKey,
boolean&nbsp;fromInclusive,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;toKey,
boolean&nbsp;toInclusive,
<a href="../../../com/sleepycat/je/CursorConfig.html" title="class in com.sleepycat.je">CursorConfig</a>&nbsp;config)
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Opens a cursor for traversing keys in a key range.
<!-- begin JE only -->
<a name="keyCursorReadUncommitted"><h4>Key Cursor Optimization with
READ_UNCOMMITTED</h4></a>
<p>Using a key cursor potentially has a large performance benefit when
the <code>READ_UNCOMMITTED</code> isolation mode is used. In this case, if
the record data is not in the JE cache, it will not be read from disk.
The performance benefit is potentially large because random access disk
reads may be reduced. Examples are:</p>
<ul>
<li>Scanning all records in key order, when the entity is not needed and
<code>READ_UNCOMMITTED</code> isolation is acceptable.</li>
<li>Skipping over records quickly to perform approximate pagination with
<code>READ_UNCOMMITTED</code> isolation.</li>
</ul>
<p>For other isolation modes (<code>READ_COMMITTED</code>, <code>REPEATABLE_READ</code> and <code>SERIALIZABLE</code>), the performance benefit of a
key cursor is not as significant. In this case, the data item must be
read into the JE cache if it is not already present, in order to lock
the record. The only performance benefit is that the data will not be
copied from the JE cache to the application's entry parameter, and will
not be unmarshalled into an entity object.</p>
<p>For information on specifying isolation modes, see <a href="../../../com/sleepycat/je/LockMode.html" title="enum in com.sleepycat.je"><code>LockMode</code></a>,
<a href="../../../com/sleepycat/je/CursorConfig.html" title="class in com.sleepycat.je"><code>CursorConfig</code></a> and <a href="../../../com/sleepycat/je/TransactionConfig.html" title="class in com.sleepycat.je"><code>TransactionConfig</code></a>.</p>
<!-- end JE only --></div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>txn</code> - the transaction used to protect all operations performed with
the cursor, or null if the operations should not be transaction
protected. If the store is non-transactional, null must be specified.
For a transactional store the transaction is optional for read-only
access and required for read-write access.</dd>
<dd><code>fromKey</code> - is the lower bound of the key range, or null if the range
has no lower bound.</dd>
<dd><code>fromInclusive</code> - is true if keys greater than or equal to fromKey
should be included in the key range, or false if only keys greater than
fromKey should be included.</dd>
<dd><code>toKey</code> - is the upper bound of the key range, or null if the range
has no upper bound.</dd>
<dd><code>toInclusive</code> - is true if keys less than or equal to toKey should be
included in the key range, or false if only keys less than toKey should
be included.</dd>
<dd><code>config</code> - the cursor configuration that determines the default lock
mode used for all cursor operations, or null to implicitly use <a href="../../../com/sleepycat/je/CursorConfig.html#DEFAULT"><code>CursorConfig.DEFAULT</code></a>.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the cursor.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
</dl>
</li>
</ul>
<a name="entities-java.lang.Object-boolean-java.lang.Object-boolean-">
<!-- -->
</a><a name="entities-K-boolean-K-boolean-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>entities</h4>
<pre><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist">EntityCursor</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a>&gt;&nbsp;entities(<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;fromKey,
boolean&nbsp;fromInclusive,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;toKey,
boolean&nbsp;toInclusive)
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Opens a cursor for traversing entities in a key range.
<p>The operations performed with the cursor will not be transaction
protected, and <a href="../../../com/sleepycat/je/CursorConfig.html#DEFAULT"><code>CursorConfig.DEFAULT</code></a> is used implicitly. If the
store is transactional, the cursor may not be used to update or delete
entities.</p></div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>fromKey</code> - is the lower bound of the key range, or null if the range
has no lower bound.</dd>
<dd><code>fromInclusive</code> - is true if keys greater than or equal to fromKey
should be included in the key range, or false if only keys greater than
fromKey should be included.</dd>
<dd><code>toKey</code> - is the upper bound of the key range, or null if the range
has no upper bound.</dd>
<dd><code>toInclusive</code> - is true if keys less than or equal to toKey should be
included in the key range, or false if only keys less than toKey should
be included.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the cursor.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
</dl>
</li>
</ul>
<a name="entities-com.sleepycat.je.Transaction-java.lang.Object-boolean-java.lang.Object-boolean-com.sleepycat.je.CursorConfig-">
<!-- -->
</a><a name="entities-com.sleepycat.je.Transaction-K-boolean-K-boolean-com.sleepycat.je.CursorConfig-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>entities</h4>
<pre><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist">EntityCursor</a>&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a>&gt;&nbsp;entities(<a href="../../../com/sleepycat/je/Transaction.html" title="class in com.sleepycat.je">Transaction</a>&nbsp;txn,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;fromKey,
boolean&nbsp;fromInclusive,
<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>&nbsp;toKey,
boolean&nbsp;toInclusive,
<a href="../../../com/sleepycat/je/CursorConfig.html" title="class in com.sleepycat.je">CursorConfig</a>&nbsp;config)
throws <a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></pre>
<div class="block">Opens a cursor for traversing entities in a key range.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>txn</code> - the transaction used to protect all operations performed with
the cursor, or null if the operations should not be transaction
protected. If the store is non-transactional, null must be specified.
For a transactional store the transaction is optional for read-only
access and required for read-write access.</dd>
<dd><code>fromKey</code> - is the lower bound of the key range, or null if the range
has no lower bound.</dd>
<dd><code>fromInclusive</code> - is true if keys greater than or equal to fromKey
should be included in the key range, or false if only keys greater than
fromKey should be included.</dd>
<dd><code>toKey</code> - is the upper bound of the key range, or null if the range
has no upper bound.</dd>
<dd><code>toInclusive</code> - is true if keys less than or equal to toKey should be
included in the key range, or false if only keys less than toKey should
be included.</dd>
<dd><code>config</code> - the cursor configuration that determines the default lock
mode used for all cursor operations, or null to implicitly use <a href="../../../com/sleepycat/je/CursorConfig.html#DEFAULT"><code>CursorConfig.DEFAULT</code></a>.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the cursor.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="../../../com/sleepycat/je/DatabaseException.html" title="class in com.sleepycat.je">DatabaseException</a></code> - the base class for all BDB exceptions.</dd>
</dl>
</li>
</ul>
<a name="map--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>map</h4>
<pre>java.util.Map&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>,<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a>&gt;&nbsp;map()</pre>
<div class="block">Returns a standard Java map based on this entity index. The <a href="../../../com/sleepycat/collections/StoredMap.html" title="class in com.sleepycat.collections"><code>StoredMap</code></a> returned is defined by the <a href="../../../com/sleepycat/collections/package-summary.html">Collections API</a>. Stored collections conform
to the standard Java collections framework interface.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the map.</dd>
</dl>
</li>
</ul>
<a name="sortedMap--">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>sortedMap</h4>
<pre>java.util.SortedMap&lt;<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">K</a>,<a href="../../../com/sleepycat/persist/EntityIndex.html" title="type parameter in EntityIndex">V</a>&gt;&nbsp;sortedMap()</pre>
<div class="block">Returns a standard Java sorted map based on this entity index. The
<a href="../../../com/sleepycat/collections/StoredSortedMap.html" title="class in com.sleepycat.collections"><code>StoredSortedMap</code></a> returned is defined by the <a href="../../../com/sleepycat/collections/package-summary.html">Collections API</a>. Stored collections conform
to the standard Java collections framework interface.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the map.</dd>
</dl>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/EntityIndex.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../index-all.html">Index</a></li>
<li><a href="../../../help-doc.html">Help</a></li>
</ul>
<div class="aboutLanguage"><b>Berkeley DB Java Edition</b><br><font size=\"-1\"> version 7.5.11</font>
</div>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../com/sleepycat/persist/EntityCursor.html" title="interface in com.sleepycat.persist"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../com/sleepycat/persist/EntityJoin.html" title="class in com.sleepycat.persist"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../index.html?com/sleepycat/persist/EntityIndex.html" target="_top">Frames</a></li>
<li><a href="EntityIndex.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.detail">Method</a></li>
</ul>
</div>
<a name="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<p class="legalCopy"><small><font size=1>Copyright (c) 2002, 2017 Oracle and/or its affiliates. All rights reserved.</font> </small></p>
</body>
</html>
Reference in a new issue View git blame Copy permalink