com.sleepycat.client

Class SCursor

java.lang.Object

com.sleepycat.client.SCursor

All Implemented Interfaces:

GetHelper, PutHelper, java.lang.AutoCloseable

Direct Known Subclasses:

SSecondaryCursor

public class SCursor
extends java.lang.Object
implements GetHelper, PutHelper, java.lang.AutoCloseable

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.

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.

If you do not close the cursor before closing the database handle or the transaction handle that owns this cursor, then, closing a database handle or a transaction handle closes these open cursors. Once the cursor close method has been called, the handle may not be accessed again, regardless of the close method's success or failure.

To obtain a cursor with default attributes:

  SCursor cursor = myDatabase.openCursor(txn, null);
 

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

  SCursorConfig config = new SCursorConfig();
  config.setDirtyRead(true);
  SCursor 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. In Queue and Recno databases, missing entries (that is, entries that were never explicitly created or that were created and then deleted) will be ignored during a sequential scan.

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

Modifier and Type	Field and Description
protected BdbService.Client	client The remote service client.
protected TCursor	tCursor The remote cursor handle.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SCursor(TCursor tCursor, SDatabase database, STransaction txn, BdbService.Client client)

Method Summary

Modifier and Type	Method and Description
void	close() Discard the cursor.
int	compare(SCursor otherCursor) Return a comparison of the two cursors.
int	count() Return a count of the number of data items for the key to which the cursor refers.
protected TCursorGetConfig	createConfig(SDatabaseEntryBase data, SLockMode lockMode)
SOperationStatus	delete() Delete the key/data pair to which the cursor refers.
SCursor	dup(boolean samePosition) Creates a new cursor that uses the same transaction and locker ID as the original cursor.
SCursorConfig	getConfig() Return this cursor's configuration.
SOperationStatus	getCurrent(SDatabaseEntry key, SDatabaseEntryBase data, SLockMode lockMode) Returns the key/data pair to which the cursor refers.
SDatabase	getDatabase() Return the SDatabase handle associated with this cursor.
SOperationStatus	getFirst(SDatabaseEntry key, SDatabaseEntryBase data, SLockMode lockMode) Move the cursor to the first key/data pair of the database, and return that pair.
SOperationStatus	getLast(SDatabaseEntry key, SDatabaseEntry data, SLockMode lockMode) Move the cursor to the last key/data pair of the database, and return that pair.
SOperationStatus	getNext(SDatabaseEntry key, SDatabaseEntryBase data, SLockMode lockMode) Move the cursor to the next key/data pair and return that pair.
SOperationStatus	getNextDup(SDatabaseEntry key, SDatabaseEntryBase data, 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 key, SDatabaseEntryBase data, SLockMode lockMode) Move the cursor to the next non-duplicate key/data pair and return that pair.
SOperationStatus	getPrev(SDatabaseEntry key, SDatabaseEntry data, SLockMode lockMode) Move the cursor to the previous key/data pair and return that pair.
SOperationStatus	getPrevDup(SDatabaseEntry key, SDatabaseEntry data, 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 key, SDatabaseEntry data, SLockMode lockMode) Move the cursor to the previous non-duplicate key/data pair and return that pair.
SCacheFilePriority	getPriority() Get the cache priority for pages referenced by the cursor.
SOperationStatus	getRecordNumber(SDatabaseEntry data, SLockMode lockMode) Return the record number associated with the cursor.
SOperationStatus	getSearchBoth(SDatabaseEntry key, SDatabaseEntryBase data, SLockMode lockMode) Move the cursor to the specified key/data pair, where both the key and data items must match.
SOperationStatus	getSearchBothRange(SDatabaseEntry key, SDatabaseEntryBase data, SLockMode lockMode) Move the cursor to the specified key and matching data item of the database.
SOperationStatus	getSearchKey(SDatabaseEntry key, SDatabaseEntryBase data, SLockMode lockMode) Move the cursor to the given key of the database, and return the datum associated with the given key.
SOperationStatus	getSearchKeyRange(SDatabaseEntry key, SDatabaseEntryBase data, 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 key, SDatabaseEntryBase data, SLockMode lockMode) Move the cursor to the specific numbered record of the database, and return the associated key/data pair.
java.util.Set<SSecondaryDatabase>	getSecondaryDatabases() Return the set of secondary databases associated with this primary database.
default <V> V	handleRuntimeExceptions(com.sleepycat.client.RemoteServiceCallable<V> remote)
SOperationStatus	put(SDatabaseEntry key, SDatabaseEntry data) Store a key/data pair into the database.
SOperationStatus	putAfter(SDatabaseEntry key, SDatabaseEntry data) Store a key/data pair into the database.
SOperationStatus	putBefore(SDatabaseEntry key, SDatabaseEntry data) Store a key/data pair into the database.
SOperationStatus	putCurrent(SDatabaseEntry data) Replaces the data in the key/data pair at the current cursor position.
SOperationStatus	putKeyFirst(SDatabaseEntry key, SDatabaseEntry data) Store a key/data pair into the database.
SOperationStatus	putKeyLast(SDatabaseEntry key, SDatabaseEntry data) Store a key/data pair into the database.
SOperationStatus	putNoDupData(SDatabaseEntry key, SDatabaseEntry data) Store a key/data pair into the database.
SOperationStatus	putNoOverwrite(SDatabaseEntry key, SDatabaseEntry data) Store a key/data pair into the database.
default <V> V	remoteCall(com.sleepycat.client.RemoteServiceCallable<V> remote)
default <V> V	remoteCallWithIOException(com.sleepycat.client.RemoteServiceCallable<V> remote)
void	setPriority(SCacheFilePriority priority) Set the cache priority for pages referenced by this cursor handle.

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

Field Detail

tCursor

protected final TCursor tCursor

The remote cursor handle.

client

protected final BdbService.Client client

The remote service client.

Constructor Detail

SCursor

protected SCursor(TCursor tCursor,
                  SDatabase database,
                  STransaction txn,
                  BdbService.Client client)

Method Detail

close

public void close()
           throws SDatabaseException

Discard the cursor.

After the close method has been called, you cannot use the cursor handle again.

It is not required to close the cursor explicitly before closing the database handle or the transaction handle that owns this cursor because closing a database handle or transaction handle closes those open cursor.

However, it is recommended that you always close all cursor handles immediately after their use to promote concurrency and to release resources such as page locks.

Specified by:

close in interface java.lang.AutoCloseable

Throws:

SDatabaseException - if any error occurs

compare

public int compare(SCursor otherCursor)
            throws SDatabaseException

Return a comparison of the two cursors. Two cursors are equal if and only if they are positioned on the same item in the same database.

Parameters:

otherCursor - the other cursor to be compared

Returns:

an integer representing the result of the comparison between this cursor and otherCursor (another cursor handle used as the comparator). 0 indicates that this cursor and otherCursor are positioned on the same item, 1 indicates this cursor is greater than otherCursor, -1 indicates that otherCursor is greater than this cursor.

Throws:

SDatabaseException - if any error occurs

count

public int count()
          throws SDatabaseException

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

Returns:

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

Throws:

SDatabaseException - if any error occurs

dup

public SCursor dup(boolean samePosition)
            throws SDatabaseException

Creates a new cursor that uses 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:

SDatabaseException - if any error occurs

getConfig

public SCursorConfig getConfig()
                        throws SDatabaseException

Return this cursor's configuration.

This may differ from the configuration used to open this object.

Returns:

this cursor's configuration

Throws:

SDatabaseException - if any error occurs

getPriority

public SCacheFilePriority getPriority()
                               throws SDatabaseException

Get the cache priority for pages referenced by the cursor.

Returns:

the cache priority for pages referenced by the cursor

Throws:

SDatabaseException - if any error occurs

setPriority

public void setPriority(SCacheFilePriority priority)
                 throws SDatabaseException

Set the cache priority for pages referenced by this cursor handle.

The priority of a page biases the replacement algorithm to be more or less likely to discard a page when space is needed in the buffer pool. The bias is temporary, and pages will eventually be discarded if they are not referenced again. The setPriority method is only advisory, and does not guarantee pages will be treated in a specific way.

Parameters:

priority - the cache priority

Throws:

SDatabaseException - if any error occurs

getDatabase

public SDatabase getDatabase()

Return the SDatabase handle associated with this cursor.

Returns:

the SDatabase handle associated with this cursor

getSecondaryDatabases

public java.util.Set<SSecondaryDatabase> getSecondaryDatabases()

Description copied from interface: PutHelper

Return the set of secondary databases associated with this primary database.

Specified by:

getSecondaryDatabases in interface PutHelper

Returns:

the set of associated secondary databases

getCurrent

public SOperationStatus getCurrent(SDatabaseEntry key,
                                   SDatabaseEntryBase data,
                                   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:

key - the key returned as output

data - the data returned as output. Use SMultipleDataEntry to return multiple duplicates of the key. Use SMultiplePairs to return multiple key/data pairs.

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 key,
                                 SDatabaseEntryBase data,
                                 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:

key - the key returned as output

data - the data returned as output. Use SMultipleDataEntry to return multiple duplicates of the key. Use SMultiplePairs to return multiple key/data pairs.

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 key,
                                SDatabaseEntry data,
                                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:

key - the key returned as output

data - the 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 key,
                                SDatabaseEntryBase data,
                                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:

key - the key returned as output

data - the data returned as output. Use SMultipleDataEntry to return multiple duplicates of the key. Use SMultiplePairs to return multiple key/data pairs.

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 key,
                                   SDatabaseEntryBase data,
                                   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:

key - the key returned as output

data - the data returned as output. Use SMultipleDataEntry to return multiple duplicates of the key. Use SMultiplePairs to return multiple key/data pairs.

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 key,
                                     SDatabaseEntryBase data,
                                     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:

key - the key returned as output

data - the data returned as output. Use SMultipleDataEntry to return multiple duplicates of the key. Use SMultiplePairs to return multiple key/data pairs.

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 key,
                                SDatabaseEntry data,
                                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:

key - the key returned as output

data - the 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 key,
                                   SDatabaseEntry data,
                                   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:

key - the key returned as output

data - the 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 key,
                                     SDatabaseEntry data,
                                     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:

key - the key returned as output

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

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

Parameters:

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

getSearchBoth

public SOperationStatus getSearchBoth(SDatabaseEntry key,
                                      SDatabaseEntryBase data,
                                      SLockMode lockMode)
                               throws SDatabaseException

Move the cursor to the specified key/data pair, where both the key and data items must match.

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

Parameters:

key - the key used as input

data - the data used as input; only SDatabaseEntry is supported

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 key,
                                           SDatabaseEntryBase data,
                                           SLockMode lockMode)
                                    throws SDatabaseException

Move the cursor to the specified key and matching data item of the database.

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

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

Parameters:

key - the key used as input

data - the data used as input and returned as output; only SDatabaseEntry is supported

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 key,
                                     SDatabaseEntryBase data,
                                     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:

key - the key used as input

data - the data returned as output. Use SMultipleDataEntry to return multiple duplicates of the key. Use SMultiplePairs to return multiple key/data pairs.

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 key,
                                          SDatabaseEntryBase data,
                                          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:

key - the key used as input and returned as output

data - the data returned as output. Use SMultipleDataEntry to return multiple duplicates of the key. Use SMultiplePairs to return multiple key/data pairs.

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 key,
                                              SDatabaseEntryBase data,
                                              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:

key - the key returned as output

data - the data returned as output. Use SMultipleDataEntry to return multiple duplicates of the key. Use SMultiplePairs to return multiple key/data pairs.

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

createConfig

protected TCursorGetConfig createConfig(SDatabaseEntryBase data,
                                        SLockMode lockMode)

put

public SOperationStatus put(SDatabaseEntry key,
                            SDatabaseEntry data)
                     throws SDatabaseException

Store 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 existing key/data pair will be replaced.

Parameters:

key - the key entry operated on

data - the data entry stored

Returns:

SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

putKeyFirst

public SOperationStatus putKeyFirst(SDatabaseEntry key,
                                    SDatabaseEntry data)
                             throws SDatabaseException

Store a key/data pair into the database.

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

In the case of the Btree and Hash access methods, insert the specified key/data pair into the database.

If the underlying database supports duplicate data items, and if the key already exists in the database and a duplicate sort function has been specified, the inserted data item is added in its sorted location. If the key already exists in the database and no duplicate sort function has been specified, the inserted data item is added as the first of the data items for that key.

The putKeyFirst method may not be called for the Queue or Recno access methods.

Parameters:

key - the key entry operated on

data - the data entry stored

Returns:

SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

putKeyLast

public SOperationStatus putKeyLast(SDatabaseEntry key,
                                   SDatabaseEntry data)
                            throws SDatabaseException

Store a key/data pair into the database.

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

In the case of the Btree and Hash access methods, insert the specified key/data pair into the database.

If the underlying database supports duplicate data items, and if the key already exists in the database and a duplicate sort function has been specified, the inserted data item is added in its sorted location. If the key already exists in the database and no duplicate sort function has been specified, the inserted data item is added as the last of the data items for that key.

The putKeyLast method may not be called for the Queue or Recno access methods.

Parameters:

key - the key entry operated on

data - the data entry stored

Returns:

SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

putNoDupData

public SOperationStatus putNoDupData(SDatabaseEntry key,
                                     SDatabaseEntry data)
                              throws SDatabaseException

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

In the case of the Btree and Hash access methods, 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, SOperationStatus.KEYEXIST is returned.

This method may only be called if the underlying database has been configured to support sorted duplicate data items.

This method may not be called for the Queue or Recno access methods.

Parameters:

key - the key entry operated on

data - the data entry stored

Returns:

SOperationStatus.KEYEXIST if a matching key/data pair already exists in the database; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

putNoOverwrite

public SOperationStatus putNoOverwrite(SDatabaseEntry key,
                                       SDatabaseEntry data)
                                throws SDatabaseException

Store 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 SOperationStatus.KEYEXIST.

Parameters:

key - the key entry operated on

data - the data entry stored

Returns:

SOperationStatus.KEYEXIST if a matching key/data pair already exists in the database; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

putAfter

public SOperationStatus putAfter(SDatabaseEntry key,
                                 SDatabaseEntry data)
                          throws SDatabaseException

Store a key/data pair into the database.

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

In the case of the Btree and Hash access methods, insert the data element as a duplicate element of the key to which the cursor refers. The new element appears immediately after the current cursor position. It is an error to call this method if the underlying Btree or Hash database does not support duplicate data items. The key parameter is ignored.

In the case of the Hash access method, the putAfter method will fail and throw an exception if the current cursor record has already been deleted.

Parameters:

key - the key entry operated on

data - the data entry stored

Returns:

SOperationStatus.NOTFOUND if the current cursor has already been deleted and the underlying access method is Hash; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

putBefore

public SOperationStatus putBefore(SDatabaseEntry key,
                                  SDatabaseEntry data)
                           throws SDatabaseException

Store a key/data pair into the database.

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

In the case of the Btree and Hash access methods, insert the data element as a duplicate element of the key to which the cursor refers. The new element appears immediately before the current cursor position. It is an error to call this method if the underlying Btree or Hash database does not support duplicate data items. The key parameter is ignored.

In the case of the Hash access method, the putBefore method will fail and throw an exception if the current cursor record has already been deleted.

Parameters:

key - the key entry operated on

data - the data entry stored

Returns:

SOperationStatus.NOTFOUND if the current cursor has already been deleted and the underlying access method is Hash; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

putCurrent

public SOperationStatus putCurrent(SDatabaseEntry data)
                            throws SDatabaseException

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 SOperationStatus.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 the old and new data are unequal, a SDatabaseException 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 entry stored

Returns:

SOperationStatus.NOTFOUND if the current cursor has already been deleted; otherwise, SOperationStatus.SUCCESS

Throws:

SDatabaseException - if any error occurs

delete

public SOperationStatus delete()
                        throws SDatabaseException

Delete 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 deletes 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:

SOperationStatus.KEYEMPTY if the key/pair at the cursor position has been 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