Module lmdbjava
Package org.lmdbjava

Class Dbi<T>

java.lang.Object
org.lmdbjava.Dbi<T>
Type Parameters:
T - buffer type
public final class Dbi<T> extends Object
LMDB Database.

  • Method Details

    • close

      public void close()
      Close the database handle (normally unnecessary; use with caution).

      It is very rare that closing a database handle is useful. There are also many warnings/restrictions if closing a database handle (refer to the LMDB C documentation). As such this is non-routine usage and this class does not track the open/closed state of the Dbi. Advanced users are expected to have specific reasons for using this method and will manage their own state accordingly.

    • delete

      public boolean delete(T key)
      Starts a new read-write transaction and deletes the key.
      Parameters:
      key - key to delete from the database (not null)
      Returns:
      true if the key/data pair was found, false otherwise
      See Also:

    • delete

      public boolean delete(Txn<T> txn, T key)
      Deletes the key using the passed transaction.
      Parameters:
      txn - transaction handle (not null; not committed; must be R-W)
      key - key to delete from the database (not null)
      Returns:
      true if the key/data pair was found, false otherwise
      See Also:

    • delete

      public boolean delete(Txn<T> txn, T key, T val)
      Removes key/data pairs from the database.

      If the database does not support sorted duplicate data items (DbiFlags.MDB_DUPSORT) the value parameter is ignored. If the database supports sorted duplicates and the value parameter is null, all of the duplicate data items for the key will be deleted. Otherwise, if the data parameter is non-null only the matching data item will be deleted.

      Parameters:
      txn - transaction handle (not null; not committed; must be R-W)
      key - key to delete from the database (not null)
      val - value to delete from the database (null permitted)
      Returns:
      true if the key/data pair was found, false otherwise

    • drop

      public void drop(Txn<T> txn)
      Drops the data in this database, leaving the database open for further use.

      This method slightly differs from the LMDB C API in that it does not provide support for also closing the DB handle. If closing the DB handle is required, please see close().

      Parameters:
      txn - transaction handle (not null; not committed; must be R-W)

    • drop

      public void drop(Txn<T> txn, boolean delete)
      Drops the database. If delete is set to true, the database will be deleted and handle will be closed. See close() for implication of handle close. Otherwise, only the data in this database will be dropped.
      Parameters:
      txn - transaction handle (not null; not committed; must be R-W)
      delete - whether database should be deleted.

    • get

      public T get(Txn<T> txn, T key)
      Get items from a database, moving the Txn.val() to the value.

      This function retrieves key/data pairs from the database. The address and length of the data associated with the specified \b key are returned in the structure to which \b data refers. If the database supports duplicate keys (DbiFlags.MDB_DUPSORT) then the first data item for the key will be returned. Retrieval of other items requires the use of #mdb_cursor_get().

      Parameters:
      txn - transaction handle (not null; not committed)
      key - key to search for in the database (not null)
      Returns:
      the data or null if not found

    • getName

      public byte[] getName()
      Obtains the name of this database.
      Returns:
      the name (may be null)

    • iterate

      public CursorIterable<T> iterate(Txn<T> txn)
      Iterate the database from the first item and forwards.
      Parameters:
      txn - transaction handle (not null; not committed)
      Returns:
      iterator

    • iterate

      public CursorIterable<T> iterate(Txn<T> txn, KeyRange<T> range)
      Iterate the database in accordance with the provided KeyRange and default Comparator.
      Parameters:
      txn - transaction handle (not null; not committed)
      range - range of acceptable keys (not null)
      Returns:
      iterator (never null)

    • iterate

      public CursorIterable<T> iterate(Txn<T> txn, KeyRange<T> range, Comparator<T> comparator)
      Iterate the database in accordance with the provided KeyRange and Comparator.

      If a comparator is provided, it must reflect the same ordering as LMDB uses for cursor operations (eg first, next, last, previous etc).

      If a null comparator is provided, any comparator provided when opening the database is used. If no database comparator was specified, the buffer's default comparator is used. Such buffer comparators reflect LMDB's default lexicographical order.

      Parameters:
      txn - transaction handle (not null; not committed)
      range - range of acceptable keys (not null)
      comparator - custom comparator for keys (may be null)
      Returns:
      iterator (never null)

    • listFlags

      public List<DbiFlags> listFlags(Txn<T> txn)

    • openCursor

      public Cursor<T> openCursor(Txn<T> txn)
      Create a cursor handle.

      A cursor is associated with a specific transaction and database. A cursor cannot be used when its database handle is closed. Nor when its transaction has ended, except with Cursor.renew(org.lmdbjava.Txn). It can be discarded with Cursor.close(). A cursor in a write-transaction can be closed before its transaction ends, and will otherwise be closed when its transaction ends. A cursor in a read-only transaction must be closed explicitly, before or after its transaction ends. It can be reused with Cursor.renew(org.lmdbjava.Txn) before finally closing it.

      Parameters:
      txn - transaction handle (not null; not committed)
      Returns:
      cursor handle

    • put

      public void put(T key, T val)
      Starts a new read-write transaction and puts the key/data pair.
      Parameters:
      key - key to store in the database (not null)
      val - value to store in the database (not null)
      See Also:

    • put

      public boolean put(Txn<T> txn, T key, T val, PutFlags... flags)
      Store a key/value pair in the database.

      This function stores key/data pairs in the database. The default behavior is to enter the new key/data pair, replacing any previously existing key if duplicates are disallowed, or adding a duplicate data item if duplicates are allowed (DbiFlags.MDB_DUPSORT).

      Parameters:
      txn - transaction handle (not null; not committed; must be R-W)
      key - key to store in the database (not null)
      val - value to store in the database (not null)
      flags - Special 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.

    • reserve

      public T reserve(Txn<T> txn, 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:
      txn - transaction handle (not null; not committed; must be R-W)
      key - key to store in the database (not null)
      size - size of the value to be stored in the database
      op - options for this operation
      Returns:
      a buffer that can be used to modify the value

    • stat

      public Stat stat(Txn<T> txn)
      Return statistics about this database.
      Parameters:
      txn - transaction handle (not null; not committed)
      Returns:
      an immutable statistics object.