com.sleepycat.je

Class SecondaryCursor

java.lang.Object

com.sleepycat.je.Cursor

com.sleepycat.je.SecondaryCursor

All Implemented Interfaces:

ForwardCursor, java.io.Closeable, java.lang.AutoCloseable

public class SecondaryCursor
extends Cursor

A database cursor for a secondary database. Cursors are not thread safe and the application is responsible for coordinating any multithreaded access to a single cursor object.

Secondary cursors are returned by SecondaryDatabase.openCursor and SecondaryDatabase.openSecondaryCursor. The distinguishing characteristics of a secondary cursor are:

• Direct calls to put() methods on a secondary cursor are prohibited.
• The delete(com.sleepycat.je.WriteOptions) method of a secondary cursor will delete the primary record and as well as all its associated secondary records.
• Calls to all get methods will return the data from the associated primary database.
• Additional get method signatures are provided to return the primary key in an additional pKey parameter.
• Calls to dup(boolean) will return a SecondaryCursor.

To obtain a secondary cursor with default attributes:

     SecondaryCursor cursor = myDb.openSecondaryCursor(txn, null);
 

To customize the attributes of a cursor, use a CursorConfig object.

     CursorConfig config = new CursorConfig();
     config.setReadUncommitted(true);
     SecondaryCursor cursor = myDb.openSecondaryCursor(txn, config);
 

Method Summary

Modifier and Type	Method and Description
OperationStatus	delete() Delete the record to which the cursor refers from the primary database and all secondary indices.
OperationResult	delete(WriteOptions options) Delete the record to which the cursor refers from the primary database and all secondary indices.
SecondaryCursor	dup(boolean samePosition) Returns a new SecondaryCursor for the same transaction as the original cursor.
SecondaryCursor	dupSecondary(boolean samePosition) Deprecated. As of JE 4.0.13, replaced by Cursor.dup(boolean).
OperationResult	get(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, Get getType, ReadOptions options) Moves the cursor to a record according to the specified Get type.
OperationResult	get(DatabaseEntry key, DatabaseEntry data, Get getType, ReadOptions options) Moves the cursor to a record according to the specified Get type.
OperationStatus	getCurrent(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode) Returns the key/data pair to which the cursor refers.
OperationStatus	getCurrent(DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Returns the key/data pair to which the cursor refers.
SecondaryDatabase	getDatabase() Returns the Database handle associated with this Cursor.
OperationStatus	getFirst(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode) Move the cursor to the first key/data pair of the database, and return that pair.
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 pKey, DatabaseEntry data, LockMode lockMode) Move the cursor to the last 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 returns that pair.
OperationStatus	getNext(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode) Move the cursor to the next key/data pair and return that pair.
OperationStatus	getNext(DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Moves the cursor to the next key/data pair and returns that pair.
OperationStatus	getNextDup(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode) If the next key/data pair of the database is a duplicate data record for the current key/data pair, move the cursor to the next key/data pair of the database 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 returns that pair.
OperationStatus	getNextNoDup(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode) Move the cursor to the next non-duplicate key/data pair and return 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 pKey, DatabaseEntry data, LockMode lockMode) Move the cursor to the previous 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 returns that pair.
OperationStatus	getPrevDup(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode) If the previous key/data pair of the database is a duplicate data record for the current key/data pair, move the cursor to the previous key/data pair of the database 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 returns that pair.
OperationStatus	getPrevNoDup(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode) Move the cursor to the previous non-duplicate key/data pair and return 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.
Database	getPrimaryDatabase() Returns the primary Database associated with this cursor.
OperationStatus	getSearchBoth(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode) Move the cursor to the specified secondary and primary key, where both the primary and secondary key items must match.
OperationStatus	getSearchBoth(DatabaseEntry key, DatabaseEntry data, LockMode lockMode) This operation is not allowed with this method signature.
OperationStatus	getSearchBothRange(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode) Move the cursor to the specified secondary key and closest matching primary key of the database.
OperationStatus	getSearchBothRange(DatabaseEntry key, DatabaseEntry data, LockMode lockMode) This operation is not allowed with this method signature.
OperationStatus	getSearchKey(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode) Move the cursor to the given key of the database, and return the datum associated with the given key.
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 pKey, DatabaseEntry data, LockMode lockMode) Move the cursor to the closest matching key of the database, and return the data item associated with the matching 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.
OperationStatus	put(DatabaseEntry key, DatabaseEntry data) This operation is not allowed on a secondary cursor.
OperationResult	put(DatabaseEntry key, DatabaseEntry data, Put putType, WriteOptions options) This operation is not allowed on a secondary cursor.
OperationStatus	putCurrent(DatabaseEntry data) This operation is not allowed on a secondary cursor.
OperationStatus	putNoDupData(DatabaseEntry key, DatabaseEntry data) This operation is not allowed on a secondary cursor.
OperationStatus	putNoOverwrite(DatabaseEntry key, DatabaseEntry data) This operation is not allowed on a secondary cursor.

Methods inherited from class com.sleepycat.je.Cursor

close, count, countEstimate, getCacheMode, getConfig, setCacheMode, skipNext, skipPrev

Methods inherited from class java.lang.Object

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

Method Detail

getDatabase

public SecondaryDatabase getDatabase()

Returns the Database handle associated with this Cursor.

Specified by:

getDatabase in interface ForwardCursor

Overrides:

getDatabase in class Cursor

Returns:

The Database handle associated with this Cursor.

getPrimaryDatabase

public Database getPrimaryDatabase()

Returns the primary Database associated with this cursor.

Calling this method is the equivalent of the following expression:

         getDatabase().getPrimaryDatabase()
 

Returns:

The primary Database associated with this cursor.

dup

public SecondaryCursor dup(boolean samePosition)

Returns a new SecondaryCursor for the same transaction as the original cursor.

Overrides:

dup in class Cursor

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.

dupSecondary

public SecondaryCursor dupSecondary(boolean samePosition)

Deprecated. As of JE 4.0.13, replaced by Cursor.dup(boolean).

Returns a new copy of the cursor as a SecondaryCursor.

Calling this method is the equivalent of calling dup(boolean) and casting the result to SecondaryCursor.

See Also:

dup(boolean)

delete

public OperationResult delete(WriteOptions options)

Delete the record to which the cursor refers from the primary database and all secondary indices.

This method behaves as if Database.delete(Transaction, DatabaseEntry, WriteOptions) were called for the primary database, using the primary key associated with this cursor position.

The cursor position is unchanged after a delete, and subsequent calls to cursor functions expecting the cursor to refer to an existing record will fail.

WARNING: Unlike read operations using a SecondaryCursor, write operations like this one are deadlock-prone.

Overrides:

delete in class Cursor

Parameters:

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

Returns:

the OperationResult if the record is deleted, else null if the record at the cursor position has already been deleted.

delete

public OperationStatus delete()

Delete the record to which the cursor refers from the primary database and all secondary indices.

This method behaves as if Database.delete(Transaction, DatabaseEntry, WriteOptions) were called for the primary database, using the primary key associated with this cursor position.

The cursor position is unchanged after a delete, and subsequent calls to cursor functions expecting the cursor to refer to an existing record will fail.

Calling this method is equivalent to calling delete(WriteOptions).

Overrides:

delete in class Cursor

Returns:

OperationStatus.KEYEMPTY if the record at the cursor position has already been deleted; otherwise, OperationStatus.SUCCESS.

put

public OperationResult put(DatabaseEntry key,
                           DatabaseEntry data,
                           Put putType,
                           WriteOptions options)

This operation is not allowed on a secondary cursor. UnsupportedOperationException will always be thrown by this method. The corresponding method on the primary cursor should be used instead.

Overrides:

put in class Cursor

Parameters:

key - the key used as input. Must be null when putType is Put.CURRENT.

data - the data used as input. May be partial only when putType is Put.CURRENT.

putType - the Put operation type. May not be null.

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

Returns:

the OperationResult if the record is written, else null.

put

public OperationStatus put(DatabaseEntry key,
                           DatabaseEntry data)

This operation is not allowed on a secondary cursor. UnsupportedOperationException will always be thrown by this method. The corresponding method on the primary cursor should be used instead.

Overrides:

put in class Cursor

Parameters:

key - the key used as input..

data - the data used as input.

Returns:

OperationStatus.SUCCESS.

putNoOverwrite

public OperationStatus putNoOverwrite(DatabaseEntry key,
                                      DatabaseEntry data)

This operation is not allowed on a secondary cursor. UnsupportedOperationException will always be thrown by this method. The corresponding method on the primary cursor should be used instead.

Overrides:

putNoOverwrite in class Cursor

Parameters:

key - the key used as input..

data - the data used as input.

Returns:

OperationStatus.KEYEXIST if the key already appears in the database, else OperationStatus.SUCCESS

putNoDupData

public OperationStatus putNoDupData(DatabaseEntry key,
                                    DatabaseEntry data)

This operation is not allowed on a secondary cursor. UnsupportedOperationException will always be thrown by this method. The corresponding method on the primary cursor should be used instead.

Overrides:

putNoDupData in class Cursor

Parameters:

key - the key used as input..

data - the data used as input.

Returns:

OperationStatus.KEYEXIST if the key/data pair already appears in the database, else OperationStatus.SUCCESS

putCurrent

public OperationStatus putCurrent(DatabaseEntry data)

This operation is not allowed on a secondary cursor. UnsupportedOperationException will always be thrown by this method. The corresponding method on the primary cursor should be used instead.

Overrides:

putCurrent in class Cursor

Parameters:

data - the data used as input. 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.

get

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

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

The difference between this method and the method it overrides in Cursor is that the key here is defined as the secondary records's key, and the data is defined as the primary record's data. In addition, two operations are not supported by this method: Get.SEARCH_BOTH and Get.SEARCH_BOTH_GTE.

Specified by:

get in interface ForwardCursor

Overrides:

get in class Cursor

Parameters:

key - the key input or output parameter, depending on getType.

data - the data input or output parameter, depending on getType.

getType - the Get operation type. May not be null.

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

Returns:

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

get

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

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

If the operation succeeds, the record at the resulting cursor position will be locked according to the lock mode specified, the key, primary key, and/or data will be returned via the (non-null) DatabaseEntry parameters, and a non-null OperationResult will be returned. If the operation fails because the record requested is not found, null is returned.

The following table lists each allowed operation and whether the key, pKey and data parameters are input or output parameters. Also specified is whether the cursor must be initialized (positioned on a record) before calling this method. See the individual Get operations for more information.

Get operation	Description	'key' parameter	'pKey' parameter	'data' parameter	Cursor position must be initialized?
Get.SEARCH	Searches using an exact match by key.	input	output	output	no
Get.SEARCH_BOTH	Searches using an exact match by key and pKey.	input	input	output	no
Get.SEARCH_GTE	Searches using a GTE match by key.	input/output	output	output	no
Get.SEARCH_BOTH_GTE	Searches using an exact match by key and a GTE match by pKey.	input	input/output	output	no
Get.CURRENT	Accesses the current record	output	output	output	yes
Get.FIRST	Finds the first record in the database.	output	output	output	no
Get.LAST	Finds the last record in the database.	output	output	output	no
Get.NEXT	Moves to the next record.	output	output	output	no**
Get.NEXT_DUP	Moves to the next record with the same key.	output	output	output	yes
Get.NEXT_NO_DUP	Moves to the next record with a different key.	output	output	output	no**
Get.PREV	Moves to the previous record.	output	output	output	no**
Get.PREV_DUP	Moves to the previous record with the same key.	output	output	output	yes
Get.PREV_NO_DUP	Moves to the previous record with a different key.	output	output	output	no**

** - For these 'next' and 'previous' operations the cursor may be uninitialized, in which case the cursor will be moved to the first or last record, respectively.

Parameters:

key - the secondary key input or output parameter, depending on getType.

pKey - the primary key input or output parameter, depending on getType.

data - the primary data output parameter.

getType - the Get operation type. May not be null.

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

Returns:

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

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

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

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

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

Since:

7.0

getCurrent

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

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

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

The difference between this method and the method it overrides in Cursor is that the key here is defined as the secondary records's key, and the data is defined as the primary record's data.

Specified by:

getCurrent in interface ForwardCursor

Overrides:

getCurrent in class Cursor

Parameters:

key - the key returned as output.

data - the data returned as output.

lockMode - the locking attributes; if null, default attributes are used. LockMode.READ_COMMITTED is not allowed.

Returns:

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

getCurrent

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

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

Parameters:

key - the secondary key returned as output. Its byte array does not need to be initialized by the caller.

pKey - the primary key returned as output. Its byte array does not need to be initialized by the caller.

data - the primary 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.

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

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

java.lang.IllegalArgumentException - if an invalid parameter is specified, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

getFirst

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

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.

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

The difference between this method and the method it overrides in Cursor is that the key here is defined as the secondary records's key, and the data is defined as the primary record's data.

Overrides:

getFirst in class Cursor

Parameters:

key - the key returned as output.

data - the data returned as output.

lockMode - the locking attributes; if null, default attributes are used. LockMode.READ_COMMITTED is not allowed.

Returns:

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

getFirst

public OperationStatus getFirst(DatabaseEntry key,
                                DatabaseEntry pKey,
                                DatabaseEntry data,
                                LockMode lockMode)

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

Parameters:

key - the secondary key returned as output. Its byte array does not need to be initialized by the caller.

pKey - the primary key returned as output. Its byte array does not need to be initialized by the caller.

data - the primary 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.

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

java.lang.IllegalArgumentException - if an invalid parameter is specified, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

getLast

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

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.

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

The difference between this method and the method it overrides in Cursor is that the key here is defined as the secondary records's key, and the data is defined as the primary record's data.

Overrides:

getLast in class Cursor

Parameters:

key - the key returned as output.

data - the data returned as output.

lockMode - the locking attributes; if null, default attributes are used. LockMode.READ_COMMITTED is not allowed.

Returns:

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

getLast

public OperationStatus getLast(DatabaseEntry key,
                               DatabaseEntry pKey,
                               DatabaseEntry data,
                               LockMode lockMode)

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

Parameters:

key - the secondary key returned as output. Its byte array does not need to be initialized by the caller.

pKey - the primary key returned as output. Its byte array does not need to be initialized by the caller.

data - the primary 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.

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

java.lang.IllegalArgumentException - if an invalid parameter is specified, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

getNext

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

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

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

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.

The difference between this method and the method it overrides in Cursor is that the key here is defined as the secondary records's key, and the data is defined as the primary record's data.

Specified by:

getNext in interface ForwardCursor

Overrides:

getNext in class Cursor

Parameters:

key - the key returned as output.

data - the data returned as output.

lockMode - the locking attributes; if null, default attributes are used. LockMode.READ_COMMITTED is not allowed.

Returns:

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

getNext

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

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

Parameters:

key - the secondary key returned as output. Its byte array does not need to be initialized by the caller.

pKey - the primary key returned as output. Its byte array does not need to be initialized by the caller.

data - the primary 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.

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

java.lang.IllegalArgumentException - if an invalid parameter is specified, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

getNextDup

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

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

The difference between this method and the method it overrides in Cursor is that the key here is defined as the secondary records's key, and the data is defined as the primary record's data.

Overrides:

getNextDup in class Cursor

Parameters:

key - the key returned as output.

data - the data returned as output.

lockMode - the locking attributes; if null, default attributes are used. LockMode.READ_COMMITTED is not allowed.

Returns:

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

getNextDup

public OperationStatus getNextDup(DatabaseEntry key,
                                  DatabaseEntry pKey,
                                  DatabaseEntry data,
                                  LockMode lockMode)

If the next key/data pair of the database is a duplicate data record for the current key/data pair, move the cursor to the next key/data pair of the database and return that pair.

Parameters:

key - the secondary key returned as output. Its byte array does not need to be initialized by the caller.

pKey - the primary key returned as output. Its byte array does not need to be initialized by the caller.

data - the primary 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.

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

java.lang.IllegalArgumentException - if an invalid parameter is specified, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

getNextNoDup

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

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.

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

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.

The difference between this method and the method it overrides in Cursor is that the key here is defined as the secondary records's key, and the data is defined as the primary record's data.

Overrides:

getNextNoDup in class Cursor

Parameters:

key - the key returned as output.

data - the data returned as output.

lockMode - the locking attributes; if null, default attributes are used. LockMode.READ_COMMITTED is not allowed.

Returns:

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

getNextNoDup

public OperationStatus getNextNoDup(DatabaseEntry key,
                                    DatabaseEntry pKey,
                                    DatabaseEntry data,
                                    LockMode lockMode)

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

Parameters:

key - the secondary key returned as output. Its byte array does not need to be initialized by the caller.

pKey - the primary key returned as output. Its byte array does not need to be initialized by the caller.

data - the primary 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.

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

java.lang.IllegalArgumentException - if an invalid parameter is specified, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

getPrev

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

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

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

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.

The difference between this method and the method it overrides in Cursor is that the key here is defined as the secondary records's key, and the data is defined as the primary record's data.

Overrides:

getPrev in class Cursor

Parameters:

key - the key returned as output.

data - the data returned as output.

lockMode - the locking attributes; if null, default attributes are used. LockMode.READ_COMMITTED is not allowed.

Returns:

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

getPrev

public OperationStatus getPrev(DatabaseEntry key,
                               DatabaseEntry pKey,
                               DatabaseEntry data,
                               LockMode lockMode)

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

Parameters:

key - the secondary key returned as output. Its byte array does not need to be initialized by the caller.

pKey - the primary key returned as output. Its byte array does not need to be initialized by the caller.

data - the primary 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.

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

java.lang.IllegalArgumentException - if an invalid parameter is specified, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

getPrevDup

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

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

The difference between this method and the method it overrides in Cursor is that the key here is defined as the secondary records's key, and the data is defined as the primary record's data.

Overrides:

getPrevDup in class Cursor

Parameters:

key - the key returned as output.

data - the data returned as output.

lockMode - the locking attributes; if null, default attributes are used. LockMode.READ_COMMITTED is not allowed.

Returns:

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

getPrevDup

public OperationStatus getPrevDup(DatabaseEntry key,
                                  DatabaseEntry pKey,
                                  DatabaseEntry data,
                                  LockMode lockMode)

If the previous key/data pair of the database is a duplicate data record for the current key/data pair, move the cursor to the previous key/data pair of the database and return that pair.

Parameters:

key - the secondary key returned as output. Its byte array does not need to be initialized by the caller.

pKey - the primary key returned as output. Its byte array does not need to be initialized by the caller.

data - the primary 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.

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

java.lang.IllegalArgumentException - if an invalid parameter is specified, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

getPrevNoDup

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

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.

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

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.

The difference between this method and the method it overrides in Cursor is that the key here is defined as the secondary records's key, and the data is defined as the primary record's data.

Overrides:

getPrevNoDup in class Cursor

Parameters:

key - the key returned as output.

data - the data returned as output.

lockMode - the locking attributes; if null, default attributes are used. LockMode.READ_COMMITTED is not allowed.

Returns:

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

getPrevNoDup

public OperationStatus getPrevNoDup(DatabaseEntry key,
                                    DatabaseEntry pKey,
                                    DatabaseEntry data,
                                    LockMode lockMode)

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

Parameters:

key - the secondary key returned as output. Its byte array does not need to be initialized by the caller.

pKey - the primary key returned as output. Its byte array does not need to be initialized by the caller.

data - the primary 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.

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

java.lang.IllegalArgumentException - if an invalid parameter is specified, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

getSearchKey

public 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. If the matching key has duplicate values, the first data item in the set of duplicates is returned.

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

The difference between this method and the method it overrides in Cursor is that the key here is defined as the secondary records's key, and the data is defined as the primary record's data.

Overrides:

getSearchKey in class Cursor

Parameters:

key - the key used as input.

data - the data returned as output.

lockMode - the locking attributes; if null, default attributes are used. LockMode.READ_COMMITTED is not allowed.

Returns:

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

getSearchKey

public OperationStatus getSearchKey(DatabaseEntry key,
                                    DatabaseEntry pKey,
                                    DatabaseEntry data,
                                    LockMode lockMode)

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

Parameters:

key - the secondary key used as input. It must be initialized with a non-null byte array by the caller.

pKey - the primary key returned as output. Its byte array does not need to be initialized by the caller.

data - the primary 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.

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

java.lang.IllegalArgumentException - if an invalid parameter is specified, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

getSearchKeyRange

public 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. If the matching key has duplicate values, the first data item in the set of duplicates is returned.

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

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.

The difference between this method and the method it overrides in Cursor is that the key here is defined as the secondary records's key, and the data is defined as the primary record's data.

Overrides:

getSearchKeyRange in class Cursor

Parameters:

key - the key used as input and returned as output.

data - the data returned as output.

lockMode - the locking attributes; if null, default attributes are used. LockMode.READ_COMMITTED is not allowed.

Returns:

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

getSearchKeyRange

public OperationStatus getSearchKeyRange(DatabaseEntry key,
                                         DatabaseEntry pKey,
                                         DatabaseEntry data,
                                         LockMode lockMode)

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

Parameters:

key - the secondary key used as input and returned as output. It must be initialized with a non-null byte array by the caller.

pKey - the primary key returned as output. Its byte array does not need to be initialized by the caller.

data - the primary 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.

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

java.lang.IllegalArgumentException - if an invalid parameter is specified, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

getSearchBoth

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

This operation is not allowed with this method signature. UnsupportedOperationException will always be thrown by this method. The corresponding method with the pKey parameter should be used instead.

Overrides:

getSearchBoth in class Cursor

Parameters:

key - the key used as input.

data - the data used as input.

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.

getSearchBoth

public OperationStatus getSearchBoth(DatabaseEntry key,
                                     DatabaseEntry pKey,
                                     DatabaseEntry data,
                                     LockMode lockMode)

Move the cursor to the specified secondary and primary key, where both the primary and secondary key items must match.

Parameters:

key - the secondary key used as input. It must be initialized with a non-null byte array by the caller.

pKey - the primary key used as input. It must be initialized with a non-null byte array by the caller.

data - the primary 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.

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

java.lang.IllegalArgumentException - if an invalid parameter is specified, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

getSearchBothRange

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

This operation is not allowed with this method signature. UnsupportedOperationException will always be thrown by this method. The corresponding method with the pKey parameter should be used instead.

Overrides:

getSearchBothRange in class Cursor

Parameters:

key - the key used as input.

data - the data used as input and returned as output.

lockMode - the locking attributes; if null, default attributes are used. LockMode.READ_COMMITTED is not allowed.

Returns:

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

getSearchBothRange

public OperationStatus getSearchBothRange(DatabaseEntry key,
                                          DatabaseEntry pKey,
                                          DatabaseEntry data,
                                          LockMode lockMode)

Move the cursor to the specified secondary key and closest matching primary key of the database.

In the case of any database supporting sorted duplicate sets, the returned key/data pair is for the smallest primary key greater than or equal to the specified primary key (as determined by the key comparison function), permitting partial matches and range searches in duplicate data sets.

Parameters:

key - the secondary key used as input. It must be initialized with a non-null byte array by the caller.

pKey - the primary key used as input and returned as output. It must be initialized with a non-null byte array by the caller.

data - the primary 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.

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

java.lang.IllegalArgumentException - if an invalid parameter is specified, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.