com.sun.sgs.service.store.db
Interface DbCursor

public interface DbCursor

The interface to a cursor for iterating over the contents of a database. A newly created cursor has no current key or value. Cursors are associated with a single transaction, and must be created and closed within that single transaction. Cursors must not be used after the close method is called. Cursor implementations are not required to be synchronized.

Method Summary

void	close() Closes this cursor, releasing any associated resources.
boolean	findFirst() Searches for the first key in the database.
boolean	findLast() Searches for the last key in the database.
boolean	findNext() Searches for the next key in the database.
boolean	findNext(byte[] key) Searches for the first key that is greater than or equal to the specified key.
byte[]	getKey() Returns the current key, or null if the cursor has no current key.
byte[]	getValue() Returns the current value, or null if the cursor has no current value.
boolean	putNoOverwrite(byte[] key, byte[] value) Uses the cursor to set the value associated with a key in the database, if the key does not already have an associated value.

Method Detail

getKey

byte[] getKey()

Returns the current key, or null if the cursor has no current key.

Returns:

the current key or null

Throws:

TransactionAbortedException - if the transaction should be aborted due to timeout or conflict

DbDatabaseException - if an unexpected database problem occurs

getValue

byte[] getValue()

Returns the current value, or null if the cursor has no current value.

Returns:

the current value or null

Throws:

TransactionAbortedException - if the transaction should be aborted due to timeout or conflict

DbDatabaseException - if an unexpected database problem occurs

findFirst

boolean findFirst()

Searches for the first key in the database. If the result is true, then sets the current key and value to the first key and its associated value.

Returns:

true if the first key was found, else false

Throws:

TransactionAbortedException - if the transaction should be aborted due to timeout or conflict

DbDatabaseException - if an unexpected database problem occurs

findNext

boolean findNext()

Searches for the next key in the database. If the cursor has no current key, then searches for the first key. If the result is true, then sets the current key and value to the key found and its associated value.

Returns:

true if the next key was found, else false

Throws:

TransactionAbortedException - if the transaction should be aborted due to timeout or conflict

DbDatabaseException - if an unexpected database problem occurs

findNext

boolean findNext(byte[] key)

Searches for the first key that is greater than or equal to the specified key. If the result is true, then sets the current key and value to the key found and its associated value.

Parameters:

key - the key at which to start searching

Returns:

true if the next key was found, else false

Throws:

TransactionAbortedException - if the transaction should be aborted due to timeout or conflict

DbDatabaseException - if an unexpected database problem occurs

findLast

boolean findLast()

Searches for the last key in the database. If the result is true, then sets the current key and value to the last key and its associated value.

Returns:

true if the last key was found, else false

Throws:

TransactionAbortedException - if the transaction should be aborted due to timeout or conflict

DbDatabaseException - if an unexpected database problem occurs

putNoOverwrite

boolean putNoOverwrite(byte[] key,
                       byte[] value)

Uses the cursor to set the value associated with a key in the database, if the key does not already have an associated value. If the result is true, then sets the current key and value to the newly inserted key and its associated value.

Parameters:

key - the key

value - the value

Returns:

true if a value was stored for the key, and false if the key already had a value

Throws:

TransactionAbortedException - if the transaction should be aborted due to timeout or conflict

DbDatabaseException - if an unexpected database problem occurs

close

void close()

Closes this cursor, releasing any associated resources. This cursor should not be used after this method is called. This method should be called before preparing, committing, or aborting the associated transaction.

Note that the Berkeley DB documentation for prepare doesn't say you need to close cursors, but my testing shows that you do. -tjb@sun.com (12/14/2006)

Throws:

TransactionAbortedException - if the transaction should be aborted due to timeout or conflict

DbDatabaseException - if an unexpected database problem occurs