com.sleepycat.je
Class Cursor

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

Direct Known Subclasses:

SecondaryCursor

public class Cursor
extends java.lang.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.

Cursors which are opened with a transaction instance are transactional cursors and may be used by multiple threads, but only serially. That is, the application must serialize access to the handle. Non-transactional cursors, opened with a null transaction instance, may not be used by multiple threads.

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.

Once the cursor close method has been called, the handle may not be accessed again, regardless of the close method's success or failure.

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

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.

Field Summary

(package private) CursorConfig	config The CursorConfig used to configure this cursor.
(package private) CursorImpl	cursorImpl The underlying cursor.

Constructor Summary

Cursor(Cursor cursor, boolean samePosition)
Copy constructor.

Cursor(Database dbHandle, Locker locker, CursorConfig cursorConfig)
Creates a cursor for a given locker with retainNonTxnLocks=false.

Cursor(Database dbHandle, Locker locker, CursorConfig cursorConfig, boolean retainNonTxnLocks)
Creates a cursor for a given locker and retainNonTxnLocks parameter.

Cursor(Database dbHandle, Transaction txn, CursorConfig cursorConfig)
Creates a cursor for a given user transaction with retainNonTxnLocks=false.

Method Summary

(package private) boolean	advanceCursor(DatabaseEntry key, DatabaseEntry data)
(package private) void	checkEnv()
(package private) void	checkState(boolean mustBeInitialized) Checks the environment and cursor state.
protected void	checkUpdatesAllowed(java.lang.String operation)
void	close() Discards the cursor.
int	count() Returns a count of the number of data items for the key to which the cursor refers.
(package private) int	countInternal(LockMode lockMode) Counts duplicates without parameter checking.
OperationStatus	delete() Deletes the key/data pair to which the cursor refers.
(package private) OperationStatus	deleteInternal() Internal version of delete() that does no parameter checking.
(package private) OperationStatus	deleteNoNotify() Clones the cursor, delete at current position, and if successful, swap cursors.
Cursor	dup(boolean samePosition) Returns a new cursor with the same transaction and locker ID as the original cursor.
CacheMode	getCacheMode() Returns the CacheMode used for operations performed using this cursor.
CursorConfig	getConfig() Returns this cursor's configuration.
OperationStatus	getCurrent(DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Returns the key/data pair to which the cursor refers.
(package private) OperationStatus	getCurrentInternal(DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Returns the current key and data.
(package private) CursorImpl	getCursorImpl() Internal entrypoint.
Database	getDatabase() Returns the Database handle associated with this Cursor.
(package private) DatabaseImpl	getDatabaseImpl() Always returns non-null, while getDatabase() returns null if no handle is 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 return that pair.
OperationStatus	getLast(DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Moves the cursor to the last key/data pair of the database, and return that pair.
OperationStatus	getNext(DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Moves the cursor to the next key/data pair 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 return that pair.
OperationStatus	getNextNoDup(DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Moves the cursor to the next non-duplicate 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 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 return that pair.
OperationStatus	getPrevNoDup(DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Moves the cursor to the previous non-duplicate key/data pair and return that pair.
OperationStatus	getSearchBoth(DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Moves the cursor to the specified key/data pair, where 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 return 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 return the data item associated with the matching key.
(package private) boolean	isReadUncommittedMode(LockMode lockMode) Returns whether the given lock mode will cause a read-uncommitted when used with this cursor, taking into account the default cursor configuration.
(package private) OperationStatus	position(DatabaseEntry key, DatabaseEntry data, LockMode lockMode, boolean first) Positions the cursor at the first or last record of the database.
OperationStatus	put(DatabaseEntry key, DatabaseEntry data) Stores a key/data pair into the database.
OperationStatus	putCurrent(DatabaseEntry data) Replaces the data in the key/data pair at the current cursor position.
(package private) OperationStatus	putInternal(DatabaseEntry key, DatabaseEntry data, PutMode putMode) Internal version of put() that does no parameter checking.
OperationStatus	putNoDupData(DatabaseEntry key, DatabaseEntry data) Stores a key/data pair into the database.
(package private) OperationStatus	putNoNotify(DatabaseEntry key, DatabaseEntry data, PutMode putMode, DatabaseEntry returnOldData) Performs the put operation but does not notify triggers (does not perform secondary updates).
OperationStatus	putNoOverwrite(DatabaseEntry key, DatabaseEntry data) Stores a key/data pair into the database.
(package private) OperationStatus	retrieveNext(DatabaseEntry key, DatabaseEntry data, LockMode lockMode, GetMode getMode) Retrieves the next or previous record.
(package private) OperationStatus	search(DatabaseEntry key, DatabaseEntry data, LockMode lockMode, CursorImpl.SearchMode searchMode) Performs search by key, data, or both.
void	setCacheMode(CacheMode cacheMode) Changes the CacheMode used for operations performed using this cursor.
(package private) void	setNonCloning(boolean nonCloning)
(package private) void	trace(java.util.logging.Level level, java.lang.String methodName, DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Sends trace messages to the java.util.logger.
(package private) void	trace(java.util.logging.Level level, java.lang.String methodName, LockMode lockMode) Sends trace messages to the java.util.logger.

Methods inherited from class java.lang.Object

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

Field Detail

cursorImpl

CursorImpl cursorImpl

The underlying cursor.

config

CursorConfig config

The CursorConfig used to configure this cursor.

Constructor Detail

Cursor

Cursor(Database dbHandle,
       Transaction txn,
       CursorConfig cursorConfig)
 throws DatabaseException

Creates a cursor for a given user transaction with retainNonTxnLocks=false.

If txn is null, a non-transactional cursor will be created that releases locks for the prior operation when the next operation suceeds.

Throws:

DatabaseException

Cursor

Cursor(Database dbHandle,
       Locker locker,
       CursorConfig cursorConfig)
 throws DatabaseException

Creates a cursor for a given locker with retainNonTxnLocks=false.

If locker is null or is non-transactional, a non-transactional cursor will be created that releases locks for the prior operation when the next operation suceeds.

Throws:

DatabaseException

Cursor

Cursor(Database dbHandle,
       Locker locker,
       CursorConfig cursorConfig,
       boolean retainNonTxnLocks)
 throws DatabaseException

Creates a cursor for a given locker and retainNonTxnLocks parameter.

The locker parameter must be non-null. With this constructor, we use the given locker and retainNonTxnLocks parameter without applying any special rules for different lockers -- the caller must supply the correct locker and retainNonTxnLocks combination.

Throws:

DatabaseException

Cursor

Cursor(Cursor cursor,
       boolean samePosition)
 throws DatabaseException

Copy constructor.

Throws:

DatabaseException

Method Detail

getCursorImpl

CursorImpl getCursorImpl()

Internal entrypoint.

getDatabase

public Database getDatabase()

Returns the Database handle associated with this Cursor.

Returns:

The Database handle associated with this Cursor.

getDatabaseImpl

DatabaseImpl getDatabaseImpl()

Always returns non-null, while getDatabase() returns null if no handle is associated with this cursor.

getConfig

public CursorConfig getConfig()

Returns this cursor's configuration.

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

Returns:

This cursor's configuration.

Throws:

DatabaseException - if a failure occurs.

getCacheMode

public CacheMode getCacheMode()

Returns the CacheMode used for operations performed using this cursor. For a newly opened cursor, the default is CacheMode.DEFAULT.

Returns:

the CacheMode object used for operations performed with this cursor.

See Also:

CacheMode

setCacheMode

public void setCacheMode(CacheMode cacheMode)

Changes the CacheMode used for operations performed using this cursor. For a newly opened cursor, the default is CacheMode.DEFAULT.

Parameters:

cacheMode - is the CacheMode to use for subsequent operations using this cursor.

See Also:

CacheMode

setNonCloning

void setNonCloning(boolean nonCloning)

close

public void close()
           throws DatabaseException

Discards the cursor.

This method may throw a DeadlockException, signaling the enclosing transaction should be aborted. If the application is already intending to abort the transaction, this error can be ignored, and the application should proceed.

The cursor handle may not be used again after this method has been called, regardless of the method's success or failure.

Throws:

DatabaseException - if a failure occurs.

count

public int count()
          throws DatabaseException

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

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

DatabaseException - if a failure occurs.

dup

public Cursor dup(boolean samePosition)
           throws DatabaseException

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

This is useful when an application is using locking and requires two or more cursors in the same thread of control.

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:

DatabaseException - if a failure occurs.

delete

public OperationStatus delete()
                       throws DatabaseException

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

When called on a cursor opened on a database that has been made into a secondary index, this method the key/data pair from the primary database and all secondary indices.

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.

Returns:

an OperationStatus for the operation.

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

Stores a key/data pair into the database.

If the put method succeeds, the cursor is always positioned to refer to the newly inserted item. If the put method 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 data associated with the key will be replaced.

Parameters:

key - the key DatabaseEntry operated on.

data - the data DatabaseEntry stored.

Returns:

an OperationStatus for the operation.

Throws:

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

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

DatabaseException - if a failure occurs.

putNoOverwrite

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

Stores a key/data pair into the database.

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

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

Parameters:

key - the key DatabaseEntry operated on.

data - the data DatabaseEntry stored.

Returns:

an OperationStatus for the operation.

Throws:

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

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

DatabaseException - if a failure occurs.

putNoDupData

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

Stores a key/data pair into the database.

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

Insert the specified key/data pair into the database, unless a key/data pair comparing equally to it already exists in the database. If a matching key/data pair already exists in the database, OperationStatus.KEYEXIST is returned.

Parameters:

key - the key DatabaseEntry operated on.

data - the data DatabaseEntry stored.

Returns:

an OperationStatus for the operation.

Throws:

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

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

DatabaseException - if a failure occurs.

putCurrent

public OperationStatus putCurrent(DatabaseEntry data)
                           throws DatabaseException

Replaces the data in the key/data pair at the current cursor position.

Whether the putCurrent method succeeds or 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. This method will return OperationStatus.NOTFOUND if the cursor currently refers to an already-deleted key/data pair.

For a database that does not support duplicates, the data may be changed by this method. If duplicates are supported, the data may be changed only if a custom partial comparator is configured and the comparator considers the old and new data to be equal (that is, the comparator returns zero). For more information on partial comparators see DatabaseConfig.setDuplicateComparator(java.util.Comparator).

If the old and new data are unequal according to the comparator, a DatabaseException is thrown. Changing the data in this case would change the sort order of the record, which would change the cursor position, and this is not allowed. To change the sort order of a record, delete it and then re-insert it.

Parameters:

data - - the data DatabaseEntry stored.

Returns:

an OperationStatus for the operation.

Throws:

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

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

DatabaseException - - if the old and new data are not equal according to the configured duplicate comparator or default comparator, or 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:

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

Throws:

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

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

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

Throws:

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

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

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

Throws:

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

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

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:

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

Throws:

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

java.lang.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 return that pair.

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:

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

Throws:

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

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

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:

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

Throws:

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

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

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:

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

Throws:

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

java.lang.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 return that pair.

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:

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

Throws:

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

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

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:

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

Throws:

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

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

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:

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

Throws:

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

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

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:

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

Throws:

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

java.lang.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, where 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:

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

Throws:

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

java.lang.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 and returned as output. 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:

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

Throws:

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

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

DatabaseException - if a failure occurs.

countInternal

int countInternal(LockMode lockMode)
            throws DatabaseException

Counts duplicates without parameter checking.

Throws:

DatabaseException

deleteInternal

OperationStatus deleteInternal()
                         throws DatabaseException

Internal version of delete() that does no parameter checking. Calls deleteNoNotify() and notifies triggers (performs secondary updates).

Throws:

DatabaseException

deleteNoNotify

OperationStatus deleteNoNotify()
                         throws DatabaseException

Clones the cursor, delete at current position, and if successful, swap cursors. Does not notify triggers (does not perform secondary updates).

Throws:

DatabaseException

putInternal

OperationStatus putInternal(DatabaseEntry key,
                            DatabaseEntry data,
                            PutMode putMode)
                      throws DatabaseException

Internal version of put() that does no parameter checking. Calls putNoNotify() and notifies triggers (performs secondary updates). Prevents phantoms.

Throws:

DatabaseException

putNoNotify

OperationStatus putNoNotify(DatabaseEntry key,
                            DatabaseEntry data,
                            PutMode putMode,
                            DatabaseEntry returnOldData)
                      throws DatabaseException

Performs the put operation but does not notify triggers (does not perform secondary updates). Prevents phantoms.

Throws:

DatabaseException

position

OperationStatus position(DatabaseEntry key,
                         DatabaseEntry data,
                         LockMode lockMode,
                         boolean first)
                   throws DatabaseException

Positions the cursor at the first or last record of the database. Prevents phantoms.

Throws:

DatabaseException

search

OperationStatus search(DatabaseEntry key,
                       DatabaseEntry data,
                       LockMode lockMode,
                       CursorImpl.SearchMode searchMode)
                 throws DatabaseException

Performs search by key, data, or both. Prevents phantoms.

Throws:

DatabaseException

retrieveNext

OperationStatus retrieveNext(DatabaseEntry key,
                             DatabaseEntry data,
                             LockMode lockMode,
                             GetMode getMode)
                       throws DatabaseException

Retrieves the next or previous record. Prevents phantoms.

Throws:

DatabaseException

getCurrentInternal

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

Returns the current key and data. There is no need to prevent phantoms.

Throws:

DatabaseException

advanceCursor

boolean advanceCursor(DatabaseEntry key,
                      DatabaseEntry data)

isReadUncommittedMode

boolean isReadUncommittedMode(LockMode lockMode)

Returns whether the given lock mode will cause a read-uncommitted when used with this cursor, taking into account the default cursor configuration.

checkUpdatesAllowed

protected void checkUpdatesAllowed(java.lang.String operation)
                            throws DatabaseException

Throws:

DatabaseException

checkState

void checkState(boolean mustBeInitialized)
          throws DatabaseException

Checks the environment and cursor state.

Throws:

DatabaseException

checkEnv

void checkEnv()
        throws RunRecoveryException

Throws:

RunRecoveryException - if the underlying environment is invalid.

trace

void trace(java.util.logging.Level level,
           java.lang.String methodName,
           DatabaseEntry key,
           DatabaseEntry data,
           LockMode lockMode)

Sends trace messages to the java.util.logger. Don't rely on the logger alone to conditionalize whether we send this message, we don't even want to construct the message if the level is not enabled.

trace

void trace(java.util.logging.Level level,
           java.lang.String methodName,
           LockMode lockMode)

Sends trace messages to the java.util.logger. Don't rely on the logger alone to conditionalize whether we send this message, we don't even want to construct the message if the level is not enabled.