jetbrains.exodus.env

Interface Store

All Known Subinterfaces:

ContextualStore

public interface Store

Store is a named collection of key/value pairs. Store can be opened using any of Environment.openStore() methods. If a Store is opened using StoreConfig.WITHOUT_DUPLICATES or StoreConfig.WITHOUT_DUPLICATES_WITH_PREFIXING then it is map, otherwise it is a multi-map. Also Store can be thought as a table with two columns, one for keys and another for values. Both keys and values are managed using instances of ByteIterable. You can use cursors to iterate over a Store, to find nearest key or key/value pair, etc. All operations can only be performed within a transaction.

Stores with and without key prefixing are implemented by different types of search trees. If Store is opened using StoreConfig.WITH_DUPLICATES or StoreConfig.WITHOUT_DUPLICATES then B+ tree is used, otherwise Patricia trie is used. Search tree types differ in performance characteristics: stores with key prefixing has better random key access, whereas stores without key prefixing are preferable for sequential access in order of keys.

Stores are rather stateless objects, so they can be used without any limitations in multi-threaded environments. Opening Store for each database operation is ok, but it will result in some performance overhead. A Store instance cannot be re-used after any of Environment.truncateStore(String, Transaction), Environment.removeStore(String, Transaction) or Environment.clear() methods is called. After truncating, any Store should be re-opened, after removing or clearing the environment it just cannot be used.

See Also:

Environment, Transaction, ContextualStore, Environment.openStore(String, StoreConfig, Transaction), Environment.openStore(String, StoreConfig, Transaction, boolean)

Method Summary

Modifier and Type	Method and Description
boolean	add(@NotNull Transaction txn, @NotNull ByteIterable key, @NotNull ByteIterable value) Adds key/value pair to the Store if the key doesn't exist.
void	close() Deprecated.
long	count(@NotNull Transaction txn)
boolean	delete(@NotNull Transaction txn, @NotNull ByteIterable key) For stores without key duplicates, deletes single key/value pair and returns true if a pair was deleted.
boolean	exists(@NotNull Transaction txn, @NotNull ByteIterable key, @NotNull ByteIterable value) Checks if specified key/value pair exists in the Store.
@Nullable ByteIterable	get(@NotNull Transaction txn, @NotNull ByteIterable key) For stores without key duplicates, it returns not-null value or null if the key doesn't exist.
@NotNull StoreConfig	getConfig()
@NotNull Environment	getEnvironment()
@NotNull java.lang.String	getName()
Cursor	openCursor(@NotNull Transaction txn) Opens cursor over the @{code Store} associated with a transaction.
boolean	put(@NotNull Transaction txn, @NotNull ByteIterable key, @NotNull ByteIterable value) Puts specified key/value pair into the Store and returns the result.
void	putRight(@NotNull Transaction txn, @NotNull ByteIterable key, @NotNull ByteIterable value) Can be used if it is a priori known that the key is definitely greater than any other key in the Store.

Method Detail

getEnvironment

@NotNull
@NotNull Environment getEnvironment()

Returns:

environment which the store was opened for

get

@Nullable
@Nullable ByteIterable get(@NotNull
                                      @NotNull Transaction txn,
                                      @NotNull
                                      @NotNull ByteIterable key)

For stores without key duplicates, it returns not-null value or null if the key doesn't exist. For stores with key duplicates, it returns the smallest not-null value associated with the key or null if no one exists.

Parameters:

txn - transaction instance

key - requested key

Returns:

not-null value if key.value pair with the specified key exists, otherwise null

exists

boolean exists(@NotNull
               @NotNull Transaction txn,
               @NotNull
               @NotNull ByteIterable key,
               @NotNull
               @NotNull ByteIterable value)

Checks if specified key/value pair exists in the Store.

Parameters:

txn - transaction instance

key - key

value - value

Returns:

true if the key/value pair exists in the Store

put

boolean put(@NotNull
            @NotNull Transaction txn,
            @NotNull
            @NotNull ByteIterable key,
            @NotNull
            @NotNull ByteIterable value)

Puts specified key/value pair into the Store and returns the result. For stores with key duplicates, it returns true if the pair didn't exist in the Store. For stores without key duplicates, it returns true if the key didn't exist or the new value differs from the existing one.

	With duplicates	Without duplicates
The key exists	Adds pair, if the value didn't exist	Overwrites value
The key doesn't exist	Adds pair	Adds pair

Parameters:

txn - transaction instance

key - not null key

value - not null value

Returns:

true if specified pair was added or value by the key was overwritten.

putRight

void putRight(@NotNull
              @NotNull Transaction txn,
              @NotNull
              @NotNull ByteIterable key,
              @NotNull
              @NotNull ByteIterable value)

Can be used if it is a priori known that the key is definitely greater than any other key in the Store. In that case, no search is been done before insertion, so putRight() can perform several times faster than put(Transaction, ByteIterable, ByteIterable). It can be useful for auto-generated keys.

Parameters:

txn - transaction instance

key - key

value - value

add

boolean add(@NotNull
            @NotNull Transaction txn,
            @NotNull
            @NotNull ByteIterable key,
            @NotNull
            @NotNull ByteIterable value)

Adds key/value pair to the Store if the key doesn't exist. For stores with and without key duplicates, it returns true if and only if the key doesn't exists. So it never overwrites value of existing key.

	With duplicates	Without duplicates
The key exists	Returns false	Returns false
The key doesn't exist	Adds pair, returns true	Adds pair, returns true

Parameters:

txn - transaction instance

key - key

value - value

Returns:

true if key/value pair was added

delete

boolean delete(@NotNull
               @NotNull Transaction txn,
               @NotNull
               @NotNull ByteIterable key)

For stores without key duplicates, deletes single key/value pair and returns true if a pair was deleted. For stores with key duplicates, it deletes all pairs with the given key and returns true if any was deleted. To delete particular key/value pair, use cursors.

Parameters:

txn - transaction instance

key - key

Returns:

true if a key/value pair was deleted.

count

long count(@NotNull
           @NotNull Transaction txn)

Parameters:

txn - transaction instance

Returns:

the number of key/value pairs in the Store

openCursor

Cursor openCursor(@NotNull
                  @NotNull Transaction txn)

Opens cursor over the @{code Store} associated with a transaction.

Parameters:

txn - transaction instance

Returns:

cursor

close

@Deprecated
void close()

Deprecated.

Deprecated method left only for compatibility with Oracle Berkeley DB JE Database.close() method.

getName

@NotNull
@NotNull java.lang.String getName()

Returns:

name of the Store

getConfig

@NotNull
@NotNull StoreConfig getConfig()

Returns:

StoreConfig using which the Store was opened.