jetbrains.exodus.env

Interface Cursor

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable

public interface Cursor
extends java.io.Closeable

Cursor allows to access key/value pairs of a Store in both successive (ascending and descending) and random order. Cursor can be opened for a Store in a Transaction. Both key (getKey()) and value (getValue()) are accessible as ByteIterable instances. Finally, any cursor should always be closed.

Each newly created cursor points to a "virtual" key/value pair which is prior to the first (leftmost) pair. Use getNext() to move to the first and getPrev() to last (rightmost) key/value pair. You can move Cursor to the last (rightmost) position from any other position using getLast().

See Also:

Store, Store.openCursor(Transaction)

Method Summary

Modifier and Type	Method and Description
void	close() This method should always be called as immediately as possible to avoid unnecessary performance degradation.
int	count()
boolean	deleteCurrent() Deletes current key/value pair in the Store and returns true if deletion succeeded.
@NotNull ByteIterable	getKey()
boolean	getLast() Moves the Cursor to the last (rightmost) key/value pair if any exists.
boolean	getNext() Moves the Cursor to the next key/value pair.
boolean	getNextDup() Moves the Cursor to the next key/value pair with the same key.
boolean	getNextNoDup() Moves the Cursor to the next key/value pair with the nearest key different from current one.
boolean	getPrev() Moves the Cursor to the previous key/value pair.
boolean	getPrevDup() Moves the Cursor to the previous key/value pair with the same key.
boolean	getPrevNoDup() Moves the Cursor to the previous key/value pair with the nearest key different from current one.
boolean	getSearchBoth(@NotNull ByteIterable key, @NotNull ByteIterable value) Moves the Cursor to the key/value pair with the specified key and value and returns true if the pair exists in the Store.
@Nullable ByteIterable	getSearchBothRange(@NotNull ByteIterable key, @NotNull ByteIterable value) Moves the Cursor to the first pair in the Store whose key matches the specified key and whose value is equal to or greater than the specified value.
@Nullable ByteIterable	getSearchKey(@NotNull ByteIterable key) Moves the Cursor to the specified key, and returns the value associated with the key.
@Nullable ByteIterable	getSearchKeyRange(@NotNull ByteIterable key) Moves the Cursor to the first pair in the Store whose key is equal to or greater than the specified key.
@NotNull ByteIterable	getValue()
boolean	isMutable() Cursor is mutable if it is created in a transaction which has dirty (not flushed/committed) modifications.

Method Detail

getNext

boolean getNext()

Moves the Cursor to the next key/value pair. If the Cursor is just created the method moves it to the first (leftmost) key/value pair.

E.g., traversing all key/value pairs of a Store in ascending order looks as follows:

 try (Cursor cursor = store.openCursor(txn)) {
     while (cursor.getNext()) {
         cursor.getKey();   // current key
         cursor.getValue(); // current value
     }
 }
 

Returns:

true if next pair exists

See Also:

getNextDup(), getNextNoDup(), getPrev(), getPrevDup(), getPrevNoDup()

getNextDup

boolean getNextDup()

Moves the Cursor to the next key/value pair with the same key.

Returns:

true if next pair with the same key exists

See Also:

getNext(), getNextNoDup(), getPrev(), getPrevDup(), getPrevNoDup()

getNextNoDup

boolean getNextNoDup()

Moves the Cursor to the next key/value pair with the nearest key different from current one.

Returns:

true if next pair exists

See Also:

getNext(), getNextDup(), getPrev(), getPrevDup(), getPrevNoDup()

getLast

boolean getLast()

Moves the Cursor to the last (rightmost) key/value pair if any exists. Returns true if the Store has at least one key/value pair.

Returns:

true if the Cursor points to the last key/value pair

See Also:

getNext(), getNextDup(), getNextNoDup(), getPrev(), getPrevDup(), getPrevNoDup()

getPrev

boolean getPrev()

Moves the Cursor to the previous key/value pair. If the Cursor is just created the method moves it to the last (rightmost) key/value pair.

E.g., traversing all key/value pairs of a Store in descending order looks as follows:

 try (Cursor cursor = store.openCursor(txn)) {
     while (cursor.getPrev()) {
         cursor.getKey();   // current key
         cursor.getValue(); // current value
     }
 }
 

Returns:

true if previous pair exists

See Also:

getNext(), getNextDup(), getNextNoDup(), getPrevDup(), getPrevNoDup()

getPrevDup

boolean getPrevDup()

Moves the Cursor to the previous key/value pair with the same key.

Returns:

true if previous pair with the same key exists

See Also:

getNext(), getNextDup(), getNextNoDup(), getPrev(), getPrevNoDup()

getPrevNoDup

boolean getPrevNoDup()

Moves the Cursor to the previous key/value pair with the nearest key different from current one.

Returns:

true if previous pair exists

See Also:

getNext(), getNextDup(), getNextNoDup(), getPrev(), getPrevDup()

getKey

@NotNull
@NotNull ByteIterable getKey()

Returns:

current key

See Also:

ByteIterable, getValue()

getValue

@NotNull
@NotNull ByteIterable getValue()

Returns:

current value

See Also:

ByteIterable, getKey()

getSearchKey

@Nullable
@Nullable ByteIterable getSearchKey(@NotNull
                                               @NotNull ByteIterable key)

Moves the Cursor to the specified key, and returns the value associated with the key. In stores with key duplicates, if the matching key has duplicate values, the Cursor moves to the first (leftmost) key/value pair.

If the method fails for any reason, it returns null, and the position of the Cursor will be unchanged.

Parameters:

key - the key to search for

Returns:

first (leftmost) value associated with the key or null if no such value exists

See Also:

getSearchKeyRange(ByteIterable), getSearchBoth(ByteIterable, ByteIterable), getSearchBothRange(ByteIterable, ByteIterable)

getSearchKeyRange

@Nullable
@Nullable ByteIterable getSearchKeyRange(@NotNull
                                                    @NotNull ByteIterable key)

Moves the Cursor to the first pair in the Store whose key is equal to or greater than the specified key. It returns not-null value if it succeeds or null if nothing is found, and the position of the Cursor will be unchanged.

Parameters:

key - the key to search for

Returns:

not-null value if it succeeds or null if nothing is found

See Also:

getSearchKey(ByteIterable), getSearchBoth(ByteIterable, ByteIterable), getSearchBothRange(ByteIterable, ByteIterable)

getSearchBoth

boolean getSearchBoth(@NotNull
                      @NotNull ByteIterable key,
                      @NotNull
                      @NotNull ByteIterable value)

Moves the Cursor to the key/value pair with the specified key and value and returns true if the pair exists in the Store. Otherwise the position of the Cursor will be unchanged.

Parameters:

key - the key to search for

value - the value to search for

Returns:

true if the pair with the specified key and value exists in the Store

See Also:

getSearchKey(ByteIterable), getSearchKeyRange(ByteIterable), getSearchBothRange(ByteIterable, ByteIterable)

getSearchBothRange

@Nullable
@Nullable ByteIterable getSearchBothRange(@NotNull
                                                     @NotNull ByteIterable key,
                                                     @NotNull
                                                     @NotNull ByteIterable value)

Moves the Cursor to the first pair in the Store whose key matches the specified key and whose value is equal to or greater than the specified value. If the Store supports key duplicates, then on matching the key, the Cursor is moved to the duplicate pair with the smallest value that is equal to or greater than the specified value. Like the getSearchKeyRange(ByteIterable) method, it returns not-null value if it succeeds or null if nothing is found, and the position of the Cursor will be unchanged.

Parameters:

key - the key to search for

value - the value to search for

Returns:

not-null value if it succeeds or null if nothing is found

See Also:

getSearchKey(ByteIterable), getSearchKeyRange(ByteIterable), getSearchBoth(ByteIterable, ByteIterable)

count

int count()

Returns:

the number of values in the Store associated with current key

isMutable

boolean isMutable()

Cursor is mutable if it is created in a transaction which has dirty (not flushed/committed) modifications. Mutable cursors automatically pick up changes made using Store.add(Transaction, ByteIterable, ByteIterable), Store.put(Transaction, ByteIterable, ByteIterable) and Store.delete(Transaction, ByteIterable) methods.

Returns:

true if cursor is mutable

close

void close()

This method should always be called as immediately as possible to avoid unnecessary performance degradation.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

deleteCurrent

boolean deleteCurrent()

Deletes current key/value pair in the Store and returns true if deletion succeeded.

Returns:

true if current key/value pair was deleted