com.sleepycat.je
Class Cursor

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

Direct Known Subclasses:

SecondaryCursor

public class Cursor

extends Object

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. They are the only way to access individual duplicate data items.

Cursors may be used by multiple threads, but only serially. That is, the application must serialize access to the handle.

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.

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.setDirtyRead(true);
  Cursor cursor = myDatabase.openCursor(txn, config);

Method Summary

void	close() Discard the cursor.
int	count() Return a count of the number of data items for the key to which the cursor refers.
OperationStatus	delete() Delete the key/data pair to which the cursor refers.
Cursor	dup(boolean samePosition) Return a new cursor for the same transaction as the original cursor.
CursorConfig	getConfig() Return this object's configuration.
OperationStatus	getCurrent(DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Returns the key/data pair to which the cursor refers.
Database	getDatabase() Return 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, that is, 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 datum associated with the matching key.
OperationStatus	put(DatabaseEntry key, DatabaseEntry data) Store a key/data pair into the database.
OperationStatus	putCurrent(DatabaseEntry data) Store a key/data pair into the database.
OperationStatus	putNoDupData(DatabaseEntry key, DatabaseEntry data) Store a key/data pair into the database.
OperationStatus	putNoOverwrite(DatabaseEntry key, DatabaseEntry data) Store a key/data pair into the database.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getDatabase

public Database getDatabase()

Return the Database handle associated with this Cursor.

Returns:

The Database handle associated with this Cursor.

getConfig

public CursorConfig getConfig()

Return this object's configuration.

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

Returns:

This object's configuration.

Throws:

DatabaseException - if a failure occurs.

close

public void close()
           throws DatabaseException

Discard the cursor.

Throws:

DatabaseException - if a failure occurs.

count

public int count()
          throws DatabaseException

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

Returns:

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

Throws:

DatabaseException - if a failure occurs.

dup

public Cursor dup(boolean samePosition)
           throws DatabaseException

Return a new cursor for the same transaction as the original cursor.

Parameters:

samePosition - If true, the newly created cursor is initialized to refer to the same position in the database as the original cursor and hold the same locks. If false, the created cursor is uninitialized and will behave like a cursor newly created using openCursor.

Returns:

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

Throws:

DatabaseException - if a failure occurs.

delete

public OperationStatus delete()
                       throws DatabaseException

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

The key/data pair is also deleted from any associated secondary databases.

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.

Throws:

DeadlockException - if the operation was selected to resolve a deadlock.

DatabaseException - if a failure occurs.

put

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

Store a key/data pair into the database.

If put succeeds, the cursor is always positioned to refer to the newly inserted item. If put fails for any reason, the state of the cursor will be unchanged.

If the key already appears in the database and duplicates are supported, the new data value is inserted at the correct sorted location. If the key already appears in the database and duplicates are not supported, the existing key/data pair will be replaced.

Parameters:

key - the key DatabaseEntry operated on.

data - the data DatabaseEntry stored.

Throws:

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

putNoOverwrite

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

Store a key/data pair into the database.

If putNoOverwrite succeeds, the cursor is always positioned to refer to the newly inserted item. If putNoOverwrite fails for any reason, the state of the cursor will be unchanged.

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

Parameters:

key - the key DatabaseEntry operated on.

data - the data DatabaseEntry stored.

Throws:

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

putNoDupData

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

Store a key/data pair into the database.

If putNoDupData succeeds, the cursor is always positioned to refer to the newly inserted item. If putNoDupData fails for any reason, the state of the cursor will be unchanged.

If as key/data pair comparing equally to it already exists in the database return KEYEXIST.

Parameters:

key - the key DatabaseEntry operated on.

data - the data DatabaseEntry stored.

Throws:

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

putCurrent

public OperationStatus putCurrent(DatabaseEntry data)
                           throws DatabaseException

Store a key/data pair into the database.

If putCurrent succeeds, the cursor is always positioned to refer to the newly inserted item. If putCurrent fails for any reason, the state of the cursor will be unchanged.

Overwrite the data of the key/data pair to which the cursor refers with the specified data item.

Parameters:

data - the data DatabaseEntry stored.

Throws:

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

getCurrent

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

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.

lockMode - the locking attributes; if null, default attributes are used.

Returns:

KEYEMPTY if the key/pair at the cursor position has been deleted; otherwise, SUCCESS.

Throws:

NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

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.

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

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.

lockMode - the locking attributes; if null, default attributes are used.

Returns:

NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.

Throws:

NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

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.

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

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.

lockMode - the locking attributes; if null, default attributes are used.

Returns:

NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.

Throws:

NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

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

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.

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

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.

lockMode - the locking attributes; if null, default attributes are used.

Returns:

NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.

Throws:

NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

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.

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.

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

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.

lockMode - the locking attributes; if null, default attributes are used.

Returns:

NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.

Throws:

NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

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.

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.

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

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.

lockMode - the locking attributes; if null, default attributes are used.

Returns:

NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.

Throws:

NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

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

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.

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

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.

lockMode - the locking attributes; if null, default attributes are used.

Returns:

NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.

Throws:

NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

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.

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.

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

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.

lockMode - the locking attributes; if null, default attributes are used.

Returns:

NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.

Throws:

NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

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.

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.

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

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.

lockMode - the locking attributes; if null, default attributes are used.

Returns:

NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.

Throws:

NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

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.

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

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.

lockMode - the locking attributes; if null, default attributes are used.

Returns:

NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.

Throws:

NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

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

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

Parameters:

key - the key used as input and returned as output. 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.

lockMode - the locking attributes; if null, default attributes are used.

Returns:

NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.

Throws:

NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

getSearchBoth

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

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

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

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.

Returns:

NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.

Throws:

NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

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.

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

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.

Returns:

NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.

Throws:

NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

DeadlockException - if the operation was selected to resolve a deadlock.

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.