Interface KVStore
-
- All Superinterfaces:
AutoCloseable
,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 fromKVStoreFactory.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.
There are two groups of common failure types that result in throwing instances of
RuntimeException
from methods that have these failures in common: read failure exceptions, and write failure exceptions. These are described below.Read Exceptions
Read operations are executed by the
get
anditerator
methods, and their related iteration calls. Examples areget
,multiGet
andstoreIterator
. In addition, theTableAPI
interface has read methods, such astable get
,tableIterator
, etc. All read methods may experience the following failures:FaultException
is the superclass of several read exceptions:ConsistencyException
is thrown if the specifiedConsistency
could not be met, within the allowed timeout period.RequestTimeoutException
is thrown when a request cannot be processed because the configured timeout interval is exceeded.RequestLimitException
is thrown when a request cannot be processed because it would exceed the maximum number of active requests for a node.
- Read operations may also fail with a security exception or stale handle exception as described below.
Write Exceptions
Write operations are executed by methods that modify data, such as
put
,delete
, the otherput
anddelete
variants,execute
, etc. In addition, theTableAPI
interface has data modification methods, such astable put
,table delete
, etc. All write methods may experience the following failures:FaultException
is the superclass of several write exceptions:DurabilityException
is thrown if the specifiedDurability
could not be met, within the allowed timeout period.RequestTimeoutException
is thrown when a request cannot be processed because the configured timeout interval is exceeded.RequestLimitException
is thrown when a request cannot be processed because it would exceed the maximum number of active requests for a node.
- Write operations may also fail with a security exception or stale handle exception as described below.
Security Exceptions
There are a number of exceptions related to security that can be thrown by any method that attempts to access data. Data access methods all throw instances of
KVSecurityException
, which is the superclass of all security exceptions. Common security exceptions are:AuthenticationFailureException
is thrown when invalid credentials are passed to an authentication operation.AuthenticationRequiredException
is thrown when a secured operation is attempted and the client is not currently authenticated.UnauthorizedException
is thrown when an authenticated user attempts to perform an operation for which they are not authorized.
Stale Handle Exceptions
Any method that attempts to access data may also throw a
StaleStoreHandleException
, which indicates that the store handle has become invalid. The application should close and reopen the handle.Thread Model for Asynchronous Execution
This and the
TableAPI
interface provide asynchronous execution methods such asexecuteAsync(String, ExecuteOptions)
. These async methods are non-blocking in that they return without waiting for any events such as network read and write, or security handshake. The actual handling of such events happens inside an internal thread pool which has a fixed number of threads. These async methods return widely-accepted asynchronous flow-control or computation classes, namely, thePublisher
andCompletableFuture
, from which user-supplied actions are triggered after the execution results are avaiable. We implement these interfaces in a way such that user-supplied actions will be performed by a thread in the internal thread pool. Therefore, these actions must be non-blocking to avoid interfering with internal event processing. This requirement corresponds to those defined in the async classes (see Subsriber Rule 2 in Reactive Streams and the policies for implementingCompletionStage
inCompletableFuture
). If the triggered method needs to perform a blocking action, use a separate executor to perform the action. For example:store.executeAsync(statement, null) .subscribe(new Subscriber<RecordValue>() { ... ... @Override public void onSubscribe(Subscription s) { ... ... // Uses ForkJoinPool.commonPool for the blocking action CompletableFuture<Void> cf = CompletableFuture.runAsync( () -> doBlockingAction()); cf.thenRun(() -> afterBlockingAction()); ... ... } ... ... });
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface oracle.kv.lob.KVLargeObject
KVLargeObject.LOBState
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method 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.ExecutionFuture
execute(char[] statement, ExecuteOptions options)
This method is equivalent toexecute(String, ExecuteOptions)
, but the statement is given as a char[].ExecutionFuture
execute(String statement)
Executes an SQL statement.ExecutionFuture
execute(String statement, ExecuteOptions options)
This method is equivalent toexecute(String)
, but it allows its users to specify execution options that override the defaults.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.org.reactivestreams.Publisher<RecordValue>
executeAsync(String statement, ExecuteOptions options)
Returns a publisher that can be used to subscribe to the results of the asynchronous execution of an SQL statement.org.reactivestreams.Publisher<RecordValue>
executeAsync(Statement statement, ExecuteOptions options)
Returns a publisher that can be used to subscribe to the results of the asynchronous execution of a table statement, either aPreparedStatement
or aBoundStatement
.StatementResult
executeSync(char[] statement, ExecuteOptions options)
Synchronously execute an SQL statement.StatementResult
executeSync(String statement)
Synchronously execute an SQL statement.StatementResult
executeSync(String statement, ExecuteOptions options)
Synchronously execute an SQL statement.StatementResult
executeSync(Statement statement)
Synchronously execute a prepared SQL statement provided as aPreparedStatement
orBoundStatement
.StatementResult
executeSync(Statement statement, ExecuteOptions options)
Synchronously execute a prepared SQL statement provided as aPreparedStatement
orBoundStatement
.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.ExecutionFuture
getFuture(byte[] futureBytes)
Obtain a handle onto a previously issued DDL operation, using a serialized version of the ExecutionFuture obtained fromExecutionFuture.toByteArray()
.OperationFactory
getOperationFactory()
Returns a factory that is used to creation operations that can be passed toexecute
.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 theparentKey
.int
multiDelete(Key parentKey, KeyRange subRange, Depth depth, Durability durability, long timeout, TimeUnit timeoutUnit)
Deletes the descendant Key/Value pairs associated with theparentKey
.SortedMap<Key,ValueVersion>
multiGet(Key parentKey, KeyRange subRange, Depth depth)
Returns the descendant key/value pairs associated with theparentKey
.SortedMap<Key,ValueVersion>
multiGet(Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit)
Returns the descendant key/value pairs associated with theparentKey
.Iterator<KeyValueVersion>
multiGetIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth)
The iterator form ofmultiGet(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 ofmultiGet(Key, KeyRange, Depth, Consistency, long, TimeUnit)
.SortedSet<Key>
multiGetKeys(Key parentKey, KeyRange subRange, Depth depth)
Returns the descendant keys associated with theparentKey
.SortedSet<Key>
multiGetKeys(Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit)
Returns the descendant keys associated with theparentKey
.Iterator<Key>
multiGetKeysIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth)
The iterator form ofmultiGetKeys(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 ofmultiGetKeys(Key, KeyRange, Depth, Consistency, long, TimeUnit)
.PreparedStatement
prepare(String statement)
Compiles a query into an execution plan.void
put(List<EntryStream<KeyValue>> streams, BulkWriteOptions bulkWriteOptions)
Loads Key/Value pairs supplied by special purpose streams into the store.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.ParallelScanIterator<KeyValueVersion>
storeIterator(Iterator<Key> parentKeyIterator, int batchSize, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit, StoreIteratorConfig storeIteratorConfig)
Returns an Iterator which iterates over all key/value pairs matching the keys supplied by iterator (or the descendants of a parentKey, or those in a KeyRange).ParallelScanIterator<KeyValueVersion>
storeIterator(List<Iterator<Key>> parentKeyIterators, int batchSize, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit, StoreIteratorConfig storeIteratorConfig)
Returns an Iterator which iterates over all key/value pairs matching the keys supplied by iterators (or the descendants of a parentKey, or those in a KeyRange).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).ParallelScanIterator<Key>
storeKeysIterator(Iterator<Key> parentKeyIterator, int batchSize, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit, StoreIteratorConfig storeIteratorConfig)
Return an Iterator which iterates over all keys matching the keys supplied by iterator (or the descendants of a parentKey, or those in a KeyRange).ParallelScanIterator<Key>
storeKeysIterator(List<Iterator<Key>> parentKeyIterators, int batchSize, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit, StoreIteratorConfig storeIteratorConfig)
Return an Iterator which iterates over all keys matching the keys supplied by iterators (or the descendants of a parentKey, or those in a KeyRange).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).-
Methods inherited from interface oracle.kv.lob.KVLargeObject
appendLOB, deleteLOB, getLOB, putLOB, putLOBIfAbsent, putLOBIfPresent
-
-
-
-
Method Detail
-
get
ValueVersion get(Key key)
Get the value associated with the key.The
default consistency
anddefault 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.
- See Also:
- Read exceptions
-
get
ValueVersion get(Key key, Consistency consistency, long timeout, TimeUnit timeoutUnit)
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, thedefault 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, thedefault 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.
- See Also:
- Read exceptions
-
multiGet
SortedMap<Key,ValueVersion> multiGet(Key parentKey, KeyRange subRange, Depth depth)
Returns the descendant key/value pairs associated with theparentKey
. ThesubRange
and thedepth
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
anddefault 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.
- See Also:
- Read exceptions
-
multiGet
SortedMap<Key,ValueVersion> multiGet(Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit)
Returns the descendant key/value pairs associated with theparentKey
. ThesubRange
and thedepth
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, thedefault 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, thedefault 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.
- See Also:
- Read exceptions
-
multiGetKeys
SortedSet<Key> multiGetKeys(Key parentKey, KeyRange subRange, Depth depth)
Returns the descendant keys associated with theparentKey
.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.- See Also:
multiGet(Key, KeyRange, Depth)
, Read exceptions
-
multiGetKeys
SortedSet<Key> multiGetKeys(Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit)
Returns the descendant keys associated with theparentKey
.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.
-
multiGetIterator
Iterator<KeyValueVersion> multiGetIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth)
The iterator form ofmultiGet(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
anddefault request timeout
are used.- Parameters:
direction
- specifies the order in which records are returned by the iterator. OnlyDirection.FORWARD
andDirection.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.
- See Also:
- Read exceptions
-
multiGetIterator
Iterator<KeyValueVersion> multiGetIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit)
The iterator form ofmultiGet(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
anddefault request timeout
are used.- Parameters:
direction
- specifies the order in which records are returned by the iterator. OnlyDirection.FORWARD
andDirection.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, thedefault 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, thedefault 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.
- See Also:
- Read exceptions
-
multiGetKeysIterator
Iterator<Key> multiGetKeysIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth)
The iterator form ofmultiGetKeys(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.
-
multiGetKeysIterator
Iterator<Key> multiGetKeysIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit)
The iterator form ofmultiGetKeys(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.
-
storeIterator
Iterator<KeyValueVersion> storeIterator(Direction direction, int batchSize)
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
anddefault request timeout
are used.- Parameters:
direction
- specifies the order in which records are returned by the iterator. Currently onlyDirection.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.- See Also:
- Read exceptions
-
storeIterator
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.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
anddefault request timeout
are used.- Parameters:
direction
- specifies the order in which records are returned by the iterator. Currently onlyDirection.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.- See Also:
- Read exceptions
-
storeIterator
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.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
anddefault request timeout
are used.- Parameters:
direction
- specifies the order in which records are returned by the iterator. Currently onlyDirection.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, thedefault 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, thedefault request timeout
is used.timeoutUnit
- is the unit of the timeout parameter, and may be null only if timeout is zero.- See Also:
- Read exceptions
-
storeIterator
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). A non-null storeIteratorConfig argument causes a multi-threaded parallel scan on multiple Replication Nodes to be performed.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 not thread safe. It does not support the remove method.
The
default consistency
anddefault request timeout
are used.- Parameters:
direction
- specifies the order in which records are returned by the iterator.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, thedefault 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, thedefault 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.- Throws:
IllegalArgumentException
- if the storeIteratorConfig argument is null.- See Also:
- Read exceptions
-
storeKeysIterator
Iterator<Key> storeKeysIterator(Direction direction, int batchSize)
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.- See Also:
storeIterator(Direction, int)
, Read exceptions
-
storeKeysIterator
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.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.- See Also:
storeIterator(Direction, int)
, Read exceptions
-
storeKeysIterator
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.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.
-
storeKeysIterator
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). A non-null storeIteratorConfig argument causes a multi-threaded parallel scan on multiple Replication Nodes to be performed.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).
-
storeIterator
ParallelScanIterator<KeyValueVersion> storeIterator(Iterator<Key> parentKeyIterator, int batchSize, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit, StoreIteratorConfig storeIteratorConfig)
Returns an Iterator which iterates over all key/value pairs matching the keys supplied by iterator (or the descendants of a parentKey, or those in a KeyRange).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. Batches are fetched in parallel across multiple Replication Nodes, the degree of parallelism is controlled by the storeIteratorConfig argument.
The
default consistency
anddefault request timeout
are used.- Parameters:
parentKeyIterator
- it yields a sequence of parent keys. The major key path must be complete. The minor key path may be omitted or may be a partial path. The iterator implementation need not be thread safe.batchSize
- the suggested number of keys to fetch during each network round trip. If zero, an internally determined default is used.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, thedefault consistency
is used.timeout
- is an upper bound on the time interval for processing each batch. A best effort is made not to exceed the specified limit. If zero, thedefault 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 internally determined default is used.- Returns:
- an iterator that contains an entry for each key that is present
in the store and matches the criteria specified by the
parentKeyIterator
,subRange
anddepth
constraints. If theparentKeyIterator
yields duplicate keys, the KeyValueVersion associated with the duplicate keys will be returned at least once and potentially multiple times. The implementation makes an effort to minimize these duplicate values but the exact number of repeated KeyValueVersion instances is not defined by the implementation, since weeding out such duplicates can be resource intensive. - Throws:
IllegalArgumentException
- if the storeIteratorConfig argument is null.- Since:
- 3.4
- See Also:
- Read exceptions
-
storeKeysIterator
ParallelScanIterator<Key> storeKeysIterator(Iterator<Key> parentKeyIterator, int batchSize, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit, StoreIteratorConfig storeIteratorConfig)
Return an Iterator which iterates over all keys matching the keys supplied by iterator (or the descendants of a parentKey, or those in a KeyRange).This method is almost identical to
storeIterator(Iterator, int, KeyRange, Depth, Consistency, long, TimeUnit, StoreIteratorConfig)
but differs solely in the type of its return value (keys instead of key/value pairs).
-
storeIterator
ParallelScanIterator<KeyValueVersion> storeIterator(List<Iterator<Key>> parentKeyIterators, int batchSize, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit, StoreIteratorConfig storeIteratorConfig)
Returns an Iterator which iterates over all key/value pairs matching the keys supplied by iterators (or the descendants of a parentKey, or those in a KeyRange).Except for the difference in the type of the first argument:
parentKeyIterators
, which is a list of iterators instead of a single iterator, this method is identical to the overloadedstoreIterator(Iterator, int, KeyRange, Depth, Consistency, long, TimeUnit, StoreIteratorConfig)
method. One or more of the iterators in theparentKeyIterators
list may be read in parallel to maximize input throughput, the element of key iterator list should be non null.
-
storeKeysIterator
ParallelScanIterator<Key> storeKeysIterator(List<Iterator<Key>> parentKeyIterators, int batchSize, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit, StoreIteratorConfig storeIteratorConfig)
Return an Iterator which iterates over all keys matching the keys supplied by iterators (or the descendants of a parentKey, or those in a KeyRange).Except for the difference in the type of the first argument:
parentKeyIterators
, which is a list of iterators instead of a single iterator, this method is identical to the overloadedstoreKeysIterator(Iterator, int, KeyRange, Depth, Consistency, long, TimeUnit, StoreIteratorConfig)
method. One or more of the iterators in theparentKeyIterators
list may be read in parallel to maximize input throughput, the element of key iterator list should be non null.
-
put
Version put(Key key, Value value)
Put a key/value pair, inserting or overwriting as appropriate.The
default durability
anddefault request timeout
are used.Possible outcomes when calling this method are:
- 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.
- 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.
- See Also:
- Write exceptions
-
put
Version put(Key key, Value value, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit)
Put a key/value pair, inserting or overwriting as appropriate.Possible outcomes when calling this method are:
-
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. -
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 pairvalue
- the value part of the key/value pair.prevValue
- aReturnValueVersion
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 theReturnValueVersion.Choice
specifies that they should not be returned.durability
- the durability associated with the operation. If null, thedefault 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, thedefault 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.
- See Also:
- Write exceptions
-
The KV pair was inserted or updated and the (non-null) version of the
new KV pair is returned. The
-
putIfAbsent
Version putIfAbsent(Key key, Value value)
Put a key/value pair, but only if no value for the given key is present.The
default durability
anddefault request timeout
are used.Possible outcomes when calling this method are:
- The KV pair was inserted and the (non-null) version of the new KV pair is returned.
- 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 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.
- See Also:
- Write exceptions
-
putIfAbsent
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.Possible outcomes when calling this method are:
-
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. -
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. -
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
- aReturnValueVersion
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 theReturnValueVersion.Choice
specifies that they should not be returned.durability
- the durability associated with the operation. If null, thedefault 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, thedefault 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.
- See Also:
- Write exceptions
-
The KV pair was inserted and the (non-null) version of the new KV pair
is returned. The
-
putIfPresent
Version putIfPresent(Key key, Value value)
Put a key/value pair, but only if a value for the given key is present.The
default durability
anddefault request timeout
are used.Possible outcomes when calling this method are:
- The KV pair was updated and the (non-null) version of the new KV pair is returned.
- 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 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.
- See Also:
- Write exceptions
-
putIfPresent
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.Possible outcomes when calling this method are:
-
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. -
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. -
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
- aReturnValueVersion
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 theReturnValueVersion.Choice
specifies that they should not be returned.durability
- the durability associated with the operation. If null, thedefault 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, thedefault 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.
- See Also:
- Write exceptions
-
The KV pair was updated and the (non-null) version of the new KV pair
is returned. The
-
putIfVersion
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. Used when updating a value to ensure that it has not changed since it was last read.The
default durability
anddefault request timeout
are used.Possible outcomes when calling this method are:
- The KV pair was updated and the (non-null) version of the new KV pair is returned.
-
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 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.
- See Also:
- Write exceptions
-
putIfVersion
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. Used when updating a value to ensure that it has not changed since it was last read.Possible outcomes when calling this method are:
-
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. -
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. TheprevValue
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. -
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
- aReturnValueVersion
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 theReturnValueVersion.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, thedefault 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, thedefault 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.
- See Also:
- Write exceptions
-
The KV pair was updated and the (non-null) version of the new KV pair
is returned. The
-
delete
boolean delete(Key key)
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
anddefault request timeout
are used.Possible outcomes when calling this method are:
- The KV pair was deleted and true is returned.
- 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 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.
- See Also:
- Write exceptions
-
delete
boolean delete(Key key, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit)
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:
-
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. -
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. -
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
- aReturnValueVersion
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 theReturnValueVersion.Choice
specifies that they should not be returned.durability
- the durability associated with the operation. If null, thedefault 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, thedefault 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.
- See Also:
- Write exceptions
-
The KV pair was deleted and true is returned. The
-
deleteIfVersion
boolean deleteIfVersion(Key key, Version matchVersion)
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
anddefault request timeout
are used.Possible outcomes when calling this method are:
- The KV pair was deleted and true is returned.
-
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. - 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.
- See Also:
- Write exceptions
-
deleteIfVersion
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. 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:
-
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. -
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. TheprevValue
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. -
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
- aReturnValueVersion
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 theReturnValueVersion.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, thedefault 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, thedefault 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.
- See Also:
- Write exceptions
-
The KV pair was deleted and true is returned. The
-
multiDelete
int multiDelete(Key parentKey, KeyRange subRange, Depth depth)
Deletes the descendant Key/Value pairs associated with theparentKey
. ThesubRange
and thedepth
arguments can be used to further limit the key/value pairs that are deleted.The
default durability
anddefault 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.
- See Also:
- Write exceptions
-
multiDelete
int multiDelete(Key parentKey, KeyRange subRange, Depth depth, Durability durability, long timeout, TimeUnit timeoutUnit)
Deletes the descendant Key/Value pairs associated with theparentKey
. ThesubRange
and thedepth
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, thedefault 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, thedefault 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.
- See Also:
- Write exceptions
-
execute
List<OperationResult> execute(List<Operation> operations) throws OperationExecutionException
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. If the underlying store instance has only one partition, as is the case withKVLocal
the shared Major Path constraint is relaxed as in that environment all keys can be accessed in a single transaction.The operations passed to this method are created using an
OperationFactory
, which is obtained from thegetOperationFactory()
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:
- 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. - 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 theabortIfUnsuccessful
parameter when the operation was created using theOperationFactory
. AnOperationExecutionException
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
anddefault 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 unless the store is single partition.- 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) andtrue
was passed for theabortIfUnsuccessful
parameter when the operation was created using theOperationFactory
.IllegalArgumentException
- if operations is null or empty, or not all operations operate on keys with the same Major Path and the store is not single partition, or more than one operation has the same Key.- See Also:
- Write exceptions
- 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
-
execute
List<OperationResult> execute(List<Operation> operations, Durability durability, long timeout, TimeUnit timeoutUnit) throws OperationExecutionException
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. If the underlying store instance has only one partition, as is the case withKVLocal
the shared Major Path constraint is relaxed as in that environment all keys can be accessed in a single transaction.The operations passed to this method are created using an
OperationFactory
, which is obtained from thegetOperationFactory()
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:
- 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. - 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 theabortIfUnsuccessful
parameter when the operation was created using theOperationFactory
. AnOperationExecutionException
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.- Parameters:
operations
- the list of operations to be performed. Note that all operations in the list must specify keys with the same Major Path unless the store is single partition.durability
- the durability associated with the transaction used to execute the operation sequence. If null, thedefault 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, thedefault 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) andtrue
was passed for theabortIfUnsuccessful
parameter when the operation was created using theOperationFactory
.IllegalArgumentException
- if operations is null or empty, or not all operations operate on keys with the same Major Path and the store is not single partition, or more than one operation has the same Key.- See Also:
- Write exceptions
- 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
-
put
void put(List<EntryStream<KeyValue>> streams, BulkWriteOptions bulkWriteOptions)
Loads Key/Value pairs supplied by special purpose streams into the store. The bulk loading of the entries is optimized to make efficient use of hardware resources. As a result, this operation can achieve much higher throughput when compared with single Key/Value put APIs.Entries are supplied to the loader by a list of EntryStream instances. Each stream is read sequentially, that is, each EntryStream.getNext() is allowed to finish before the next operation is issued. The load operation typically reads from these streams in parallel as determined by
BulkWriteOptions.getStreamParallelism()
.If an entry is associated with a key that's already present in the store, the
EntryStream.keyExists(E)
method is invoked on it and the entry is not loaded into the store by this method; theEntryStream.keyExists(E)
method may of course choose to do so itself, if the values differ.If the key is absent, a new entry is created in the store, that is, the load operation has putIfAbsent semantics. The putIfAbsent semantics permit restarting a load of a stream that failed for some reason.
The collection of streams defines a partial insertion order, with insertion of Key/Value pairs containing the same major key within a stream being strictly ordered, but with no ordering constraints being imposed on keys across streams, or for different keys within the same stream.
The behavior of the bulk put operation with respect to duplicate entries contained in different streams is thus undefined. If the duplicate entries are just present in a single stream, then the first entry will be inserted (if it's not already present) and the second entry and subsequent entries will result in the invocation of the
EntryStream.keyExists(E)
method. If duplicates exist across streams, then the first entry to win the race is inserted and subsequent duplicates will result inEntryStream.keyExists(E)
being invoked on them.Load operations tend to be long running. In order to facilitate resumption of such a long running operation due to a process or client machine failure, the application may use to checkpoint its progress at granularity of a stream, using the
EntryStream.completed()
method. The javadoc for this method provides further details.Exceptions encountered during the reading of streams result in the put operation being terminated and the first such exception being thrown from the put method.
Exceptions encountered when inserting a Key/Value pair into the store result in the
EntryStream.catchException(java.lang.RuntimeException, E)
being invoked.- Parameters:
streams
- the streams that supply the Key/Value pairs to be inserted. Elements of stream list must not be null.bulkWriteOptions
- non-default arguments controlling the behavior the bulk write operations- Since:
- 4.0
-
getOperationFactory
OperationFactory getOperationFactory()
Returns a factory that is used to creation operations that can be passed toexecute
.
-
close
void close()
Close the K/V Store handle and release resources. If the K/V Store is secure, this also logs out of the store.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
-
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.
-
getTableAPI
TableAPI getTableAPI()
Returns an instance of the TableAPI interface for the store.
-
login
void login(LoginCredentials creds) throws RequestTimeoutException, AuthenticationFailureException, FaultException, IllegalArgumentException
Updates the login credentials for this store handle. This should be called in one of two specific circumstances.-
If the application has caught an
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. - If this handle is currently logged out, login credentials for any user may be provided, and the login, if successful, will associate the handle with that user.
- Parameters:
creds
- the login credentials to associate with the store handle- Throws:
RequestTimeoutException
- 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.- Since:
- 3.0
-
If the application has caught an
-
logout
void logout() throws RequestTimeoutException, FaultException
Logout the store handle. After calling this method, the application should not call methods on this handle other than close() before first making a successful call to login(). Calls to other methods will result in AuthenticationRequiredException being thrown.- Throws:
RequestTimeoutException
- if the request timeout interval was exceeded.FaultException
- if the operation cannot be completed for any reason.- Since:
- 3.0
-
execute
ExecutionFuture execute(String statement)
Executes an SQL statement. The statement may be a DDL or DML statement. DDL statements can be used to create or modify tables, indices, users and roles. DML statements may be read-only SQL queries that extract data from tables, or SQL statements that insert, update, or delete table rows.For DDL statements, the operation is asynchronous and may not be finished when the method returns. An
ExecutionFuture
instance is returned which extendsFuture
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 store is currently executing another DDL 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. For example:
// 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)");
For DML statements, the method initiates the execution and returns a
ExecutionFuture
that is already in the "done" state. However, no query results have been produced yet. Obtaining the query results must be done by iterating over the result set via theStatementResult.iterator()
. For example:// Execute a query ExecutionFuture future = null; try { future = store.execute("select id, lastName from users where age > 30"); } 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); } // The following get() call will return immediately, because the future // is done already. assert(futue.isDone()); StatementResult resultSet = future.get(); // iterate over the query result set TableIterator<RecordValue> ither = resultSet.iterator(); while (iter.hasNext()) { RecordValue rec = iter.next(); System.out.println(rec); } resultSet.close();
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.Note that this method supersedes oracle.kv.table.TableAPI.execute.
- Parameters:
statement
- must follow valid SQL syntax.- Throws:
IllegalArgumentException
- if statement is not valid or cannot be executed because of a syntactic or semantic error.- Since:
- 3.3
- See Also:
- Read exceptions, Write exceptions
-
execute
ExecutionFuture execute(String statement, ExecuteOptions options)
This method is equivalent toexecute(String)
, but it allows its users to specify execution options that override the defaults.- Parameters:
statement
- must follow valid SQL syntax.options
- options that override the defaults.- Throws:
IllegalArgumentException
- if statement is not valid or cannot be executed because of a syntactic or semantic error.- Since:
- 4.0
- See Also:
- Read exceptions, Write exceptions
-
execute
ExecutionFuture execute(char[] statement, ExecuteOptions options)
This method is equivalent toexecute(String, ExecuteOptions)
, but the statement is given as a char[].Note: Use this method when statement may contain passwords. It is safe to clean the contents of the statement char array after the call.
- Since:
- 4.5
-
executeSync
StatementResult executeSync(String statement)
Synchronously execute an SQL statement. This is a convenience method that is equivalent to:ExecutionFuture future = execute(statement); return future.get();
- Parameters:
statement
- must follow valid SQL syntax.- Throws:
IllegalArgumentException
- if statement is not valid or cannot be executed because of a syntactic or semantic error.- Since:
- 3.3
- See Also:
- Read exceptions,
Write exceptions,
execute(String)
-
executeSync
StatementResult executeSync(String statement, ExecuteOptions options)
Synchronously execute an SQL statement. This is a convenience method that is equivalent to:ExecutionFuture future = execute(statement, options); return future.get();
- Parameters:
statement
- must follow valid SQL syntax.options
- options that override the defaults.- Throws:
IllegalArgumentException
- if statement is not valid or cannot be executed because of a syntactic or semantic error.- Since:
- 4.0
- See Also:
- Read exceptions, Write exceptions
-
executeSync
StatementResult executeSync(char[] statement, ExecuteOptions options)
Synchronously execute an SQL statement. This is a convenience method that is equivalent to:ExecutionFuture future = execute(statement, options); return future.get();
Note: Use this method when statement may contain passwords. It is safe to clean the contents of the statement char array after the call.
- Since:
- 4.5
-
executeSync
StatementResult executeSync(Statement statement)
Synchronously execute a prepared SQL statement provided as aPreparedStatement
orBoundStatement
.The method has the same semantics as
executeSync(String)
, but takes a prepared statement as input, whereasexecuteSync(String)
internally compiles/prepares its input statement text.Use this method if you want to execute the same query multiple times. If the query contains external variables, these variables must be bound to specific values before each execution.
- Parameters:
statement
- The prepared statement to be executed.- Returns:
- Returns the result of the statement.
- Throws:
IllegalArgumentException
- if the statement fails to be executed because of a semantic problem with the query.- Since:
- 4.0
- See Also:
- Read exceptions, Write exceptions
-
executeSync
StatementResult executeSync(Statement statement, ExecuteOptions options)
Synchronously execute a prepared SQL statement provided as aPreparedStatement
orBoundStatement
.The method has the same semantics as
executeSync(String, ExecuteOptions)
, but takes a prepared statement as input, whereasexecuteSync(String, ExecuteOptions)
internally compiles/prepares its input statement text.Use this method if you want to execute the same query multiple times. If the query contains external variables, these variables must be bound to specific values before each execution.
- Parameters:
statement
- The prepared statement to be executed.options
- Execution options.- Returns:
- Returns the result of the statement.
- Throws:
IllegalArgumentException
- if the statement fails to be executed because of a semantic problem with the query.- Since:
- 4.0
- See Also:
- Read exceptions, Write exceptions
-
executeAsync
org.reactivestreams.Publisher<RecordValue> executeAsync(String statement, ExecuteOptions options)
Returns a publisher that can be used to subscribe to the results of the asynchronous execution of an SQL statement. DDL statements are not supported. The subscription supplied to the subscriber will implementExecutionSubscription
. The publisher may only be used for a single subscription.The subscription can be used to iterate over the results of the query, to wait for the query to complete, to close the query, or to check the status of the query.
For example:
// Query a table store.executeAsync("SELECT * FROM users", null) .subscribe(new Subscriber<RecordValue>() { @Override public void onSubscribe(Subscription s) { s.request(1000); } @Override public void onNext(RecordValue record) { System.out.println(record); } @Override public void onComplete() { System.out.println("Done"); } @Override public void onError(Throwable exception) { exception.printStackTrace(); } });
This method only supports data access (DML) operations. If the statement is a data definition (DDL) or administrative operation, the
Subscriber.onError(java.lang.Throwable)
method will be called with anUnsupportedOperationException
.See the documentation for a full description of the supported DML statements.
If
Publisher.subscribe(org.reactivestreams.Subscriber<? super T>)
is called more than once on the publisher,Subscriber.onError(java.lang.Throwable)
will be called with anIllegalStateException
.If statement execution fails,
Subscriber.onError(java.lang.Throwable)
will be called with one of the following exceptions:-
IllegalArgumentException
- if the statement is not valid or cannot be executed because of a syntactic or semantic error -
FaultException
- for one of the standard read exceptions or write exceptions
- Parameters:
statement
- statement using Table syntaxoptions
- options that override the defaults- Returns:
- a publisher for subscribing to the operation
- Since:
- 19.5
- See Also:
- Read exceptions, Write exceptions, Thread model for asynchronous execution
-
-
executeAsync
org.reactivestreams.Publisher<RecordValue> executeAsync(Statement statement, ExecuteOptions options)
Returns a publisher that can be used to subscribe to the results of the asynchronous execution of a table statement, either aPreparedStatement
or aBoundStatement
. DDL statements are not supported. The subscription supplied to the subscriber will implementExecutionSubscription
. The publisher may only be used for a single subscription.The subscription can be used to iterate over the results of the query, to wait for the query to complete, to close the query, or to check the status of the query.
For example:
// Query a table Statement statement = store.prepare("SELECT * FROM users"); store.executeAsync(statement, null) .subscribe(new Subscriber<RecordValue>() { @Override public void onSubscribe(Subscription s) { s.request(1000); } @Override public void onNext(RecordValue record) { System.out.println(record); } @Override public void onComplete() { System.out.println("Done"); } @Override public void onError(Throwable exception) { exception.printStackTrace(); } });
This method only supports data access (DML) operations. If the statement is a data definition (DDL) or administrative operation, the
Subscriber.onError(java.lang.Throwable)
method will be called with anUnsupportedOperationException
.See the documentation for a full description of the supported DML statements.
If
Publisher.subscribe(org.reactivestreams.Subscriber<? super T>)
is called more than once on the publisher,Subscriber.onError(java.lang.Throwable)
will be called with anIllegalStateException
.If statement execution fails,
Subscriber.onError(java.lang.Throwable)
will be called with one of the following exceptions:-
IllegalArgumentException
- if the statement is not valid or cannot be executed because of a syntactic or semantic error -
FaultException
- for one of the standard read exceptions or write exceptions
- Parameters:
statement
- statement to be executedoptions
- options that override the defaults- Returns:
- a publisher for subscribing to the operation
- Since:
- 19.5
- See Also:
- Read exceptions, Write exceptions, Thread model for asynchronous execution
-
-
getFuture
ExecutionFuture getFuture(byte[] futureBytes) throws IllegalArgumentException
Obtain a handle onto a previously issued DDL operation, using a serialized version of the ExecutionFuture obtained fromExecutionFuture.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();
Values created with either the current or earlier releases can be used with this method, but values created by later releases are not guaranteed to be compatible.
- Returns:
- an ExecutionFuture representing a previously issued DDL operation
- Throws:
IllegalArgumentException
- if futureBytes isn't a valid representation of an ExecutionFuture instance.- Since:
- 3.3
-
prepare
PreparedStatement prepare(String statement)
Compiles a query into an execution plan.- Parameters:
statement
- The statement to be compiled.- Returns:
- Returns the prepared statement of the query.
- Throws:
IllegalArgumentException
- if statement is not valid.- Since:
- 4.0
- See Also:
- Read exceptions
-
-