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

com.sleepycat.je

## Interface ForwardCursor

- All Superinterfaces:
    AutoCloseable, Closeable
  All Known Implementing Classes:
    Cursor, DiskOrderedCursor, SecondaryCursor

      public interface ForwardCursor
      extends Closeable

  The interface for forward-moving Cursor operations. Specific implementations may modify the documented behavior on each of these methods.
  Since:
    5.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Discards the cursor.
    `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 ForwardCursor.
    `OperationStatus` | `getNext(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` Moves the cursor to the next key/data pair and returns that pair.

- - ### Method Detail

    - #### getDatabase

          Database getDatabase()

      Returns the Database handle associated with this ForwardCursor.
      Returns:
        The Database handle associated with this ForwardCursor.

    - #### close

          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.

      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 `AutoCloseable`
      Specified by:
        `close` in interface `Closeable`
      Throws:
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `DatabaseException`

    - #### getCurrent

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

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

      If this method fails for any reason, the position of the cursor will be unchanged.

      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.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`

    - #### getNext

          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.

      If this method fails for any reason, the position of the cursor will be unchanged.

      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`

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