Module org.cojen.tupl
Package org.cojen.tupl

Interface Cursor

All Superinterfaces:
AutoCloseable, Closeable, ValueAccessor
public interface Cursor extends ValueAccessor, Closeable
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:

  • Field Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    autoload()
    Returns the current autoload mode.
    boolean
    autoload(boolean mode)
    By default, values are loaded automatically, as they are seen.
    default void
    close()
    Equivalent to the reset method, which moves the Cursor to an undefined position.
    default void
    commit(byte[] value)
    Combined store and commit to the linked transaction.
    default Comparator<byte[]>
    comparator()
    Returns a key comparator for the ordering of this view, or null if unordered.
    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.
    default void
    delete()
    Deletes the value for the current entry, leaving the position unchanged.
    boolean
    exists()
    Quickly check if the value still exists without locking it.
    LockResult
    find(byte[] key)
    Moves the Cursor to find the given key.
    default LockResult
    findGe(byte[] key)
    Moves the Cursor to find the closest available entry greater than or equal to the given key.
    default LockResult
    findGt(byte[] key)
    Moves the Cursor to find the closest available entry greater than the given key.
    default LockResult
    findLe(byte[] key)
    Moves the Cursor to find the closest available entry less than or equal to the given key.
    default LockResult
    findLt(byte[] key)
    Moves the Cursor to find the closest 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.
    default LockResult
    findNearbyGe(byte[] key)
    Optimized version of the regular findGe method, which can perform fewer search steps if the given key is in close proximity to the current one.
    default LockResult
    findNearbyGt(byte[] key)
    Optimized version of the regular findGt method, which can perform fewer search steps if the given key is in close proximity to the current one.
    default LockResult
    findNearbyLe(byte[] key)
    Optimized version of the regular findLe method, which can perform fewer search steps if the given key is in close proximity to the current one.
    default LockResult
    findNearbyLt(byte[] key)
    Optimized version of the regular findLt 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.
    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.
    Ordering
    ordering()
    Returns the key ordering for this cursor.
    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, boolean lowInclusive, byte[] highKey, boolean highInclusive)
    Moves the Cursor to a random entry, but not guaranteed to be chosen from a uniform distribution.
    default LockResult
    random(byte[] lowKey, byte[] highKey)
    Moves the Cursor to a random entry, but not guaranteed to be chosen from a uniform distribution.
    default boolean
    register()
    Attempt to register this cursor for direct redo operations, which can improve replication performance when modifying a range of values.
    void
    reset()
    Resets the 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.
    default void
    unregister()
    Unregisters the cursor for direct redo operations.
    byte[]
    value()
    Returns an uncopied reference to the current value, which might be null or NOT_LOADED.

    Methods inherited from interface org.cojen.tupl.ValueAccessor

    newValueInputStream, newValueInputStream, newValueOutputStream, newValueOutputStream, valueClear, valueLength, valueLength, valueRead, valueWrite

  • Field Details

    • NOT_LOADED

      static final byte[] NOT_LOADED
      Empty marker which indicates that value exists but has not been loaded.

  • Method Details

    • ordering

      Ordering ordering()
      Returns the key ordering for this cursor.

    • comparator

      default Comparator<byte[]> comparator()
      Returns a key comparator for the ordering of this view, or null if unordered.

    • 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:
      IllegalStateException - 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. Altering the value via the ValueAccessor methods doesn't affect the object returned by this method.

    • 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

    • register

      default boolean register() throws IOException
      Attempt to register this cursor for direct redo operations, which can improve replication performance when modifying a range of values. Without registration, replicas must perform a full find operation for each modification made in the range. Registration isn't useful when using the cursor for single updates.

      The cursor is automatically unregistered when reset, or when moved to an undefined position, or when moving the cursor non-incrementally. Methods whose name starts with "next", "previous", "skip", or "findNearby" are considered to move the cursor incrementally. The use of these methods generally indicates that registering the cursor might be beneficial.

      To be effective, cursor registration must be performed after the cursor is initially positioned: 

      Cursor c = ...
c.findGe(startKey);
c.register(); // register after initial positioning
while (more updates to perform) {
    c.store(...);
    c.next(); // incremental move
}
      Throws:
      IOException

    • unregister

      default void unregister()
      Unregisters the cursor for direct redo operations.
      See Also:

    • 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:
      UnpositionedCursorException - 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:
      UnpositionedCursorException - 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:
      UnpositionedCursorException - 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
      UnpositionedCursorException - 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
      UnpositionedCursorException - 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:
      UnpositionedCursorException - 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
      UnpositionedCursorException - 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
      UnpositionedCursorException - if position is undefined at invocation time
      IOException

    • find

      LockResult find(byte[] key) throws IOException
      Moves the Cursor to find the given key. If no such key exists, the cursor is still positioned at the key, but the value is null.

      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 closest available entry greater than or equal to the given key. If no such key exists, the cursor is unpositioned. Logically equivalent to NavigableMap.ceilingEntry.

      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 closest available entry greater than the given key. If no such key exists, the cursor is unpositioned. Logically equivalent to NavigableMap.higherEntry.

      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 closest available entry less than or equal to the given key. If no such key exists, the cursor is unpositioned. Logically equivalent to NavigableMap.floorEntry.

      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 closest available entry less than the given key. If no such key exists, the cursor is unpositioned. Logically equivalent to NavigableMap.lowerEntry.

      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

    • findNearbyGe

      default LockResult findNearbyGe(byte[] key) throws IOException
      Optimized version of the regular findGe 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

    • findNearbyGt

      default LockResult findNearbyGt(byte[] key) throws IOException
      Optimized version of the regular findGt 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

    • findNearbyLe

      default LockResult findNearbyLe(byte[] key) throws IOException
      Optimized version of the regular findLe 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

    • findNearbyLt

      default LockResult findNearbyLt(byte[] key) throws IOException
      Optimized version of the regular findLt 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

      default 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. If no entries exists, or if random searches aren't supported, the cursor is unpositioned.
      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

    • random

      LockResult random(byte[] lowKey, boolean lowInclusive, byte[] highKey, boolean highInclusive) throws IOException
      Moves the Cursor to a random entry, but not guaranteed to be chosen from a uniform distribution. If no entries exists, or if random searches aren't supported, the cursor is unpositioned.
      Parameters:
      lowKey - lowest key in the selectable range; pass null for open range
      lowInclusive - true for inclusive key, false for exclusive, ignored if key is null
      highKey - highest key in the selectable range; pass null for open range
      highInclusive - true for inclusive key, false for exclusive, ignored if key is null
      Returns:
      UNOWNED, ACQUIRED, OWNED_SHARED, OWNED_UPGRADABLE, or OWNED_EXCLUSIVE
      Throws:
      IOException

    • exists

      boolean exists() throws IOException
      Quickly check if the value still exists without locking it.
      Throws:
      UnpositionedCursorException - if position is undefined at invocation time
      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:
      UnpositionedCursorException - 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:
      UnpositionedCursorException - 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:
      UnpositionedCursorException - if position is undefined at invocation time
      ViewConstraintException - if value is not permitted
      IOException

    • delete

      default void delete() throws IOException
      Deletes the value for the current entry, leaving the position unchanged. Unless an exception is thrown, the object returned by the value method will be null after calling this method.
      Throws:
      UnpositionedCursorException - if position is undefined at invocation time
      ViewConstraintException - if 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:
      UnpositionedCursorException - if position is undefined at invocation time
      ViewConstraintException - if value is not permitted
      IOException
      See Also:

    • 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 the Cursor and moves it to an undefined position. The key and value references are set to null.

    • close

      default void close() throws IOException
      Equivalent to the reset method, which moves the Cursor to an undefined position. The Cursor is re-opened automatically if positioned again.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Specified by:
      close in interface ValueAccessor
      Throws:
      IOException