com.sleepycat.persist

Interface EntityCursor<V>

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, ForwardCursor<V>, java.lang.Iterable<V>

public interface EntityCursor<V>
extends ForwardCursor<V>

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.

EntityCursor objects are not thread-safe. Cursors should be opened, used and closed by a single thread.

Cursors are opened using the EntityIndex.keys() and EntityIndex.entities() family of methods. These methods are available for objects of any class that implements EntityIndex: PrimaryIndex, SecondaryIndex, and the indices returned by SecondaryIndex.keysIndex and SecondaryIndex.subIndex(SK). A ForwardCursor, which implements a subset of cursor operations, is also available via the EntityJoin.keys() and EntityJoin.entities() methods.

Values are always returned by a cursor in key order, where the key is defined by the underlying EntityIndex. For example, a cursor on a SecondaryIndex returns values ordered by secondary key, while an index on a PrimaryIndex or a SecondaryIndex.subIndex(SK) 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 close() in a finally block. For example, the following code traverses all Employee entities and closes the cursor whether or not an exception occurs:

 @Entity
 class Employee {

     @PrimaryKey
     long id;

     @SecondaryKey(relate=MANY_TO_ONE)
     String department;

     String name;

     private Employee() {}
 }

 EntityStore store = ...

 PrimaryIndex<Long, Employee> primaryIndex =
     store.getPrimaryIndex(Long.class, Employee.class);

 EntityCursor<Employee> 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, current() and delete(), throw IllegalStateException when called for an uninitialized cursor.

Note that the next() and 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:

 EntityCursor<Employee> cursor = primaryIndex.entities();
 try {
     Employee entity;
     while ((entity = cursor.next()) != null) {
         // Do something with the entity...
     }
 } finally {
     cursor.close();
 }

Cursors and Iterators

The iterator() method can be used to return a standard Java Iterator that returns the same values that the cursor returns. For example:

 EntityCursor<Employee> cursor = primaryIndex.entities();
 try {
     Iterator<Employee> i = cursor.iterator();
     while (i.hasNext()) {
          Employee entity = i.next();
         // Do something with the entity...
     }
 } finally {
     cursor.close();
 }

The Iterable interface is also extended by EntityCursor to allow using the cursor as the target of a Java "foreach" statement:

 EntityCursor<Employee> 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 next() when Iterator.hasNext() or Iterator.next() is called. Because of this interaction, to keep things simple it is best not to mix the use of an EntityCursor Iterator with the use of the EntityCursor traversal methods such as next(), for a single 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 fromKey and/or toKey parameter may be specified when calling EntityIndex.keys(Object,boolean,Object,boolean) or 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 first() cursor value is the first existing value in the range, and the 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):

 EntityCursor<Employee> 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 SecondaryIndex, the keys in the index may be non-unique (duplicates) if SecondaryKey.relate() is MANY_TO_ONE or MANY_TO_MANY. For example, a MANY_TO_ONE Employee.department secondary key is non-unique because there are multiple Employee entities with the same department key value. The nextDup(), prevDup(), nextNoDup() and prevNoDup() methods may be used to control how non-unique keys are returned by the cursor.

nextDup() and 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.

nextNoDup() and 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 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 nextDup().

 SecondaryIndex<String, Long, Employee> secondaryIndex =
     store.getSecondaryIndex(primaryIndex, String.class, "department");

 String regex = ...;
 EntityCursor<Employee> 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 update(V) and 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:

 SecondaryIndex<String, Long, Employee> secondaryIndex =
     store.getSecondaryIndex(primaryIndex, String.class, "department");

 String regex = ...;
 EntityCursor<Employee> 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, current() will return null, delete() will return false, and update(V) will return false.

The update(V) method is supported only if the value type is an entity class (not a key class) and the underlying index is a PrimaryIndex; in other words, for a cursor returned by one of the BasicIndex.entities() methods. For example, the following code changes all employee names to uppercase:

 EntityCursor<Employee> 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

Method Summary

Modifier and Type	Method and Description
void	close() Closes the cursor.
int	count() 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.
long	countEstimate() 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.
V	current() Returns the value at the cursor position, or null if the value at the cursor position has been deleted.
V	current(LockMode lockMode) Returns the value at the cursor position, or null if the value at the cursor position has been deleted.
boolean	delete() Deletes the entity at the cursor position.
OperationResult	delete(WriteOptions options) Deletes the entity at the cursor position, using a WriteOptions parameter and returning an OperationResult.
EntityCursor<V>	dup() Duplicates the cursor at the cursor position.
V	first() Moves the cursor to the first value and returns it, or returns null if the cursor range is empty.
V	first(LockMode lockMode) Moves the cursor to the first value and returns it, or returns null if the cursor range is empty.
EntityResult<V>	get(Get getType, ReadOptions options) Moves the cursor according to the specified Get type and returns the value at the updated position.
CacheMode	getCacheMode() Returns the default CacheMode used for subsequent operations performed using this cursor.
java.util.Iterator<V>	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.
java.util.Iterator<V>	iterator(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.
V	last() Moves the cursor to the last value and returns it, or returns null if the cursor range is empty.
V	last(LockMode lockMode) Moves the cursor to the last value and returns it, or returns null if the cursor range is empty.
V	next() Moves the cursor to the next value and returns it, or returns null if there are no more values in the cursor range.
V	next(LockMode lockMode) Moves the cursor to the next value and returns it, or returns null if there are no more values in the cursor range.
V	nextDup() 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.
V	nextDup(LockMode lockMode) 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.
V	nextNoDup() 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.
V	nextNoDup(LockMode lockMode) 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.
V	prev() Moves the cursor to the previous value and returns it, or returns null if there are no preceding values in the cursor range.
V	prev(LockMode lockMode) Moves the cursor to the previous value and returns it, or returns null if there are no preceding values in the cursor range.
V	prevDup() 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.
V	prevDup(LockMode lockMode) 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.
V	prevNoDup() 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.
V	prevNoDup(LockMode lockMode) 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.
void	setCacheMode(CacheMode cacheMode) Changes the CacheMode default used for subsequent operations performed using this cursor.
boolean	update(V entity) Replaces the entity at the cursor position with the given entity.
OperationResult	update(V entity, WriteOptions options) Replaces the entity at the cursor position with the given entity, using a WriteOptions parameter and returning an OperationResult.

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

first

V first()
 throws DatabaseException

Moves the cursor to the first value and returns it, or returns null if the cursor range is empty.

LockMode.DEFAULT is used implicitly.

Returns:

the first value, or null if the cursor range is empty.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

first

V first(LockMode lockMode)
 throws DatabaseException

Moves the cursor to the first value and returns it, or returns null if the cursor range is empty.

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

the first value, or null if the cursor range is empty.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

last

V last()
throws DatabaseException

Moves the cursor to the last value and returns it, or returns null if the cursor range is empty.

LockMode.DEFAULT is used implicitly.

Returns:

the last value, or null if the cursor range is empty.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

last

V last(LockMode lockMode)
throws DatabaseException

Moves the cursor to the last value and returns it, or returns null if the cursor range is empty.

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

the last value, or null if the cursor range is empty.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

next

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 first().

LockMode.DEFAULT is used implicitly.

Specified by:

next in interface ForwardCursor<V>

Returns:

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.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

next

V next(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 first().

Specified by:

next in interface ForwardCursor<V>

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

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.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

nextDup

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.

LockMode.DEFAULT is used implicitly.

Returns:

the next value with the same key, or null if no more values are present for the key at the current position.

Throws:

java.lang.IllegalStateException - if the cursor is uninitialized.

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

nextDup

V nextDup(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.

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

the next value with the same key, or null if no more values are present for the key at the current position.

Throws:

java.lang.IllegalStateException - if the cursor is uninitialized.

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

nextNoDup

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 first().

LockMode.DEFAULT is used implicitly.

Returns:

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.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

nextNoDup

V nextNoDup(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 first().

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

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.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

prev

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 last().

LockMode.DEFAULT is used implicitly.

Returns:

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.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

prev

V prev(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 last().

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

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.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

prevDup

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.

LockMode.DEFAULT is used implicitly.

Returns:

the previous value with the same key, or null if no preceding values are present for the key at the current position.

Throws:

java.lang.IllegalStateException - if the cursor is uninitialized.

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

prevDup

V prevDup(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.

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

the previous value with the same key, or null if no preceding values are present for the key at the current position.

Throws:

java.lang.IllegalStateException - if the cursor is uninitialized.

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

prevNoDup

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 last().

LockMode.DEFAULT is used implicitly.

Returns:

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.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

prevNoDup

V prevNoDup(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 last().

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

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.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

current

V current()
   throws DatabaseException

Returns the value at the cursor position, or null if the value at the cursor position has been deleted.

LockMode.DEFAULT is used implicitly.

Returns:

the value at the cursor position, or null if it has been deleted.

Throws:

java.lang.IllegalStateException - if the cursor is uninitialized.

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

current

V current(LockMode lockMode)
   throws DatabaseException

Returns the value at the cursor position, or null if the value at the cursor position has been deleted.

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

the value at the cursor position, or null if it has been deleted.

Throws:

java.lang.IllegalStateException - if the cursor is uninitialized.

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

get

EntityResult<V> get(Get getType,
                    ReadOptions options)
             throws DatabaseException

Moves the cursor according to the specified 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 Get operations for more information.

Get operation	Description	Cursor position must be initialized?
Get.CURRENT	Accesses the current value.	yes
Get.FIRST	Finds the first value in the cursor range.	no
Get.LAST	Finds the last value in the cursor range.	no
Get.NEXT	Moves to the next value.	no**
Get.NEXT_DUP	Moves to the next value with the same key.	yes
Get.NEXT_NO_DUP	Moves to the next value with a different key.	no**
Get.PREV	Moves to the previous value.	no**
Get.PREV_DUP	Moves to the previous value with the same key.	yes
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.

Parameters:

getType - the Get operation type. Must be one of the values listed above.

options - the ReadOptions, or null to use default options.

Returns:

the EntityResult, including the value at the new cursor position, or null if the requested value is not present in the cursor range.

Throws:

java.lang.IllegalStateException - if the cursor is uninitialized.

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

Since:

7.0

count

int count()
   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.

LockMode.DEFAULT is used implicitly.

Returns:

the number of duplicates, or zero if all values for the current key have been deleted.

Throws:

java.lang.IllegalStateException - if the cursor is uninitialized.

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

countEstimate

long countEstimate()
            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 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 EntityJoin.

Returns:

an estimate of the count of the number of data items for the key to which the cursor refers.

Throws:

java.lang.IllegalStateException - if the cursor is uninitialized.

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

iterator

java.util.Iterator<V> 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.

LockMode.DEFAULT is used implicitly.

Specified by:

iterator in interface ForwardCursor<V>

Specified by:

iterator in interface java.lang.Iterable<V>

Returns:

the iterator.

iterator

java.util.Iterator<V> iterator(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.

Specified by:

iterator in interface ForwardCursor<V>

Parameters:

lockMode - the lock mode to use for all operations performed using the iterator, or null to use LockMode.DEFAULT.

Returns:

the iterator.

update

boolean update(V entity)
        throws DatabaseException

Replaces the entity at the cursor position with the given entity.

Parameters:

entity - the entity to replace the entity at the current position.

Returns:

true if successful or false if the entity at the current position was previously deleted.

Throws:

java.lang.IllegalStateException - if the cursor is uninitialized.

java.lang.UnsupportedOperationException - if the index is read only or if the value type is not an entity type.

DuplicateDataException - if the old and new data are not equal according to the configured duplicate comparator or default comparator.

OperationFailureException - if one of the Write Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

update

OperationResult update(V entity,
                       WriteOptions options)
                throws DatabaseException

Replaces the entity at the cursor position with the given entity, using a WriteOptions parameter and returning an OperationResult.

Parameters:

entity - the entity to replace the entity at the current position.

options - the WriteOptions, or null to use default options.

Returns:

the OperationResult if successful or null if the entity at the current position was previously deleted.

Throws:

java.lang.IllegalStateException - if the cursor is uninitialized.

java.lang.UnsupportedOperationException - if the index is read only or if the value type is not an entity type.

DuplicateDataException - if the old and new data are not equal according to the configured duplicate comparator or default comparator.

OperationFailureException - if one of the Write Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

Since:

7.0

delete

boolean delete()
        throws DatabaseException

Deletes the entity at the cursor position.

Returns:

true if successful or false if the entity at the current position has been deleted.

Throws:

java.lang.IllegalStateException - if the cursor is uninitialized.

java.lang.UnsupportedOperationException - if the index is read only.

OperationFailureException - if one of the Write Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

delete

OperationResult delete(WriteOptions options)
                throws DatabaseException

Deletes the entity at the cursor position, using a WriteOptions parameter and returning an OperationResult.

Returns:

the OperationResult if successful or null if the entity at the current position was previously deleted.

Throws:

java.lang.IllegalStateException - if the cursor is uninitialized.

java.lang.UnsupportedOperationException - if the index is read only.

OperationFailureException - if one of the Write Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

Since:

7.0

dup

EntityCursor<V> dup()
             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 Transaction and CursorConfig.

Returns:

the duplicated cursor.

Throws:

DatabaseException - the base class for all BDB exceptions.

close

void close()
    throws DatabaseException

Closes the cursor.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface ForwardCursor<V>

Throws:

DatabaseException - the base class for all BDB exceptions.

setCacheMode

void setCacheMode(CacheMode cacheMode)

Changes the CacheMode default used for subsequent operations performed using this cursor. For a newly opened cursor, the default is CacheMode.DEFAULT. Note that the default is always overridden by a non-null cache mode that is specified via ReadOptions or WriteOptions.

Parameters:

cacheMode - is the default CacheMode used for subsequent operations using this cursor, or null to configure the Database or Environment default.

See Also:

CacheMode

getCacheMode

CacheMode getCacheMode()

Returns the default CacheMode used for subsequent operations performed using this cursor. If setCacheMode(com.sleepycat.je.CacheMode) has not been called with a non-null value, the configured Database or Environment default is returned.

Returns:

the CacheMode default used for subsequent operations using this cursor.

See Also:

CacheMode