Berkeley DB Java Edition
version 1.5.1

com.sleepycat.je
Class SecondaryCursor

java.lang.Object
  |
  +--com.sleepycat.je.Cursor
        |
        +--com.sleepycat.je.SecondaryCursor

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:

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.setDirtyRead(true);
  SecondaryCursor cursor = myDb.openSecondaryCursor(txn, config);
 


Method Summary
 OperationStatus delete()
          Delete the key/data pair to which the cursor refers from the primary database and all secondary indices.
 Cursor dup(boolean samePosition)
          Returns a new SecondaryCursor for the same transaction as the original cursor.
 SecondaryCursor dupSecondary(boolean samePosition)
          Returns a new copy of the cursor as a SecondaryCursor.
 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.
 OperationStatus getFirst(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode)
          Moves the cursor to the first key/data pair of the database, and returns 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)
          Moves the cursor to the last key/data pair of the database, and returns that pair.
 OperationStatus getLast(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
          Moves the cursor to the last key/data pair of the database, and returns that pair.
 OperationStatus getNext(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode)
          Moves the cursor to the next key/data pair and returns that pair.
 OperationStatus getNext(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
          Moves the cursor to the next key/data pair and returns that pair.
 OperationStatus 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, moves the cursor to the next key/data pair of the database and returns 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)
          Moves the cursor to the next non-duplicate key/data pair and returns that pair.
 OperationStatus getNextNoDup(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
          Moves the cursor to the next non-duplicate key/data pair and returns that pair.
 OperationStatus getPrev(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode)
          Moves the cursor to the previous key/data pair and returns that pair.
 OperationStatus getPrev(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
          Moves the cursor to the previous key/data pair and returns that pair.
 OperationStatus getPrevDup(DatabaseEntry key, DatabaseEntry 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, moves the cursor to the previous key/data pair of the database and returns that pair.
 OperationStatus getPrevDup(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
          If the previous key/data pair of the database is a duplicate data record for the current key/data pair, moves the cursor to the previous key/data pair of the database and returns that pair.
 OperationStatus getPrevNoDup(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode)
          Moves the cursor to the previous non-duplicate key/data pair and returns that pair.
 OperationStatus getPrevNoDup(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
          Moves the cursor to the previous non-duplicate key/data pair and returns that pair.
 Database getPrimaryDatabase()
          Returns the primary Database associated with this cursor.
 OperationStatus getSearchBoth(DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode)
          Moves the cursor to the specified secondary and primary key, that is, 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)
          Moves 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)
          Moves the cursor to the given key of the database, and returns 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)
          Moves the cursor to the closest matching key of the database, and returns the datum 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 datum associated with the matching key.
 OperationStatus put(DatabaseEntry key, DatabaseEntry data)
          This operation is not allowed on a secondary database.
 OperationStatus putCurrent(DatabaseEntry data)
          This operation is not allowed on a secondary database.
 OperationStatus putNoDupData(DatabaseEntry key, DatabaseEntry data)
          This operation is not allowed on a secondary database.
 OperationStatus putNoOverwrite(DatabaseEntry key, DatabaseEntry data)
          This operation is not allowed on a secondary database.
 
Methods inherited from class com.sleepycat.je.Cursor
close, count, getConfig, getDatabase
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getPrimaryDatabase

public Database getPrimaryDatabase()
Returns the primary Database associated with this cursor.

Calling this method is the equivalent of the following expression:

((SecondaryDatabase) this.getDatabase()).getPrimaryDatabase()

Returns:
the primary Database associated with this cursor.

dup

public Cursor dup(boolean samePosition)
           throws DatabaseException
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 and hold the same locks. If false, the created cursor is uninitialized and will behave like a cursor newly created using openCursor.

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

Throws:
DatabaseException - if a failure occurs.

dupSecondary

public SecondaryCursor dupSecondary(boolean samePosition)
                             throws DatabaseException
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.

DatabaseException
See Also:
dup(boolean)

delete

public OperationStatus delete()
                       throws DatabaseException
Delete the key/data pair to which the cursor refers from the primary database and all secondary indices.

This method behaves as if Database.delete(com.sleepycat.je.Transaction, com.sleepycat.je.DatabaseEntry) were called for the primary database, using the primary key obtained via the secondary key parameter.

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.

Overrides:
delete in class Cursor
Throws:
DatabaseException - if a failure occurs.

put

public OperationStatus put(DatabaseEntry key,
                           DatabaseEntry data)
                    throws DatabaseException
This operation is not allowed on a secondary database. UnsupportedOperationException will always be thrown by this method. The corresponding method on the primary database should be used instead.

Overrides:
put in class Cursor
Parameters:
key - the key DatabaseEntry operated on.

data - the data DatabaseEntry stored.

Throws:
DatabaseException - if a failure occurs.

putNoOverwrite

public OperationStatus putNoOverwrite(DatabaseEntry key,
                                      DatabaseEntry data)
                               throws DatabaseException
This operation is not allowed on a secondary database. UnsupportedOperationException will always be thrown by this method. The corresponding method on the primary database should be used instead.

Overrides:
putNoOverwrite in class Cursor
Parameters:
key - the key DatabaseEntry operated on.

data - the data DatabaseEntry stored.

Throws:
DatabaseException - if a failure occurs.

putNoDupData

public OperationStatus putNoDupData(DatabaseEntry key,
                                    DatabaseEntry data)
                             throws DatabaseException
This operation is not allowed on a secondary database. UnsupportedOperationException will always be thrown by this method. The corresponding method on the primary database should be used instead.

Overrides:
putNoDupData in class Cursor
Parameters:
key - the key DatabaseEntry operated on.

data - the data DatabaseEntry stored.

Throws:
DatabaseException - if a failure occurs.

putCurrent

public OperationStatus putCurrent(DatabaseEntry data)
                           throws DatabaseException
This operation is not allowed on a secondary database. UnsupportedOperationException will always be thrown by this method. The corresponding method on the primary database should be used instead.

Overrides:
putCurrent in class Cursor
Parameters:
data - the data DatabaseEntry stored.

Throws:
DatabaseException - if a failure occurs.

getCurrent

public OperationStatus getCurrent(DatabaseEntry key,
                                  DatabaseEntry data,
                                  LockMode lockMode)
                           throws DatabaseException
Returns the key/data pair to which the cursor refers.

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

Overrides:
getCurrent in class Cursor
Parameters:
key - the secondary 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.

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

Returns:
KEYEMPTY if the key/pair at the cursor position has been deleted; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getCurrent

public OperationStatus getCurrent(DatabaseEntry key,
                                  DatabaseEntry pKey,
                                  DatabaseEntry data,
                                  LockMode lockMode)
                           throws DatabaseException
Returns the key/data pair to which the cursor refers.

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

Parameters:
key - the 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.

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

Returns:
KEYEMPTY if the key/pair at the cursor position has been deleted; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getFirst

public OperationStatus getFirst(DatabaseEntry key,
                                DatabaseEntry data,
                                LockMode lockMode)
                         throws DatabaseException
Moves the cursor to the first key/data pair of the database, and returns that pair. If the first key has duplicate values, the first data item in the set of duplicates is returned.

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

Overrides:
getFirst in class Cursor
Parameters:
key - the secondary 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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getFirst

public OperationStatus getFirst(DatabaseEntry key,
                                DatabaseEntry pKey,
                                DatabaseEntry data,
                                LockMode lockMode)
                         throws DatabaseException
Moves the cursor to the first key/data pair of the database, and returns that pair. If the first key has duplicate values, the first data item in the set of duplicates is returned.

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

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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getLast

public OperationStatus getLast(DatabaseEntry key,
                               DatabaseEntry data,
                               LockMode lockMode)
                        throws DatabaseException
Moves the cursor to the last key/data pair of the database, and returns that pair. If the last key has duplicate values, the last data item in the set of duplicates is returned.

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

Overrides:
getLast in class Cursor
Parameters:
key - the secondary 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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getLast

public OperationStatus getLast(DatabaseEntry key,
                               DatabaseEntry pKey,
                               DatabaseEntry data,
                               LockMode lockMode)
                        throws DatabaseException
Moves the cursor to the last key/data pair of the database, and returns that pair. If the last key has duplicate values, the last data item in the set of duplicates is returned.

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

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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getNext

public OperationStatus getNext(DatabaseEntry key,
                               DatabaseEntry data,
                               LockMode lockMode)
                        throws DatabaseException
Moves the cursor to the next key/data pair and returns that pair. If the matching key has duplicate values, the first data item in the set of duplicates is returned.

If the cursor is not yet initialized, move the cursor to the first key/data pair of the database, and return that pair. Otherwise, the cursor is moved to the next 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.

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.

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

Overrides:
getNext in class Cursor
Parameters:
key - the secondary 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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getNext

public OperationStatus getNext(DatabaseEntry key,
                               DatabaseEntry pKey,
                               DatabaseEntry data,
                               LockMode lockMode)
                        throws DatabaseException
Moves the cursor to the next key/data pair and returns that pair. If the matching key has duplicate values, the first data item in the set of duplicates is returned.

If the cursor is not yet initialized, move the cursor to the first key/data pair of the database, and return that pair. Otherwise, the cursor is moved to the next 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.

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.

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

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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getNextDup

public OperationStatus getNextDup(DatabaseEntry key,
                                  DatabaseEntry data,
                                  LockMode lockMode)
                           throws DatabaseException
If the next key/data pair of the database is a duplicate data record for the current key/data pair, moves the cursor to the next key/data pair of the database and returns that pair.

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.

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

Overrides:
getNextDup in class Cursor
Parameters:
key - the secondary 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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getNextDup

public OperationStatus getNextDup(DatabaseEntry key,
                                  DatabaseEntry pKey,
                                  DatabaseEntry data,
                                  LockMode lockMode)
                           throws DatabaseException
If the next key/data pair of the database is a duplicate data record for the current key/data pair, moves the cursor to the next key/data pair of the database and returns that pair.

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.

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

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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getNextNoDup

public OperationStatus getNextNoDup(DatabaseEntry key,
                                    DatabaseEntry data,
                                    LockMode lockMode)
                             throws DatabaseException
Moves the cursor to the next non-duplicate key/data pair and returns that pair. If the matching key has duplicate values, the first data item in the set of duplicates is returned.

If the cursor is not yet initialized, move the cursor to the first key/data pair of the database, and return that pair. Otherwise, the cursor is moved to the next non-duplicate key of the database, and that key/data pair is returned.

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.

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

Overrides:
getNextNoDup in class Cursor
Parameters:
key - the secondary 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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getNextNoDup

public OperationStatus getNextNoDup(DatabaseEntry key,
                                    DatabaseEntry pKey,
                                    DatabaseEntry data,
                                    LockMode lockMode)
                             throws DatabaseException
Moves the cursor to the next non-duplicate key/data pair and returns that pair. If the matching key has duplicate values, the first data item in the set of duplicates is returned.

If the cursor is not yet initialized, move the cursor to the first key/data pair of the database, and return that pair. Otherwise, the cursor is moved to the next non-duplicate key of the database, and that key/data pair is returned.

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.

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

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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getPrev

public OperationStatus getPrev(DatabaseEntry key,
                               DatabaseEntry data,
                               LockMode lockMode)
                        throws DatabaseException
Moves the cursor to the previous key/data pair and returns that pair. If the matching key has duplicate values, the last data item in the set of duplicates is returned.

If the cursor is not yet initialized, move the cursor to the last key/data pair of the database, and return that pair. Otherwise, the cursor is moved to the previous 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.

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.

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

Overrides:
getPrev in class Cursor
Parameters:
key - the secondary 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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getPrev

public OperationStatus getPrev(DatabaseEntry key,
                               DatabaseEntry pKey,
                               DatabaseEntry data,
                               LockMode lockMode)
                        throws DatabaseException
Moves the cursor to the previous key/data pair and returns that pair. If the matching key has duplicate values, the last data item in the set of duplicates is returned.

If the cursor is not yet initialized, move the cursor to the last key/data pair of the database, and return that pair. Otherwise, the cursor is moved to the previous 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.

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.

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

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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getPrevDup

public OperationStatus getPrevDup(DatabaseEntry key,
                                  DatabaseEntry data,
                                  LockMode lockMode)
                           throws DatabaseException
If the previous key/data pair of the database is a duplicate data record for the current key/data pair, moves the cursor to the previous key/data pair of the database and returns that pair.

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.

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

Overrides:
getPrevDup in class Cursor
Parameters:
key - the secondary 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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getPrevDup

public OperationStatus getPrevDup(DatabaseEntry key,
                                  DatabaseEntry pKey,
                                  DatabaseEntry data,
                                  LockMode lockMode)
                           throws DatabaseException
If the previous key/data pair of the database is a duplicate data record for the current key/data pair, moves the cursor to the previous key/data pair of the database and returns that pair.

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.

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

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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getPrevNoDup

public OperationStatus getPrevNoDup(DatabaseEntry key,
                                    DatabaseEntry data,
                                    LockMode lockMode)
                             throws DatabaseException
Moves the cursor to the previous non-duplicate key/data pair and returns that pair. If the matching key has duplicate values, the last data item in the set of duplicates is returned.

If the cursor is not yet initialized, move the cursor to the last key/data pair of the database, and return that pair. Otherwise, the cursor is moved to the previous non-duplicate key of the database, and that key/data pair is returned.

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.

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

Overrides:
getPrevNoDup in class Cursor
Parameters:
key - the secondary 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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getPrevNoDup

public OperationStatus getPrevNoDup(DatabaseEntry key,
                                    DatabaseEntry pKey,
                                    DatabaseEntry data,
                                    LockMode lockMode)
                             throws DatabaseException
Moves the cursor to the previous non-duplicate key/data pair and returns that pair. If the matching key has duplicate values, the last data item in the set of duplicates is returned.

If the cursor is not yet initialized, move the cursor to the last key/data pair of the database, and return that pair. Otherwise, the cursor is moved to the previous non-duplicate key of the database, and that key/data pair is returned.

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.

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

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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getSearchKey

public OperationStatus getSearchKey(DatabaseEntry key,
                                    DatabaseEntry data,
                                    LockMode lockMode)
                             throws DatabaseException
Moves the cursor to the given key of the database, and returns the datum associated with the given key. If the matching key has duplicate values, the first data item in the set of duplicates is returned.

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

Overrides:
getSearchKey in class Cursor
Parameters:
key - the secondary 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.

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getSearchKey

public OperationStatus getSearchKey(DatabaseEntry key,
                                    DatabaseEntry pKey,
                                    DatabaseEntry data,
                                    LockMode lockMode)
                             throws DatabaseException
Moves the cursor to the given key of the database, and returns the datum associated with the given key. If the matching key has duplicate values, the first data item in the set of duplicates is returned.

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

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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getSearchKeyRange

public OperationStatus getSearchKeyRange(DatabaseEntry key,
                                         DatabaseEntry data,
                                         LockMode lockMode)
                                  throws DatabaseException
Moves the cursor to the closest matching key of the database, and returns the datum 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.

Overrides:
getSearchKeyRange in class Cursor
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.

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.

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getSearchKeyRange

public OperationStatus getSearchKeyRange(DatabaseEntry key,
                                         DatabaseEntry pKey,
                                         DatabaseEntry data,
                                         LockMode lockMode)
                                  throws DatabaseException
Moves the cursor to the closest matching key of the database, and returns the datum 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 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.

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getSearchBoth

public OperationStatus getSearchBoth(DatabaseEntry key,
                                     DatabaseEntry data,
                                     LockMode lockMode)
                              throws DatabaseException
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. It must be initialized with a non-null byte array by the caller.

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

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
DatabaseException - if a failure occurs.


getSearchBoth

public OperationStatus getSearchBoth(DatabaseEntry key,
                                     DatabaseEntry pKey,
                                     DatabaseEntry data,
                                     LockMode lockMode)
                              throws DatabaseException
Moves the cursor to the specified secondary and primary key, that is, 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:
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.

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


getSearchBothRange

public OperationStatus getSearchBothRange(DatabaseEntry key,
                                          DatabaseEntry data,
                                          LockMode lockMode)
                                   throws DatabaseException
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. It must be initialized with a non-null byte array by the caller.

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

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

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
DatabaseException - if a failure occurs.


getSearchBothRange

public OperationStatus getSearchBothRange(DatabaseEntry key,
                                          DatabaseEntry pKey,
                                          DatabaseEntry data,
                                          LockMode lockMode)
                                   throws DatabaseException
Moves 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:
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.

Returns:
NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.
Throws:
NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.


Berkeley DB Java Edition
version 1.5.1

Copyright (c) 1996-2004 Sleepycat Software, Inc. - All rights reserved.