com.sleepycat.persist.EntityCursor Maven / Gradle / Ivy
/*-
* Copyright (C) 2002, 2018, Oracle and/or its affiliates. All rights reserved.
*
* This file was distributed by Oracle as part of a version of Oracle Berkeley
* DB Java Edition made available at:
*
* http://www.oracle.com/technetwork/database/database-technologies/berkeleydb/downloads/index.html
*
* Please see the LICENSE file included in the top-level directory of the
* appropriate version of Oracle Berkeley DB Java Edition for a copy of the
* license and additional information.
*/
package com.sleepycat.persist;
import java.util.Iterator;
/* */
import com.sleepycat.je.CacheMode;
/* */
import com.sleepycat.je.CursorConfig;
import com.sleepycat.je.DatabaseConfig;
import com.sleepycat.je.DatabaseException;
/* */
import com.sleepycat.je.DuplicateDataException;
import com.sleepycat.je.EnvironmentFailureException;
import com.sleepycat.je.Get;
/* */
import com.sleepycat.je.LockMode;
import com.sleepycat.je.OperationFailureException;
/* */
import com.sleepycat.je.OperationResult;
import com.sleepycat.je.ReadOptions;
/* */
import com.sleepycat.je.Transaction;
/* */
import com.sleepycat.je.WriteOptions;
/* */
import com.sleepycat.persist.model.Relationship;
import com.sleepycat.persist.model.SecondaryKey;
/**
* Traverses entity values or key values and allows deleting or updating the
* entity at the current cursor position. The value type (V) is either an
* entity class or a key class, depending on how the cursor was opened.
*
* {@code EntityCursor} objects are not thread-safe. Cursors
* should be opened, used and closed by a single thread.
*
* Cursors are opened using the {@link EntityIndex#keys} and {@link
* EntityIndex#entities} family of methods. These methods are available for
* objects of any class that implements {@link EntityIndex}: {@link
* PrimaryIndex}, {@link SecondaryIndex}, and the indices returned by {@link
* SecondaryIndex#keysIndex} and {@link SecondaryIndex#subIndex}. A {@link
* ForwardCursor}, which implements a subset of cursor operations, is also
* available via the {@link EntityJoin#keys} and {@link EntityJoin#entities}
* methods.
*
* Values are always returned by a cursor in key order, where the key is
* defined by the underlying {@link EntityIndex}. For example, a cursor on a
* {@link SecondaryIndex} returns values ordered by secondary key, while an
* index on a {@link PrimaryIndex} or a {@link SecondaryIndex#subIndex} returns
* values ordered by primary key.
*
* WARNING: Cursors must always be closed to prevent resource leaks
* which could lead to the index becoming unusable or cause an
* OutOfMemoryError. To ensure that a cursor is closed in the
* face of exceptions, call {@link #close} in a finally block. For example,
* the following code traverses all Employee entities and closes the cursor
* whether or not an exception occurs:
*
*
* {@literal @Entity}
* class Employee {
*
* {@literal @PrimaryKey}
* long id;
*
* {@literal @SecondaryKey(relate=MANY_TO_ONE)}
* String department;
*
* String name;
*
* private Employee() {}
* }
*
* EntityStore store = ...
*
* {@code PrimaryIndex} primaryIndex =
* store.getPrimaryIndex(Long.class, Employee.class);
*
* {@code EntityCursor} cursor = primaryIndex.entities();
* try {
* for (Employee entity = cursor.first();
* entity != null;
* entity = cursor.next()) {
* // Do something with the entity...
* }
* } finally {
* cursor.close();
* }
*
* Initializing the Cursor Position
*
* When it is opened, a cursor is not initially positioned on any value; in
* other words, it is uninitialized. Most methods in this interface initialize
* the cursor position but certain methods, for example, {@link #current} and
* {@link #delete}, throw {@link IllegalStateException} when called for an
* uninitialized cursor.
*
* Note that the {@link #next} and {@link #prev} methods return the first or
* last value respectively for an uninitialized cursor. This allows the loop
* in the example above to be rewritten as follows:
*
*
* {@code EntityCursor} cursor = primaryIndex.entities();
* try {
* Employee entity;
* while ((entity = cursor.next()) != null) {
* // Do something with the entity...
* }
* } finally {
* cursor.close();
* }
*
* Cursors and Iterators
*
* The {@link #iterator} method can be used to return a standard Java {@code
* Iterator} that returns the same values that the cursor returns. For
* example:
*
*
* {@code EntityCursor} cursor = primaryIndex.entities();
* try {
* {@code Iterator} i = cursor.iterator();
* while (i.hasNext()) {
* Employee entity = i.next();
* // Do something with the entity...
* }
* } finally {
* cursor.close();
* }
*
* The {@link Iterable} interface is also extended by {@link EntityCursor}
* to allow using the cursor as the target of a Java "foreach" statement:
*
*
* {@code EntityCursor} cursor = primaryIndex.entities();
* try {
* for (Employee entity : cursor) {
* // Do something with the entity...
* }
* } finally {
* cursor.close();
* }
*
* The iterator uses the cursor directly, so any changes to the cursor
* position impact the iterator and vice versa. The iterator advances the
* cursor by calling {@link #next()} when {@link Iterator#hasNext} or {@link
* Iterator#next} is called. Because of this interaction, to keep things
* simple it is best not to mix the use of an {@code EntityCursor}
* {@code Iterator} with the use of the {@code EntityCursor} traversal methods
* such as {@link #next()}, for a single {@code EntityCursor} object.
*
* Key Ranges
*
* A key range may be specified when opening the cursor, to restrict the
* key range of the cursor to a subset of the complete range of keys in the
* index. A {@code fromKey} and/or {@code toKey} parameter may be specified
* when calling {@link EntityIndex#keys(Object,boolean,Object,boolean)} or
* {@link EntityIndex#entities(Object,boolean,Object,boolean)}. The key
* arguments may be specified as inclusive or exclusive values.
*
* Whenever a cursor with a key range is moved, the key range bounds will be
* checked, and the cursor will never be positioned outside the range. The
* {@link #first} cursor value is the first existing value in the range, and
* the {@link #last} cursor value is the last existing value in the range. For
* example, the following code traverses Employee entities with keys from 100
* (inclusive) to 200 (exclusive):
*
*
* {@code EntityCursor} cursor = primaryIndex.entities(100, true, 200, false);
* try {
* for (Employee entity : cursor) {
* // Do something with the entity...
* }
* } finally {
* cursor.close();
* }
*
* Duplicate Keys
*
* When using a cursor for a {@link SecondaryIndex}, the keys in the index
* may be non-unique (duplicates) if {@link SecondaryKey#relate} is {@link
* Relationship#MANY_TO_ONE MANY_TO_ONE} or {@link Relationship#MANY_TO_MANY
* MANY_TO_MANY}. For example, a {@code MANY_TO_ONE} {@code
* Employee.department} secondary key is non-unique because there are multiple
* Employee entities with the same department key value. The {@link #nextDup},
* {@link #prevDup}, {@link #nextNoDup} and {@link #prevNoDup} methods may be
* used to control how non-unique keys are returned by the cursor.
*
* {@link #nextDup} and {@link #prevDup} return the next or previous value
* only if it has the same key as the current value, and null is returned when
* a different key is encountered. For example, these methods can be used to
* return all employees in a given department.
*
* {@link #nextNoDup} and {@link #prevNoDup} return the next or previous
* value with a unique key, skipping over values that have the same key. For
* example, these methods can be used to return the first employee in each
* department.
*
* For example, the following code will find the first employee in each
* department with {@link #nextNoDup} until it finds a department name that
* matches a particular regular expression. For each matching department it
* will find all employees in that department using {@link #nextDup}.
*
*
* {@code SecondaryIndex} secondaryIndex =
* store.getSecondaryIndex(primaryIndex, String.class, "department");
*
* String regex = ...;
* {@code EntityCursor} cursor = secondaryIndex.entities();
* try {
* for (Employee entity = cursor.first();
* entity != null;
* entity = cursor.nextNoDup()) {
* if (entity.department.matches(regex)) {
* while (entity != null) {
* // Do something with the matching entities...
* entity = cursor.nextDup();
* }
* }
* }
* } finally {
* cursor.close();
* }
*
* Updating and Deleting Entities with a Cursor
*
* The {@link #update} and {@link #delete} methods operate on the entity at
* the current cursor position. Cursors on any type of index may be used to
* delete entities. For example, the following code deletes all employees in
* departments which have names that match a particular regular expression:
*
*
* {@code SecondaryIndex} secondaryIndex =
* store.getSecondaryIndex(primaryIndex, String.class, "department");
*
* String regex = ...;
* {@code EntityCursor} cursor = secondaryIndex.entities();
* try {
* for (Employee entity = cursor.first();
* entity != null;
* entity = cursor.nextNoDup()) {
* if (entity.department.matches(regex)) {
* while (entity != null) {
* cursor.delete();
* entity = cursor.nextDup();
* }
* }
* }
* } finally {
* cursor.close();
* }
*
* Note that the cursor can be moved to the next (or previous) value after
* deleting the entity at the current position. This is an important property
* of cursors, since without it you would not be able to easily delete while
* processing multiple values with a cursor. A cursor positioned on a deleted
* entity is in a special state. In this state, {@link #current} will return
* null, {@link #delete} will return false, and {@link #update} will return
* false.
*
* The {@link #update} method is supported only if the value type is an
* entity class (not a key class) and the underlying index is a {@link
* PrimaryIndex}; in other words, for a cursor returned by one of the {@link
* PrimaryIndex#entities} methods. For example, the following code changes all
* employee names to uppercase:
*
*
* {@code EntityCursor} cursor = primaryIndex.entities();
* try {
* for (Employee entity = cursor.first();
* entity != null;
* entity = cursor.next()) {
* entity.name = entity.name.toUpperCase();
* cursor.update(entity);
* }
* } finally {
* cursor.close();
* }
*
* @author Mark Hayes
*/
public interface EntityCursor extends ForwardCursor {
/**
* Moves the cursor to the first value and returns it, or returns null if
* the cursor range is empty.
*
* {@link LockMode#DEFAULT} is used implicitly.
*
* @return the first value, or null if the cursor range is empty.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V first()
throws DatabaseException;
/**
* Moves the cursor to the first value and returns it, or returns null if
* the cursor range is empty.
*
* @param lockMode the lock mode to use for this operation, or null to
* use {@link LockMode#DEFAULT}.
*
* @return the first value, or null if the cursor range is empty.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V first(LockMode lockMode)
throws DatabaseException;
/**
* Moves the cursor to the last value and returns it, or returns null if
* the cursor range is empty.
*
* {@link LockMode#DEFAULT} is used implicitly.
*
* @return the last value, or null if the cursor range is empty.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V last()
throws DatabaseException;
/**
* Moves the cursor to the last value and returns it, or returns null if
* the cursor range is empty.
*
* @param lockMode the lock mode to use for this operation, or null to
* use {@link LockMode#DEFAULT}.
*
* @return the last value, or null if the cursor range is empty.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V last(LockMode lockMode)
throws DatabaseException;
/**
* Moves the cursor to the next value and returns it, or returns null
* if there are no more values in the cursor range. If the cursor is
* uninitialized, this method is equivalent to {@link #first}.
*
* {@link LockMode#DEFAULT} is used implicitly.
*
* @return the next value, or null if there are no more values in the
* cursor range.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V next()
throws DatabaseException;
/**
* Moves the cursor to the next value and returns it, or returns null
* if there are no more values in the cursor range. If the cursor is
* uninitialized, this method is equivalent to {@link #first}.
*
* @param lockMode the lock mode to use for this operation, or null to
* use {@link LockMode#DEFAULT}.
*
* @return the next value, or null if there are no more values in the
* cursor range.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V next(LockMode lockMode)
throws DatabaseException;
/**
* Moves the cursor to the next value with the same key (duplicate) and
* returns it, or returns null if no more values are present for the key at
* the current position.
*
* {@link LockMode#DEFAULT} is used implicitly.
*
* @return the next value with the same key, or null if no more values are
* present for the key at the current position.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V nextDup()
throws DatabaseException;
/**
* Moves the cursor to the next value with the same key (duplicate) and
* returns it, or returns null if no more values are present for the key at
* the current position.
*
* @param lockMode the lock mode to use for this operation, or null to
* use {@link LockMode#DEFAULT}.
*
* @return the next value with the same key, or null if no more values are
* present for the key at the current position.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V nextDup(LockMode lockMode)
throws DatabaseException;
/**
* Moves the cursor to the next value with a different key and returns it,
* or returns null if there are no more unique keys in the cursor range.
* If the cursor is uninitialized, this method is equivalent to {@link
* #first}.
*
* {@link LockMode#DEFAULT} is used implicitly.
*
* @return the next value with a different key, or null if there are no
* more unique keys in the cursor range.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V nextNoDup()
throws DatabaseException;
/**
* Moves the cursor to the next value with a different key and returns it,
* or returns null if there are no more unique keys in the cursor range.
* If the cursor is uninitialized, this method is equivalent to {@link
* #first}.
*
* @param lockMode the lock mode to use for this operation, or null to
* use {@link LockMode#DEFAULT}.
*
* @return the next value with a different key, or null if there are no
* more unique keys in the cursor range.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V nextNoDup(LockMode lockMode)
throws DatabaseException;
/**
* Moves the cursor to the previous value and returns it, or returns null
* if there are no preceding values in the cursor range. If the cursor is
* uninitialized, this method is equivalent to {@link #last}.
*
* {@link LockMode#DEFAULT} is used implicitly.
*
* @return the previous value, or null if there are no preceding values in
* the cursor range.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V prev()
throws DatabaseException;
/**
* Moves the cursor to the previous value and returns it, or returns null
* if there are no preceding values in the cursor range. If the cursor is
* uninitialized, this method is equivalent to {@link #last}.
*
* @param lockMode the lock mode to use for this operation, or null to
* use {@link LockMode#DEFAULT}.
*
* @return the previous value, or null if there are no preceding values in
* the cursor range.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V prev(LockMode lockMode)
throws DatabaseException;
/**
* Moves the cursor to the previous value with the same key (duplicate) and
* returns it, or returns null if no preceding values are present for the
* key at the current position.
*
* {@link LockMode#DEFAULT} is used implicitly.
*
* @return the previous value with the same key, or null if no preceding
* values are present for the key at the current position.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V prevDup()
throws DatabaseException;
/**
* Moves the cursor to the previous value with the same key (duplicate) and
* returns it, or returns null if no preceding values are present for the
* key at the current position.
*
* @param lockMode the lock mode to use for this operation, or null to
* use {@link LockMode#DEFAULT}.
*
* @return the previous value with the same key, or null if no preceding
* values are present for the key at the current position.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V prevDup(LockMode lockMode)
throws DatabaseException;
/**
* Moves the cursor to the preceding value with a different key and returns
* it, or returns null if there are no preceding unique keys in the cursor
* range. If the cursor is uninitialized, this method is equivalent to
* {@link #last}.
*
* {@link LockMode#DEFAULT} is used implicitly.
*
* @return the previous value with a different key, or null if there are no
* preceding unique keys in the cursor range.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V prevNoDup()
throws DatabaseException;
/**
* Moves the cursor to the preceding value with a different key and returns
* it, or returns null if there are no preceding unique keys in the cursor
* range. If the cursor is uninitialized, this method is equivalent to
* {@link #last}.
*
* @param lockMode the lock mode to use for this operation, or null to
* use {@link LockMode#DEFAULT}.
*
* @return the previous value with a different key, or null if there are no
* preceding unique keys in the cursor range.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V prevNoDup(LockMode lockMode)
throws DatabaseException;
/**
* Returns the value at the cursor position, or null if the value at the
* cursor position has been deleted.
*
* {@link LockMode#DEFAULT} is used implicitly.
*
* @return the value at the cursor position, or null if it has been
* deleted.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V current()
throws DatabaseException;
/**
* Returns the value at the cursor position, or null if the value at the
* cursor position has been deleted.
*
* @param lockMode the lock mode to use for this operation, or null to
* use {@link LockMode#DEFAULT}.
*
* @return the value at the cursor position, or null if it has been
* deleted.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
V current(LockMode lockMode)
throws DatabaseException;
/* */
/**
* Moves the cursor according to the specified {@link Get} type and returns
* the value at the updated position.
*
* The following table lists each allowed operation. Also specified is
* whether the cursor must be initialized (positioned on a value) before
* calling this method. See the individual {@link Get} operations for more
* information.
*
*
*
* Get operation
* Description
* Cursor position
must be initialized?
*
*
* {@link Get#CURRENT}
* Accesses the current value.
* yes
*
*
* {@link Get#FIRST}
* Finds the first value in the cursor range.
* no
*
*
* {@link Get#LAST}
* Finds the last value in the cursor range.
* no
*
*
* {@link Get#NEXT}
* Moves to the next value.
* no**
*
*
* {@link Get#NEXT_DUP}
* Moves to the next value with the same key.
* yes
*
*
* {@link Get#NEXT_NO_DUP}
* Moves to the next value with a different key.
* no**
*
*
* {@link Get#PREV}
* Moves to the previous value.
* no**
*
*
* {@link Get#PREV_DUP}
* Moves to the previous value with the same key.
* yes
*
*
* {@link Get#PREV_NO_DUP}
* Moves to the previous value with a different key.
* no**
*
*
*
* ** - For these 'next' and 'previous' operations the cursor may be
* uninitialized, in which case the cursor will be moved to the first or
* last value in the cursor range, respectively.
*
* @param getType the Get operation type. Must be one of the values listed
* above.
*
* @param options the ReadOptions, or null to use default options.
*
* @return the EntityResult, including the value at the new cursor
* position, or null if the requested value is not present in the cursor
* range.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
* @throws DatabaseException the base class for all BDB exceptions.
*
* @since 7.0
*/
EntityResult get(Get getType, ReadOptions options)
throws DatabaseException;
/* */
/**
* Returns the number of values (duplicates) for the key at the cursor
* position, or returns zero if all values for the key have been deleted.
* Returns one or zero if the underlying index has unique keys.
*
*
* The cost of this method is directly proportional to the number of
* values.
*
*
* {@link LockMode#DEFAULT} is used implicitly.
*
* @return the number of duplicates, or zero if all values for the current
* key have been deleted.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
int count()
throws DatabaseException;
/* */
/**
* Returns a rough estimate of the number of values (duplicates) for the
* key at the cursor position, or returns zero if all values for the key
* have been deleted. Returns one or zero if the underlying index has
* unique keys.
*
* If the underlying index has non-unique keys, a quick estimate of the
* number of values is computed using information in the Btree. Because
* the Btree is unbalanced, in some cases the estimate may be off by a
* factor of two or more. The estimate is accurate when the number of
* records is less than the configured {@link
* DatabaseConfig#setNodeMaxEntries NodeMaxEntries}.
*
* The cost of this method is fixed, rather than being proportional to
* the number of values. Because its accuracy is variable, this method
* should normally be used when accuracy is not required, such as for query
* optimization, and a fixed cost operation is needed. For example, this
* method is used internally for determining the index processing order in
* an {@link EntityJoin}.
*
* @return an estimate of the count of the number of data items for the key
* to which the cursor refers.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
long countEstimate()
throws DatabaseException;
/* */
/* */
/* for FUTURE use
* Moves the cursor forward by a number of values and returns the number
* moved, or returns zero if there are no values following the cursor
* position.
*
* Without regard to performance, calling this method is equivalent to
* repeatedly calling {@link #next} with {@link LockMode#READ_UNCOMMITTED}
* to skip over the desired number of values, and then calling {@link
* #current} with {@link LockMode#DEFAULT} parameter to return the final
* value.
*
* With regard to performance, this method is optimized to skip over
* values using a smaller number of Btree operations. When there is no
* contention on the bottom internal nodes (BINs) and all BINs are in
* cache, the number of Btree operations is reduced by roughly two orders
* of magnitude, where the exact number depends on the {@link
* com.sleepycat.je.EnvironmentConfig#NODE_MAX_ENTRIES} setting. When
* there is contention on BINs or fetching BINs is required, the scan is
* broken up into smaller operations to avoid blocking other threads for
* long time periods.
*
* @param maxCount the maximum number of values to skip, i.e., the maximum
* number by which the cursor should be moved; must be greater than
* zero.
*
* @return the number of values skipped, i.e., the number by which the
* cursor has moved; if zero is returned, the cursor position is
* unchanged.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
* @throws DatabaseException the base class for all BDB exceptions.
long skipNext(long maxCount);
*/
/* */
/* */
/* for FUTURE use
* Moves the cursor forward by a number of values and returns the number
* moved, or returns zero if there are no values following the cursor
* position.
*
* Without regard to performance, calling this method is equivalent to
* repeatedly calling {@link #next} with {@link LockMode#READ_UNCOMMITTED}
* to skip over the desired number of values, and then calling {@link
* #current} with the {@code lockMode} parameter to return the final
* value.
*
* With regard to performance, this method is optimized to skip over
* values using a smaller number of Btree operations. When there is no
* contention on the bottom internal nodes (BINs) and all BINs are in
* cache, the number of Btree operations is reduced by roughly two orders
* of magnitude, where the exact number depends on the {@link
* com.sleepycat.je.EnvironmentConfig#NODE_MAX_ENTRIES} setting. When
* there is contention on BINs or fetching BINs is required, the scan is
* broken up into smaller operations to avoid blocking other threads for
* long time periods.
*
* @param maxCount the maximum number of values to skip, i.e., the maximum
* number by which the cursor should be moved; must be greater than
* zero.
*
* @param lockMode the lock mode to use for this operation, or null to
* use {@link LockMode#DEFAULT}.
*
* @return the number of values skipped, i.e., the number by which the
* cursor has moved; if zero is returned, the cursor position is
* unchanged.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
* @throws DatabaseException the base class for all BDB exceptions.
long skipNext(long maxCount, LockMode lockMode);
*/
/* */
/* */
/* for FUTURE use
* Moves the cursor backward by a number of values and returns the number
* moved, or returns zero if there are no values following the cursor
* position.
*
* Without regard to performance, calling this method is equivalent to
* repeatedly calling {@link #prev} with {@link LockMode#READ_UNCOMMITTED}
* to skip over the desired number of values, and then calling {@link
* #current} with {@link LockMode#DEFAULT} parameter to return the final
* value.
*
* With regard to performance, this method is optimized to skip over
* values using a smaller number of Btree operations. When there is no
* contention on the bottom internal nodes (BINs) and all BINs are in
* cache, the number of Btree operations is reduced by roughly two orders
* of magnitude, where the exact number depends on the {@link
* com.sleepycat.je.EnvironmentConfig#NODE_MAX_ENTRIES} setting. When
* there is contention on BINs or fetching BINs is required, the scan is
* broken up into smaller operations to avoid blocking other threads for
* long time periods.
*
* @param maxCount the maximum number of values to skip, i.e., the maximum
* number by which the cursor should be moved; must be greater than
* zero.
*
* @return the number of values skipped, i.e., the number by which the
* cursor has moved; if zero is returned, the cursor position is
* unchanged.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
* @throws DatabaseException the base class for all BDB exceptions.
long skipPrev(long maxCount);
*/
/* */
/* */
/* for FUTURE use
* Moves the cursor backward by a number of values and returns the number
* moved, or returns zero if there are no values following the cursor
* position.
*
* Without regard to performance, calling this method is equivalent to
* repeatedly calling {@link #prev} with {@link LockMode#READ_UNCOMMITTED}
* to skip over the desired number of values, and then calling {@link
* #current} with the {@code lockMode} parameter to return the final
* value.
*
* With regard to performance, this method is optimized to skip over
* values using a smaller number of Btree operations. When there is no
* contention on the bottom internal nodes (BINs) and all BINs are in
* cache, the number of Btree operations is reduced by roughly two orders
* of magnitude, where the exact number depends on the {@link
* com.sleepycat.je.EnvironmentConfig#NODE_MAX_ENTRIES} setting. When
* there is contention on BINs or fetching BINs is required, the scan is
* broken up into smaller operations to avoid blocking other threads for
* long time periods.
*
* @param maxCount the maximum number of values to skip, i.e., the maximum
* number by which the cursor should be moved; must be greater than
* zero.
*
* @param lockMode the lock mode to use for this operation, or null to
* use {@link LockMode#DEFAULT}.
*
* @return the number of values skipped, i.e., the number by which the
* cursor has moved; if zero is returned, the cursor position is
* unchanged.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
* @throws OperationFailureException if one of the Read Operation
* Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
* @throws DatabaseException the base class for all BDB exceptions.
long skipPrev(long maxCount, LockMode lockMode);
*/
/* */
/**
* Returns an iterator over the key range, starting with the value
* following the current position or at the first value if the cursor is
* uninitialized.
*
* {@link LockMode#DEFAULT} is used implicitly.
*
* @return the iterator.
*/
Iterator iterator();
/**
* Returns an iterator over the key range, starting with the value
* following the current position or at the first value if the cursor is
* uninitialized.
*
* @param lockMode the lock mode to use for all operations performed
* using the iterator, or null to use {@link LockMode#DEFAULT}.
*
* @return the iterator.
*/
Iterator iterator(LockMode lockMode);
/**
* Replaces the entity at the cursor position with the given entity.
*
* @param entity the entity to replace the entity at the current position.
*
* @return true if successful or false if the entity at the current
* position was previously deleted.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
* @throws UnsupportedOperationException if the index is read only or if
* the value type is not an entity type.
*
*
* @throws DuplicateDataException if the old and new data are not equal
* according to the configured duplicate comparator or default comparator.
*
* @throws OperationFailureException if one of the Write
* Operation Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
boolean update(V entity)
throws DatabaseException;
/* */
/**
* Replaces the entity at the cursor position with the given entity,
* using a WriteOptions parameter and returning an OperationResult.
*
* @param entity the entity to replace the entity at the current position.
*
* @param options the WriteOptions, or null to use default options.
*
* @return the OperationResult if successful or null if the entity at the
* current position was previously deleted.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
* @throws UnsupportedOperationException if the index is read only or if
* the value type is not an entity type.
*
* @throws DuplicateDataException if the old and new data are not equal
* according to the configured duplicate comparator or default comparator.
*
* @throws OperationFailureException if one of the Write
* Operation Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
* @throws DatabaseException the base class for all BDB exceptions.
*
* @since 7.0
*/
OperationResult update(V entity, WriteOptions options)
throws DatabaseException;
/* */
/**
* Deletes the entity at the cursor position.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
* @throws UnsupportedOperationException if the index is read only.
*
* @return true if successful or false if the entity at the current
* position has been deleted.
*
*
* @throws OperationFailureException if one of the Write
* Operation Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
boolean delete()
throws DatabaseException;
/* */
/**
* Deletes the entity at the cursor position, using a WriteOptions
* parameter and returning an OperationResult.
*
* @throws IllegalStateException if the cursor is uninitialized.
*
* @throws UnsupportedOperationException if the index is read only.
*
* @return the OperationResult if successful or null if the entity at the
* current position was previously deleted.
*
* @throws OperationFailureException if one of the Write
* Operation Failures occurs.
*
* @throws EnvironmentFailureException if an unexpected, internal or
* environment-wide failure occurs.
*
* @throws DatabaseException the base class for all BDB exceptions.
*
* @since 7.0
*/
OperationResult delete(WriteOptions options)
throws DatabaseException;
/* */
/**
* Duplicates the cursor at the cursor position. The returned cursor will
* be initially positioned at the same position as this current cursor, and
* will inherit this cursor's {@link Transaction} and {@link CursorConfig}.
*
* @return the duplicated cursor.
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
EntityCursor dup()
throws DatabaseException;
/**
* Closes the cursor.
*
* @throws DatabaseException the base class for all BDB exceptions.
*/
void close()
throws DatabaseException;
/* */
/**
* Changes the {@code CacheMode} default used for subsequent operations
* performed using this cursor. For a newly opened cursor, the default is
* {@link CacheMode#DEFAULT}. Note that the default is always overridden by
* a non-null cache mode that is specified via {@link ReadOptions} or
* {@link WriteOptions}.
*
* @param cacheMode is the default {@code CacheMode} used for subsequent
* operations using this cursor, or null to configure the Database or
* Environment default.
*
* @see CacheMode
*/
void setCacheMode(CacheMode cacheMode);
/* */
/* */
/**
* Returns the default {@code CacheMode} used for subsequent operations
* performed using this cursor. If {@link #setCacheMode} has not been
* called with a non-null value, the configured Database or Environment
* default is returned.
*
* @return the {@code CacheMode} default used for subsequent operations
* using this cursor.
*
* @see CacheMode
*/
CacheMode getCacheMode();
/* */
}