Module lmdbjava
Package org.lmdbjava

Class Cursor<T>

java.lang.Object
org.lmdbjava.Cursor<T>
Type Parameters:
T - buffer type
All Implemented Interfaces:
AutoCloseable
public final class Cursor<T> extends Object implements AutoCloseable
A cursor handle.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    Cursor.ClosedException
    Cursor has already been closed.
    static final class 
    Cursor.FullException
    Cursor stack too deep - internal error.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Close a cursor handle.
    long
    count()
    Return count of duplicates for current key.
    void
    delete(PutFlags... f)
    Delete current key/data pair.
    boolean
    first()
    Position at first key/data item.
    boolean
    get(T key, GetOp op)
    Reposition the key/value buffers based on the passed key and operation.
    boolean
    get(T key, T data, SeekOp op)
    Reposition the key/value buffers based on the passed key and operation.
    T
    key()
    Obtain the key.
    boolean
    last()
    Position at last key/data item.
    boolean
    next()
    Position at next data item.
    boolean
    prev()
    Position at previous data item.
    boolean
    put(T key, T val, PutFlags... op)
    Store by cursor.
    void
    putMultiple(T key, T val, int elements, PutFlags... op)
    Put multiple values into the database in one MDB_MULTIPLE operation.
    void
    renew(Txn<T> newTxn)
    Renew a cursor handle.
    T
    reserve(T key, int size, PutFlags... op)
    Reserve space for data of the given size, but don't copy the given val.
    boolean
    seek(SeekOp op)
    Reposition the key/value buffers based on the passed operation.
    T
    val()
    Obtain the value.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • close

      public void close()
      Close a cursor handle.

      The cursor handle will be freed and must not be used again after this call. Its transaction must still be live if it is a write-transaction.

      Specified by:
      close in interface AutoCloseable

    • count

      public long count()
      Return count of duplicates for current key.

      This call is only valid on databases that support sorted duplicate data items DbiFlags.MDB_DUPSORT.

      Returns:
      count of duplicates for current key

    • delete

      public void delete(PutFlags... f)
      Delete current key/data pair.

      This function deletes the key/data pair to which the cursor refers.

      Parameters:
      f - flags (either null or PutFlags.MDB_NODUPDATA

    • first

      public boolean first()
      Position at first key/data item.
      Returns:
      false if requested position not found

    • get

      public boolean get(T key, T data, SeekOp op)
      Reposition the key/value buffers based on the passed key and operation.
      Parameters:
      key - to search for
      data - to search for
      op - options for this operation
      Returns:
      false if key not found

    • get

      public boolean get(T key, GetOp op)
      Reposition the key/value buffers based on the passed key and operation.
      Parameters:
      key - to search for
      op - options for this operation
      Returns:
      false if key not found

    • key

      public T key()
      Obtain the key.
      Returns:
      the key that the cursor is located at.

    • last

      public boolean last()
      Position at last key/data item.
      Returns:
      false if requested position not found

    • next

      public boolean next()
      Position at next data item.
      Returns:
      false if requested position not found

    • prev

      public boolean prev()
      Position at previous data item.
      Returns:
      false if requested position not found

    • put

      public boolean put(T key, T val, PutFlags... op)
      Store by cursor.

      This function stores key/data pairs into the database.

      Parameters:
      key - key to store
      val - data to store
      op - options for this operation
      Returns:
      true if the value was put, false if MDB_NOOVERWRITE or MDB_NODUPDATA were set and the key/value existed already.

    • putMultiple

      public void putMultiple(T key, T val, int elements, PutFlags... op)
      Put multiple values into the database in one MDB_MULTIPLE operation.

      The database must have been opened with DbiFlags.MDB_DUPFIXED. The buffer must contain fixed-sized values to be inserted. The size of each element is calculated from the buffer's size divided by the given element count. For example, to populate 10 X 4 byte integers at once, present a buffer of 40 bytes and specify the element as 10.

      Parameters:
      key - key to store in the database (not null)
      val - value to store in the database (not null)
      elements - number of elements contained in the passed value buffer
      op - options for operation (must set MDB_MULTIPLE)

    • renew

      public void renew(Txn<T> newTxn)
      Renew a cursor handle.

      A cursor is associated with a specific transaction and database. Cursors that are only used in read-only transactions may be re-used, to avoid unnecessary malloc/free overhead. The cursor may be associated with a new read-only transaction, and referencing the same database handle as it was created with. This may be done whether the previous transaction is live or dead.

      Parameters:
      newTxn - transaction handle

    • reserve

      public T reserve(T key, int size, PutFlags... op)
      Reserve space for data of the given size, but don't copy the given val. Instead, return a pointer to the reserved space, which the caller can fill in later - before the next update operation or the transaction ends. This saves an extra memcpy if the data is being generated later. LMDB does nothing else with this memory, the caller is expected to modify all of the space requested.

      This flag must not be specified if the database was opened with MDB_DUPSORT

      Parameters:
      key - key to store in the database (not null)
      size - size of the value to be stored in the database (not null)
      op - options for this operation
      Returns:
      a buffer that can be used to modify the value

    • seek

      public boolean seek(SeekOp op)
      Reposition the key/value buffers based on the passed operation.
      Parameters:
      op - options for this operation
      Returns:
      false if requested position not found

    • val

      public T val()
      Obtain the value.
      Returns:
      the value that the cursor is located at.