EntityCursor (Oracle - Berkeley DB Java API)
Date: 2017-04-13

com.sleepycat.persist

## Interface EntityCursor<V>

- All Superinterfaces:
    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();
       }

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    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.
    `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.
    `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.
    `boolean` | `update(V entity)` Replaces the entity at the cursor position with the given entity.

    - ### 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:
        `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:
        `java.lang.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:
        `java.lang.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:
        `java.lang.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:
        `java.lang.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:
        `java.lang.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:
        `java.lang.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:
        `java.lang.IllegalStateException` - if the cursor is uninitialized.
        `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.
        `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:
        `java.lang.IllegalStateException` - if the cursor is uninitialized.
        `java.lang.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.

Copyright (c) 1996, 2017 Oracle and/or its affiliates. All rights reserved.