oracle.kv
Interface KVStore

All Superinterfaces:

Closeable, KVLargeObject

public interface KVStore
extends KVLargeObject, Closeable

KVStore is the handle to a store that is running remotely. To create a connection to a store, request a KVStore instance from KVStoreFactory.getStore.

Method Summary

void	close() Close the K/V Store handle and release resources.
boolean	delete(Key key) Delete the key/value pair associated with the key.
boolean	delete(Key key, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit) Delete the key/value pair associated with the key.
boolean	deleteIfVersion(Key key, Version matchVersion) Delete a key/value pair, but only if the version of the existing value matches the matchVersion argument.
boolean	deleteIfVersion(Key key, Version matchVersion, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit) Delete a key/value pair, but only if the version of the existing value matches the matchVersion argument.
List<OperationResult>	execute(List<Operation> operations) This method provides an efficient and transactional mechanism for executing a sequence of operations associated with keys that share the same Major Path.
List<OperationResult>	execute(List<Operation> operations, Durability durability, long timeout, TimeUnit timeoutUnit) This method provides an efficient and transactional mechanism for executing a sequence of operations associated with keys that share the same Major Path.
ValueVersion	get(Key key) Get the value associated with the key.
ValueVersion	get(Key key, Consistency consistency, long timeout, TimeUnit timeoutUnit) Get the value associated with the key.
AvroCatalog	getAvroCatalog() Returns the catalog of Avro schemas and bindings for this store.
OperationFactory	getOperationFactory() Returns a factory that is used to creation operations that can be passed to execute.
KVStats	getStats(boolean clear) Returns the statistics related to the K/V Store client.
int	multiDelete(Key parentKey, KeyRange subRange, Depth depth) Deletes the descendant Key/Value pairs associated with the parentKey.
int	multiDelete(Key parentKey, KeyRange subRange, Depth depth, Durability durability, long timeout, TimeUnit timeoutUnit) Deletes the descendant Key/Value pairs associated with the parentKey.
SortedMap<Key,ValueVersion>	multiGet(Key parentKey, KeyRange subRange, Depth depth) Returns the descendant key/value pairs associated with the parentKey.
SortedMap<Key,ValueVersion>	multiGet(Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit) Returns the descendant key/value pairs associated with the parentKey.
Iterator<KeyValueVersion>	multiGetIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth) The iterator form of multiGet(Key, KeyRange, Depth).
Iterator<KeyValueVersion>	multiGetIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit) The iterator form of multiGet(Key, KeyRange, Depth, Consistency, long, TimeUnit).
SortedSet<Key>	multiGetKeys(Key parentKey, KeyRange subRange, Depth depth) Returns the descendant keys associated with the parentKey.
SortedSet<Key>	multiGetKeys(Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit) Returns the descendant keys associated with the parentKey.
Iterator<Key>	multiGetKeysIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth) The iterator form of multiGetKeys(Key, KeyRange, Depth).
Iterator<Key>	multiGetKeysIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit) The iterator form of multiGetKeys(Key, KeyRange, Depth, Consistency, long, TimeUnit).
Version	put(Key key, Value value) Put a key/value pair, inserting or overwriting as appropriate.
Version	put(Key key, Value value, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit) Put a key/value pair, inserting or overwriting as appropriate.
Version	putIfAbsent(Key key, Value value) Put a key/value pair, but only if no value for the given key is present.
Version	putIfAbsent(Key key, Value value, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit) Put a key/value pair, but only if no value for the given key is present.
Version	putIfPresent(Key key, Value value) Put a key/value pair, but only if a value for the given key is present.
Version	putIfPresent(Key key, Value value, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit) Put a key/value pair, but only if a value for the given key is present.
Version	putIfVersion(Key key, Value value, Version matchVersion) Put a key/value pair, but only if the version of the existing value matches the matchVersion argument.
Version	putIfVersion(Key key, Value value, Version matchVersion, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit) Put a key/value pair, but only if the version of the existing value matches the matchVersion argument.
Iterator<KeyValueVersion>	storeIterator(Direction direction, int batchSize) Return an Iterator which iterates over all key/value pairs in unsorted order.
Iterator<KeyValueVersion>	storeIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth) Return an Iterator which iterates over all key/value pairs (or the descendants of a parentKey, or those in a KeyRange) in unsorted order.
Iterator<KeyValueVersion>	storeIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit) Return an Iterator which iterates over all key/value pairs (or the descendants of a parentKey, or those in a KeyRange) in unsorted order.
Iterator<Key>	storeKeysIterator(Direction direction, int batchSize) Return an Iterator which iterates over all keys in unsorted order.
Iterator<Key>	storeKeysIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth) Return an Iterator which iterates over all keys (or the descendants of a parentKey, or those in a KeyRange) in unsorted order.
Iterator<Key>	storeKeysIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit) Return an Iterator which iterates over all keys (or the descendants of a parentKey, or those in a KeyRange) in unsorted order.

Methods inherited from interface oracle.kv.lob.KVLargeObject

deleteLOB, getLOB, putLOB, putLOBIfAbsent, putLOBIfPresent

Method Detail

get

ValueVersion get(Key key)
                 throws ConsistencyException,
                        RequestTimeoutException,
                        FaultException

Get the value associated with the key.

The default consistency and default request timeout are used.

Parameters:

key - the key used to lookup the key/value pair.

Returns:

the value and version associated with the key, or null if no associated value was found.

Throws:

ConsistencyException - if the specified Consistency cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

get

ValueVersion get(Key key,
                 Consistency consistency,
                 long timeout,
                 TimeUnit timeoutUnit)
                 throws ConsistencyException,
                        RequestTimeoutException,
                        FaultException

Get the value associated with the key.

Parameters:

key - the key used to lookup the key/value pair.

consistency - determines the consistency associated with the read used to lookup the value. If null, the default consistency is used.

timeout - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the default request timeout is used.

timeoutUnit - is the unit of the timeout parameter, and may be null only if timeout is zero.

Returns:

the value and version associated with the key, or null if no associated value was found.

Throws:

ConsistencyException - if the specified Consistency cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

multiGet

SortedMap<Key,ValueVersion> multiGet(Key parentKey,
                                     KeyRange subRange,
                                     Depth depth)
                                     throws ConsistencyException,
                                            RequestTimeoutException,
                                            FaultException

Returns the descendant key/value pairs associated with the parentKey. The subRange and the depth arguments can be used to further limit the key/value pairs that are retrieved. The key/value pairs are fetched within the scope of a single transaction that effectively provides serializable isolation.

This API should be used with caution since it could result in an OutOfMemoryError, or excessive GC activity, if the results cannot all be held in memory at one time. Consider using the multiGetIterator(oracle.kv.Direction, int, oracle.kv.Key, oracle.kv.KeyRange, oracle.kv.Depth) version instead.

This method only allows fetching key/value pairs that are descendants of a parentKey that has a complete major path. To fetch the descendants of a parentKey with a partial major path, use storeIterator(oracle.kv.Direction, int) instead.

The default consistency and default request timeout are used.

Parameters:

parentKey - the parent key whose "child" KV pairs are to be fetched. It must not be null. The major key path must be complete. The minor key path may be omitted or may be a partial path.

subRange - further restricts the range under the parentKey to the minor path components in this subRange. It may be null.

depth - specifies whether the parent and only children or all descendants are returned. If null, Depth.PARENT_AND_DESCENDANTS is implied.

Returns:

a SortedMap of key-value pairs, one for each key selected, or an empty map if no keys are selected.

Throws:

ConsistencyException - if the specified Consistency cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

multiGet

SortedMap<Key,ValueVersion> multiGet(Key parentKey,
                                     KeyRange subRange,
                                     Depth depth,
                                     Consistency consistency,
                                     long timeout,
                                     TimeUnit timeoutUnit)
                                     throws ConsistencyException,
                                            RequestTimeoutException,
                                            FaultException

Returns the descendant key/value pairs associated with the parentKey. The subRange and the depth arguments can be used to further limit the key/value pairs that are retrieved. The key/value pairs are fetched within the scope of a single transaction that effectively provides serializable isolation.

This API should be used with caution since it could result in an OutOfMemoryError, or excessive GC activity, if the results cannot all be held in memory at one time. Consider using the multiGetIterator(oracle.kv.Direction, int, oracle.kv.Key, oracle.kv.KeyRange, oracle.kv.Depth) version instead.

This method only allows fetching key/value pairs that are descendants of a parentKey that has a complete major path. To fetch the descendants of a parentKey with a partial major path, use storeIterator(oracle.kv.Direction, int) instead.

Parameters:

parentKey - the parent key whose "child" KV pairs are to be fetched. It must not be null. The major key path must be complete. The minor key path may be omitted or may be a partial path.

subRange - further restricts the range under the parentKey to the minor path components in this subRange. It may be null.

depth - specifies whether the parent and only children or all descendants are returned. If null, Depth.PARENT_AND_DESCENDANTS is implied.

consistency - determines the read consistency associated with the lookup of the child KV pairs. If null, the default consistency is used.

timeout - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the default request timeout is used.

timeoutUnit - is the unit of the timeout parameter, and may be null only if timeout is zero.

Returns:

a SortedMap of key-value pairs, one for each key selected, or an empty map if no keys are selected.

Throws:

ConsistencyException - if the specified Consistency cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

multiGetKeys

SortedSet<Key> multiGetKeys(Key parentKey,
                            KeyRange subRange,
                            Depth depth)
                            throws ConsistencyException,
                                   RequestTimeoutException,
                                   FaultException

Returns the descendant keys associated with the parentKey.

This method is almost identical to multiGet(Key, KeyRange, Depth). It differs solely in the type of its return value: It returns a SortedSet of keys instead of returning a SortedMap representing key-value pairs.

Throws:

ConsistencyException

RequestTimeoutException

FaultException

See Also:

multiGet(Key, KeyRange, Depth)

multiGetKeys

SortedSet<Key> multiGetKeys(Key parentKey,
                            KeyRange subRange,
                            Depth depth,
                            Consistency consistency,
                            long timeout,
                            TimeUnit timeoutUnit)
                            throws ConsistencyException,
                                   RequestTimeoutException,
                                   FaultException

Returns the descendant keys associated with the parentKey.

This method is almost identical to multiGet(Key, KeyRange, Depth, Consistency, long, TimeUnit). It differs solely in the type of its return value: It returns a SortedSet of keys instead of returning a SortedMap representing key-value pairs.

Throws:

ConsistencyException

RequestTimeoutException

FaultException

See Also:

multiGet(Key, KeyRange, Depth, Consistency, long, TimeUnit)

multiGetIterator

Iterator<KeyValueVersion> multiGetIterator(Direction direction,
                                           int batchSize,
                                           Key parentKey,
                                           KeyRange subRange,
                                           Depth depth)
                                           throws ConsistencyException,
                                                  RequestTimeoutException,
                                                  FaultException

The iterator form of multiGet(Key, KeyRange, Depth).

The iterator permits an ordered traversal of the descendant key/value pairs associated with the parentKey. It's useful when the result is too large to fit in memory. Note that the result is not transactional and the operation effectively provides read-committed isolation. The implementation batches the fetching of KV pairs in the iterator, to minimize the number of network round trips, while not monopolizing the available bandwidth.

This method only allows fetching key/value pairs that are descendants of a parentKey that has a complete major path. To fetch the descendants of a parentKey with a partial major path, use storeIterator(oracle.kv.Direction, int) instead.

The iterator does not support the remove method.

The default consistency and default request timeout are used.

Parameters:

direction - specifies the order in which records are returned by the iterator. Only Direction.FORWARD and Direction.REVERSE are supported by this method.

batchSize - the suggested number of keys to fetch during each network round trip. If only the first or last key-value pair is desired, passing a value of one (1) is recommended. If zero, an internally determined default is used.

parentKey - the parent key whose "child" KV pairs are to be fetched. It must not be null. The major key path must be complete. The minor key path may be omitted or may be a partial path.

subRange - further restricts the range under the parentKey to the minor path components in this subRange. It may be null.

depth - specifies whether the parent and only children or all descendants are returned. If null, Depth.PARENT_AND_DESCENDANTS is implied.

Returns:

an iterator that permits an ordered traversal of the descendant key/value pairs.

Throws:

ConsistencyException - if the specified Consistency cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

multiGetIterator

Iterator<KeyValueVersion> multiGetIterator(Direction direction,
                                           int batchSize,
                                           Key parentKey,
                                           KeyRange subRange,
                                           Depth depth,
                                           Consistency consistency,
                                           long timeout,
                                           TimeUnit timeoutUnit)
                                           throws ConsistencyException,
                                                  RequestTimeoutException,
                                                  FaultException

The iterator form of multiGet(Key, KeyRange, Depth, Consistency, long, TimeUnit).

The iterator permits an ordered traversal of the descendant key/value pairs associated with the parentKey. It's useful when the result is too large to fit in memory. Note that the result is not transactional and the operation effectively provides read-committed isolation. The implementation batches the fetching of KV pairs in the iterator, to minimize the number of network round trips, while not monopolizing the available bandwidth.

This method only allows fetching key/value pairs that are descendants of a parentKey that has a complete major path. To fetch the descendants of a parentKey with a partial major path, use storeIterator(oracle.kv.Direction, int) instead.

The iterator does not support the remove method.

The default consistency and default request timeout are used.

Parameters:

direction - specifies the order in which records are returned by the iterator. Only Direction.FORWARD and Direction.REVERSE are supported by this method.

batchSize - the suggested number of keys to fetch during each network round trip. If only the first or last key-value pair is desired, passing a value of one (1) is recommended. If zero, an internally determined default is used.

parentKey - the parent key whose "child" KV pairs are to be fetched. It must not be null. The major key path must be complete. The minor key path may be omitted or may be a partial path.

subRange - further restricts the range under the parentKey to the minor path components in this subRange. It may be null.

depth - specifies whether the parent and only children or all descendants are returned. If null, Depth.PARENT_AND_DESCENDANTS is implied.

consistency - determines the read consistency associated with the lookup of the child KV pairs. If null, the default consistency is used.

timeout - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the default request timeout is used.

timeoutUnit - is the unit of the timeout parameter, and may be null only if timeout is zero.

Returns:

an iterator that permits an ordered traversal of the descendant key/value pairs.

Throws:

ConsistencyException - if the specified Consistency cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

multiGetKeysIterator

Iterator<Key> multiGetKeysIterator(Direction direction,
                                   int batchSize,
                                   Key parentKey,
                                   KeyRange subRange,
                                   Depth depth)
                                   throws ConsistencyException,
                                          RequestTimeoutException,
                                          FaultException

The iterator form of multiGetKeys(Key, KeyRange, Depth).

This method is almost identical to multiGetIterator(Direction, int, Key, KeyRange, Depth). It differs solely in the type of its return value: it returns an iterator over keys instead of key/value pairs.

Throws:

ConsistencyException

RequestTimeoutException

FaultException

See Also:

multiGetIterator(Direction, int, Key, KeyRange, Depth)

multiGetKeysIterator

Iterator<Key> multiGetKeysIterator(Direction direction,
                                   int batchSize,
                                   Key parentKey,
                                   KeyRange subRange,
                                   Depth depth,
                                   Consistency consistency,
                                   long timeout,
                                   TimeUnit timeoutUnit)
                                   throws ConsistencyException,
                                          RequestTimeoutException,
                                          FaultException

The iterator form of multiGetKeys(Key, KeyRange, Depth, Consistency, long, TimeUnit).

This method is almost identical to multiGetIterator(Direction, int, Key, KeyRange, Depth, Consistency, long, TimeUnit). It differs solely in the type of its return value: it returns an iterator over keys instead of key/value pairs.

Throws:

ConsistencyException

RequestTimeoutException

FaultException

See Also:

multiGetIterator(Direction, int, Key, KeyRange, Depth, Consistency, long, TimeUnit)

storeIterator

Iterator<KeyValueVersion> storeIterator(Direction direction,
                                        int batchSize)
                                        throws ConsistencyException,
                                               RequestTimeoutException,
                                               FaultException

Return an Iterator which iterates over all key/value pairs in unsorted order.

Note that the result is not transactional and the operation effectively provides read-committed isolation. The implementation batches the fetching of KV pairs in the iterator, to minimize the number of network round trips, while not monopolizing the available bandwidth.

The iterator does not support the remove method.

The default consistency and default request timeout are used.

Parameters:

direction - specifies the order in which records are returned by the iterator. Currently only Direction.UNORDERED is supported by this method.

batchSize - the suggested number of keys to fetch during each network round trip. If only the first or last key-value pair is desired, passing a value of one (1) is recommended. If zero, an internally determined default is used.

Throws:

ConsistencyException - if the specified Consistency cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

storeIterator

Iterator<KeyValueVersion> storeIterator(Direction direction,
                                        int batchSize,
                                        Key parentKey,
                                        KeyRange subRange,
                                        Depth depth)
                                        throws ConsistencyException,
                                               RequestTimeoutException,
                                               FaultException

Return an Iterator which iterates over all key/value pairs (or the descendants of a parentKey, or those in a KeyRange) in unsorted order.

Note that the result is not transactional and the operation effectively provides read-committed isolation. The implementation batches the fetching of KV pairs in the iterator, to minimize the number of network round trips, while not monopolizing the available bandwidth.

This method only allows fetching key/value pairs that are descendants of a parentKey that is null or has a partial major path. To fetch the descendants of a parentKey with a complete major path, use multiGetIterator(oracle.kv.Direction, int, oracle.kv.Key, oracle.kv.KeyRange, oracle.kv.Depth) instead.

The iterator does not support the remove method.

The default consistency and default request timeout are used.

Parameters:

direction - specifies the order in which records are returned by the iterator. Currently only Direction.UNORDERED is supported by this method.

batchSize - the suggested number of keys to fetch during each network round trip. If only the first or last key-value pair is desired, passing a value of one (1) is recommended. If zero, an internally determined default is used.

parentKey - the parent key whose "child" KV pairs are to be fetched. It may be null to fetch all keys in the store. If non-null, the major key path must be a partial path and the minor key path must be empty.

subRange - further restricts the range under the parentKey to the major path components in this subRange. It may be null.

depth - specifies whether the parent and only children or all descendants are returned. If null, Depth.PARENT_AND_DESCENDANTS is implied.

Throws:

ConsistencyException - if the specified Consistency cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

storeIterator

Iterator<KeyValueVersion> storeIterator(Direction direction,
                                        int batchSize,
                                        Key parentKey,
                                        KeyRange subRange,
                                        Depth depth,
                                        Consistency consistency,
                                        long timeout,
                                        TimeUnit timeoutUnit)
                                        throws ConsistencyException,
                                               RequestTimeoutException,
                                               FaultException

Return an Iterator which iterates over all key/value pairs (or the descendants of a parentKey, or those in a KeyRange) in unsorted order.

Note that the result is not transactional and the operation effectively provides read-committed isolation. The implementation batches the fetching of KV pairs in the iterator, to minimize the number of network round trips, while not monopolizing the available bandwidth.

This method only allows fetching key/value pairs that are descendants of a parentKey that is null or has a partial major path. To fetch the descendants of a parentKey with a complete major path, use multiGetIterator(oracle.kv.Direction, int, oracle.kv.Key, oracle.kv.KeyRange, oracle.kv.Depth) instead.

The iterator does not support the remove method.

The default consistency and default request timeout are used.

Parameters:

direction - specifies the order in which records are returned by the iterator. Currently only Direction.UNORDERED is supported by this method.

batchSize - the suggested number of keys to fetch during each network round trip. If only the first or last key-value pair is desired, passing a value of one (1) is recommended. If zero, an internally determined default is used.

parentKey - the parent key whose "child" KV pairs are to be fetched. It may be null to fetch all keys in the store. If non-null, the major key path must be a partial path and the minor key path must be empty.

subRange - further restricts the range under the parentKey to the major path components in this subRange. It may be null.

depth - specifies whether the parent and only children or all descendants are returned. If null, Depth.PARENT_AND_DESCENDANTS is implied.

consistency - determines the read consistency associated with the lookup of the child KV pairs. Version-based consistency may not be used. If null, the default consistency is used.

timeout - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the default request timeout is used.

timeoutUnit - is the unit of the timeout parameter, and may be null only if timeout is zero.

Throws:

ConsistencyException - if the specified Consistency cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

storeKeysIterator

Iterator<Key> storeKeysIterator(Direction direction,
                                int batchSize)
                                throws ConsistencyException,
                                       RequestTimeoutException,
                                       FaultException

Return an Iterator which iterates over all keys in unsorted order.

This method is almost identical to storeIterator(Direction, int). It differs solely in the type of its return value: it returns an iterator over keys instead of key/value pairs.

Throws:

ConsistencyException

RequestTimeoutException

FaultException

See Also:

storeIterator(Direction, int)

storeKeysIterator

Iterator<Key> storeKeysIterator(Direction direction,
                                int batchSize,
                                Key parentKey,
                                KeyRange subRange,
                                Depth depth)
                                throws ConsistencyException,
                                       RequestTimeoutException,
                                       FaultException

Return an Iterator which iterates over all keys (or the descendants of a parentKey, or those in a KeyRange) in unsorted order.

This method is almost identical to storeIterator(Direction, int, Key, KeyRange, Depth). It differs solely in the type of its return value: it returns an iterator over keys instead of key/value pairs.

Throws:

ConsistencyException

RequestTimeoutException

FaultException

See Also:

storeIterator(Direction, int)

storeKeysIterator

Iterator<Key> storeKeysIterator(Direction direction,
                                int batchSize,
                                Key parentKey,
                                KeyRange subRange,
                                Depth depth,
                                Consistency consistency,
                                long timeout,
                                TimeUnit timeoutUnit)
                                throws ConsistencyException,
                                       RequestTimeoutException,
                                       FaultException

Return an Iterator which iterates over all keys (or the descendants of a parentKey, or those in a KeyRange) in unsorted order.

This method is almost identical to storeIterator(Direction, int, Key, KeyRange, Depth, Consistency, long, TimeUnit). It differs solely in the type of its return value: it returns an iterator over keys instead of key/value pairs.

Throws:

ConsistencyException

RequestTimeoutException

FaultException

See Also:

storeIterator(Direction, int, Key, KeyRange, Depth, Consistency, long, TimeUnit)

put

Version put(Key key,
            Value value)
            throws DurabilityException,
                   RequestTimeoutException,
                   FaultException

Put a key/value pair, inserting or overwriting as appropriate.

The default durability and default request timeout are used.

Possible outcomes when calling this method are:

1. The KV pair was inserted or updated and the (non-null) version of the new KV pair is returned. There is no way to distinguish between an insertion and an update when using this method signature.
2. The KV pair was not guaranteed to be inserted or updated successfully, and one of the exceptions listed below is thrown.

Parameters:

key - the key part of the key/value pair.

value - the value part of the key/value pair.

Returns:

the version of the new value.

Throws:

DurabilityException - if the specified Durability cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

put

Version put(Key key,
            Value value,
            ReturnValueVersion prevValue,
            Durability durability,
            long timeout,
            TimeUnit timeoutUnit)
            throws DurabilityException,
                   RequestTimeoutException,
                   FaultException

Put a key/value pair, inserting or overwriting as appropriate.

Possible outcomes when calling this method are:

1. The KV pair was inserted or updated and the (non-null) version of the new KV pair is returned. The prevValue parameter may be specified to determine whether an insertion or update was performed. If a non-null previous value or version is returned then an update was performed, otherwise an insertion was performed. The previous value or version may also be useful for other application specific reasons.
2. The KV pair was not guaranteed to be inserted or updated successfully, and one of the exceptions listed below is thrown. The prevValue parameter, if specified, is left unmodified.

Parameters:

key - the key part of the key/value pair

value - the value part of the key/value pair.

prevValue - a ReturnValueVersion object to contain the previous value and version associated with the given key, or null if they should not be returned. The version and value in this object are set to null if a previous value does not exist, or the ReturnValueVersion.Choice specifies that they should not be returned.

durability - the durability associated with the operation. If null, the default durability is used.

timeout - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the default request timeout is used.

timeoutUnit - is the unit of the timeout parameter, and may be null only if timeout is zero.

Returns:

the version of the new value.

Throws:

DurabilityException - if the specified Durability cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

putIfAbsent

Version putIfAbsent(Key key,
                    Value value)
                    throws DurabilityException,
                           RequestTimeoutException,
                           FaultException

Put a key/value pair, but only if no value for the given key is present.

The default durability and default request timeout are used.

Possible outcomes when calling this method are:

1. The KV pair was inserted and the (non-null) version of the new KV pair is returned.
2. The KV pair was not inserted because a value was already present with the given key; null is returned and no exception is thrown.
3. The KV pair was not guaranteed to be inserted successfully and one of the exceptions listed below is thrown.

Parameters:

key - the key part of the key/value pair.

value - the value part of the key/value pair.

Returns:

the version of the new value, or null if an existing value is present and the put is unsuccessful.

Throws:

DurabilityException - if the specified Durability cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

putIfAbsent

Version putIfAbsent(Key key,
                    Value value,
                    ReturnValueVersion prevValue,
                    Durability durability,
                    long timeout,
                    TimeUnit timeoutUnit)
                    throws DurabilityException,
                           RequestTimeoutException,
                           FaultException

Put a key/value pair, but only if no value for the given key is present.

Possible outcomes when calling this method are:

1. The KV pair was inserted and the (non-null) version of the new KV pair is returned. The prevValue parameter, if specified, will contain a null previous value and version.
2. The KV pair was not inserted because a value was already present with the given key; null is returned and no exception is thrown. The prevValue parameter, if specified, will contain a non-null previous value and version. The previous value and version may be useful for application specific reasons; for example, if an update will be performed next in this case.
3. The KV pair was not guaranteed to be inserted successfully and one of the exceptions listed below is thrown. The prevValue parameter, if specified, is left unmodified.

Parameters:

key - the key part of the key/value pair.

value - the value part of the key/value pair.

prevValue - a ReturnValueVersion object to contain the previous value and version associated with the given key, or null if they should not be returned. The version and value in this object are set to null if a previous value does not exist, or the ReturnValueVersion.Choice specifies that they should not be returned.

durability - the durability associated with the operation. If null, the default durability is used.

timeout - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the default request timeout is used.

timeoutUnit - is the unit of the timeout parameter, and may be null only if timeout is zero.

Returns:

the version of the new value, or null if an existing value is present and the put is unsuccessful.

Throws:

DurabilityException - if the specified Durability cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

putIfPresent

Version putIfPresent(Key key,
                     Value value)
                     throws DurabilityException,
                            RequestTimeoutException,
                            FaultException

Put a key/value pair, but only if a value for the given key is present.

The default durability and default request timeout are used.

Possible outcomes when calling this method are:

1. The KV pair was updated and the (non-null) version of the new KV pair is returned.
2. The KV pair was not updated because no existing value was present with the given key; null is returned and no exception is thrown.
3. The KV pair was not guaranteed to be updated successfully and one of the exceptions listed below is thrown.

Parameters:

key - the key part of the key/value pair.

value - the value part of the key/value pair.

Returns:

the version of the new value, or null if no existing value is present and the put is unsuccessful.

Throws:

DurabilityException - if the specified Durability cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

putIfPresent

Version putIfPresent(Key key,
                     Value value,
                     ReturnValueVersion prevValue,
                     Durability durability,
                     long timeout,
                     TimeUnit timeoutUnit)
                     throws DurabilityException,
                            RequestTimeoutException,
                            FaultException

Put a key/value pair, but only if a value for the given key is present.

Possible outcomes when calling this method are:

1. The KV pair was updated and the (non-null) version of the new KV pair is returned. The prevValue parameter, if specified, will contain a non-null previous value and version. The previous value and version may be useful for application specific reasons.
2. The KV pair was not updated because no existing value was present with the given key; null is returned and no exception is thrown. The prevValue parameter, if specified, will contain a null previous value and version.
3. The KV pair was not guaranteed to be updated successfully and one of the exceptions listed below is thrown. The prevValue parameter, if specified, is left unmodified.

Parameters:

key - the key part of the key/value pair.

value - the value part of the key/value pair.

prevValue - a ReturnValueVersion object to contain the previous value and version associated with the given key, or null if they should not be returned. The version and value in this object are set to null if a previous value does not exist, or the ReturnValueVersion.Choice specifies that they should not be returned.

durability - the durability associated with the operation. If null, the default durability is used.

timeout - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the default request timeout is used.

timeoutUnit - is the unit of the timeout parameter, and may be null only if timeout is zero.

Returns:

the version of the new value, or null if no existing value is present and the put is unsuccessful.

Throws:

DurabilityException - if the specified Durability cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

putIfVersion

Version putIfVersion(Key key,
                     Value value,
                     Version matchVersion)
                     throws DurabilityException,
                            RequestTimeoutException,
                            FaultException

Put a key/value pair, but only if the version of the existing value matches the matchVersion argument. Used when updating a value to ensure that it has not changed since it was last read.

The default durability and default request timeout are used.

Possible outcomes when calling this method are:

1. The KV pair was updated and the (non-null) version of the new KV pair is returned.
2. The KV pair was not updated because no existing value was present with the given key, or the version of the existing KV pair did not equal the given matchVersion parameter; null is returned and no exception is thrown.
3. The KV pair was not guaranteed to be updated successfully and one of the exceptions listed below is thrown.

Parameters:

key - the key part of the key/value pair.

value - the value part of the key/value pair.

matchVersion - the version to be matched.

Returns:

the version of the new value, or null if the matchVersion parameter does not match the existing value (or no existing value is present) and the put is unsuccessful.

Throws:

DurabilityException - if the specified Durability cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

putIfVersion

Version putIfVersion(Key key,
                     Value value,
                     Version matchVersion,
                     ReturnValueVersion prevValue,
                     Durability durability,
                     long timeout,
                     TimeUnit timeoutUnit)
                     throws DurabilityException,
                            RequestTimeoutException,
                            FaultException

Put a key/value pair, but only if the version of the existing value matches the matchVersion argument. Used when updating a value to ensure that it has not changed since it was last read.

Possible outcomes when calling this method are:

1. The KV pair was updated and the (non-null) version of the new KV pair is returned. The prevValue parameter, if specified, will contain a non-null previous value and version. The previous value may be useful for application specific reasons.
2. The KV pair was not updated because no existing value was present with the given key, or the version of the existing KV pair did not equal the given matchVersion parameter; null is returned and no exception is thrown. The prevValue parameter may be specified to determine whether the failure was due to a missing KV pair or a version mismatch. If a null previous value or version is returned then the KV pair was missing, otherwise a version mismatch occurred. The previous value or version may also be useful for other application specific reasons.
3. The KV pair was not guaranteed to be updated successfully and one of the exceptions listed below is thrown. The prevValue parameter, if specified, is left unmodified.

Parameters:

key - the key part of the key/value pair.

value - the value part of the key/value pair.

matchVersion - the version to be matched.

prevValue - a ReturnValueVersion object to contain the previous value and version associated with the given key, or null if they should not be returned. The version and value in this object are set to null if a previous value does not exist, or the ReturnValueVersion.Choice specifies that they should not be returned, or the matchVersion parameter matches the existing value and the put is successful.

durability - the durability associated with the operation. If null, the default durability is used.

timeout - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the default request timeout is used.

timeoutUnit - is the unit of the timeout parameter, and may be null only if timeout is zero.

Returns:

the version of the new value, or null if the matchVersion parameter does not match the existing value (or no existing value is present) and the put is unsuccessful.

Throws:

DurabilityException - if the specified Durability cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

delete

boolean delete(Key key)
               throws DurabilityException,
                      RequestTimeoutException,
                      FaultException

Delete the key/value pair associated with the key.

Deleting a key/value pair with this method does not automatically delete its children or descendant key/value pairs. To delete children or descendants, use multiDelete instead.

The default durability and default request timeout are used.

Possible outcomes when calling this method are:

1. The KV pair was deleted and true is returned.
2. The KV pair was not deleted because no existing value was present with the given key; false is returned and no exception is thrown.
3. The KV pair was not guaranteed to be deleted successfully and one of the exceptions listed below is thrown.

Parameters:

key - the key used to lookup the key/value pair.

Returns:

true if the delete is successful, or false if no existing value is present.

Throws:

DurabilityException - if the specified Durability cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

delete

boolean delete(Key key,
               ReturnValueVersion prevValue,
               Durability durability,
               long timeout,
               TimeUnit timeoutUnit)
               throws DurabilityException,
                      RequestTimeoutException,
                      FaultException

Delete the key/value pair associated with the key.

Deleting a key/value pair with this method does not automatically delete its children or descendant key/value pairs. To delete children or descendants, use multiDelete instead.

Possible outcomes when calling this method are:

1. The KV pair was deleted and true is returned. The prevValue parameter, if specified, will contain a non-null previous value and version. The previous value may be useful for application specific reasons.
2. The KV pair was not deleted because no existing value was present with the given key; false is returned and no exception is thrown. The prevValue parameter, if specified, will contain a null previous value and version.
3. The KV pair was not guaranteed to be deleted successfully and one of the exceptions listed below is thrown. The prevValue parameter, if specified, is left unmodified.

Parameters:

key - the key used to lookup the key/value pair.

prevValue - a ReturnValueVersion object to contain the previous value and version associated with the given key, or null if they should not be returned. The version and value in this object are set to null if a previous value does not exist, or the ReturnValueVersion.Choice specifies that they should not be returned.

durability - the durability associated with the operation. If null, the default durability is used.

timeout - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the default request timeout is used.

timeoutUnit - is the unit of the timeout parameter, and may be null only if timeout is zero.

Returns:

true if the delete is successful, or false if no existing value is present.

Throws:

DurabilityException - if the specified Durability cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

deleteIfVersion

boolean deleteIfVersion(Key key,
                        Version matchVersion)
                        throws DurabilityException,
                               RequestTimeoutException,
                               FaultException

Delete a key/value pair, but only if the version of the existing value matches the matchVersion argument. Used when deleting a value to ensure that it has not changed since it was last read.

Deleting a key/value pair with this method does not automatically delete its children or descendant key/value pairs. To delete children or descendants, use multiDelete instead.

The default durability and default request timeout are used.

Possible outcomes when calling this method are:

1. The KV pair was deleted and true is returned.
2. The KV pair was not deleted because no existing value was present with the given key, or the version of the existing KV pair did not equal the given matchVersion parameter; false is returned and no exception is thrown. There is no way to distinguish between a missing KV pair and a version mismatch when using this method signature.
3. The KV pair was not guaranteed to be deleted successfully and one of the exceptions listed below is thrown.

Parameters:

key - the key to be used to identify the key/value pair.

matchVersion - the version to be matched.

Returns:

true if the deletion is successful.

Throws:

DurabilityException - if the specified Durability cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

deleteIfVersion

boolean deleteIfVersion(Key key,
                        Version matchVersion,
                        ReturnValueVersion prevValue,
                        Durability durability,
                        long timeout,
                        TimeUnit timeoutUnit)
                        throws DurabilityException,
                               RequestTimeoutException,
                               FaultException

Delete a key/value pair, but only if the version of the existing value matches the matchVersion argument. Used when deleting a value to ensure that it has not changed since it was last read.

Deleting a key/value pair with this method does not automatically delete its children or descendant key/value pairs. To delete children or descendants, use multiDelete instead.

Possible outcomes when calling this method are:

1. The KV pair was deleted and true is returned. The prevValue parameter, if specified, will contain a non-null previous value and version. The previous value may be useful for application specific reasons.
2. The KV pair was not deleted because no existing value was present with the given key, or the version of the existing KV pair did not equal the given matchVersion parameter; false is returned and no exception is thrown. The prevValue parameter may be specified to determine whether the failure was due to a missing KV pair or a version mismatch. If a null previous value or version is returned then the KV pair was missing, otherwise a version mismatch occurred. The previous value or version may also be useful for other application specific reasons.
3. The KV pair was not guaranteed to be deleted successfully and one of the exceptions listed below is thrown. The prevValue parameter, if specified, is left unmodified.

Parameters:

key - the key to be used to identify the key/value pair.

matchVersion - the version to be matched.

prevValue - a ReturnValueVersion object to contain the previous value and version associated with the given key, or null if they should not be returned. The version and value in this object are set to null if a previous value does not exist, or the ReturnValueVersion.Choice specifies that they should not be returned, or the matchVersion parameter matches the existing value and the delete is successful.

durability - the durability associated with the operation. If null, the default durability is used.

timeout - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the default request timeout is used.

timeoutUnit - is the unit of the timeout parameter, and may be null only if timeout is zero.

Returns:

true if the deletion is successful.

Throws:

DurabilityException - if the specified Durability cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

multiDelete

int multiDelete(Key parentKey,
                KeyRange subRange,
                Depth depth)
                throws DurabilityException,
                       RequestTimeoutException,
                       FaultException

Deletes the descendant Key/Value pairs associated with the parentKey. The subRange and the depth arguments can be used to further limit the key/value pairs that are deleted.

The default durability and default request timeout are used.

Parameters:

parentKey - the parent key whose "child" KV pairs are to be deleted. It must not be null. The major key path must be complete. The minor key path may be omitted or may be a partial path.

subRange - further restricts the range under the parentKey to the minor path components in this subRange. It may be null.

depth - specifies whether the parent and only children or all descendants are deleted. If null, Depth.PARENT_AND_DESCENDANTS is implied.

Returns:

a count of the keys that were deleted.

Throws:

DurabilityException - if the specified Durability cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

multiDelete

int multiDelete(Key parentKey,
                KeyRange subRange,
                Depth depth,
                Durability durability,
                long timeout,
                TimeUnit timeoutUnit)
                throws DurabilityException,
                       RequestTimeoutException,
                       FaultException

Deletes the descendant Key/Value pairs associated with the parentKey. The subRange and the depth arguments can be used to further limit the key/value pairs that are deleted.

Parameters:

parentKey - the parent key whose "child" KV pairs are to be deleted. It must not be null. The major key path must be complete. The minor key path may be omitted or may be a partial path.

subRange - further restricts the range under the parentKey to the minor path components in this subRange. It may be null.

depth - specifies whether the parent and only children or all descendants are deleted. If null, Depth.PARENT_AND_DESCENDANTS is implied.

durability - the durability associated with the operation. If null, the default durability is used.

timeout - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the default request timeout is used.

timeoutUnit - is the unit of the timeout parameter, and may be null only if timeout is zero.

Returns:

a count of the keys that were deleted.

Throws:

DurabilityException - if the specified Durability cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

execute

List<OperationResult> execute(List<Operation> operations)
                              throws OperationExecutionException,
                                     DurabilityException,
                                     FaultException

This method provides an efficient and transactional mechanism for executing a sequence of operations associated with keys that share the same Major Path. The efficiency results from the use of a single network interaction to accomplish the entire sequence of operations.

The operations passed to this method are created using an OperationFactory, which is obtained from the getOperationFactory() method.

All the operations specified are executed within the scope of a single transaction that effectively provides serializable isolation. The transaction is started and either committed or aborted by this method. If the method returns without throwing an exception, then all operations were executed atomically, the transaction was committed, and the returned list contains the result of each operation.

If the transaction is aborted for any reason, an exception is thrown. An abort may occur for two reasons:

1. An operation or transaction results in an exception that is considered a fault, such as a durability or consistency error, a failure due to message delivery or networking error, etc. A FaultException is thrown.
2. An individual operation returns normally but is unsuccessful as defined by the particular operation (e.g., a delete operation for a non-existent key) and true was passed for the abortIfUnsuccessful parameter when the operation was created using the OperationFactory. An OperationExecutionException is thrown, and the exception contains information about the failed operation.

Operations are not executed in the sequence they appear the operations list, but are rather executed in an internally defined sequence that prevents deadlocks. Additionally, if there are two operations for the same key, their relative order of execution is arbitrary; this should be avoided.

The default durability and default request timeout are used.

Parameters:

operations - the list of operations to be performed. Note that all operations in the list must specify keys with the same Major Path.

Returns:

the sequence of results associated with the operation. There is one entry for each Operation in the operations argument list. The returned list is in the same order as the operations argument list.

Throws:

OperationExecutionException - if an operation is not successful as defined by the particular operation (e.g., a delete operation for a non-existent key) and true was passed for the abortIfUnsuccessful parameter when the operation was created using the OperationFactory.

IllegalArgumentException - if operations is null or empty, or not all operations operate on keys with the same Major Path, or more than one operation has the same Key.

DurabilityException - if the specified Durability cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

execute

List<OperationResult> execute(List<Operation> operations,
                              Durability durability,
                              long timeout,
                              TimeUnit timeoutUnit)
                              throws OperationExecutionException,
                                     DurabilityException,
                                     FaultException

This method provides an efficient and transactional mechanism for executing a sequence of operations associated with keys that share the same Major Path. The efficiency results from the use of a single network interaction to accomplish the entire sequence of operations.

The operations passed to this method are created using an OperationFactory, which is obtained from the getOperationFactory() method.

All the operations specified are executed within the scope of a single transaction that effectively provides serializable isolation. The transaction is started and either committed or aborted by this method. If the method returns without throwing an exception, then all operations were executed atomically, the transaction was committed, and the returned list contains the result of each operation.

If the transaction is aborted for any reason, an exception is thrown. An abort may occur for two reasons:

1. An operation or transaction results in an exception that is considered a fault, such as a durability or consistency error, a failure due to message delivery or networking error, etc. A FaultException is thrown.
2. An individual operation returns normally but is unsuccessful as defined by the particular operation (e.g., a delete operation for a non-existent key) and true was passed for the abortIfUnsuccessful parameter when the operation was created using the OperationFactory. An OperationExecutionException is thrown, and the exception contains information about the failed operation.

Operations are not executed in the sequence they appear the operations list, but are rather executed in an internally defined sequence that prevents deadlocks. Additionally, if there are two operations for the same key, their relative order of execution is arbitrary; this should be avoided.

Parameters:

operations - the list of operations to be performed. Note that all operations in the list must specify keys with the same Major Path.

durability - the durability associated with the transaction used to execute the operation sequence. If null, the default durability is used.

timeout - is an upper bound on the time interval for processing the set of operations. A best effort is made not to exceed the specified limit. If zero, the default request timeout is used.

timeoutUnit - is the unit of the timeout parameter, and may be null only if timeout is zero.

Returns:

the sequence of results associated with the operation. There is one entry for each Operation in the operations argument list. The returned list is in the same order as the operations argument list.

Throws:

OperationExecutionException - if an operation is not successful as defined by the particular operation (e.g., a delete operation for a non-existent key) and true was passed for the abortIfUnsuccessful parameter when the operation was created using the OperationFactory.

IllegalArgumentException - if operations is null or empty, or not all operations operate on keys with the same Major Path, or more than one operation has the same Key.

DurabilityException - if the specified Durability cannot be satisfied.

RequestTimeoutException - if the request timeout interval was exceeded.

FaultException - if the operation cannot be completed for any reason.

getOperationFactory

OperationFactory getOperationFactory()

Returns a factory that is used to creation operations that can be passed to execute.

close

void close()

Close the K/V Store handle and release resources. After calling close, the application should discard the KVStore instance to allow network connections to be garbage collected and closed.

Specified by:

close in interface Closeable

getStats

KVStats getStats(boolean clear)

Returns the statistics related to the K/V Store client.

Parameters:

clear - If set to true, configure the statistics operation to reset statistics after they are returned.

Returns:

The K/V Store client side statistics.

getAvroCatalog

AvroCatalog getAvroCatalog()

Returns the catalog of Avro schemas and bindings for this store.

Since:

2.0