com.sleepycat.client

Class SSecondaryCursor

java.lang.Object

com.sleepycat.client.SCursor

com.sleepycat.client.SSecondaryCursor

All Implemented Interfaces:

GetHelper, PutHelper, java.lang.AutoCloseable

public class SSecondaryCursor
extends SCursor

A database cursor for a secondary database.

Secondary cursors are returned by SSecondaryDatabase.openCursor(com.sleepycat.client.STransaction, com.sleepycat.client.SCursorConfig). The distinguishing characteristics of a secondary cursor are:

• Direct calls to put() methods on a secondary cursor are prohibited.
• The SCursor.delete() 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 SSecondaryCursor.

To obtain a secondary cursor with default attributes:

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

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

  SCursorConfig config = new SCursorConfig();
  config.setDirtyRead(true);
  SSecondaryCursor cursor = myDb.openSecondaryCursor(txn, config);
 

Nested Class Summary

Nested classes/interfaces inherited from interface com.sleepycat.client.GetHelper

GetHelper.RemoteGetFunction, GetHelper.RemotePGetFunction

Nested classes/interfaces inherited from interface com.sleepycat.client.PutHelper

PutHelper.RemotePutFunction

Field Summary

Fields inherited from class com.sleepycat.client.SCursor

client, tCursor

Method Summary

Modifier and Type	Method and Description
SSecondaryCursor	dup(boolean samePosition) Returns a new SSecondaryCursor for the same transaction as the original cursor.
SOperationStatus	getCurrent(SDatabaseEntry sKey, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode lockMode) Returns the key/data pair to which the cursor refers.
SSecondaryDatabase	getDatabase() Return the SSecondaryDatabase handle associated with this cursor.
SOperationStatus	getFirst(SDatabaseEntry sKey, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode lockMode) Move the cursor to the first key/data pair of the database, and return that pair.
SOperationStatus	getLast(SDatabaseEntry sKey, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode lockMode) Move the cursor to the last key/data pair of the database, and return that pair.
SOperationStatus	getNext(SDatabaseEntry sKey, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode lockMode) Move the cursor to the next key/data pair and return that pair.
SOperationStatus	getNextDup(SDatabaseEntry sKey, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode 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.
SOperationStatus	getNextNoDup(SDatabaseEntry sKey, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode lockMode) Move the cursor to the next non-duplicate key/data pair and return that pair.
SOperationStatus	getPrev(SDatabaseEntry sKey, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode lockMode) Move the cursor to the previous key/data pair and return that pair.
SOperationStatus	getPrevDup(SDatabaseEntry sKey, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode 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.
SOperationStatus	getPrevNoDup(SDatabaseEntry sKey, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode lockMode) Move the cursor to the previous non-duplicate key/data pair and return that pair.
SOperationStatus	getRecordNumber(SDatabaseEntry secondaryRecno, SDatabaseEntry primaryRecno, SLockMode lockMode) Return the record number associated with the cursor.
SOperationStatus	getSearchBoth(SDatabaseEntry sKey, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode lockMode) Move the cursor to the specified secondary and primary key, where both the primary and secondary key items must match.
SOperationStatus	getSearchBothRange(SDatabaseEntry sKey, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode lockMode) Move the cursor to the specified secondary key and closest matching primary key of the database.
SOperationStatus	getSearchKey(SDatabaseEntry sKey, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode lockMode) Move the cursor to the given key of the database, and return the datum associated with the given key.
SOperationStatus	getSearchKeyRange(SDatabaseEntry sKey, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode lockMode) Move the cursor to the closest matching key of the database, and return the data item associated with the matching key.
SOperationStatus	getSearchRecordNumber(SDatabaseEntry secondaryRecno, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode lockMode) Move the cursor to the specific numbered record of the database, and return the associated key/data pair.
default <V> V	handleRuntimeExceptions(com.sleepycat.client.RemoteServiceCallable<V> remote)
default <V> V	remoteCall(com.sleepycat.client.RemoteServiceCallable<V> remote)
default <V> V	remoteCallWithIOException(com.sleepycat.client.RemoteServiceCallable<V> remote)

Methods inherited from class com.sleepycat.client.SCursor

close, compare, count, createConfig, delete, getConfig, getCurrent, getFirst, getLast, getNext, getNextDup, getNextNoDup, getPrev, getPrevDup, getPrevNoDup, getPriority, getRecordNumber, getSearchBoth, getSearchBothRange, getSearchKey, getSearchKeyRange, getSearchRecordNumber, getSecondaryDatabases, put, putAfter, putBefore, putCurrent, putKeyFirst, putKeyLast, putNoDupData, putNoOverwrite, setPriority

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.sleepycat.client.GetHelper

createGetSearchTerm, createPGetSearchTerm, remoteGet, remotePGet, updateKeyData, updateTuple

Methods inherited from interface com.sleepycat.client.PutHelper

calculateSKey, remotePut

Method Detail

getDatabase

public SSecondaryDatabase getDatabase()

Return the SSecondaryDatabase handle associated with this cursor.

Overrides:

getDatabase in class SCursor

Returns:

the SSecondaryDatabase handle associated with this cursor

dup

public SSecondaryCursor dup(boolean samePosition)
                     throws SDatabaseException

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

Overrides:

dup in class SCursor

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:

SDatabaseException - if any error occurs

getCurrent

public SOperationStatus getCurrent(SDatabaseEntry sKey,
                                   SDatabaseEntry pKey,
                                   SDatabaseEntry pData,
                                   SLockMode lockMode)
                            throws SDatabaseException

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

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

Parameters:

sKey - the secondary key returned as output

pKey - the primary key returned as output

pData - the primary data returned as output

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

Returns:

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

Throws:

SDatabaseException - if any error occurs

getFirst

public SOperationStatus getFirst(SDatabaseEntry sKey,
                                 SDatabaseEntry pKey,
                                 SDatabaseEntry pData,
                                 SLockMode lockMode)
                          throws SDatabaseException

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.

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

Parameters:

sKey - the secondary key returned as output

pKey - the primary key returned as output

pData - the primary data returned as output

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

Returns:

SOperationStatus.NOTFOUND if no matching key/data pair is found; SOperationStatus.KEYEMPTY if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

getLast

public SOperationStatus getLast(SDatabaseEntry sKey,
                                SDatabaseEntry pKey,
                                SDatabaseEntry pData,
                                SLockMode lockMode)
                         throws SDatabaseException

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.

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

Parameters:

sKey - the secondary key returned as output

pKey - the primary key returned as output

pData - the primary data returned as output

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

Returns:

SOperationStatus.NOTFOUND if no matching key/data pair is found; SOperationStatus.KEYEMPTY if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

getNext

public SOperationStatus getNext(SDatabaseEntry sKey,
                                SDatabaseEntry pKey,
                                SDatabaseEntry pData,
                                SLockMode lockMode)
                         throws SDatabaseException

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.

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

Parameters:

sKey - the secondary key returned as output

pKey - the primary key returned as output

pData - the primary data returned as output

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

Returns:

SOperationStatus.NOTFOUND if no matching key/data pair is found; SOperationStatus.KEYEMPTY if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

getNextDup

public SOperationStatus getNextDup(SDatabaseEntry sKey,
                                   SDatabaseEntry pKey,
                                   SDatabaseEntry pData,
                                   SLockMode lockMode)
                            throws SDatabaseException

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.

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

Parameters:

sKey - the secondary key returned as output

pKey - the primary key returned as output

pData - the primary data returned as output

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

Returns:

SOperationStatus.NOTFOUND if no matching key/data pair is found; SOperationStatus.KEYEMPTY if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

getNextNoDup

public SOperationStatus getNextNoDup(SDatabaseEntry sKey,
                                     SDatabaseEntry pKey,
                                     SDatabaseEntry pData,
                                     SLockMode lockMode)
                              throws SDatabaseException

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.

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

Parameters:

sKey - the secondary key returned as output

pKey - the primary key returned as output

pData - the primary data returned as output

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

Returns:

SOperationStatus.NOTFOUND if no matching key/data pair is found; SOperationStatus.KEYEMPTY if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

getPrev

public SOperationStatus getPrev(SDatabaseEntry sKey,
                                SDatabaseEntry pKey,
                                SDatabaseEntry pData,
                                SLockMode lockMode)
                         throws SDatabaseException

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.

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

Parameters:

sKey - the secondary key returned as output

pKey - the primary key returned as output

pData - the primary data returned as output

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

Returns:

SOperationStatus.NOTFOUND if no matching key/data pair is found; SOperationStatus.KEYEMPTY if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

getPrevDup

public SOperationStatus getPrevDup(SDatabaseEntry sKey,
                                   SDatabaseEntry pKey,
                                   SDatabaseEntry pData,
                                   SLockMode lockMode)
                            throws SDatabaseException

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.

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

Parameters:

sKey - the secondary key returned as output

pKey - the primary key returned as output

pData - the primary data returned as output

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

Returns:

SOperationStatus.NOTFOUND if no matching key/data pair is found; SOperationStatus.KEYEMPTY if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

getPrevNoDup

public SOperationStatus getPrevNoDup(SDatabaseEntry sKey,
                                     SDatabaseEntry pKey,
                                     SDatabaseEntry pData,
                                     SLockMode lockMode)
                              throws SDatabaseException

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.

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

Parameters:

sKey - the secondary key returned as output

pKey - the primary key returned as output

pData - the primary data returned as output

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

Returns:

SOperationStatus.NOTFOUND if no matching key/data pair is found; SOperationStatus.KEYEMPTY if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

getRecordNumber

public SOperationStatus getRecordNumber(SDatabaseEntry secondaryRecno,
                                        SDatabaseEntry primaryRecno,
                                        SLockMode lockMode)
                                 throws SDatabaseException

Return the record number associated with the cursor. The record number will be returned in the data parameter.

For this method to be called, the underlying database must be of type Btree, and it must have been configured to support record numbers.

When called on a cursor opened on a database that has been made into a secondary index, the method returns the record numbers of both the secondary and primary databases. If either underlying database is not of type Btree or is not configured with record numbers, the out-of-band record number of 0 is returned.

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

Parameters:

secondaryRecno - the secondary record number returned as output

primaryRecno - the primary record number returned as output

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

Returns:

SOperationStatus.NOTFOUND if no matching key/data pair is found; SOperationStatus.KEYEMPTY if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

getSearchBoth

public SOperationStatus getSearchBoth(SDatabaseEntry sKey,
                                      SDatabaseEntry pKey,
                                      SDatabaseEntry pData,
                                      SLockMode lockMode)
                               throws SDatabaseException

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

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

Parameters:

sKey - the secondary key used as input

pKey - the primary key used as input

pData - the primary data returned as output

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

Returns:

SOperationStatus.NOTFOUND if no matching key/data pair is found; SOperationStatus.KEYEMPTY if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

getSearchBothRange

public SOperationStatus getSearchBothRange(SDatabaseEntry sKey,
                                           SDatabaseEntry pKey,
                                           SDatabaseEntry pData,
                                           SLockMode lockMode)
                                    throws SDatabaseException

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.

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

Parameters:

sKey - the secondary key used as input

pKey - the primary key used as input and returned as output

pData - the primary data returned as output

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

Returns:

SOperationStatus.NOTFOUND if no matching key/data pair is found; SOperationStatus.KEYEMPTY if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

getSearchKey

public SOperationStatus getSearchKey(SDatabaseEntry sKey,
                                     SDatabaseEntry pKey,
                                     SDatabaseEntry pData,
                                     SLockMode lockMode)
                              throws SDatabaseException

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.

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

Parameters:

sKey - the secondary key used as input

pKey - the primary key returned as output

pData - the primary data returned as output

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

Returns:

SOperationStatus.NOTFOUND if no matching key/data pair is found; SOperationStatus.KEYEMPTY if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

getSearchKeyRange

public SOperationStatus getSearchKeyRange(SDatabaseEntry sKey,
                                          SDatabaseEntry pKey,
                                          SDatabaseEntry pData,
                                          SLockMode lockMode)
                                   throws SDatabaseException

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.

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

Parameters:

sKey - the secondary key used as input and returned as output

pKey - the primary key returned as output

pData - the primary data returned as output

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

Returns:

SOperationStatus.NOTFOUND if no matching key/data pair is found; SOperationStatus.KEYEMPTY if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

getSearchRecordNumber

public SOperationStatus getSearchRecordNumber(SDatabaseEntry secondaryRecno,
                                              SDatabaseEntry pKey,
                                              SDatabaseEntry pData,
                                              SLockMode lockMode)
                                       throws SDatabaseException

Move the cursor to the specific numbered record of the database, and return the associated key/data pair.

The specified key must be a record number as described in SDatabaseEntry. This determines the record to be retrieved.

For this method to be called, the underlying database must be of type Btree, and it must have been configured to support record numbers.

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

Parameters:

secondaryRecno - the secondary record number used as input

pKey - the primary key returned as output

pData - the primary data returned as output

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

Returns:

SOperationStatus.NOTFOUND if no matching key/data pair is found; SOperationStatus.KEYEMPTY if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

remoteCallWithIOException

public <V> V remoteCallWithIOException(com.sleepycat.client.RemoteServiceCallable<V> remote)
                                throws java.io.IOException

Throws:

java.io.IOException

remoteCall

public <V> V remoteCall(com.sleepycat.client.RemoteServiceCallable<V> remote)

handleRuntimeExceptions

public <V> V handleRuntimeExceptions(com.sleepycat.client.RemoteServiceCallable<V> remote)
                              throws org.apache.thrift.TException

Throws:

org.apache.thrift.TException