com.sleepycat.persist
Interface EntityCursor<V>

All Superinterfaces:

ForwardCursor<V>, 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();
 }

Method Summary

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, Returns one or zero if the underlying index has unique keys.
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.
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.
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.
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.
boolean	update(V entity) Replaces the entity at the cursor position with the given entity.

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:

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:

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:

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:

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:

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:

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:

IllegalStateException - if the cursor is uninitialized.

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:

IllegalStateException - if the cursor is uninitialized.

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:

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:

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:

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:

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:

IllegalStateException - if the cursor is uninitialized.

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:

IllegalStateException - if the cursor is uninitialized.

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:

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:

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:

IllegalStateException - if the cursor is uninitialized.

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:

IllegalStateException - if the cursor is uninitialized.

DatabaseException - the base class for all BDB exceptions.

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.

LockMode.DEFAULT is used implicitly.

Returns:

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

Throws:

IllegalStateException - if the cursor is uninitialized.

DatabaseException - the base class for all BDB exceptions.

iterator

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 Iterable<V>

Returns:

the iterator.

iterator

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:

IllegalStateException - if the cursor is uninitialized.

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

DatabaseException - the base class for all BDB exceptions.

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:

IllegalStateException - if the cursor is uninitialized.

UnsupportedOperationException - if the index is read only.

DatabaseException - the base class for all BDB exceptions.

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 ForwardCursor<V>

Throws:

DatabaseException - the base class for all BDB exceptions.