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

com.sleepycat.je

## Class SecondaryCursor

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

- All Implemented Interfaces:
    ForwardCursor, Closeable, AutoCloseable

      public class SecondaryCursor
      extends Cursor

  A database cursor for a secondary database. Cursors are not thread safe and the application is responsible for coordinating any multithreaded access to a single cursor object.

  Secondary cursors are returned by `SecondaryDatabase.openCursor` and `SecondaryDatabase.openSecondaryCursor`. The distinguishing characteristics of a secondary cursor are:

  - Direct calls to `put()` methods on a secondary cursor are prohibited.
  - The `delete()` method of a secondary cursor will delete the primary record and as well as all its associated secondary records.
  - Calls to all get methods will return the data from the associated primary database.
  - Additional get method signatures are provided to return the primary key in an additional pKey parameter.
  - Calls to `dup(boolean)` will return a `SecondaryCursor`.

  To obtain a secondary cursor with default attributes:

  >          SecondaryCursor cursor = myDb.openSecondaryCursor(txn, null);

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

  >          CursorConfig config = new CursorConfig();
  >          config.setReadUncommitted(true);
  >          SecondaryCursor cursor = myDb.openSecondaryCursor(txn, config);

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `OperationStatus` | `delete()` Delete the key/data pair to which the cursor refers from the primary database and all secondary indices.
    `SecondaryCursor` | `dup(boolean samePosition)` Returns a new `SecondaryCursor` for the same transaction as the original cursor.
    `SecondaryCursor` | `dupSecondary(boolean samePosition)` Deprecated. As of JE 4.0.13, replaced by `Cursor.dup(boolean)`.
    `OperationStatus` | `getCurrent(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode)` Returns the key/data pair to which the cursor refers.
    `OperationStatus` | `getCurrent(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` Returns the key/data pair to which the cursor refers.
    `SecondaryDatabase` | `getDatabase()` Returns the Database handle associated with this Cursor.
    `OperationStatus` | `getFirst(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode)` Move the cursor to the first key/data pair of the database, and return that pair.
    `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 pKey, DatabaseEntry data, LockMode lockMode)` Move the cursor to the last key/data pair of the database, and return 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 pKey, DatabaseEntry data, LockMode lockMode)` Move the cursor to the next key/data pair and return 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 pKey, DatabaseEntry data, LockMode lockMode)` If the next key/data pair of the database is a duplicate data record for the current key/data pair, move the cursor to the next key/data pair of the database and return 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 pKey, DatabaseEntry data, LockMode lockMode)` Move the cursor to the next non-duplicate key/data pair and return 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 pKey, DatabaseEntry data, LockMode lockMode)` Move the cursor to the previous key/data pair and return 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 pKey, DatabaseEntry data, LockMode lockMode)` If the previous key/data pair of the database is a duplicate data record for the current key/data pair, move the cursor to the previous key/data pair of the database and return 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 pKey, DatabaseEntry data, LockMode lockMode)` Move the cursor to the previous non-duplicate key/data pair and return 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.
    `Database` | `getPrimaryDatabase()` Returns the primary `Database` associated with this cursor.
    `OperationStatus` | `getSearchBoth(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode)` Move the cursor to the specified secondary and primary key, where both the primary and secondary key items must match.
    `OperationStatus` | `getSearchBoth(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` This operation is not allowed with this method signature.
    `OperationStatus` | `getSearchBothRange(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode)` Move the cursor to the specified secondary key and closest matching primary key of the database.
    `OperationStatus` | `getSearchBothRange(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` This operation is not allowed with this method signature.
    `OperationStatus` | `getSearchKey(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode)` Move the cursor to the given key of the database, and return the datum associated with the given key.
    `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 pKey, DatabaseEntry data, LockMode lockMode)` Move the cursor to the closest matching key of the database, and return the data item associated with the matching 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)` This operation is not allowed on a secondary database.
    `OperationStatus` | `putCurrent(DatabaseEntry data)` This operation is not allowed on a secondary database.
    `OperationStatus` | `putNoDupData(DatabaseEntry key, DatabaseEntry data)` This operation is not allowed on a secondary database.
    `OperationStatus` | `putNoOverwrite(DatabaseEntry key, DatabaseEntry data)` This operation is not allowed on a secondary database.

    - ### Methods inherited from class com.sleepycat.je.Cursor

      `close, count, countEstimate, getCacheMode, getConfig, setCacheMode, skipNext, skipPrev`

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

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

- - ### Method Detail

    - #### getDatabase

          public SecondaryDatabase getDatabase()

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

    - #### getPrimaryDatabase

          public Database getPrimaryDatabase()

      Returns the primary `Database` associated with this cursor.

      Calling this method is the equivalent of the following expression:

      >              getDatabase().getPrimaryDatabase()

      Returns:
        The primary `Database` associated with this cursor.

    - #### dup

          public SecondaryCursor dup(boolean samePosition)
                              throws DatabaseException

      Returns a new `SecondaryCursor` for the same transaction as the original cursor.
      Overrides:
        `dup` in class `Cursor`
      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.
        `DatabaseException`

    - #### dupSecondary

          public SecondaryCursor dupSecondary(boolean samePosition)
                                       throws DatabaseException

      Deprecated. As of JE 4.0.13, replaced by `Cursor.dup(boolean)`.
      Returns a new copy of the cursor as a `SecondaryCursor`.

      Calling this method is the equivalent of calling `dup(boolean)` and casting the result to `SecondaryCursor`.

      Throws:
        `DatabaseException`
      See Also:
        `dup(boolean)`

    - #### delete

          public OperationStatus delete()
                                 throws LockConflictException,
                                        DatabaseException,
                                        UnsupportedOperationException,
                                        IllegalStateException

      Delete the key/data pair to which the cursor refers from the primary database and all secondary indices.

      This method behaves as if `Database.delete(com.sleepycat.je.Transaction, com.sleepycat.je.DatabaseEntry)` were called for the primary database, using the primary key associated with this cursor position. 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.

      Overrides:
        `delete` in class `Cursor`
      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)

      This operation is not allowed on a secondary database. `UnsupportedOperationException` will always be thrown by this method. The corresponding method on the primary database should be used instead.
      Overrides:
        `put` in class `Cursor`
      Parameters:
        `key` - the key `DatabaseEntry` operated on.
        `data` - the data `DatabaseEntry` stored.
      Returns:
        an OperationStatus for the operation.

    - #### putNoOverwrite

          public OperationStatus putNoOverwrite(DatabaseEntry key,
                                       DatabaseEntry data)

      This operation is not allowed on a secondary database. `UnsupportedOperationException` will always be thrown by this method. The corresponding method on the primary database should be used instead.
      Overrides:
        `putNoOverwrite` in class `Cursor`
      Parameters:
        `key` - the key `DatabaseEntry` operated on.
        `data` - the data `DatabaseEntry` stored.
      Returns:
        an OperationStatus for the operation.

    - #### putNoDupData

          public OperationStatus putNoDupData(DatabaseEntry key,
                                     DatabaseEntry data)

      This operation is not allowed on a secondary database. `UnsupportedOperationException` will always be thrown by this method. The corresponding method on the primary database should be used instead.
      Overrides:
        `putNoDupData` in class `Cursor`
      Parameters:
        `key` - the key `DatabaseEntry` operated on.
        `data` - the data `DatabaseEntry` stored.
      Returns:
        an OperationStatus for the operation.

    - #### putCurrent

          public OperationStatus putCurrent(DatabaseEntry data)

      This operation is not allowed on a secondary database. `UnsupportedOperationException` will always be thrown by this method. The corresponding method on the primary database should be used instead.
      Overrides:
        `putCurrent` in class `Cursor`
      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`.

    - #### getCurrent

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

      Description copied from class: `Cursor`
      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`
      Overrides:
        `getCurrent` in class `Cursor`
      Parameters:
        `key` - the secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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.
        `DatabaseException`

    - #### getCurrent

          public OperationStatus getCurrent(DatabaseEntry key,
                                   DatabaseEntry pKey,
                                   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.

      Parameters:
        `key` - the secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `pKey` - the primary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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.
        `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, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.
        `DatabaseException`

    - #### getFirst

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

      Description copied from class: `Cursor`
      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.

      Overrides:
        `getFirst` in class `Cursor`
      Parameters:
        `key` - the secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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.
        `DatabaseException`

    - #### getFirst

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

      Move the cursor to the first key/data pair of the database, and return 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 secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `pKey` - the primary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.
        `DatabaseException`

    - #### getLast

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

      Description copied from class: `Cursor`
      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.

      Overrides:
        `getLast` in class `Cursor`
      Parameters:
        `key` - the secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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.
        `DatabaseException`

    - #### getLast

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

      Move the cursor to the last key/data pair of the database, and return 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 secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `pKey` - the primary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.
        `DatabaseException`

    - #### getNext

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

      Description copied from class: `Cursor`
      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`
      Overrides:
        `getNext` in class `Cursor`
      Parameters:
        `key` - the secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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.
        `DatabaseException`

    - #### getNext

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

      Move the cursor to the next key/data pair and return 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 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 secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `pKey` - the primary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.
        `DatabaseException`

    - #### getNextDup

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

      Description copied from class: `Cursor`
      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.

      Overrides:
        `getNextDup` in class `Cursor`
      Parameters:
        `key` - the secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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.
        `DatabaseException`

    - #### getNextDup

          public OperationStatus getNextDup(DatabaseEntry key,
                                   DatabaseEntry pKey,
                                   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, move the cursor to the next key/data pair of the database and return 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 secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `pKey` - the primary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.
        `DatabaseException`

    - #### getNextNoDup

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

      Description copied from class: `Cursor`
      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.

      Overrides:
        `getNextNoDup` in class `Cursor`
      Parameters:
        `key` - the secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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.
        `DatabaseException`

    - #### getNextNoDup

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

      Move the cursor to the next non-duplicate key/data pair and return 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 secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `pKey` - the primary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.
        `DatabaseException`

    - #### getPrev

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

      Description copied from class: `Cursor`
      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.

      Overrides:
        `getPrev` in class `Cursor`
      Parameters:
        `key` - the secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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.
        `DatabaseException`

    - #### getPrev

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

      Move the cursor to the previous key/data pair and return 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 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 secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `pKey` - the primary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.
        `DatabaseException`

    - #### getPrevDup

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

      Description copied from class: `Cursor`
      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.

      Overrides:
        `getPrevDup` in class `Cursor`
      Parameters:
        `key` - the secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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.
        `DatabaseException`

    - #### getPrevDup

          public OperationStatus getPrevDup(DatabaseEntry key,
                                   DatabaseEntry pKey,
                                   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, move the cursor to the previous key/data pair of the database and return 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 secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `pKey` - the primary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.
        `DatabaseException`

    - #### getPrevNoDup

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

      Description copied from class: `Cursor`
      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.

      Overrides:
        `getPrevNoDup` in class `Cursor`
      Parameters:
        `key` - the secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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.
        `DatabaseException`

    - #### getPrevNoDup

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

      Move the cursor to the previous non-duplicate key/data pair and return 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 secondary key returned as output. Its byte array does not need to be initialized by the caller.
        `pKey` - the primary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.
        `DatabaseException`

    - #### getSearchKey

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

      Description copied from class: `Cursor`
      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.

      Overrides:
        `getSearchKey` in class `Cursor`
      Parameters:
        `key` - the secondary key used as input. It must be initialized with a non-null byte array by the caller.
        `data` - the primary 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.
        `DatabaseException`

    - #### getSearchKey

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

      Move the cursor to the given key of the database, and return 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 secondary key used as input. It must be initialized with a non-null byte array by the caller.
        `pKey` - the primary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.
        `DatabaseException`

    - #### getSearchKeyRange

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

      Description copied from class: `Cursor`
      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.

      Overrides:
        `getSearchKeyRange` in class `Cursor`
      Parameters:
        `key` - the secondary key used as input and returned as output. It must be initialized with a non-null byte array by the caller.
        `data` - the primary 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.
        `DatabaseException`

    - #### getSearchKeyRange

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

      Move the cursor to the closest matching key of the database, and return 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 secondary key used as input and returned as output. It must be initialized with a non-null byte array by the caller.
        `pKey` - the primary key returned as output. Its byte array does not need to be initialized by the caller.
        `data` - the primary 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, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.
        `DatabaseException`

    - #### getSearchBoth

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

      This operation is not allowed with this method signature. `UnsupportedOperationException` will always be thrown by this method. The corresponding method with the `pKey` parameter should be used instead.
      Overrides:
        `getSearchBoth` in class `Cursor`
      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`.

    - #### getSearchBoth

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

      Move the cursor to the specified secondary and primary key, where both the primary and secondary key 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 secondary key used as input. It must be initialized with a non-null byte array by the caller.
        `pKey` - the primary key used as input. It must be initialized with a non-null byte array by the caller.
        `data` - the primary 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, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.
        `DatabaseException`

    - #### getSearchBothRange

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

      This operation is not allowed with this method signature. `UnsupportedOperationException` will always be thrown by this method. The corresponding method with the `pKey` parameter should be used instead.
      Overrides:
        `getSearchBothRange` in class `Cursor`
      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`.

    - #### getSearchBothRange

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

      Move the cursor to the specified secondary key and closest matching primary key of the database.

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

      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 secondary key used as input. It must be initialized with a non-null byte array by the caller.
        `pKey` - the primary key used as input and returned as output. It must be initialized with a non-null byte array by the caller.
        `data` - the primary 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, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.
        `DatabaseException`

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