Package oracle.kv

# Interface ExecutionFuture

All Superinterfaces:
  `Future<StatementResult>`

public interface ExecutionFuture extends Future<StatementResult>
An ExecutionFuture is a `Future` that provides a handle to an administrative statement that has been issued and is being processed by the kvstore. ExecutionFuture provides a way to check on the interim status of the administrative operation, wait for the operation to complete, or cancel the operation.

For example:

     // Create a table and get a handle on the operation.
     ExecutionFuture future = null;
     try {
         future = kvstore.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);
     }
     // Get current status on the asynchronously executing DDL statement
     StatementResult result = future.updateStatus();

Note that this class supersedes oracle.kv.table.ExecutionFuture.

Since:
  3.3

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `cancel(boolean mayInterruptIfRunning)`
  Attempts to cancel execution of this statement.
  `StatementResult`
  `get()`
  Block until the command represented by this future completes.
  `StatementResult`
  `get(long timeout, TimeUnit unit)`
  Block until the administrative operation has finished or the timeout period is exceeded.
  `StatementResult`
  `getLastStatus()`
  Returns information about the execution of the statement.
  `String`
  `getStatement()`
  Return the statement which has been executed.
  `boolean`
  `isCancelled()`
  Returns true if the operation was cancelled.
  `boolean`
  `isDone()`
  Returns true if the operation has been terminated.
  `byte[]`
  `toByteArray()`
  Return a serialized version of the ExecutionFuture, which can be saved for later use, via `KVStore.getFuture(byte[])`.
  `StatementResult`
  `updateStatus()`
  Returns information about the execution of the statement.

- ## Method Details

  - ### cancel

    boolean cancel(boolean mayInterruptIfRunning) throws FaultException
    Attempts to cancel execution of this statement. Returns false if the statement couldn't be cancelled, possibly because it has already finished. If the statement hasn't succeeded already, and is stopped, the operation will deem to have failed.
    Specified by:
      `cancel` in interface `Future<StatementResult>`
    Parameters:
      `mayInterruptIfRunning` - Since command execution begins immediately, if mayInterreuptIfRunning is false, cancel returns false.
    Throws:
      `FaultException` - if the Admin service connection fails.

  - ### get

    StatementResult get() throws CancellationException, ExecutionException, InterruptedException
    Block until the command represented by this future completes. Returns information about the execution of the statement. This call will result in communication with the kvstore server.

    Note that ExecutionException is thrown if the statement execution threw an exception. Once get() throws ExecutionException, all further calls to get() will continue to throw ExecutionException.

    Specified by:
      `get` in interface `Future<StatementResult>`
    Throws:
      `ExecutionException` - if the command failed.
      `CancellationException` - if the command was cancelled.
      `InterruptedException` - if the current thread was interrupted
      `FaultException` - if tbw

  - ### get

    StatementResult get(long timeout, TimeUnit unit) throws InterruptedException, TimeoutException, ExecutionException
    Block until the administrative operation has finished or the timeout period is exceeded. This call will result in communication with the kvstore server.

    Note that ExecutionException is thrown if the statement execution threw an exception. Once get() throws ExecutionException, all further calls to get() will continue to throw ExecutionException.

    Specified by:
      `get` in interface `Future<StatementResult>`
    Returns:
      information about the execution of the statement
    Throws:
      `TimeoutException` - if the timeout is exceeded.
      `InterruptedException` - if the operation is interrupted
      `ExecutionException`

  - ### isCancelled

    boolean isCancelled()
    Returns true if the operation was cancelled. The cancellation may still be in progress, and the operation may still be running.
    Specified by:
      `isCancelled` in interface `Future<StatementResult>`

  - ### isDone

    boolean isDone()
    Returns true if the operation has been terminated. If the operation is still executing, or if status has never been requested before, this call will result in communication with the kvstore server to obtain up to date status.

    When the statement has terminated, results and status can be obtained via `StatementResult`

    Specified by:
      `isDone` in interface `Future<StatementResult>`

  - ### updateStatus

    StatementResult updateStatus() throws FaultException
    Returns information about the execution of the statement. If the statement is still executing, this call will result in communication with the kvstore server to obtain up to date status, and the status returned will reflect interim information.
    Throws:
      `FaultException` - if there was any problem with accessing the server. In general, such issues are transient, and the request can be retried.

  - ### getLastStatus

    StatementResult getLastStatus()
    Returns information about the execution of the statement. The information returned is that obtained by the last communication with the kvstore server, and will not cause any additional communication. To request a current check, use `updateStatus()`

  - ### getStatement

    String getStatement()
    Return the statement which has been executed.

  - ### toByteArray

    byte[] toByteArray()
    Return a serialized version of the ExecutionFuture, which can be saved for later use, via `KVStore.getFuture(byte[])`. For example:

         byte[] futureBytes = future.toByteArray();

         // futureBytes can be saved and used later to recreate an
         // ExecutionFuture instance
         ExecutionFuture laterFuture = store.getFuture(futureBytes);
         StatementResult laterResult = laterFuture.get();

    Values returned by calls to this method can be used with current and newer releases, but are not guaranteed to be compatible with earlier releases.

    Since:
      3.3