org.cojen.tupl

Interface Cursor

All Known Implementing Classes:

WrappedCursor

public interface Cursor

Maintains a logical position in a View. Cursor instances can only be safely used by one thread at a time, and they must be reset when no longer needed. Instances can be exchanged by threads, as long as a happens-before relationship is established. Without proper exclusion, multiple threads interacting with a Cursor instance may cause database corruption.

Methods which return LockResult might acquire a lock to access the requested entry. The return type indicates if the lock is still held, and in what fashion. Except where indicated, a LockTimeoutException is thrown when a lock cannot be acquired in time. When cursor is linked to a transaction, it defines the locking behavior and timeout. Otherwise, a lock is always acquired, with the default timeout.

If a LockFailureException is thrown from any method, the Cursor is positioned at the desired key, but the value is NOT_LOADED.

See Also:

View.newCursor

Field Summary

Fields

Modifier and Type	Field and Description
static byte[]	NOT_LOADED Empty marker which indicates that value exists but has not been loaded.

Method Summary

Modifier and Type	Method and Description
boolean	autoload() Returns the current autoload mode.
boolean	autoload(boolean mode) By default, values are loaded automatically, as they are seen.
default void	commit(byte[] value) Combined store and commit to the linked transaction.
default int	compareKeyTo(byte[] rkey) Compare the current key to the one given.
default int	compareKeyTo(byte[] rkey, int offset, int length) Compare the current key to the one given.
Cursor	copy() Returns a new independent Cursor, positioned where this one is, and linked to the same transaction.
LockResult	find(byte[] key) Moves the Cursor to find the given key.
default LockResult	findGe(byte[] key) Moves the Cursor to find the first available entry greater than or equal to the given key.
default LockResult	findGt(byte[] key) Moves the Cursor to find the first available entry greater than the given key.
default LockResult	findLe(byte[] key) Moves the Cursor to find the first available entry less than or equal to the given key.
default LockResult	findLt(byte[] key) Moves the Cursor to find the first available entry less than the given key.
default LockResult	findNearby(byte[] key) Optimized version of the regular find method, which can perform fewer search steps if the given key is in close proximity to the current one.
LockResult	first() Moves the Cursor to find the first available entry.
Ordering	getOrdering() Returns the key ordering for this cursor.
byte[]	key() Returns an uncopied reference to the current key, or null if Cursor is unpositioned.
LockResult	last() Moves the Cursor to find the last available entry.
Transaction	link() Returns the transaction the cursor is currently linked to.
Transaction	link(Transaction txn) Link to a transaction, which can be null for auto-commit mode.
LockResult	load() Loads or reloads the value at the cursor's current position.
default LockResult	lock() Locks the current entry, as if by calling load.
LockResult	next() Moves to the Cursor to the next available entry.
default LockResult	nextLe(byte[] limitKey) Moves to the Cursor to the next available entry, but only when less than or equal to the given limit key.
default LockResult	nextLt(byte[] limitKey) Moves to the Cursor to the next available entry, but only when less than the given limit key.
LockResult	previous() Moves to the Cursor to the previous available entry.
default LockResult	previousGe(byte[] limitKey) Moves to the Cursor to the previous available entry, but only when greater than or equal to the given limit key.
default LockResult	previousGt(byte[] limitKey) Moves to the Cursor to the previous available entry, but only when greater than the given limit key.
LockResult	random(byte[] lowKey, byte[] highKey) Moves the Cursor to a random entry, but not guaranteed to be chosen from a uniform distribution.
void	reset() Resets Cursor and moves it to an undefined position.
LockResult	skip(long amount) Moves the Cursor by a relative amount of entries.
default LockResult	skip(long amount, byte[] limitKey, boolean inclusive) Moves the Cursor by a relative amount of entries, stopping sooner if the limit key is reached.
void	store(byte[] value) Stores a value into the current entry, leaving the position unchanged.
byte[]	value() Returns an uncopied reference to the current value, which might be null or NOT_LOADED.

Field Detail

NOT_LOADED

static final byte[] NOT_LOADED

Empty marker which indicates that value exists but has not been loaded.

Method Detail

getOrdering

Ordering getOrdering()

Returns the key ordering for this cursor.

link

Transaction link(Transaction txn)

Link to a transaction, which can be null for auto-commit mode. All entries visited by the cursor become part of the given transaction. To continue using a cursor after the transaction is complete, link it to null or another transaction. Otherwise, the original transaction will be resurrected.

Returns:

prior linked transaction

Throws:

IllegalArgumentException - if transaction belongs to another database instance

link

Transaction link()

Returns the transaction the cursor is currently linked to.

key

byte[] key()

Returns an uncopied reference to the current key, or null if Cursor is unpositioned. Array contents must not be modified.

value

byte[] value()

Returns an uncopied reference to the current value, which might be null or NOT_LOADED. Array contents can be safely modified.

autoload

boolean autoload(boolean mode)

By default, values are loaded automatically, as they are seen. When disabled, values might need to be manually loaded. When a Transformer is used, the value might still be loaded automatically. When the value exists but hasn't been loaded, the value field of the cursor is set to NOT_LOADED.

Parameters:

mode - false to disable

Returns:

prior autoload mode

autoload

boolean autoload()

Returns the current autoload mode.

compareKeyTo

default int compareKeyTo(byte[] rkey)

Compare the current key to the one given.

Parameters:

rkey - key to compare to

Returns:

a negative integer, zero, or a positive integer as current key is less than, equal to, or greater than the rkey.

Throws:

NullPointerException - if current key or rkey is null

compareKeyTo

default int compareKeyTo(byte[] rkey,
                         int offset,
                         int length)

Compare the current key to the one given.

Parameters:

rkey - key to compare to

offset - offset into rkey

length - length of rkey

Returns:

a negative integer, zero, or a positive integer as current key is less than, equal to, or greater than the rkey.

Throws:

NullPointerException - if current key or rkey is null

first

LockResult first()
          throws IOException

Moves the Cursor to find the first available entry. Cursor key and value are set to null if no entries exist, and position will be undefined.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

IOException

last

LockResult last()
         throws IOException

Moves the Cursor to find the last available entry. Cursor key and value are set to null if no entries exist, and position will be undefined.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

IOException

skip

LockResult skip(long amount)
         throws IOException

Moves the Cursor by a relative amount of entries. Pass a positive amount to skip forward, and pass a negative amount to skip backwards. If less than the given amount of entries are available, the Cursor is reset.

Skipping by 1 is equivalent to calling next, and skipping by -1 is equivalent to calling previous. A skip of 0 merely checks and returns the lock state for the current key. Lock acquisition only applies to the target entry — no locks are acquired for entries in between.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

IllegalStateException - if position is undefined at invocation time

IOException

skip

default LockResult skip(long amount,
                        byte[] limitKey,
                        boolean inclusive)
                 throws IOException

Moves the Cursor by a relative amount of entries, stopping sooner if the limit key is reached. Pass a positive amount to skip forward, and pass a negative amount to skip backwards. If the limit key is reached, or if less than the given amount of entries are available, the Cursor is reset.

Skipping by 1 is equivalent to calling nextLe, nextLt or next, depending on which type of limit was provided. Likewise, skipping by -1 is equivalent to calling previousGe, previousGt or previous. A skip of 0 merely checks and returns the lock state for the current key. Lock acquisition only applies to the target entry — no locks are acquired for entries in between.

Parameters:

limitKey - limit key; pass null for no limit

inclusive - true if limit is inclusive, false for exclusive

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

IllegalStateException - if position is undefined at invocation time

IOException

next

LockResult next()
         throws IOException

Moves to the Cursor to the next available entry. Cursor key and value are set to null if no next entry exists, and position will be undefined.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

IllegalStateException - if position is undefined at invocation time

IOException

nextLe

default LockResult nextLe(byte[] limitKey)
                   throws IOException

Moves to the Cursor to the next available entry, but only when less than or equal to the given limit key. Cursor key and value are set to null if no applicable entry exists, and position will be undefined.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

NullPointerException - if limit key is null

IllegalStateException - if position is undefined at invocation time

IOException

nextLt

default LockResult nextLt(byte[] limitKey)
                   throws IOException

Moves to the Cursor to the next available entry, but only when less than the given limit key. Cursor key and value are set to null if no applicable entry exists, and position will be undefined.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

NullPointerException - if limit key is null

IllegalStateException - if position is undefined at invocation time

IOException

previous

LockResult previous()
             throws IOException

Moves to the Cursor to the previous available entry. Cursor key and value are set to null if no previous entry exists, and position will be undefined.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

IllegalStateException - if position is undefined at invocation time

IOException

previousGe

default LockResult previousGe(byte[] limitKey)
                       throws IOException

Moves to the Cursor to the previous available entry, but only when greater than or equal to the given limit key. Cursor key and value are set to null if no applicable entry exists, and position will be undefined.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

NullPointerException - if limit key is null

IllegalStateException - if position is undefined at invocation time

IOException

previousGt

default LockResult previousGt(byte[] limitKey)
                       throws IOException

Moves to the Cursor to the previous available entry, but only when greater than the given limit key. Cursor key and value are set to null if no applicable entry exists, and position will be undefined.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

NullPointerException - if limit key is null

IllegalStateException - if position is undefined at invocation time

IOException

find

LockResult find(byte[] key)
         throws IOException

Moves the Cursor to find the given key.

Ownership of the key instance transfers to the Cursor, and it must not be modified after calling this method.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

NullPointerException - if key is null

IOException

findGe

default LockResult findGe(byte[] key)
                   throws IOException

Moves the Cursor to find the first available entry greater than or equal to the given key.

Ownership of the key instance transfers to the Cursor, and it must not be modified after calling this method.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

NullPointerException - if key is null

IOException

findGt

default LockResult findGt(byte[] key)
                   throws IOException

Moves the Cursor to find the first available entry greater than the given key.

Ownership of the key instance transfers to the Cursor, and it must not be modified after calling this method.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

NullPointerException - if key is null

IOException

findLe

default LockResult findLe(byte[] key)
                   throws IOException

Moves the Cursor to find the first available entry less than or equal to the given key.

Ownership of the key instance transfers to the Cursor, and it must not be modified after calling this method.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

NullPointerException - if key is null

IOException

findLt

default LockResult findLt(byte[] key)
                   throws IOException

Moves the Cursor to find the first available entry less than the given key.

Ownership of the key instance transfers to the Cursor, and it must not be modified after calling this method.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

NullPointerException - if key is null

IOException

findNearby

default LockResult findNearby(byte[] key)
                       throws IOException

Optimized version of the regular find method, which can perform fewer search steps if the given key is in close proximity to the current one. Even if not in close proximity, the find outcome is identical, although it may perform more slowly.

Ownership of the key instance transfers to the Cursor, and it must not be modified after calling this method.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

NullPointerException - if key is null

IOException

random

LockResult random(byte[] lowKey,
                  byte[] highKey)
           throws IOException

Moves the Cursor to a random entry, but not guaranteed to be chosen from a uniform distribution. Cursor key and value are set to null if no entries exist, and position will be undefined.

Parameters:

lowKey - inclusive lowest key in the selectable range; pass null for open range

highKey - exclusive highest key in the selectable range; pass null for open range

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

IOException

lock

default LockResult lock()
                 throws IOException

Locks the current entry, as if by calling load. Locking is performed automatically within transactions, and so invocation of this method is necessary only when manually tweaking the lock mode. If a lock was acquired (even if not retained), the cursor value field is updated according to the current autoload mode.

By default, this method simply calls load. Subclasses are encouraged to provide a more efficient implementation.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

IllegalStateException - if position is undefined at invocation time

IOException

load

LockResult load()
         throws IOException

Loads or reloads the value at the cursor's current position. Cursor value is set to null if entry no longer exists, but the position remains unmodified.

Returns:

UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE

Throws:

IllegalStateException - if position is undefined at invocation time

IOException

store

void store(byte[] value)
    throws IOException

Stores a value into the current entry, leaving the position unchanged. An entry may be inserted, updated or deleted by this method. A null value deletes the entry. Unless an exception is thrown, the object returned by the value method will be the same instance as was provided to this method.

Parameters:

value - value to store; pass null to delete

Throws:

IllegalStateException - if position is undefined at invocation time

ViewConstraintException - if value is not permitted

IOException

commit

default void commit(byte[] value)
             throws IOException

Combined store and commit to the linked transaction. Although similar to storing and committing explicitly, additional optimizations can be applied. In particular, no undo log entry is required when committing the outermost transaction scope. This is the same optimization used by null transactions (auto-commit).

Parameters:

value - value to store; pass null to delete

Throws:

IllegalStateException - if position is undefined at invocation time

ViewConstraintException - if value is not permitted

IOException

copy

Cursor copy()

Returns a new independent Cursor, positioned where this one is, and linked to the same transaction. The original and copied Cursor can be acted upon without affecting each other's state.

reset

void reset()

Resets Cursor and moves it to an undefined position. The key and value references are also cleared.