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.
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 operations are executed by the get
and iterator
methods, and their related iteration calls. Examples are
get
, multiGet
and
storeIterator
. In addition,
the TableAPI
interface has read methods, such as
table get
,
tableIterator
, etc. All read methods may
experience the following failures:
FaultException
is the superclass of several read exceptions:
ConsistencyException
is thrown if the specified
Consistency
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 are executed by methods that modify data, such as put
, delete
, the other put
and
delete
variants, execute
, etc.
In addition, the TableAPI
interface has data modification methods,
such as table 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 specified
Durability
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.
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.
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.
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.
|
ExecutionFuture |
execute(char[] statement,
ExecuteOptions options)
Asynchronously executes a DDL statement.
|
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.
|
ExecutionFuture |
execute(String statement,
ExecuteOptions options)
Asynchronously executes a DDL statement.
|
StatementResult |
executeSync(char[] statement,
ExecuteOptions options)
Synchronously execute a table statement.
|
StatementResult |
executeSync(Statement statement)
Synchronously execute a table statement:
PreparedStatement or
BoundStatement . |
StatementResult |
executeSync(Statement statement,
ExecuteOptions options)
Synchronously execute a table statement:
PreparedStatement or
BoundStatement . |
StatementResult |
executeSync(String statement)
Synchronously execute a table statement.
|
StatementResult |
executeSync(String statement,
ExecuteOptions options)
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()
Deprecated.
as of 4.0, use the table API instead.
|
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) . |
PreparedStatement |
prepare(String statement)
Compiles a query into an execution plan.
|
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.
|
void |
put(List<EntryStream<KeyValue>> streams,
BulkWriteOptions bulkWriteOptions)
Loads Key/Value pairs supplied by special purpose streams into the store.
|
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).
|
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<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).
|
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).
|
appendLOB, deleteLOB, getLOB, putLOB, putLOBIfAbsent, putLOBIfPresent
ValueVersion get(Key key)
The default consistency
and
default request timeout
are
used.
key
- the key used to lookup the key/value pair.ValueVersion get(Key key, Consistency consistency, long timeout, TimeUnit timeoutUnit)
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.SortedMap<Key,ValueVersion> multiGet(Key parentKey, KeyRange subRange, Depth depth)
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.SortedMap<Key,ValueVersion> multiGet(Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit)
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.SortedSet<Key> multiGetKeys(Key parentKey, KeyRange subRange, Depth depth)
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.
multiGet(Key, KeyRange, Depth)
,
Read exceptionsSortedSet<Key> multiGetKeys(Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit)
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)
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.Iterator<KeyValueVersion> multiGetIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit)
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.Iterator<Key> multiGetKeysIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth)
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)
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)
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.Iterator<KeyValueVersion> storeIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth)
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.Iterator<KeyValueVersion> storeIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit)
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.ParallelScanIterator<KeyValueVersion> storeIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit, StoreIteratorConfig storeIteratorConfig)
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
and
default request timeout
are
used.
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, 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.IllegalArgumentException
- if the storeIteratorConfig argument is
null.Iterator<Key> storeKeysIterator(Direction direction, int batchSize)
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.
storeIterator(Direction, int)
,
Read exceptionsIterator<Key> storeKeysIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth)
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.
storeIterator(Direction, int)
,
Read exceptionsIterator<Key> storeKeysIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit)
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)
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).
ParallelScanIterator<KeyValueVersion> storeIterator(Iterator<Key> parentKeyIterator, int batchSize, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit, StoreIteratorConfig storeIteratorConfig)
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
and
default request timeout
are
used.
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, the default 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, 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
internally determined default is used.parentKeyIterator
, subRange
and
depth
constraints. If the parentKeyIterator
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.IllegalArgumentException
- if the storeIteratorConfig argument is
null.ParallelScanIterator<Key> storeKeysIterator(Iterator<Key> parentKeyIterator, int batchSize, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit, StoreIteratorConfig storeIteratorConfig)
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).
ParallelScanIterator<KeyValueVersion> storeIterator(List<Iterator<Key>> parentKeyIterators, int batchSize, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit, StoreIteratorConfig storeIteratorConfig)
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 overloaded storeIterator(Iterator, int, KeyRange, Depth, Consistency, long,
TimeUnit, StoreIteratorConfig)
method. One or more of the iterators in
the parentKeyIterators
list may be read in parallel to
maximize input throughput, the element of key iterator list should be
non null.
ParallelScanIterator<Key> storeKeysIterator(List<Iterator<Key>> parentKeyIterators, int batchSize, KeyRange subRange, Depth depth, Consistency consistency, long timeout, TimeUnit timeoutUnit, StoreIteratorConfig storeIteratorConfig)
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 overloaded
storeKeysIterator(Iterator, int, KeyRange, Depth, Consistency,
long, TimeUnit, StoreIteratorConfig)
method. One or more of the
iterators in the parentKeyIterators
list may be read in
parallel to maximize input throughput, the element of key iterator list
should be non null.
Version put(Key key, Value value)
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.Version put(Key key, Value value, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit)
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.Version putIfAbsent(Key key, Value value)
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.Version putIfAbsent(Key key, Value value, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit)
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.Version putIfPresent(Key key, Value value)
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.Version putIfPresent(Key key, Value value, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit)
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.Version putIfVersion(Key key, Value value, Version matchVersion)
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.Version putIfVersion(Key key, Value value, Version matchVersion, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit)
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.boolean delete(Key key)
Deleting a key/value pair with this method does not automatically
delete its children or descendant key/value pairs. To delete children
or descendants, use multiDelete
instead.
The default durability
and default request timeout
are used.
Possible outcomes when calling this method are:
key
- the key used to lookup the key/value pair.boolean delete(Key key, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit)
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.boolean deleteIfVersion(Key key, Version matchVersion)
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.boolean deleteIfVersion(Key key, Version matchVersion, ReturnValueVersion prevValue, Durability durability, long timeout, TimeUnit timeoutUnit)
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.int multiDelete(Key parentKey, KeyRange subRange, Depth depth)
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.int multiDelete(Key parentKey, KeyRange subRange, Depth depth, Durability durability, long timeout, TimeUnit timeoutUnit)
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.List<OperationResult> execute(List<Operation> operations) throws OperationExecutionException
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.List<OperationResult> execute(List<Operation> operations, Durability durability, long timeout, TimeUnit timeoutUnit) throws OperationExecutionException
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.void put(List<EntryStream<KeyValue>> streams, BulkWriteOptions bulkWriteOptions)
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; the
EntryStream.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 in EntryStream.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.
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 operationsOperationFactory getOperationFactory()
execute
.void close()
close
in interface AutoCloseable
close
in interface Closeable
KVStats getStats(boolean clear)
clear
- If set to true, configure the statistics operation to
reset statistics after they are returned.@Deprecated 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)
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.
Note that this method supersedes oracle.kv.table.TableAPI.execute.
statement
- must follow valid Table syntax.IllegalArgumentException
- if statement is not valid or cannot be executed
because of a syntactic or semantic error.ExecutionFuture execute(String statement, ExecuteOptions options)
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.
Note that this method supersedes oracle.kv.table.TableAPI.execute.
statement
- must follow valid Table syntax.options
- options that override the defaults.IllegalArgumentException
- if statement is not valid or cannot be executed
because of a syntactic or semantic error.ExecutionFuture execute(char[] statement, ExecuteOptions options)
execute(String, ExecuteOptions)
, but statement is 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.
StatementResult executeSync(String statement)
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 statement is not valid or cannot be executed
because of a syntactic or semantic error.
Note that this method supersedes oracle.kv.table.TableAPI.executeSync
StatementResult executeSync(String statement, ExecuteOptions options)
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.options
- options that override the defaults.IllegalArgumentException
- if statement is not valid or cannot be executed
because of a syntactic or semantic error.
Note that this method supersedes oracle.kv.table.TableAPI.executeSync
StatementResult executeSync(char[] statement, ExecuteOptions options)
execute(String)
, but statement is 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.
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();
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.
IllegalArgumentException
- if futureBytes isn't a valid
representation of an ExecutionFuture instance.PreparedStatement prepare(String statement)
statement
- The statement to be compiled.IllegalArgumentException
- if statement is not valid.StatementResult executeSync(Statement statement)
PreparedStatement
or
BoundStatement
. For DDL statements the method will only return
when the statement has finished and has the same semantics as execute(String)
, but offers synchronous behavior as a convenience.
In the case of DML statements the execution is delayed until the
iteration of the results.
When executeSync() returns, statement execution will have terminated,
and the resulting StatementResult
will provide information
about the outcome.
statement
- The statement to be executed.IllegalArgumentException
- if the statement fails to be executed
because of a semantic problem with the query.StatementResult executeSync(Statement statement, ExecuteOptions options)
PreparedStatement
or
BoundStatement
. For DDL statements the method will only return
when the statement has finished and has the same semantics as execute(String)
, but offers synchronous behavior as a convenience.
In the case of DML statements the execution is delayed until the
iteration of the results.
When executeSync() returns, statement execution will have terminated,
and the resulting StatementResult
will provide information
about the outcome.
statement
- The statement to be executed.options
- Execution options.IllegalArgumentException
- if the statement fails to be executed
because of a semantic problem with the query.Copyright (c) 2011, 2017 Oracle and/or its affiliates. All rights reserved.