Package org.lmdbjava

Lightning Memory Database (LMDB) for Java (LmdbJava).

LmdbJava is intended for extremely low latency use cases. Users are required to understand and comply with the LMDB C API contract (eg handle usage patterns, thread binding, process rules).

Priorities:

1. Minimize latency, particularly on any critical path (see below)
2. Preserve the LMDB C API model as far as practical
3. Apply Java idioms only when not in conflict with the above
4. Fully encapsulate (hide) the native call library and patterns
5. Don't require runtime dependencies beyond the native call library
6. Support official JVMs running on typical 64-bit operating systems
7. Prepare for Java 9 (eg Unsafe, native call technology roadmap etc)

Critical paths of special latency focus:

• Releasing and renewing a read-only transaction
• Any operation that uses a cursor

The classes in LmdbJava DO NOT provide any concurrency guarantees. Instead you MUST observe LMDB's specific thread rules (eg do not share transactions between threads). LmdbJava does not shield you from these requirements, as doing so would impose locking overhead on use cases that may not require it or have already carefully implemented application threading (as most low latency applications do to optimize the memory hierarchy, core pinning etc).

Most methods in this package will throw a standard Java exception for failing preconditions (eg NullPointerException if a mandatory argument was missing) or a subclass of LmdbException for precondition or LMDB C failures. The majority of LMDB exceptions indicate an API usage or Env configuration issues, and as such are typically unrecoverable.

Interface Summary

Interface	Description
MaskedFlag	Indicates an enum that can provide integers for each of its values.

Class Summary

Class	Description
BufferProxy<T>	The strategy for mapping memory address to a given buffer type.
ByteArrayProxy	Byte array proxy.
ByteBufferProxy	ByteBuffer-based proxy.
ByteBufProxy	A buffer proxy backed by Netty's ByteBuf.
Cursor<T>	A cursor handle.
CursorIterable<T>	Iterable that creates a single Iterator that will iterate over a Cursor as specified by a KeyRange.
CursorIterable.KeyVal<T>	Holder for a key and value pair.
Dbi<T>	LMDB Database.
DirectBufferProxy	A buffer proxy backed by Agrona's DirectBuffer.
Env<T>	LMDB environment.
Env.Builder<T>	Builder for configuring and opening Env.
EnvInfo	Environment information, as returned by Env.info().
KeyRange<T>	Limits the range and direction of keys to iterate.
Meta	LMDB metadata functions.
Meta.Version	Immutable return value from Meta.version().
Stat	Statistics, as returned by Env.stat() and Dbi.stat(org.lmdbjava.Txn).
Txn<T>	LMDB transaction.
Verifier	Verifies correct operation of LmdbJava in a given environment.

Enum Summary

Enum	Description
CopyFlags	Flags for use when performing a Env.copy(java.io.File, org.lmdbjava.CopyFlags...).
DbiFlags	Flags for use when opening a Dbi.
EnvFlags	Flags for use when opening the Env.
GetOp	Flags for use when performing a Cursor.get(java.lang.Object, org.lmdbjava.GetOp).
KeyRangeType	Key range type.
PutFlags	Flags for use when performing a "put".
SeekOp	Flags for use when performing a Cursor.seek(org.lmdbjava.SeekOp).
TxnFlags	Flags for use when creating a Txn.

Exception Summary

Exception	Description
ByteBufferProxy.BufferMustBeDirectException	The buffer must be a direct buffer (not heap allocated).
Cursor.ClosedException	Cursor has already been closed.
Cursor.FullException	Cursor stack too deep - internal error.
Dbi.BadDbiException	The specified DBI was changed unexpectedly.
Dbi.BadValueSizeException	Unsupported size of key/DB name/data, or wrong DUPFIXED size.
Dbi.DbFullException	Environment maxdbs reached.
Dbi.IncompatibleException	Operation and DB incompatible, or DB type changed.
Dbi.KeyExistsException	Key/data pair already exists.
Dbi.KeyNotFoundException	Key/data pair not found (EOF).
Dbi.MapResizedException	Database contents grew beyond environment mapsize.
Env.AlreadyClosedException	Object has already been closed and the operation is therefore prohibited.
Env.AlreadyOpenException	Object has already been opened and the operation is therefore prohibited.
Env.FileInvalidException	File is not a valid LMDB file.
Env.InvalidCopyDestination	The specified copy destination is invalid.
Env.MapFullException	Environment mapsize reached.
Env.ReadersFullException	Environment maxreaders reached.
Env.VersionMismatchException	Environment version mismatch.
LmdbException	Superclass for all LmdbJava custom exceptions.
LmdbNativeException	Superclass for all exceptions that originate from a native C call.
LmdbNativeException.ConstantDerivedException	Exception raised from a system constant table lookup.
LmdbNativeException.PageCorruptedException	Located page was wrong type.
LmdbNativeException.PageFullException	Page has not enough space - internal error.
LmdbNativeException.PageNotFoundException	Requested page not found - this usually indicates corruption.
LmdbNativeException.PanicException	Update of meta page failed or environment had fatal error.
LmdbNativeException.TlsFullException	Too many TLS keys in use - Windows only.
Txn.BadException	Transaction must abort, has a child, or is invalid.
Txn.BadReaderLockException	Invalid reuse of reader locktable slot.
Txn.EnvIsReadOnly	The proposed R-W transaction is incompatible with a R-O Env.
Txn.IncompatibleParent	The proposed transaction is incompatible with its parent transaction.
Txn.NotReadyException	Transaction is not in a READY state.
Txn.NotResetException	The current transaction has not been reset.
Txn.ReadOnlyRequiredException	The current transaction is not a read-only transaction.
Txn.ReadWriteRequiredException	The current transaction is not a read-write transaction.
Txn.ResetException	The current transaction has already been reset.
Txn.TxFullException	Transaction has too many dirty pages.