com.sleepycat.je

Interface ForwardCursor

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable

All Known Implementing Classes:

Cursor, DiskOrderedCursor, JoinCursor, SecondaryCursor

public interface ForwardCursor
extends java.io.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

Modifier and Type	Method and Description
void	close() Discards the cursor.
OperationResult	get(DatabaseEntry key, DatabaseEntry data, Get getType, ReadOptions options) Moves the cursor to a record according to the specified Get type.
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()

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 java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

get

OperationResult get(DatabaseEntry key,
                    DatabaseEntry data,
                    Get getType,
                    ReadOptions options)

Moves the cursor to a record according to the specified Get type.

Parameters:

key - the key returned as output.

data - the data returned as output.

getType - is Get.NEXT or Get.CURRENT. interface. Get.CURRENT is permitted only if the cursor is initialized (positioned on a record).

options - the ReadOptions, or null to use default options.

Returns:

the OperationResult if the record requested is found, else null.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

java.lang.IllegalStateException - if the cursor or database has been closed, the cursor is uninitialized (not positioned on a record) and this is not permitted (see above), or the non-transactional cursor was created in a different thread.

java.lang.IllegalArgumentException - if an invalid parameter is specified. This includes passing a null getType, a null input key/data parameter, an input key/data parameter with a null data array, a partial key/data input parameter, and specifying a lock mode of READ_COMMITTED.

Since:

7.0

getCurrent

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

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

Calling this method is equivalent to calling get(DatabaseEntry, DatabaseEntry, Get, ReadOptions) with Get.CURRENT.

Parameters:

key - the key returned as output.

data - the data returned as output.

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.

java.lang.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.

java.lang.IllegalArgumentException - if an invalid parameter is specified.

getNext

OperationStatus getNext(DatabaseEntry key,
                        DatabaseEntry data,
                        LockMode lockMode)

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

Calling this method is equivalent to calling get(DatabaseEntry, DatabaseEntry, Get, ReadOptions) with Get.NEXT.

Parameters:

key - the key returned as output.

data - the data returned as output.

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.

java.lang.IllegalStateException - if the cursor or database has been closed, or the non-transactional cursor was created in a different thread.

java.lang.IllegalArgumentException - if an invalid parameter is specified.