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:

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:

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:

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());
             ... ...
         }
         ... ...
     });

  • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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

      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:

    • 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

      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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

      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:

    • 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:

      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:

    • 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: