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 and Description
static class	Cursor.ClosedException Cursor has already been closed.
static class	Cursor.FullException Cursor stack too deep - internal error.

Method Summary

Modifier and Type	Method and 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.
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 Detail

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,
                   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.