Cursor (Oracle - Berkeley DB Java Edition API)
Date: 2014-12-16

com.sleepycat.je

## Class Cursor

- java.lang.Object
- - com.sleepycat.je.Cursor

- All Implemented Interfaces:
    ForwardCursor, Closeable, AutoCloseable
  Direct Known Subclasses:
    SecondaryCursor

      public class Cursor
      extends Object
      implements ForwardCursor

  A database cursor. Cursors are used for operating on collections of records, for iterating over a database, and for saving handles to individual records, so that they can be modified after they have been read.

  Cursors which are opened with a transaction instance are transactional cursors and may be used by multiple threads, but only serially. That is, the application must serialize access to the handle. Non-transactional cursors, opened with a null transaction instance, may not be used by multiple threads.

  If the cursor is to be used to perform operations on behalf of a transaction, the cursor must be opened and closed within the context of that single transaction.

  Once the cursor `close()` method has been called, the handle may not be accessed again, regardless of the `close` method's success or failure, with one exception: the `close` method itself may be called any number of times to simplify error handling.

  To obtain a cursor with default attributes:

  >          Cursor cursor = myDatabase.openCursor(txn, null);

  To customize the attributes of a cursor, use a CursorConfig object.

  >          CursorConfig config = new CursorConfig();
  >          config.setReadUncommitted(true);
  >          Cursor cursor = myDatabase.openCursor(txn, config);

  Modifications to the database during a sequential scan will be reflected in the scan; that is, records inserted behind a cursor will not be returned while records inserted in front of a cursor will be returned.

  By default, a cursor is "sticky", meaning that the prior position is maintained by cursor movement operations, and the cursor stays at the prior position when `NOTFOUND` is returned or an exception is thrown. However, it is possible to configure a cursor as non-sticky to enable certain performance benefits. See `CursorConfig.setNonSticky(boolean)` for details.

  ### Using Partial DatabaseEntry Parameters

  The `DatabaseEntry Partial` property can be used to optimize in certain cases. This provides varying degrees of performance benefits that depend on the specific operation and use of `READ_UNCOMMITTED` isolation, as described below.

  When retrieving a record with a `Database` or `Cursor` method, if only the key is needed by the application then the retrieval of the data item can be suppressed using the Partial property. If `setPartial(0, 0, true)` is called for the `DatabaseEntry` passed as the data parameter, the data item will not be returned by the `Database` or `Cursor` method.

  Suppressing the return of the data item potentially has a large performance benefit. In this case, if the record data is not in the JE cache, it will not be read from disk. The performance benefit is potentially large because random access disk reads may be reduced. Examples use cases are:

  - Scanning all records in key order, when the data is not needed.
  - Skipping over records quickly with `READ_UNCOMMITTED` isolation to select records for further processing by examining the key value.

  Note that by "record data" we mean both the `data` parameter for a regular or primary DB, and the `pKey` parameter for a secondary DB. Also note that the performance advantage of a key-only operation does not apply to databases configured for duplicates. For a duplicates DB, the data is always available along with the key and does not have to be fetched separately.

  For information on specifying isolation modes, see `LockMode`, `CursorConfig` and `TransactionConfig`.

  The Partial property may also be used to retrieve or update only a portion of a data item. This avoids copying the entire record between the JE cache and the application data parameter. However, this feature is not currently fully optimized, since the entire record is always read or written to the database, and the entire record is cached. A partial update may be performed only with `Cursor.putCurrent`.

  In limited cases, the Partial property may also be used to retrieve a partial key item. For example, a `DatabaseEntry` with a Partial property may be passed to `getNext`. However, in practice this has limited value since the entire key is usually needed by the application, and the benefit of copying a portion of the key is generally very small. Partial key items may not be passed to methods that use the key as an input parameter, for example, `getSearchKey`. In general, the usefulness of partial key items is very limited.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Discards the cursor.
    `int` | `count()` Returns a count of the number of data items for the key to which the cursor refers.
    `long` | `countEstimate()` Returns a rough estimate of the count of the number of data items for the key to which the cursor refers.
    `OperationStatus` | `delete()` Deletes the key/data pair to which the cursor refers.
    `Cursor` | `dup(boolean samePosition)` Returns a new cursor with the same transaction and locker ID as the original cursor.
    `CacheMode` | `getCacheMode()` Returns the `CacheMode` used for subsequent operations performed using this cursor.
    `CursorConfig` | `getConfig()` Returns this cursor's configuration.
    `OperationStatus` | `getCurrent(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` Returns the key/data pair to which the cursor refers.
    `Database` | `getDatabase()` Returns the Database handle associated with this Cursor.
    `OperationStatus` | `getFirst(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` Moves the cursor to the first key/data pair of the database, and returns that pair.
    `OperationStatus` | `getLast(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` Moves the cursor to the last key/data pair of the database, and returns that pair.
    `OperationStatus` | `getNext(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` Moves the cursor to the next key/data pair and returns that pair.
    `OperationStatus` | `getNextDup(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` If the next key/data pair of the database is a duplicate data record for the current key/data pair, moves the cursor to the next key/data pair of the database and returns that pair.
    `OperationStatus` | `getNextNoDup(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` Moves the cursor to the next non-duplicate key/data pair and returns that pair.
    `OperationStatus` | `getPrev(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` Moves the cursor to the previous key/data pair and returns that pair.
    `OperationStatus` | `getPrevDup(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` If the previous key/data pair of the database is a duplicate data record for the current key/data pair, moves the cursor to the previous key/data pair of the database and returns that pair.
    `OperationStatus` | `getPrevNoDup(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` Moves the cursor to the previous non-duplicate key/data pair and returns that pair.
    `OperationStatus` | `getSearchBoth(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` Moves the cursor to the specified key/data pair, where both the key and data items must match.
    `OperationStatus` | `getSearchBothRange(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` Moves the cursor to the specified key and closest matching data item of the database.
    `OperationStatus` | `getSearchKey(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` Moves the cursor to the given key of the database, and returns the datum associated with the given key.
    `OperationStatus` | `getSearchKeyRange(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` Moves the cursor to the closest matching key of the database, and returns the data item associated with the matching key.
    `OperationStatus` | `put(DatabaseEntry key, DatabaseEntry data)` Stores a key/data pair into the database.
    `OperationStatus` | `putCurrent(DatabaseEntry data)` Replaces the data in the key/data pair at the current cursor position.
    `OperationStatus` | `putNoDupData(DatabaseEntry key, DatabaseEntry data)` Stores a key/data pair into the database.
    `OperationStatus` | `putNoOverwrite(DatabaseEntry key, DatabaseEntry data)` Stores a key/data pair into the database.
    `void` | `setCacheMode(CacheMode cacheMode)` Sets the `CacheMode` used for subsequent operations performed using this cursor.
    `long` | `skipNext(long maxCount, DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` Skips forward a given number of key/data pairs and returns the number by which the cursor is moved.
    `long` | `skipPrev(long maxCount, DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` Skips backward a given number of key/data pairs and returns the number by which the cursor is moved.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### getDatabase

          public Database getDatabase()

      Returns the Database handle associated with this Cursor.
      Specified by:
        `getDatabase` in interface `ForwardCursor`
      Returns:
        The Database handle associated with this Cursor.

    - #### getConfig

          public CursorConfig getConfig()

      Returns this cursor's configuration.

      This may differ from the configuration used to open this object if the cursor existed previously.

      Returns:
        This cursor's configuration.

    - #### getCacheMode

          public CacheMode getCacheMode()

      Returns the `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` used for subsequent operations using this cursor.
      See Also:
        `setCacheMode(com.sleepycat.je.CacheMode)`

    - #### setCacheMode

          public void setCacheMode(CacheMode cacheMode)

      Sets the `CacheMode` used for subsequent operations performed using this cursor. This method may be used to override the defaults specified using `DatabaseConfig.setCacheMode(com.sleepycat.je.CacheMode)` and `EnvironmentMutableConfig.setCacheMode(com.sleepycat.je.CacheMode)`.
      Parameters:
        `cacheMode` - is the `CacheMode` used for subsequent operations using this cursor, or null to configure the Database or Environment default.
      See Also:
        `for further details.`

    - #### close

          public void close()
                     throws DatabaseException

      Discards the cursor.

      The cursor handle may not be used again after this method has been called, regardless of the method's success or failure, with one exception: the `close` method itself may be called any number of times.

      WARNING: To guard against memory leaks, the application should discard all references to the closed handle. While BDB makes an effort to discard references from closed objects to the allocated memory for an environment, this behavior is not guaranteed. The safe course of action for an application is to discard all references to closed BDB objects.

      Specified by:
        `close` in interface `ForwardCursor`
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Throws:
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `DatabaseException`

    - #### dup

          public Cursor dup(boolean samePosition)
                     throws DatabaseException

      Returns a new cursor with the same transaction and locker ID as the original cursor.

      This is useful when an application is using locking and requires two or more cursors in the same thread of control.

      Parameters:
        `samePosition` - If true, the newly created cursor is initialized to refer to the same position in the database as the original cursor (if any) and hold the same locks (if any). If false, or the original cursor does not hold a database position and locks, the returned cursor is uninitialized and will behave like a newly created cursor.
      Returns:
        A new cursor with the same transaction and locker ID as the original cursor.
      Throws:
        `DatabasePreemptedException` - in a replicated environment if the master has truncated, removed or renamed the database.
        `OperationFailureException` - if this exception occurred earlier and caused the transaction to be invalidated.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed.
        `DatabaseException`

    - #### delete

          public OperationStatus delete()
                                 throws LockConflictException,
                                        DatabaseException,
                                        UnsupportedOperationException

      Deletes the key/data pair to which the cursor refers.

      When called on a cursor opened on a database that has been made into a secondary index, this method the key/data pair from the primary database and all secondary indices.

      The cursor position is unchanged after a delete, and subsequent calls to cursor functions expecting the cursor to refer to an existing key will fail.

      Returns:
        `OperationStatus.KEYEMPTY` if the key/pair at the cursor position has been deleted; otherwise, `OperationStatus.SUCCESS`.
      Throws:
        `OperationFailureException` - if one of the Write Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `UnsupportedOperationException` - if the database is transactional but this cursor was not opened with a non-null transaction parameter, or the database is read-only.
        `IllegalStateException` - if the cursor or database has been closed, or the cursor is uninitialized (not positioned on a record), or the non-transactional cursor was created in a different thread.
        `LockConflictException`
        `DatabaseException`

    - #### put

          public OperationStatus put(DatabaseEntry key,
                            DatabaseEntry data)
                              throws DatabaseException,
                                     UnsupportedOperationException

      Stores a key/data pair into the database.

      If the put method succeeds, the cursor is always positioned to refer to the newly inserted item.

      If the key already appears in the database and duplicates are supported, the new data value is inserted at the correct sorted location, unless the new data value also appears in the database already. In the later case, although the given key/data pair compares equal to an existing key/data pair, the two records may not be identical if custom comparators are used, in which case the existing record will be replaced with the new record. If the key already appears in the database and duplicates are not supported, the data associated with the key will be replaced.

      Parameters:
        `key` - the key `DatabaseEntry` operated on.
        `data` - the data `DatabaseEntry` stored.
      Returns:
        an OperationStatus for the operation.
      Throws:
        `OperationFailureException` - if one of the Write Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `UnsupportedOperationException` - if the database is transactional but this cursor was not opened with a non-null transaction parameter, or the database is read-only.
        `IllegalStateException` - if the cursor or database has been closed, or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### putNoOverwrite

          public OperationStatus putNoOverwrite(DatabaseEntry key,
                                       DatabaseEntry data)
                                         throws DatabaseException,
                                                UnsupportedOperationException

      Stores a key/data pair into the database.

      If the putNoOverwrite method succeeds, the cursor is always positioned to refer to the newly inserted item.

      If the key already appears in the database, putNoOverwrite will return `OperationStatus.KEYEXIST`.

      Parameters:
        `key` - the key `DatabaseEntry` operated on.
        `data` - the data `DatabaseEntry` stored.
      Returns:
        an OperationStatus for the operation.
      Throws:
        `OperationFailureException` - if one of the Write Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `UnsupportedOperationException` - if the database is transactional but this cursor was not opened with a non-null transaction parameter, or the database is read-only.
        `IllegalStateException` - if the cursor or database has been closed, or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### putNoDupData

          public OperationStatus putNoDupData(DatabaseEntry key,
                                     DatabaseEntry data)
                                       throws DatabaseException,
                                              UnsupportedOperationException

      Stores a key/data pair into the database. The database must be configured for duplicates.

      If the putNoDupData method succeeds, the cursor is always positioned to refer to the newly inserted item.

      Insert the specified key/data pair into the database, unless a key/data pair comparing equally to it already exists in the database. If a matching key/data pair already exists in the database, `OperationStatus.KEYEXIST` is returned.

      Parameters:
        `key` - the key `DatabaseEntry` operated on.
        `data` - the data `DatabaseEntry` stored.
      Returns:
        an OperationStatus for the operation.
      Throws:
        `OperationFailureException` - if one of the Write Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `UnsupportedOperationException` - if the database is transactional but this cursor was not opened with a non-null transaction parameter, or the database is read-only, or the database is not configured for duplicates.
        `IllegalStateException` - if the cursor or database has been closed, or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### putCurrent

          public OperationStatus putCurrent(DatabaseEntry data)
                                     throws DatabaseException,
                                            UnsupportedOperationException

      Replaces the data in the key/data pair at the current cursor position.

      Overwrite the data of the key/data pair to which the cursor refers with the specified data item. This method will return OperationStatus.NOTFOUND if the cursor currently refers to an already-deleted key/data pair.

      For a database that does not support duplicates, the data may be changed by this method. If duplicates are supported, the data may be changed only if a custom partial comparator is configured and the comparator considers the old and new data to be equal (that is, the comparator returns zero). For more information on partial comparators see `DatabaseConfig.setDuplicateComparator(java.util.Comparator<byte[]>)`.

      If the old and new data are unequal according to the comparator, a `DuplicateDataException` is thrown. Changing the data in this case would change the sort order of the record, which would change the cursor position, and this is not allowed. To change the sort order of a record, delete it and then re-insert it.

      Parameters:
        `data` - - the data DatabaseEntry stored. A partial data item may be specified to optimize for partial data update.
      Returns:
        `OperationStatus.KEYEMPTY` if the key/pair at the cursor position has been deleted; otherwise, `OperationStatus.SUCCESS`.
      Throws:
        `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.
        `UnsupportedOperationException` - if the database is transactional but this cursor was not opened with a non-null transaction parameter, or the database is read-only.
        `IllegalStateException` - if the cursor or database has been closed, or the cursor is uninitialized (not positioned on a record), or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### getCurrent

          public OperationStatus getCurrent(DatabaseEntry key,
                                   DatabaseEntry data,
                                   LockMode lockMode)
                                     throws DatabaseException

      Returns the key/data pair to which the cursor refers.

      In a replicated environment, an explicit transaction must have been specified when opening the cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameter.

      Specified by:
        `getCurrent` in interface `ForwardCursor`
      Parameters:
        `key` - the key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the data returned as output. Its byte array does not need to be initialized by the caller. A partial data item may be specified to optimize for key only or partial data retrieval.
        `lockMode` - the locking attributes; if null, default attributes are used. `LockMode.READ_COMMITTED` is not allowed.
      Returns:
        `OperationStatus.KEYEMPTY` if the key/pair at the cursor position has been deleted; otherwise, `OperationStatus.SUCCESS`.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the cursor is uninitialized (not positioned on a record), or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### getFirst

          public OperationStatus getFirst(DatabaseEntry key,
                                 DatabaseEntry data,
                                 LockMode lockMode)
                                   throws DatabaseException

      Moves the cursor to the first key/data pair of the database, and returns that pair. If the first key has duplicate values, the first data item in the set of duplicates is returned.

      In a replicated environment, an explicit transaction must have been specified when opening the cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameter.

      Parameters:
        `key` - the key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the data returned as output. Its byte array does not need to be initialized by the caller. A partial data item may be specified to optimize for key only or partial data retrieval.
        `lockMode` - the locking attributes; if null, default attributes are used. `LockMode.READ_COMMITTED` is not allowed.
      Returns:
        `OperationStatus.NOTFOUND` if no matching key/data pair is found; otherwise, `OperationStatus.SUCCESS`.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### getLast

          public OperationStatus getLast(DatabaseEntry key,
                                DatabaseEntry data,
                                LockMode lockMode)
                                  throws DatabaseException

      Moves the cursor to the last key/data pair of the database, and returns that pair. If the last key has duplicate values, the last data item in the set of duplicates is returned.

      In a replicated environment, an explicit transaction must have been specified when opening the cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameter.

      Parameters:
        `key` - the key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the data returned as output. Its byte array does not need to be initialized by the caller. A partial data item may be specified to optimize for key only or partial data retrieval.
        `lockMode` - the locking attributes; if null, default attributes are used. `LockMode.READ_COMMITTED` is not allowed.
      Returns:
        `OperationStatus.NOTFOUND` if no matching key/data pair is found; otherwise, `OperationStatus.SUCCESS`.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### getNext

          public OperationStatus getNext(DatabaseEntry key,
                                DatabaseEntry data,
                                LockMode lockMode)
                                  throws DatabaseException

      Moves the cursor to the next key/data pair and returns that pair.

      If the cursor is not yet initialized, move the cursor to the first key/data pair of the database, and return that pair. Otherwise, the cursor is moved to the next key/data pair of the database, and that pair is returned. In the presence of duplicate key values, the value of the key may not change.

      In a replicated environment, an explicit transaction must have been specified when opening the cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameter.

      Specified by:
        `getNext` in interface `ForwardCursor`
      Parameters:
        `key` - the key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the data returned as output. Its byte array does not need to be initialized by the caller. A partial data item may be specified to optimize for key only or partial data retrieval.
        `lockMode` - the locking attributes; if null, default attributes are used. `LockMode.READ_COMMITTED` is not allowed.
      Returns:
        `OperationStatus.NOTFOUND` if no matching key/data pair is found; otherwise, `OperationStatus.SUCCESS`.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### getNextDup

          public OperationStatus getNextDup(DatabaseEntry key,
                                   DatabaseEntry data,
                                   LockMode lockMode)
                                     throws DatabaseException

      If the next key/data pair of the database is a duplicate data record for the current key/data pair, moves the cursor to the next key/data pair of the database and returns that pair.

      In a replicated environment, an explicit transaction must have been specified when opening the cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameter.

      Parameters:
        `key` - the key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the data returned as output. Its byte array does not need to be initialized by the caller. A partial data item may be specified to optimize for key only or partial data retrieval.
        `lockMode` - the locking attributes; if null, default attributes are used. `LockMode.READ_COMMITTED` is not allowed.
      Returns:
        `OperationStatus.NOTFOUND` if no matching key/data pair is found; otherwise, `OperationStatus.SUCCESS`.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the cursor is uninitialized (not positioned on a record), or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### getNextNoDup

          public OperationStatus getNextNoDup(DatabaseEntry key,
                                     DatabaseEntry data,
                                     LockMode lockMode)
                                       throws DatabaseException

      Moves the cursor to the next non-duplicate key/data pair and returns that pair. If the matching key has duplicate values, the first data item in the set of duplicates is returned.

      If the cursor is not yet initialized, move the cursor to the first key/data pair of the database, and return that pair. Otherwise, the cursor is moved to the next non-duplicate key of the database, and that key/data pair is returned.

      In a replicated environment, an explicit transaction must have been specified when opening the cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameter.

      Parameters:
        `key` - the key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the data returned as output. Its byte array does not need to be initialized by the caller. A partial data item may be specified to optimize for key only or partial data retrieval.
        `lockMode` - the locking attributes; if null, default attributes are used. `LockMode.READ_COMMITTED` is not allowed.
      Returns:
        `OperationStatus.NOTFOUND` if no matching key/data pair is found; otherwise, `OperationStatus.SUCCESS`.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### getPrev

          public OperationStatus getPrev(DatabaseEntry key,
                                DatabaseEntry data,
                                LockMode lockMode)
                                  throws DatabaseException

      Moves the cursor to the previous key/data pair and returns that pair.

      If the cursor is not yet initialized, move the cursor to the last key/data pair of the database, and return that pair. Otherwise, the cursor is moved to the previous key/data pair of the database, and that pair is returned. In the presence of duplicate key values, the value of the key may not change.

      In a replicated environment, an explicit transaction must have been specified when opening the cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameter.

      Parameters:
        `key` - the key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the data returned as output. Its byte array does not need to be initialized by the caller. A partial data item may be specified to optimize for key only or partial data retrieval.
        `lockMode` - the locking attributes; if null, default attributes are used. `LockMode.READ_COMMITTED` is not allowed.
      Returns:
        `OperationStatus.NOTFOUND` if no matching key/data pair is found; otherwise, `OperationStatus.SUCCESS`.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### getPrevDup

          public OperationStatus getPrevDup(DatabaseEntry key,
                                   DatabaseEntry data,
                                   LockMode lockMode)
                                     throws DatabaseException

      If the previous key/data pair of the database is a duplicate data record for the current key/data pair, moves the cursor to the previous key/data pair of the database and returns that pair.

      In a replicated environment, an explicit transaction must have been specified when opening the cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameter.

      Parameters:
        `key` - the key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the data returned as output. Its byte array does not need to be initialized by the caller. A partial data item may be specified to optimize for key only or partial data retrieval.
        `lockMode` - the locking attributes; if null, default attributes are used. `LockMode.READ_COMMITTED` is not allowed.
      Returns:
        `OperationStatus.NOTFOUND` if no matching key/data pair is found; otherwise, `OperationStatus.SUCCESS`.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the cursor is uninitialized (not positioned on a record), or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### getPrevNoDup

          public OperationStatus getPrevNoDup(DatabaseEntry key,
                                     DatabaseEntry data,
                                     LockMode lockMode)
                                       throws DatabaseException

      Moves the cursor to the previous non-duplicate key/data pair and returns that pair. If the matching key has duplicate values, the last data item in the set of duplicates is returned.

      If the cursor is not yet initialized, move the cursor to the last key/data pair of the database, and return that pair. Otherwise, the cursor is moved to the previous non-duplicate key of the database, and that key/data pair is returned.

      In a replicated environment, an explicit transaction must have been specified when opening the cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameter.

      Parameters:
        `key` - the key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the data returned as output. Its byte array does not need to be initialized by the caller. A partial data item may be specified to optimize for key only or partial data retrieval.
        `lockMode` - the locking attributes; if null, default attributes are used. `LockMode.READ_COMMITTED` is not allowed.
      Returns:
        `OperationStatus.NOTFOUND` if no matching key/data pair is found; otherwise, `OperationStatus.SUCCESS`.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### skipNext

          public long skipNext(long maxCount,
                      DatabaseEntry key,
                      DatabaseEntry data,
                      LockMode lockMode)
                        throws DatabaseException

      Skips forward a given number of key/data pairs and returns the number by which the cursor is moved.

      Without regard to performance, calling this method is equivalent to repeatedly calling `getNext` with `LockMode.READ_UNCOMMITTED` to skip over the desired number of key/data pairs, and then calling `getCurrent` with the `lockMode` parameter to return the final key/data pair.

      With regard to performance, this method is optimized to skip over key/value pairs 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 `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.

      If the returned count is greater than zero, then the key/data pair at the new cursor position is also returned. If zero is returned, then there are no key/value pairs that follow the cursor position and a key/data pair is not returned.

      In a replicated environment, an explicit transaction must have been specified when opening the cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameter.

      Parameters:
        `maxCount` - the maximum number of key/data pairs to skip, i.e., the maximum number by which the cursor should be moved; must be greater than zero.
        `key` - the key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the data returned as output. Its byte array does not need to be initialized by the caller. A partial data item may be specified to optimize for key only or partial data retrieval.
        `lockMode` - the locking attributes; if null, default attributes are used. `LockMode.READ_COMMITTED` is not allowed.
      Returns:
        the number of key/data pairs skipped, i.e., the number by which the cursor has moved; if zero is returned, the cursor position is unchanged and the key/data pair is not returned.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the cursor is uninitialized (not positioned on a record), or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### skipPrev

          public long skipPrev(long maxCount,
                      DatabaseEntry key,
                      DatabaseEntry data,
                      LockMode lockMode)
                        throws DatabaseException

      Skips backward a given number of key/data pairs and returns the number by which the cursor is moved.

      Without regard to performance, calling this method is equivalent to repeatedly calling `getPrev` with `LockMode.READ_UNCOMMITTED` to skip over the desired number of key/data pairs, and then calling `getCurrent` with the `lockMode` parameter to return the final key/data pair.

      With regard to performance, this method is optimized to skip over key/value pairs 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 `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.

      If the returned count is greater than zero, then the key/data pair at the new cursor position is also returned. If zero is returned, then there are no key/value pairs that follow the cursor position and a key/data pair is not returned.

      In a replicated environment, an explicit transaction must have been specified when opening the cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameter.

      Parameters:
        `maxCount` - the maximum number of key/data pairs to skip, i.e., the maximum number by which the cursor should be moved; must be greater than zero.
        `key` - the key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the data returned as output. Its byte array does not need to be initialized by the caller. A partial data item may be specified to optimize for key only or partial data retrieval.
        `lockMode` - the locking attributes; if null, default attributes are used. `LockMode.READ_COMMITTED` is not allowed.
      Returns:
        the number of key/data pairs skipped, i.e., the number by which the cursor has moved; if zero is returned, the cursor position is unchanged and the key/data pair is not returned.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the cursor is uninitialized (not positioned on a record), or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### getSearchKey

          public OperationStatus getSearchKey(DatabaseEntry key,
                                     DatabaseEntry data,
                                     LockMode lockMode)
                                       throws DatabaseException

      Moves the cursor to the given key of the database, and returns the datum associated with the given key. If the matching key has duplicate values, the first data item in the set of duplicates is returned.

      In a replicated environment, an explicit transaction must have been specified when opening the cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameter.

      Parameters:
        `key` - the key used as input. It must be initialized with a non-null byte array by the caller.
        `data` - the data returned as output. Its byte array does not need to be initialized by the caller. A partial data item may be specified to optimize for key only or partial data retrieval.
        `lockMode` - the locking attributes; if null, default attributes are used. `LockMode.READ_COMMITTED` is not allowed.
      Returns:
        `OperationStatus.NOTFOUND` if no matching key/data pair is found; otherwise, `OperationStatus.SUCCESS`.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### getSearchKeyRange

          public OperationStatus getSearchKeyRange(DatabaseEntry key,
                                          DatabaseEntry data,
                                          LockMode lockMode)
                                            throws DatabaseException

      Moves the cursor to the closest matching key of the database, and returns the data item associated with the matching key. If the matching key has duplicate values, the first data item in the set of duplicates is returned.

      The returned key/data pair is for the smallest key greater than or equal to the specified key (as determined by the key comparison function), permitting partial key matches and range searches.

      In a replicated environment, an explicit transaction must have been specified when opening the cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameter.

      Parameters:
        `key` - the key used as input and returned as output. It must be initialized with a non-null byte array by the caller. A partial data item may be specified to optimize for key only or partial data retrieval.
        `data` - the data returned as output. Its byte array does not need to be initialized by the caller.
        `lockMode` - the locking attributes; if null, default attributes are used. `LockMode.READ_COMMITTED` is not allowed.
      Returns:
        `OperationStatus.NOTFOUND` if no matching key/data pair is found; otherwise, `OperationStatus.SUCCESS`.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### getSearchBoth

          public OperationStatus getSearchBoth(DatabaseEntry key,
                                      DatabaseEntry data,
                                      LockMode lockMode)
                                        throws DatabaseException

      Moves the cursor to the specified key/data pair, where both the key and data items must match.

      In a replicated environment, an explicit transaction must have been specified when opening the cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameter.

      Parameters:
        `key` - the key used as input. It must be initialized with a non-null byte array by the caller.
        `data` - the data used as input. It must be initialized with a non-null byte array by the caller.
        `lockMode` - the locking attributes; if null, default attributes are used. `LockMode.READ_COMMITTED` is not allowed.
      Returns:
        `OperationStatus.NOTFOUND` if no matching key/data pair is found; otherwise, `OperationStatus.SUCCESS`.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### getSearchBothRange

          public OperationStatus getSearchBothRange(DatabaseEntry key,
                                           DatabaseEntry data,
                                           LockMode lockMode)
                                             throws DatabaseException

      Moves the cursor to the specified key and closest matching data item of the database.

      In the case of any database supporting sorted duplicate sets, the returned key/data pair is for the smallest data item greater than or equal to the specified data item (as determined by the duplicate comparison function), permitting partial matches and range searches in duplicate data sets.

      In the case of databases that do not support sorted duplicate sets, this method is equivalent to getSearchBoth.

      In a replicated environment, an explicit transaction must have been specified when opening the cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameter.

      Parameters:
        `key` - the key used as input. It must be initialized with a non-null byte array by the caller.
        `data` - the data used as input and returned as output. It must be initialized with a non-null byte array by the caller.
        `lockMode` - the locking attributes; if null, default attributes are used. `LockMode.READ_COMMITTED` is not allowed.
      Returns:
        `OperationStatus.NOTFOUND` if no matching key/data pair is found; otherwise, `OperationStatus.SUCCESS`.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the non-transactional cursor was created in a different thread.
        `IllegalArgumentException` - if an invalid parameter is specified.
        `DatabaseException`

    - #### count

          public int count()
                    throws DatabaseException

      Returns a count of the number of data items for the key to which the cursor refers.

      If the database is configured for duplicates, the database is scanned internally, without taking any record locks, to count the number of non-deleted entries. Although the internal scan is more efficient under some conditions, the result is the same as if a cursor were used to iterate over the entries using `LockMode.READ_UNCOMMITTED`.

      If the database is not configured for duplicates, the count returned is always zero or one, depending on the record at the cursor position is deleted or not.

      The cost of this method is directly proportional to the number of records scanned.

      Returns:
        A count of the number of data items for the key to which the cursor refers.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the cursor is uninitialized (not positioned on a record), or the non-transactional cursor was created in a different thread.
        `DatabaseException`

    - #### countEstimate

          public long countEstimate()
                             throws DatabaseException

      Returns a rough estimate of the count of the number of data items for the key to which the cursor refers.

      If the database is configured for duplicates, a quick estimate of the number of records 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`.

      If the database is not configured for duplicates, the count returned is always zero or one, depending on the record at the cursor position is deleted or not.

      The cost of this method is fixed, rather than being proportional to the number of records scanned. 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 a `JoinCursor`.

      Returns:
        an estimate of the count of the number of data items for the key to which the cursor refers.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if the cursor or database has been closed, or the cursor is uninitialized (not positioned on a record), or the non-transactional cursor was created in a different thread.
        `DatabaseException`

Copyright (c) 2004, 2014 Oracle and/or its affiliates. All rights reserved.