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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Dbi.BadDbiException	The specified DBI was changed unexpectedly.
static class	Dbi.BadValueSizeException	Unsupported size of key/DB name/data, or wrong DUPFIXED size.
static class	Dbi.DbFullException	Environment maxdbs reached.
static class	Dbi.IncompatibleException	Operation and DB incompatible, or DB type changed.
static class	Dbi.KeyExistsException	Key/data pair already exists.
static class	Dbi.KeyNotFoundException	Key/data pair not found (EOF).
static class	Dbi.MapResizedException	Database contents grew beyond environment mapsize.

Method Summary

Modifier and Type	Method	Description
void	close()	Close the database handle (normally unnecessary; use with caution).
boolean	delete(Txn<T> txn, T key)	Deletes the key using the passed transaction.
boolean	delete(Txn<T> txn, T key, T val)	Removes key/data pairs from the database.
boolean	delete(T key)	Starts a new read-write transaction and deletes the key.
void	drop(Txn<T> txn)	Drops the data in this database, leaving the database open for further use.
void	drop(Txn<T> txn, boolean delete)	Drops the database.
T	get(Txn<T> txn, T key)	Get items from a database, moving the Txn.val() to the value.
byte[]	getName()	Obtains the name of this database.
CursorIterable<T>	iterate(Txn<T> txn)	Iterate the database from the first item and forwards.
CursorIterable<T>	iterate(Txn<T> txn, KeyRange<T> range)	Iterate the database in accordance with the provided KeyRange and default Comparator.
CursorIterable<T>	iterate(Txn<T> txn, KeyRange<T> range, Comparator<T> comparator)	Iterate the database in accordance with the provided KeyRange and Comparator.
List<DbiFlags>	listFlags(Txn<T> txn)
Cursor<T>	openCursor(Txn<T> txn)	Create a cursor handle.
boolean	put(Txn<T> txn, T key, T val, PutFlags... flags)	Store a key/value pair in the database.
void	put(T key, T val)	Starts a new read-write transaction and puts the key/data pair.
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.
Stat	stat(Txn<T> txn)	Return statistics about this database.

Methods inherited from class java.lang.Object

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

Method Detail

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(org.lmdbjava.Txn, java.lang.Object, java.lang.Object)

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(org.lmdbjava.Txn, java.lang.Object, java.lang.Object)

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(org.lmdbjava.Txn, java.lang.Object, java.lang.Object, org.lmdbjava.PutFlags...)

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.