Package oracle.kv

# 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 from `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 Exceptions

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.
- 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 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.
- 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 as `executeAsync(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, the `Publisher` and `CompletableFuture`, 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 implementing `CompletionStage` in `CompletableFuture`). 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

  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 to `execute(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 to `execute(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.
  `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.
  `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 a `PreparedStatement` or a `BoundStatement`.
  `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 a `PreparedStatement` or `BoundStatement`.
  `StatementResult`
  `executeSync(Statement statement, ExecuteOptions options)`
  Synchronously execute a prepared SQL statement provided as a `PreparedStatement` or `BoundStatement`.
  `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 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.
  `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 Details

  - ### get

    ValueVersion get(Key key)
    Get the value associated with the key.

    The `default consistency` and `default request timeout` are used.

    Parameters:
      `key` - the key used to lookup the key/value pair.
    Returns:
      the value and version associated with the key, or null if no associated value was found.
    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, the `default consistency` is used.
      `timeout` - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the `default request timeout` is used.
      `timeoutUnit` - is the unit of the timeout parameter, and may be null only if timeout is zero.
    Returns:
      the value and version associated with the key, or null if no associated value was found.
    See Also:
      - Read exceptions

  - ### multiGet

    SortedMap<Key,ValueVersion> multiGet(Key parentKey, KeyRange subRange, Depth depth)
    Returns the descendant key/value pairs associated with the `parentKey`. The `subRange` and the `depth` arguments can be used to further limit the key/value pairs that are retrieved. The key/value pairs are fetched within the scope of a single transaction that effectively provides serializable isolation.

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

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

    The `default consistency` and `default request timeout` are used.

    Parameters:
      `parentKey` - the parent key whose "child" KV pairs are to be fetched. It must not be null. The major key path must be complete. The minor key path may be omitted or may be a partial path.
      `subRange` - further restricts the range under the parentKey to the minor path components in this subRange. It may be null.
      `depth` - specifies whether the parent and only children or all descendants are returned. If null, `Depth.PARENT_AND_DESCENDANTS` is implied.
    Returns:
      a SortedMap of key-value pairs, one for each key selected, or an empty map if no keys are selected.
    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 the `parentKey`. The `subRange` and the `depth` arguments can be used to further limit the key/value pairs that are retrieved. The key/value pairs are fetched within the scope of a single transaction that effectively provides serializable isolation.

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

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

    Parameters:
      `parentKey` - the parent key whose "child" KV pairs are to be fetched. It must not be null. The major key path must be complete. The minor key path may be omitted or may be a partial path.
      `subRange` - further restricts the range under the parentKey to the minor path components in this subRange. It may be null.
      `depth` - specifies whether the parent and only children or all descendants are returned. If null, `Depth.PARENT_AND_DESCENDANTS` is implied.
      `consistency` - determines the read consistency associated with the lookup of the child KV pairs. If null, the `default consistency` is used.
      `timeout` - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the `default request timeout` is used.
      `timeoutUnit` - is the unit of the timeout parameter, and may be null only if timeout is zero.
    Returns:
      a SortedMap of key-value pairs, one for each key selected, or an empty map if no keys are selected.
    See Also:
      - Read exceptions

  - ### multiGetKeys

    SortedSet<Key> multiGetKeys(Key parentKey, KeyRange subRange, Depth depth)
    Returns the descendant keys associated with the `parentKey`.

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

    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 the `parentKey`.

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

    See Also:
      - `multiGet(Key, KeyRange, Depth, Consistency, long, TimeUnit)`
      - Read exceptions

  - ### multiGetIterator

    Iterator<KeyValueVersion> multiGetIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth)
    The iterator form of `multiGet(Key, KeyRange, Depth)`.

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

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

    The iterator does not support the remove method.

    The `default consistency` and `default request timeout` are used.

    Parameters:
      `direction` - specifies the order in which records are returned by the iterator. Only `Direction.FORWARD` and `Direction.REVERSE` are supported by this method.
      `batchSize` - the suggested number of keys to fetch during each network round trip. If only the first or last key-value pair is desired, passing a value of one (1) is recommended. If zero, an internally determined default is used.
      `parentKey` - the parent key whose "child" KV pairs are to be fetched. It must not be null. The major key path must be complete. The minor key path may be omitted or may be a partial path.
      `subRange` - further restricts the range under the parentKey to the minor path components in this subRange. It may be null.
      `depth` - specifies whether the parent and only children or all descendants are returned. If null, `Depth.PARENT_AND_DESCENDANTS` is implied.
    Returns:
      an iterator that permits an ordered traversal of the descendant key/value pairs.
    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 of `multiGet(Key, KeyRange, Depth, Consistency, long, TimeUnit)`.

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

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

    The iterator does not support the remove method.

    The `default consistency` and `default request timeout` are used.

    Parameters:
      `direction` - specifies the order in which records are returned by the iterator. Only `Direction.FORWARD` and `Direction.REVERSE` are supported by this method.
      `batchSize` - the suggested number of keys to fetch during each network round trip. If only the first or last key-value pair is desired, passing a value of one (1) is recommended. If zero, an internally determined default is used.
      `parentKey` - the parent key whose "child" KV pairs are to be fetched. It must not be null. The major key path must be complete. The minor key path may be omitted or may be a partial path.
      `subRange` - further restricts the range under the parentKey to the minor path components in this subRange. It may be null.
      `depth` - specifies whether the parent and only children or all descendants are returned. If null, `Depth.PARENT_AND_DESCENDANTS` is implied.
      `consistency` - determines the read consistency associated with the lookup of the child KV pairs. If null, the `default consistency` is used.
      `timeout` - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the `default request timeout` is used.
      `timeoutUnit` - is the unit of the timeout parameter, and may be null only if timeout is zero.
    Returns:
      an iterator that permits an ordered traversal of the descendant key/value pairs.
    See Also:
      - Read exceptions

  - ### multiGetKeysIterator

    Iterator<Key> multiGetKeysIterator(Direction direction, int batchSize, Key parentKey, KeyRange subRange, Depth depth)
    The iterator form of `multiGetKeys(Key, KeyRange, Depth)`.

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

    See Also:
      - `multiGetIterator(Direction, int, Key, KeyRange, Depth)`
      - Read exceptions

  - ### multiGetKeysIterator

    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)`.

    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.

    See Also:
      - `multiGetIterator(Direction, int, Key, KeyRange, Depth, Consistency, long, TimeUnit)`
      - Read exceptions

  - ### 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` and `default request timeout` are used.

    Parameters:
      `direction` - specifies the order in which records are returned by the iterator. Currently only `Direction.UNORDERED` is supported by this method.
      `batchSize` - the suggested number of keys to fetch during each network round trip. If only the first or last key-value pair is desired, passing a value of one (1) is recommended. If zero, an internally determined default is used.
    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` and `default request timeout` are used.

    Parameters:
      `direction` - specifies the order in which records are returned by the iterator. Currently only `Direction.UNORDERED` is supported by this method.
      `batchSize` - the suggested number of keys to fetch during each network round trip. If only the first or last key-value pair is desired, passing a value of one (1) is recommended. If zero, an internally determined default is used.
      `parentKey` - the parent key whose "child" KV pairs are to be fetched. It may be null to fetch all keys in the store. If non-null, the major key path must be a partial path and the minor key path must be empty.
      `subRange` - further restricts the range under the parentKey to the major path components in this subRange. It may be null.
      `depth` - specifies whether the parent and only children or all descendants are returned. If null, `Depth.PARENT_AND_DESCENDANTS` is implied.
    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` and `default request timeout` are used.

    Parameters:
      `direction` - specifies the order in which records are returned by the iterator. Currently only `Direction.UNORDERED` is supported by this method.
      `batchSize` - the suggested number of keys to fetch during each network round trip. If only the first or last key-value pair is desired, passing a value of one (1) is recommended. If zero, an internally determined default is used.
      `parentKey` - the parent key whose "child" KV pairs are to be fetched. It may be null to fetch all keys in the store. If non-null, the major key path must be a partial path and the minor key path must be empty.
      `subRange` - further restricts the range under the parentKey to the major path components in this subRange. It may be null.
      `depth` - specifies whether the parent and only children or all descendants are returned. If null, `Depth.PARENT_AND_DESCENDANTS` is implied.
      `consistency` - determines the read consistency associated with the lookup of the child KV pairs. Version-based consistency may not be used. If null, the `default consistency` is used.
      `timeout` - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the `default request timeout` is used.
      `timeoutUnit` - is the unit of the timeout parameter, and may be null only if timeout is zero.
    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` and `default 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, 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.
    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.

    See Also:
      - `storeIterator(Direction, int, Key, KeyRange, Depth, Consistency, long, TimeUnit)`
      - Read exceptions

  - ### 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).

    See Also:
      - `storeIterator(Direction, int, Key, KeyRange, Depth, Consistency, long, TimeUnit, StoreIteratorConfig)`
      - Read exceptions

  - ### 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` and `default 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, 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.
    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` 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.
    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).

    Since:
      3.4
    See Also:
      - `storeIterator(Iterator, int, KeyRange, Depth, Consistency, long, TimeUnit, StoreIteratorConfig)`
      - Read exceptions

  - ### 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 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.

    Since:
      3.4
    See Also:
      - `storeIterator(Iterator, int, KeyRange, Depth, Consistency, long, TimeUnit, StoreIteratorConfig)`
      - Read exceptions

  - ### 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 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.

    Since:
      3.4
    See Also:
      - `storeKeysIterator(Iterator, int, KeyRange, Depth, Consistency, long, TimeUnit, StoreIteratorConfig)`
      - Read exceptions

  - ### put

    Version put(Key key, Value value)
    Put a key/value pair, inserting or overwriting as appropriate.

    The `default durability` and `default request timeout` are used.

    Possible outcomes when calling this method are:

    1. The KV pair was inserted or updated and the (non-null) version of the new KV pair is returned. There is no way to distinguish between an insertion and an update when using this method signature.
    2. The KV pair was not guaranteed to be inserted or updated successfully, and one of the exceptions listed below is thrown.
    Parameters:
      `key` - the key part of the key/value pair.
      `value` - the value part of the key/value pair.
    Returns:
      the version of the new value.
    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:

    1. The KV pair was inserted or updated and the (non-null) version of the new KV pair is returned. The `prevValue` parameter may be specified to determine whether an insertion or update was performed. If a non-null previous value or version is returned then an update was performed, otherwise an insertion was performed. The previous value or version may also be useful for other application specific reasons.
    2. The KV pair was not guaranteed to be inserted or updated successfully, and one of the exceptions listed below is thrown. The `prevValue` parameter, if specified, is left unmodified.
    Parameters:
      `key` - the key part of the key/value pair
      `value` - the value part of the key/value pair.
      `prevValue` - a `ReturnValueVersion` object to contain the previous value and version associated with the given key, or null if they should not be returned. The version and value in this object are set to null if a previous value does not exist, or the `ReturnValueVersion.Choice` specifies that they should not be returned.
      `durability` - the durability associated with the operation. If null, the `default durability` is used.
      `timeout` - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the `default request timeout` is used.
      `timeoutUnit` - is the unit of the timeout parameter, and may be null only if timeout is zero.
    Returns:
      the version of the new value.
    See Also:
      - Write exceptions

  - ### 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` and `default request timeout` are used.

    Possible outcomes when calling this method are:

    1. The KV pair was inserted and the (non-null) version of the new KV pair is returned.
    2. The KV pair was not inserted because a value was already present with the given key; null is returned and no exception is thrown.
    3. The KV pair was not guaranteed to be inserted successfully and one of the exceptions listed below is thrown.
    Parameters:
      `key` - the key part of the key/value pair.
      `value` - the value part of the key/value pair.
    Returns:
      the version of the new value, or null if an existing value is present and the put is unsuccessful.
    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:

    1. The KV pair was inserted and the (non-null) version of the new KV pair is returned. The `prevValue` parameter, if specified, will contain a null previous value and version.
    2. The KV pair was not inserted because a value was already present with the given key; null is returned and no exception is thrown. The `prevValue` parameter, if specified, will contain a non-null previous value and version. The previous value and version may be useful for application specific reasons; for example, if an update will be performed next in this case.
    3. The KV pair was not guaranteed to be inserted successfully and one of the exceptions listed below is thrown. The `prevValue` parameter, if specified, is left unmodified.
    Parameters:
      `key` - the key part of the key/value pair.
      `value` - the value part of the key/value pair.
      `prevValue` - a `ReturnValueVersion` object to contain the previous value and version associated with the given key, or null if they should not be returned. The version and value in this object are set to null if a previous value does not exist, or the `ReturnValueVersion.Choice` specifies that they should not be returned.
      `durability` - the durability associated with the operation. If null, the `default durability` is used.
      `timeout` - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the `default request timeout` is used.
      `timeoutUnit` - is the unit of the timeout parameter, and may be null only if timeout is zero.
    Returns:
      the version of the new value, or null if an existing value is present and the put is unsuccessful.
    See Also:
      - Write exceptions

  - ### 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` and `default request timeout` are used.

    Possible outcomes when calling this method are:

    1. The KV pair was updated and the (non-null) version of the new KV pair is returned.
    2. The KV pair was not updated because no existing value was present with the given key; null is returned and no exception is thrown.
    3. The KV pair was not guaranteed to be updated successfully and one of the exceptions listed below is thrown.
    Parameters:
      `key` - the key part of the key/value pair.
      `value` - the value part of the key/value pair.
    Returns:
      the version of the new value, or null if no existing value is present and the put is unsuccessful.
    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:

    1. The KV pair was updated and the (non-null) version of the new KV pair is returned. The `prevValue` parameter, if specified, will contain a non-null previous value and version. The previous value and version may be useful for application specific reasons.
    2. The KV pair was not updated because no existing value was present with the given key; null is returned and no exception is thrown. The `prevValue` parameter, if specified, will contain a null previous value and version.
    3. The KV pair was not guaranteed to be updated successfully and one of the exceptions listed below is thrown. The `prevValue` parameter, if specified, is left unmodified.
    Parameters:
      `key` - the key part of the key/value pair.
      `value` - the value part of the key/value pair.
      `prevValue` - a `ReturnValueVersion` object to contain the previous value and version associated with the given key, or null if they should not be returned. The version and value in this object are set to null if a previous value does not exist, or the `ReturnValueVersion.Choice` specifies that they should not be returned.
      `durability` - the durability associated with the operation. If null, the `default durability` is used.
      `timeout` - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the `default request timeout` is used.
      `timeoutUnit` - is the unit of the timeout parameter, and may be null only if timeout is zero.
    Returns:
      the version of the new value, or null if no existing value is present and the put is unsuccessful.
    See Also:
      - Write exceptions

  - ### 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` and `default request timeout` are used.

    Possible outcomes when calling this method are:

    1. The KV pair was updated and the (non-null) version of the new KV pair is returned.
    2. The KV pair was not updated because no existing value was present with the given key, or the version of the existing KV pair did not equal the given `matchVersion` parameter; null is returned and no exception is thrown.
    3. The KV pair was not guaranteed to be updated successfully and one of the exceptions listed below is thrown.
    Parameters:
      `key` - the key part of the key/value pair.
      `value` - the value part of the key/value pair.
      `matchVersion` - the version to be matched.
    Returns:
      the version of the new value, or null if the matchVersion parameter does not match the existing value (or no existing value is present) and the put is unsuccessful.
    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:

    1. The KV pair was updated and the (non-null) version of the new KV pair is returned. The `prevValue` parameter, if specified, will contain a non-null previous value and version. The previous value may be useful for application specific reasons.
    2. The KV pair was not updated because no existing value was present with the given key, or the version of the existing KV pair did not equal the given `matchVersion` parameter; null is returned and no exception is thrown. The `prevValue` parameter may be specified to determine whether the failure was due to a missing KV pair or a version mismatch. If a null previous value or version is returned then the KV pair was missing, otherwise a version mismatch occurred. The previous value or version may also be useful for other application specific reasons.
    3. The KV pair was not guaranteed to be updated successfully and one of the exceptions listed below is thrown. The `prevValue` parameter, if specified, is left unmodified.
    Parameters:
      `key` - the key part of the key/value pair.
      `value` - the value part of the key/value pair.
      `matchVersion` - the version to be matched.
      `prevValue` - a `ReturnValueVersion` object to contain the previous value and version associated with the given key, or null if they should not be returned. The version and value in this object are set to null if a previous value does not exist, or the `ReturnValueVersion.Choice` specifies that they should not be returned, or the matchVersion parameter matches the existing value and the put is successful.
      `durability` - the durability associated with the operation. If null, the `default durability` is used.
      `timeout` - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the `default request timeout` is used.
      `timeoutUnit` - is the unit of the timeout parameter, and may be null only if timeout is zero.
    Returns:
      the version of the new value, or null if the matchVersion parameter does not match the existing value (or no existing value is present) and the put is unsuccessful.
    See Also:
      - Write exceptions

  - ### 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` and `default request timeout` are used.

    Possible outcomes when calling this method are:

    1. The KV pair was deleted and true is returned.
    2. The KV pair was not deleted because no existing value was present with the given key; false is returned and no exception is thrown.
    3. The KV pair was not guaranteed to be deleted successfully and one of the exceptions listed below is thrown.
    Parameters:
      `key` - the key used to lookup the key/value pair.
    Returns:
      true if the delete is successful, or false if no existing value is present.
    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:

    1. The KV pair was deleted and true is returned. The `prevValue` parameter, if specified, will contain a non-null previous value and version. The previous value may be useful for application specific reasons.
    2. The KV pair was not deleted because no existing value was present with the given key; false is returned and no exception is thrown. The `prevValue` parameter, if specified, will contain a null previous value and version.
    3. The KV pair was not guaranteed to be deleted successfully and one of the exceptions listed below is thrown. The `prevValue` parameter, if specified, is left unmodified.
    Parameters:
      `key` - the key used to lookup the key/value pair.
      `prevValue` - a `ReturnValueVersion` object to contain the previous value and version associated with the given key, or null if they should not be returned. The version and value in this object are set to null if a previous value does not exist, or the `ReturnValueVersion.Choice` specifies that they should not be returned.
      `durability` - the durability associated with the operation. If null, the `default durability` is used.
      `timeout` - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the `default request timeout` is used.
      `timeoutUnit` - is the unit of the timeout parameter, and may be null only if timeout is zero.
    Returns:
      true if the delete is successful, or false if no existing value is present.
    See Also:
      - Write exceptions

  - ### 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` and `default request timeout` are used.

    Possible outcomes when calling this method are:

    1. The KV pair was deleted and true is returned.
    2. The KV pair was not deleted because no existing value was present with the given key, or the version of the existing KV pair did not equal the given `matchVersion` parameter; false is returned and no exception is thrown. There is no way to distinguish between a missing KV pair and a version mismatch when using this method signature.
    3. The KV pair was not guaranteed to be deleted successfully and one of the exceptions listed below is thrown.
    Parameters:
      `key` - the key to be used to identify the key/value pair.
      `matchVersion` - the version to be matched.
    Returns:
      true if the deletion is successful.
    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:

    1. The KV pair was deleted and true is returned. The `prevValue` parameter, if specified, will contain a non-null previous value and version. The previous value may be useful for application specific reasons.
    2. The KV pair was not deleted because no existing value was present with the given key, or the version of the existing KV pair did not equal the given `matchVersion` parameter; false is returned and no exception is thrown. The `prevValue` parameter may be specified to determine whether the failure was due to a missing KV pair or a version mismatch. If a null previous value or version is returned then the KV pair was missing, otherwise a version mismatch occurred. The previous value or version may also be useful for other application specific reasons.
    3. The KV pair was not guaranteed to be deleted successfully and one of the exceptions listed below is thrown. The `prevValue` parameter, if specified, is left unmodified.
    Parameters:
      `key` - the key to be used to identify the key/value pair.
      `matchVersion` - the version to be matched.
      `prevValue` - a `ReturnValueVersion` object to contain the previous value and version associated with the given key, or null if they should not be returned. The version and value in this object are set to null if a previous value does not exist, or the `ReturnValueVersion.Choice` specifies that they should not be returned, or the matchVersion parameter matches the existing value and the delete is successful.
      `durability` - the durability associated with the operation. If null, the `default durability` is used.
      `timeout` - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the `default request timeout` is used.
      `timeoutUnit` - is the unit of the timeout parameter, and may be null only if timeout is zero.
    Returns:
      true if the deletion is successful.
    See Also:
      - Write exceptions

  - ### multiDelete

    int multiDelete(Key parentKey, KeyRange subRange, Depth depth)
    Deletes the descendant Key/Value pairs associated with the `parentKey`. The `subRange` and the `depth` arguments can be used to further limit the key/value pairs that are deleted.

    The `default durability` and `default request timeout` are used.

    Parameters:
      `parentKey` - the parent key whose "child" KV pairs are to be deleted. It must not be null. The major key path must be complete. The minor key path may be omitted or may be a partial path.
      `subRange` - further restricts the range under the parentKey to the minor path components in this subRange. It may be null.
      `depth` - specifies whether the parent and only children or all descendants are deleted. If null, `Depth.PARENT_AND_DESCENDANTS` is implied.
    Returns:
      a count of the keys that were deleted.
    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 the `parentKey`. The `subRange` and the `depth` arguments can be used to further limit the key/value pairs that are deleted.
    Parameters:
      `parentKey` - the parent key whose "child" KV pairs are to be deleted. It must not be null. The major key path must be complete. The minor key path may be omitted or may be a partial path.
      `subRange` - further restricts the range under the parentKey to the minor path components in this subRange. It may be null.
      `depth` - specifies whether the parent and only children or all descendants are deleted. If null, `Depth.PARENT_AND_DESCENDANTS` is implied.
      `durability` - the durability associated with the operation. If null, the `default durability` is used.
      `timeout` - is an upper bound on the time interval for processing the operation. A best effort is made not to exceed the specified limit. If zero, the `default request timeout` is used.
      `timeoutUnit` - is the unit of the timeout parameter, and may be null only if timeout is zero.
    Returns:
      a count of the keys that were deleted.
    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 with `KVLocal` 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 the `getOperationFactory()` method.

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

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

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

    Operations are not executed in the sequence they appear 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.

    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) 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 and the store is not single partition, or more than one operation has the same Key.
    See Also:
      - Write exceptions

  - ### 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 with `KVLocal` 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 the `getOperationFactory()` method.

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

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

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

    Operations are not executed in the sequence they appear 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, the `default durability` is used.
      `timeout` - is an upper bound on the time interval for processing the set of operations. A best effort is made not to exceed the specified limit. If zero, the `default request timeout` is used.
      `timeoutUnit` - is the unit of the timeout parameter, and may be null only if timeout is zero.
    Returns:
      the sequence of results associated with the operation. There is one entry for each Operation in the operations argument list. The returned list is in the same order as the operations argument list.
    Throws:
      `OperationExecutionException` - if an operation is not successful as defined by the particular operation (e.g., a delete operation for a non-existent key) and `true` was passed for the `abortIfUnsuccessful` parameter when the operation was created using the `OperationFactory`.
      `IllegalArgumentException` - if operations is null or empty, or not all operations operate on keys with the same Major Path and the store is not single partition, or more than one operation has the same Key.
    See Also:
      - Write exceptions

  - ### 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; 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.

    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 to `execute`.

  - ### 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 interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`

  - ### getStats

    KVStats getStats(boolean clear)
    Returns the statistics related to the K/V Store client.
    Parameters:
      `clear` - If set to true, configure the statistics operation to reset statistics after they are returned.
    Returns:
      The K/V Store client side statistics.

  - ### 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 null
      `FaultException` - if the operation cannot be completed for any reason.
    Since:
      3.0

  - ### 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 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 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 the `StatementResult.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 to `execute(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 to `execute(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 a `PreparedStatement` or `BoundStatement`.

    The method has the same semantics as `executeSync(String)`, but takes a prepared statement as input, whereas `executeSync(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 a `PreparedStatement` or `BoundStatement`.

    The method has the same semantics as `executeSync(String, ExecuteOptions)`, but takes a prepared statement as input, whereas `executeSync(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

    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 implement `ExecutionSubscription`. 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 an `UnsupportedOperationException`.

    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 an `IllegalStateException`.

    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 syntax
      `options` - 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

    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 a `PreparedStatement` or a `BoundStatement`. DDL statements are not supported. The subscription supplied to the subscriber will implement `ExecutionSubscription`. 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 an `UnsupportedOperationException`.

    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 an `IllegalStateException`.

    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 executed
      `options` - 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 from `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.

    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