com.sleepycat.je
Class Cursor

java.lang.Object
  extended by com.sleepycat.je.Cursor
All Implemented Interfaces:
ForwardCursor, Closeable
Direct Known Subclasses:
SecondaryCursor

public class Cursor
extends Object
implements ForwardCursor

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, with one exception: the close method itself may be called any number of times to simplify error handling.

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

Using Partial DatabaseEntry Parameters

The DatabaseEntry Partial property can be used to optimize in certain cases. This provides varying degrees of performance benefits that depend on the specific operation and use of READ_UNCOMMITTED isolation, as described below.

When retrieving a record with a Database or Cursor method, if only the key is needed by the application then the retrieval of the data item can be suppressed using the Partial property. If setPartial(0, 0, true) is called for the DatabaseEntry passed as the data parameter, the data item will not be returned by the Database or Cursor method.

Suppressing the return of the data item potentially has a large performance benefit when the READ_UNCOMMITTED isolation mode is used. In this case, if the record data is not in the JE cache, it will not be read from disk. The performance benefit is potentially large because random access disk reads may be reduced. Examples are:

For other isolation modes (READ_COMMITTED, REPEATABLE_READ and SERIALIZABLE), the performance benefit is not as significant. In this case, the data item must be read into the JE cache if it is not already present, in order to lock the record. The only performance benefit is that the data will not be copied from the JE cache to the application's entry parameter.

For information on specifying isolation modes, see LockMode, CursorConfig and TransactionConfig.

The Partial property may also be used to retrieve or update only a portion of a data item. This avoids copying the entire record between the JE cache and the application data parameter. However, this feature is not currently fully optimized, since the entire record is always read or written to the database, and the entire record is cached. A partial update may be performed only with Cursor.putCurrent.

In limited cases, the Partial property may also be used to retrieve a partial key item. For example, a DatabaseEntry with a Partial property may be passed to getNext. However, in practice this has limited value since the entire key is usually needed by the application, and the benefit of copying a portion of the key is generally very small. Partial key items may not be passed to methods that use the key as an input parameter, for example, getSearchKey. In general, the usefulness of partial key items is very limited.


Field Summary
(package private)  CursorConfig config
          The CursorConfig used to configure this cursor.
(package private)  CursorImpl cursorImpl
          The underlying cursor.
(package private) static int READ_PRIMARY_MAX_RETRIES
           
(package private) static int SLEEP_BEFORE_READ_PRIMARY_RETRY
           
 
Constructor Summary
Cursor(Cursor cursor, boolean samePosition)
          Copy constructor.
Cursor(DatabaseImpl databaseImpl, Locker locker, CursorConfig cursorConfig, boolean retainNonTxnLocks)
          Creates a cursor for internal use, without a Database handle.
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) static void checkArgsNoValRequired(DatabaseEntry key, DatabaseEntry data)
          Note that this flavor of checkArgs allows the key and data to be null.
(package private) static void checkArgsValRequired(DatabaseEntry key, DatabaseEntry data)
          Note that this flavor of checkArgs requires that the key and data are not null.
(package private)  void checkEnv()
           
(package private)  boolean checkForPrimaryUpdate(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, int retries)
          Checks for a secondary corruption caused by a primary record update during a read-uncommitted read.
(package private)  void checkState(boolean mustBeInitialized)
          Checks the environment and cursor state.
protected  void checkUpdatesAllowed(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.
 long countEstimate()
          Returns a rough estimate of the count of the number of data items for the key to which the cursor refers.
(package private)  long countEstimateInternal()
          Estimates duplicate count without parameter checking.
(package private)  int countInternal()
          Counts duplicates without parameter checking.
 OperationStatus delete()
          Deletes the key/data pair to which the cursor refers.
(package private)  OperationStatus deleteInternal(ReplicationContext repContext)
          Internal version of delete() that does no parameter checking.
(package private)  OperationStatus deleteNoNotify(ReplicationContext repContext)
          Delete at current position.
 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 subsequent 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 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 getNextAfterPrefix(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
           
 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, 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 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 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)
          Internal version of getFirst/getLast that does no parameter checking.
 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 putForReplay(byte[] key, LN ln, PutMode putMode, ReplicationContext repContext)
          Version of putInternal that allows passing an existing LN and does not interpret duplicates.
(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.
 OperationStatus putNoOverwrite(DatabaseEntry key, DatabaseEntry data)
          Stores a key/data pair into the database.
(package private)  OperationStatus readPrimaryAfterGet(Database priDb, DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode, int retries)
          Reads the primary data for a primary key that was read via a secondary cursor, or a regular Cursor in the role of a secondary cursor.
(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.
(package private)  OperationStatus searchForReplay(DatabaseEntry key, DatabaseEntry data, LockMode lockMode, CursorImpl.SearchMode searchMode)
          Version of search that does not interpret duplicates.
 void setCacheMode(CacheMode cacheMode)
          Sets the CacheMode used for subsequent operations performed using this cursor.
(package private)  void setNonCloning(boolean nonCloning)
          Prevents this cursor from being cloned to perform an operation that changes the cursor position.
 void setRangeConstraint(RangeConstraint rangeConstraint)
           
 long skipNext(long maxCount, DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
          Skips forward a given number of key/data pairs and returns the number by which the cursor is moved.
 long skipPrev(long maxCount, DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
          Skips backward a given number of key/data pairs and returns the number by which the cursor is moved.
(package private)  void trace(Level level, String methodName, DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
          Sends trace messages to the java.util.logger.
(package private)  void trace(Level level, 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

READ_PRIMARY_MAX_RETRIES

static final int READ_PRIMARY_MAX_RETRIES
See Also:
Constant Field Values

SLEEP_BEFORE_READ_PRIMARY_RETRY

static final int SLEEP_BEFORE_READ_PRIMARY_RETRY
See Also:
Constant Field Values

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


Cursor

Cursor(Database dbHandle,
       Locker locker,
       CursorConfig cursorConfig)
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 succeeds.


Cursor

Cursor(Database dbHandle,
       Locker locker,
       CursorConfig cursorConfig,
       boolean retainNonTxnLocks)
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.


Cursor

Cursor(DatabaseImpl databaseImpl,
       Locker locker,
       CursorConfig cursorConfig,
       boolean retainNonTxnLocks)
Creates a cursor for internal use, without a Database handle.


Cursor

Cursor(Cursor cursor,
       boolean samePosition)
Copy constructor.

Method Detail

setNonCloning

void setNonCloning(boolean nonCloning)
Prevents this cursor from being cloned to perform an operation that changes the cursor position. [#13879] NonCloning is an optimization used for Database.get/put operations. Normally cloning is used before an operation to allow use of the old cursor position after the operation fails. With the Database operations, if an operation fails the cursor is simply discarded. NonCloning cursors are also used for internal operations. They can also be used to avoid deadlocks for non-transactional or read-committed modes, because with a NonCloning cursor the lock at the old position is released before getting the lock at the new position. With a regular cursor, the lock at the old position is held until getting the lock at the new position, meaning that two locks are held at a time and there is a possibility of deadlocks.


getCursorImpl

CursorImpl getCursorImpl()
Internal entrypoint.


getDatabase

public Database getDatabase()
Returns the Database handle associated with this Cursor.

Specified by:
getDatabase in interface ForwardCursor
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.

getCacheMode

public CacheMode getCacheMode()
Returns the CacheMode used for subsequent operations performed using this cursor. If setCacheMode(com.sleepycat.je.CacheMode) has not been called with a non-null value, the configured Database or Environment default is returned.

Returns:
the CacheMode used for subsequent operations using this cursor.
See Also:
setCacheMode(com.sleepycat.je.CacheMode)

setCacheMode

public void setCacheMode(CacheMode cacheMode)
Sets the CacheMode used for subsequent operations performed using this cursor. This method may be used to override the defaults specified using DatabaseConfig.setCacheMode(com.sleepycat.je.CacheMode) and EnvironmentMutableConfig.setCacheMode(com.sleepycat.je.CacheMode).

Parameters:
cacheMode - is the CacheMode used for subsequent operations using this cursor, or null to configure the Database or Environment default.
See Also:
for further details.

setRangeConstraint

public void setRangeConstraint(RangeConstraint rangeConstraint)

close

public 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, with one exception: the close method itself may be called any number of times.

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

count

public int count()
          throws DatabaseException
Returns a count of the number of data items for the key to which the cursor refers.

If the database is configured for duplicates, the database is scanned internally, without taking any record locks, to count the number of non-deleted entries. Although the internal scan is more efficient under some conditions, the result is the same as if a cursor were used to iterate over the entries using LockMode.READ_UNCOMMITTED.

If the database is not configured for duplicates, the count returned is always zero or one, depending on the record at the cursor position is deleted or not.

The cost of this method is directly proportional to the number of records scanned.

Returns:
A count of the number of data items for the key to which the cursor refers.
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 cursor is uninitialized (not positioned on a record), or the non-transactional cursor was created in a different thread.
DatabaseException

countEstimate

public long countEstimate()
                   throws DatabaseException
Returns a rough estimate of the count of the number of data items for the key to which the cursor refers.

If the database is configured for duplicates, a quick estimate of the number of records is computed using information in the Btree. Because the Btree is unbalanced, in some cases the estimate may be off by a factor of two or more. The estimate is accurate when the number of records is less than the configured NodeMaxEntries.

If the database is not configured for duplicates, the count returned is always zero or one, depending on the record at the cursor position is deleted or not.

The cost of this method is fixed, rather than being proportional to the number of records scanned. Because its accuracy is variable, this method should normally be used when accuracy is not required, such as for query optimization, and a fixed cost operation is needed. For example, this method is used internally for determining the index processing order in a JoinCursor.

Returns:
an estimate of the count of the number of data items for the key to which the cursor refers.
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 cursor is uninitialized (not positioned on a record), or the non-transactional cursor was created in a different thread.
DatabaseException

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:
DatabasePreemptedException - in a replicated environment if the master has truncated, removed or renamed the database.
OperationFailureException - if this exception occurred earlier and caused the transaction to be invalidated.
EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.
IllegalStateException - if the cursor or database has been closed.
DatabaseException

delete

public OperationStatus delete()
                       throws LockConflictException,
                              DatabaseException,
                              UnsupportedOperationException
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:
OperationStatus.KEYEMPTY if the key/pair at the cursor position has been deleted; otherwise, OperationStatus.SUCCESS.
Throws:
OperationFailureException - if one of the Write Operation Failures occurs.
EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.
UnsupportedOperationException - if the database is transactional but this cursor was not opened with a non-null transaction parameter, or the database is read-only.
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.
LockConflictException
DatabaseException

put

public OperationStatus put(DatabaseEntry key,
                           DatabaseEntry data)
                    throws DatabaseException,
                           UnsupportedOperationException
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:
OperationFailureException - if one of the Write Operation Failures occurs.
EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.
UnsupportedOperationException - if the database is transactional but this cursor was not opened with a non-null transaction parameter, or the database is read-only.
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

putNoOverwrite

public OperationStatus putNoOverwrite(DatabaseEntry key,
                                      DatabaseEntry data)
                               throws DatabaseException,
                                      UnsupportedOperationException
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:
OperationFailureException - if one of the Write Operation Failures occurs.
EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.
UnsupportedOperationException - if the database is transactional but this cursor was not opened with a non-null transaction parameter, or the database is read-only.
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

putNoDupData

public OperationStatus putNoDupData(DatabaseEntry key,
                                    DatabaseEntry data)
                             throws DatabaseException,
                                    UnsupportedOperationException
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:
OperationFailureException - if one of the Write Operation Failures occurs.
EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.
UnsupportedOperationException - if the database is transactional but this cursor was not opened with a non-null transaction parameter, or the database is read-only, or the database is not configured for duplicates.
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

putCurrent

public OperationStatus putCurrent(DatabaseEntry data)
                           throws DatabaseException,
                                  UnsupportedOperationException
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 DuplicateDataException 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. A partial data item may be specified to optimize for partial data update.
Returns:
OperationStatus.KEYEMPTY if the key/pair at the cursor position has been deleted; otherwise, OperationStatus.SUCCESS.
Throws:
DuplicateDataException - if the old and new data are not equal according to the configured duplicate comparator or default comparator.
OperationFailureException - if one of the Write Operation Failures occurs.
EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.
UnsupportedOperationException - if the database is transactional but this cursor was not opened with a non-null transaction parameter, or the database is read-only.
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

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.

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.

Specified by:
getCurrent in interface ForwardCursor
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

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.

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

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.

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

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

Specified by:
getNext in interface ForwardCursor
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

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.

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

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.

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

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

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

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.

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

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.

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

skipNext

public long skipNext(long maxCount,
                     DatabaseEntry key,
                     DatabaseEntry data,
                     LockMode lockMode)
              throws DatabaseException
Skips forward a given number of key/data pairs and returns the number by which the cursor is moved.

Without regard to performance, calling this method is equivalent to repeatedly calling getNext with LockMode.READ_UNCOMMITTED to skip over the desired number of key/data pairs, and then calling getCurrent with the lockMode parameter to return the final key/data pair.

With regard to performance, this method is optimized to skip over key/value pairs using a smaller number of Btree operations. When there is no contention on the bottom internal nodes (BINs) and all BINs are in cache, the number of Btree operations is reduced by roughly two orders of magnitude, where the exact number depends on the EnvironmentConfig.NODE_MAX_ENTRIES setting. When there is contention on BINs or fetching BINs is required, the scan is broken up into smaller operations to avoid blocking other threads for long time periods.

If the returned count is greater than zero, then the key/data pair at the new cursor position is also returned. If zero is returned, then there are no key/value pairs that follow the cursor position and a key/data pair is not returned.

If this method fails for any reason or if zero is returned, 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:
maxCount - the maximum number of key/data pairs to skip, i.e., the maximum number by which the cursor should be moved; must be greater than zero.
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:
the number of key/data pairs skipped, i.e., the number by which the cursor has moved; if zero is returned, the cursor position is unchanged and the key/data pair is not returned.
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 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

skipPrev

public long skipPrev(long maxCount,
                     DatabaseEntry key,
                     DatabaseEntry data,
                     LockMode lockMode)
              throws DatabaseException
Skips backward a given number of key/data pairs and returns the number by which the cursor is moved.

Without regard to performance, calling this method is equivalent to repeatedly calling getPrev with LockMode.READ_UNCOMMITTED to skip over the desired number of key/data pairs, and then calling getCurrent with the lockMode parameter to return the final key/data pair.

With regard to performance, this method is optimized to skip over key/value pairs using a smaller number of Btree operations. When there is no contention on the bottom internal nodes (BINs) and all BINs are in cache, the number of Btree operations is reduced by roughly two orders of magnitude, where the exact number depends on the EnvironmentConfig.NODE_MAX_ENTRIES setting. When there is contention on BINs or fetching BINs is required, the scan is broken up into smaller operations to avoid blocking other threads for long time periods.

If the returned count is greater than zero, then the key/data pair at the new cursor position is also returned. If zero is returned, then there are no key/value pairs that follow the cursor position and a key/data pair is not returned.

If this method fails for any reason or if zero is returned, 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:
maxCount - the maximum number of key/data pairs to skip, i.e., the maximum number by which the cursor should be moved; must be greater than zero.
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:
the number of key/data pairs skipped, i.e., the number by which the cursor has moved; if zero is returned, the cursor position is unchanged and the key/data pair is not returned.
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 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

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.

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

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

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 used as input and returned as output. It must be initialized with a non-null byte array by the caller. A partial data item may be specified to optimize for key only or partial data retrieval.
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. 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

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.

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

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.

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

getNextAfterPrefix

public OperationStatus getNextAfterPrefix(DatabaseEntry key,
                                          DatabaseEntry data,
                                          LockMode lockMode)

countInternal

int countInternal()
Counts duplicates without parameter checking. No need to dup the cursor because we never change the position.


countEstimateInternal

long countEstimateInternal()
Estimates duplicate count without parameter checking. No need to dup the cursor because we never change the position.


deleteInternal

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


deleteNoNotify

OperationStatus deleteNoNotify(ReplicationContext repContext)
Delete at current position. Does not notify triggers (does not perform secondary updates).


putInternal

OperationStatus putInternal(DatabaseEntry key,
                            DatabaseEntry data,
                            PutMode putMode)
Internal version of put that does no parameter checking. Interprets duplicates, notifies triggers, and prevents phantoms.


putForReplay

OperationStatus putForReplay(byte[] key,
                             LN ln,
                             PutMode putMode,
                             ReplicationContext repContext)
Version of putInternal that allows passing an existing LN and does not interpret duplicates. Used for replication stream replay. Notifies triggers and prevents phantoms.


position

OperationStatus position(DatabaseEntry key,
                         DatabaseEntry data,
                         LockMode lockMode,
                         boolean first)
Internal version of getFirst/getLast that does no parameter checking. Interprets duplicates.


search

OperationStatus search(DatabaseEntry key,
                       DatabaseEntry data,
                       LockMode lockMode,
                       CursorImpl.SearchMode searchMode)
Performs search by key, data, or both. Prevents phantoms.


searchForReplay

OperationStatus searchForReplay(DatabaseEntry key,
                                DatabaseEntry data,
                                LockMode lockMode,
                                CursorImpl.SearchMode searchMode)
Version of search that does not interpret duplicates. Used for replication stream replay. Notifies triggers and prevents phantoms.


retrieveNext

OperationStatus retrieveNext(DatabaseEntry key,
                             DatabaseEntry data,
                             LockMode lockMode,
                             GetMode getMode)
Retrieves the next or previous record. Prevents phantoms.


getCurrentInternal

OperationStatus getCurrentInternal(DatabaseEntry key,
                                   DatabaseEntry data,
                                   LockMode lockMode)
Returns the current key and data. There is no need to use a dup cursor or prevent phantoms.


readPrimaryAfterGet

OperationStatus readPrimaryAfterGet(Database priDb,
                                    DatabaseEntry key,
                                    DatabaseEntry pKey,
                                    DatabaseEntry data,
                                    LockMode lockMode,
                                    int retries)
                              throws DatabaseException
Reads the primary data for a primary key that was read via a secondary cursor, or a regular Cursor in the role of a secondary cursor. This method is in the Cursor class, rather than in SecondaryCursor, to support joins with plain Cursors [#21258]. When SUCCESS is returned by this method, the caller should return SUCCESS. When KEYEMPTY is returned, the caller should treat this as a deleted record and either retry the operation (in the case of position, search, and retrieveNext) or return KEYEMPTY (in the case of getCurrent). KEYEMPTY is only returned when read-uncommitted is used.

Returns:
SUCCESS if the primary was read succesfully, or KEYEMPTY if using read-uncommitted and the primary has been deleted, or KEYEMPTY if using read-uncommitted and the primary has been updated and no longer contains the secondary key.
Throws:
SecondaryIntegrityException - to indicate a corrupt secondary reference if the primary record is not found and read-uncommitted is not used (or read-uncommitted is used, but we cannot verify that a valid deletion has occured or the number of retries has been exceeded).
DatabaseException

checkForPrimaryUpdate

boolean checkForPrimaryUpdate(DatabaseEntry key,
                              DatabaseEntry pKey,
                              DatabaseEntry data,
                              int retries)
Checks for a secondary corruption caused by a primary record update during a read-uncommitted read. Checking in this method is not possible because there is no secondary key creator available. It is overridden by SecondaryCursor. This method is in the Cursor class, rather than in SecondaryCursor, to support joins with plain Cursors [#21258].


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(String operation)
Throws:
UnsupportedOperationException - via all Cursor write methods.

checkArgsNoValRequired

static void checkArgsNoValRequired(DatabaseEntry key,
                                   DatabaseEntry data)
Note that this flavor of checkArgs allows the key and data to be null.


checkArgsValRequired

static void checkArgsValRequired(DatabaseEntry key,
                                 DatabaseEntry data)
Note that this flavor of checkArgs requires that the key and data are not null.


checkState

void checkState(boolean mustBeInitialized)
Checks the environment and cursor state.


checkEnv

void checkEnv()
Throws:
EnvironmentFailureException - if the underlying environment is invalid.

trace

void trace(Level level,
           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(Level level,
           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.



Copyright (c) 2004-2012 Oracle. All rights reserved.