public interface KVStore extends KVLargeObject, Closeable
KVStoreFactory.getStore
.
A handle has thread, memory and network resources associated with it.
Consequently, the close()
method must be invoked to free up
the resources when the application is done using the KVStore.
To minimize resource allocation and deallocation overheads, it's best to avoid repeated creation and closing of handles to the same store. For example, creating and closing a handle around each KVStore operation, would incur large resource allocation overheads resulting in poor application performance.
A handle permits concurrent operations, so a single handle is sufficient to access a KVStore in a multi-threaded application. The creation of multiple handles incurs additional resource overheads without providing any performance benefit.
Iterators returned by methods of this interface can only be used safely by one thread at a time unless synchronized externally.
KVLargeObject.LOBState
Modifier and Type | Method and Description |
---|---|
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.
|
ExecutionFuture |
execute(String statement)
Asynchronously executes a DDL statement.
|
StatementResult |
executeSync(String statement)
Synchronously execute a table statement.
|
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.
|
ExecutionFuture |
getFuture(byte[] futureBytes)
Obtain a handle onto a previously issued DDL operation, using a
serialized version of the ExecutionFuture obtained from
ExecutionFuture.toByteArray() . |
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.
|
TableAPI |
getTableAPI()
Returns an instance of the TableAPI interface for the store.
|
void |
login(LoginCredentials creds)
Updates the login credentials for this store handle.
|
void |
logout()
Logout the store handle.
|
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.
|
ParallelScanIterator<KeyValueVersion> |
storeIterator(Direction direction,
int batchSize,
Key parentKey,
KeyRange subRange,
Depth depth,
Consistency consistency,
long timeout,
TimeUnit timeoutUnit,
StoreIteratorConfig storeIteratorConfig)
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.
|
ParallelScanIterator<Key> |
storeKeysIterator(Direction direction,
int batchSize,
Key parentKey,
KeyRange subRange,
Depth depth,
Consistency consistency,
long timeout,
TimeUnit timeoutUnit,
StoreIteratorConfig storeIteratorConfig)
Return an Iterator which iterates over all keys (or the descendants of a
parentKey, or those in a KeyRange) in unsorted order.
|
appendLOB, deleteLOB, getLOB, putLOB, putLOBIfAbsent, putLOBIfPresent
ValueVersion get(Key key) throws ConsistencyException, RequestTimeoutException, FaultException
The default consistency
and
default request timeout
are
used.
key
- the key used to lookup the key/value pair.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.ValueVersion get(Key key, Consistency consistency, long timeout, TimeUnit timeoutUnit) throws ConsistencyException, RequestTimeoutException, FaultException
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.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.SortedMap<Key,ValueVersion> multiGet(Key parentKey, KeyRange subRange, Depth depth) throws ConsistencyException, RequestTimeoutException, FaultException
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.
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.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.SortedMap<Key,ValueVersion> multiGet(Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit) throws ConsistencyException, RequestTimeoutException, FaultException
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.
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.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.SortedSet<Key> multiGetKeys(Key parentKey, KeyRange subRange, Depth depth) throws ConsistencyException, RequestTimeoutException, FaultException
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.
SortedSet<Key> multiGetKeys(Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit) throws ConsistencyException, RequestTimeoutException, FaultException
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.
Iterator<KeyValueVersion> multiGetIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth) throws ConsistencyException, RequestTimeoutException, FaultException
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.
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.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.Iterator<KeyValueVersion> multiGetIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit) throws ConsistencyException, RequestTimeoutException, FaultException
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.
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.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.Iterator<Key> multiGetKeysIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth) throws ConsistencyException, RequestTimeoutException, FaultException
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.
Iterator<Key> multiGetKeysIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit) throws ConsistencyException, RequestTimeoutException, FaultException
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.
Iterator<KeyValueVersion> storeIterator(Direction direction, int batchSize) throws ConsistencyException, RequestTimeoutException, FaultException
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.
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.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.Iterator<KeyValueVersion> storeIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth) throws ConsistencyException, RequestTimeoutException, FaultException
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.
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.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.Iterator<KeyValueVersion> storeIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit) throws ConsistencyException, RequestTimeoutException, FaultException
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.
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.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.ParallelScanIterator<KeyValueVersion> storeIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit, StoreIteratorConfig storeIteratorConfig) throws ConsistencyException, RequestTimeoutException, FaultException
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 is thread safe. It does not support the remove method.
The default consistency
and
default request timeout
are
used.
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 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.storeIteratorConfig
- specifies the configuration for parallel
scanning across multiple Replication Nodes. If this is null, an
IllegalArgumentException is thrown.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.IllegalArgumentException
- if the storeIteratorConfig argument is
null.Iterator<Key> storeKeysIterator(Direction direction, int batchSize) throws ConsistencyException, RequestTimeoutException, FaultException
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.
Iterator<Key> storeKeysIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth) throws ConsistencyException, RequestTimeoutException, FaultException
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.
Iterator<Key> storeKeysIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit) throws ConsistencyException, RequestTimeoutException, FaultException
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.
ParallelScanIterator<Key> storeKeysIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit, StoreIteratorConfig storeIteratorConfig) throws ConsistencyException, RequestTimeoutException, FaultException
This method is almost identical to storeIterator(Direction, int,
Key, KeyRange, Depth, Consistency, long, TimeUnit,
StoreIteratorConfig)
but differs solely in the type of its return
value (keys instead of key/value pairs).
Version put(Key key, Value value) throws DurabilityException, RequestTimeoutException, FaultException
The default durability
and default request timeout
are used.
Possible outcomes when calling this method are:
key
- the key part of the key/value pair.value
- the value part of the key/value pair.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.Version put(Key key, Value value, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit) throws DurabilityException, RequestTimeoutException, FaultException
Possible outcomes when calling this method are:
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.
prevValue
parameter, if specified, is left unmodified.
key
- the key part of the key/value pairvalue
- 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.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.Version putIfAbsent(Key key, Value value) throws DurabilityException, RequestTimeoutException, FaultException
The default durability
and default request timeout
are used.
Possible outcomes when calling this method are:
key
- the key part of the key/value pair.value
- the value part of the key/value pair.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.Version putIfAbsent(Key key, Value value, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit) throws DurabilityException, RequestTimeoutException, FaultException
Possible outcomes when calling this method are:
prevValue
parameter, if specified, will
contain a null previous value and version.
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.
prevValue
parameter, if specified, is left unmodified.
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.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.Version putIfPresent(Key key, Value value) throws DurabilityException, RequestTimeoutException, FaultException
The default durability
and default request timeout
are used.
Possible outcomes when calling this method are:
key
- the key part of the key/value pair.value
- the value part of the key/value pair.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.Version putIfPresent(Key key, Value value, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit) throws DurabilityException, RequestTimeoutException, FaultException
Possible outcomes when calling this method are:
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.
prevValue
parameter, if specified, will contain a null
previous value and version.
prevValue
parameter, if specified, is left unmodified.
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.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.Version putIfVersion(Key key, Value value, Version matchVersion) throws DurabilityException, RequestTimeoutException, FaultException
The default durability
and default request timeout
are used.
Possible outcomes when calling this method are:
matchVersion
parameter; null is returned and no
exception is thrown.
key
- the key part of the key/value pair.value
- the value part of the key/value pair.matchVersion
- the version to be matched.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.Version putIfVersion(Key key, Value value, Version matchVersion, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit) throws DurabilityException, RequestTimeoutException, FaultException
Possible outcomes when calling this method are:
prevValue
parameter, if specified, will
contain a non-null previous value and version. The previous value may
be useful for application specific reasons.
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.
prevValue
parameter, if specified, is left unmodified.
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.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.boolean delete(Key key) throws DurabilityException, RequestTimeoutException, FaultException
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:
key
- the key used to lookup the key/value pair.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.boolean delete(Key key, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit) throws DurabilityException, RequestTimeoutException, FaultException
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:
prevValue
parameter, if specified, will contain a non-null previous value and
version. The previous value may be useful for application specific
reasons.
prevValue
parameter, if specified, will contain a null
previous value and version.
prevValue
parameter, if specified, is left unmodified.
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.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.boolean deleteIfVersion(Key key, Version matchVersion) throws DurabilityException, RequestTimeoutException, FaultException
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:
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.
key
- the key to be used to identify the key/value pair.matchVersion
- the version to be matched.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.boolean deleteIfVersion(Key key, Version matchVersion, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit) throws DurabilityException, RequestTimeoutException, FaultException
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:
prevValue
parameter, if specified, will contain a non-null previous value and
version. The previous value may be useful for application specific
reasons.
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.
prevValue
parameter, if specified, is left unmodified.
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.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.int multiDelete(Key parentKey, KeyRange subRange, Depth depth) throws DurabilityException, RequestTimeoutException, FaultException
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.
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.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.int multiDelete(Key parentKey, KeyRange subRange, Depth depth, Durability durability, long timeout, TimeUnit timeoutUnit) throws DurabilityException, RequestTimeoutException, FaultException
parentKey
. The subRange
and the
depth
arguments can be used to further limit the key/value
pairs that are deleted.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.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.List<OperationResult> execute(List<Operation> operations) throws OperationExecutionException, DurabilityException, FaultException
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:
FaultException
is thrown.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 in 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.
operations
- the list of operations to be performed. Note that all
operations in the list must specify keys with the same Major Path.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.List<OperationResult> execute(List<Operation> operations, Durability durability, long timeout, TimeUnit timeoutUnit) throws OperationExecutionException, DurabilityException, FaultException
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:
FaultException
is thrown.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 in 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.
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.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.OperationFactory getOperationFactory()
execute
.void close()
KVStats getStats(boolean clear)
clear
- If set to true, configure the statistics operation to
reset statistics after they are returned.AvroCatalog getAvroCatalog()
AvroCatalog.refreshSchemaCache(oracle.kv.Consistency)
for details.TableAPI getTableAPI()
void login(LoginCredentials creds) throws RequestTimeoutException, AuthenticationFailureException, FaultException, IllegalArgumentException
AuthenticationRequiredException
,
this method will attempt to re-establish the authentication of this
handle against the store, and the credentials provided must be for
the store handle's currently logged-in user.
creds
- the login credentials to associate with the store handleRequestTimeoutException
- if the request timeout interval was
exceeded.AuthenticationFailureException
- if the LoginCredentials
do not contain valid credentials.IllegalArgumentException
- if the LoginCredentials are nullFaultException
- if the operation cannot be completed for any
reason.void logout() throws RequestTimeoutException, FaultException
RequestTimeoutException
- if the request timeout interval was
exceeded.FaultException
- if the operation cannot be completed for any
reason.ExecutionFuture execute(String statement) throws FaultException, IllegalArgumentException
An ExecutionFuture
instance is returned which extends
Future
and can be used to get information
about the status of the operation, or to await completion of the
operation.
For example:
// Create a table ExecutionFuture future = null; try { future = store.execute ("CREATE TABLE users (" + "id INTEGER, " + "firstName STRING, " + "lastName STRING, " + "age INTEGER, " + "PRIMARY KEY (id))"); } catch (IllegalArgumentException e) { System.out.println("The statement is invalid: " + e); } catch (FaultException e) { System.out.println("There is a transient problem, retry the " + "operation: " + e); } // Wait for the operation to finish StatementResult result = future.get()
If the statement is a data definition or administrative operation, and the store is currently executing an operation that is the logical equivalent of the action specified by the statement, the method will return an ExecutionFuture that serves as a handle to that operation, rather than starting a new invocation of the command. The caller can use the ExecutionFuture to await the completion of the operation.
// process A starts an index creation ExecutionFuture futureA = store.execute("CREATE INDEX age ON users(age)"); // process B starts the same index creation. If the index creation is // still running in the cluster, futureA and futureB will refer to // the same operation ExecutionFuture futureB = store.execute("CREATE INDEX age ON users(age)");
Note that, in a secure store, creating and modifying table and index
definitions may require a level of system privileges over and beyond
that required for reads and writes of table records.
See the documentation for a full description of the supported statements.
statement
- must follow valid Table syntax.IllegalArgumentException
- if the statement is not validFaultException
- if the statement cannot be completed. This
indicates a transient problem with communication to the server or
within the server, and the statement can be retried.
Note that this method supersedes oracle.kv.table.TableAPI.execute.
StatementResult executeSync(String statement) throws FaultException, IllegalArgumentException
execute(String)
, but offers synchronous behavior as a convenience.
ExecuteSync() is the equivalent of:
ExecutionFuture future = tableAPI.execute( ... ); return future.get();When executeSync() returns, statement execution will have terminated, and the resulting
StatementResult
will provide information
about the outcome.statement
- must follow valid Table syntax.IllegalArgumentException
- if the statement is not validFaultException
- if the statement cannot be completed. This
indicates a transient problem with communication to the server or
within the server, and the statement can be retried.
Note that this method supersedes oracle.kv.table.TableAPI.executeSync
ExecutionFuture getFuture(byte[] futureBytes) throws IllegalArgumentException
ExecutionFuture.toByteArray()
. Does not result in any
communication with the server. The user must call the appropriate
methods on the reconstituted future to get up to date status.
For example:
// futureBytes can be saved and used later to recreate an // ExecutionFuture instance ExecutionFuture laterFuture = store.getFuture(futureBytes); // laterFuture doesn't have any status yet. Call ExecutionFuture.get // or updateStatus to communicate with the server and get new // information StatementResult laterResult = laterFuture.get();
IllegalArgumentException
- if futureBytes isn't a valid
representation of an ExecutionFuture instance.Copyright (c) 2011, 2015 Oracle and/or its affiliates. All rights reserved.