com.sleepycat.je
Interface ForwardCursor

All Superinterfaces:

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

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