Package oracle.kv

# Interface StatementResult

All Superinterfaces:
  `Iterable<RecordValue>`

public interface StatementResult extends Iterable<RecordValue>
A StatementResult provides information about the execution and outcome of a table statement. If obtained via `ExecutionFuture.updateStatus()`, it can represent information about either a completed or in progress operation. If obtained via `ExecutionFuture.get()` or `KVStore.executeSync(java.lang.String)`, it represents the final status of a finished operation.

Since:
  3.2

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static enum`
  `StatementResult.Kind`
  Shows the kind of StatementResult.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Closes the result including the iterator and releases all the resources related to this result.
  `String`
  `getErrorMessage()`
  If `isSuccessful()` is false, return a description of the problem.
  `String`
  `getInfo()`
  Returns information about the execution of the statement, in human readable form.
  `String`
  `getInfoAsJson()`
  Returns the same information as `getInfo()`, in JSON format.
  `StatementResult.Kind`
  `getKind()`
  Returns the Kind of StatementResult.
  `int`
  `getPlanId()`
  Returns the administrative plan id for this operation if the statement was a DDL statement: create or remove table, a create or remove index, or an alter index.
  `String`
  `getResult()`
  Returns the output of a DDL statement that generates results, such as SHOW TABLES, SHOW AS JSON TABLES, DESCRIBE TABLE, or DESCRIBE AS JSON TABLE.
  `RecordDef`
  `getResultDef()`
  Returns the definition of the result of this statement if the statement is a query, otherwise null.
  `boolean`
  `isCancelled()`
  Returns true if the statement had been cancelled.
  `boolean`
  `isDone()`
  Returns true if the statement completed.
  `boolean`
  `isSuccessful()`
  Returns true if this statement has finished and was successful.
  `TableIterator<RecordValue>`
  `iterator()`
  Returns a TableIterator over the records in this result.
  `default void`
  `printTrace(PrintStream out)`

  ### Methods inherited from interface java.lang.Iterable

  `forEach, spliterator`

- ## Method Details

  - ### getPlanId

    int getPlanId()
    Returns the administrative plan id for this operation if the statement was a DDL statement: create or remove table, a create or remove index, or an alter index. When using the Admin CLI (runadmin) utility, administrative operations are identified by plan id. The plan id can be used to correlate data definition and administrative statements issued programmatically using the API against operations viewed via the interactive Admin CLI or other monitoring tool.

    The plan id will be 0 if this statement was not an administrative operation, or did not require execution.

  - ### getInfo

    String getInfo()
    Returns information about the execution of the statement, in human readable form. If the statement was a data definition command, the information will show the start and end time of the operation and details about server side processing. For data manipulation commands it will return null.

  - ### getInfoAsJson

    String getInfoAsJson()
    Returns the same information as `getInfo()`, in JSON format. Several possible formats are returned, depending on the statement. The format of a data definition command which requires server side processing is as follows:

         {
           "version" : "2",
           "planInfo" : {
             "id" : 6,
             "name" : "CreateIndex:users:LastName",
             "isDone" : true,
             "state" : "SUCCEEDED",
             "start" : "2014-10-29 18:41:12 UTC",
             "interrupted" : null,
             "end" : "2014-10-29 18:41:12 UTC",
             "error" : null,
             "executionDetails" : {
               "taskCounts" : {
                 "total" : 3,
                 "successful" : 3,
                 "failed" : 0,
                 "interrupted" : 0,
                 "incomplete" : 0,
                 "notStarted" : 0
               },
               "finished" : [ {
                 "taskNum" : 1,
                 "name" : "StartAddIndex:users:LastName",
                 "state" : "SUCCEEDED",
                 "start" : "2014-10-29 18:41:12 UTC",
                 "end" : "2014-10-29 18:41:12 UTC"
               }, {
                 "taskNum" : 2,
                 "name" : "WaitForAddIndex:users:LastName",
                 "state" : "SUCCEEDED",
                 "start" : "2014-10-29 18:41:12 UTC",
                 "end" : "2014-10-29 18:41:12 UTC"
               }, {
                 "taskNum" : 3,
                 "name" : "CompleteAddIndex:users:LastName",
                 "state" : "SUCCEEDED",
                 "start" : "2014-10-29 18:41:12 UTC",
                 "end" : "2014-10-29 18:41:12 UTC"
               } ],
               "running" : [ ],
               "pending" : [ ]
             }
           }
         }

    For data manipulation commands it will return null.

  - ### getErrorMessage

    String getErrorMessage()
    If `isSuccessful()` is false, return a description of the problem. Will be null if `isSuccessful()` is true.

  - ### isSuccessful

    boolean isSuccessful()
    Returns true if this statement has finished and was successful.

  - ### isDone

    boolean isDone()
    Returns true if the statement completed. For DDL this is the equivalent of `ExecutionFuture.isDone()`. For QUERY statements this indicates if the iterator is depleted.

  - ### isCancelled

    boolean isCancelled()
    Returns true if the statement had been cancelled. This is the equivalent of `ExecutionFuture.isCancelled()`
    See Also:
      - `ExecutionFuture.cancel(boolean)`

  - ### getResult

    String getResult()
    Returns the output of a DDL statement that generates results, such as SHOW TABLES, SHOW AS JSON TABLES, DESCRIBE TABLE, or DESCRIBE AS JSON TABLE. The output of a DESCRIBE AS JSON TABLES command is:

         {
             "type" : "table",
             "name" : "users",
             "comment" : null,
             "shardKey" : [ "id" ],
             "primaryKey" : [ "id" ],
             "fields" : [ {
               "name" : "id",
               "type" : "INTEGER",
               "nullable" : true,
               "default" : null
             }, {
               "name" : "firstName",
               "type" : "STRING",
               "nullable" : true,
               "default" : null
             }, {
               "name" : "lastName",
               "type" : "STRING",
               "nullable" : true,
               "default" : null
             }, {
               "name" : "age",
               "type" : "INTEGER",
               "nullable" : true,
               "default" : null
             } ],
             "indexes" : [ {
               "name" : "LastName",
               "comment" : null,
               "fields" : [ "lastName" ]
             } ]
           }
         }

    The output of a SHOW AS JSON TABLES command is:

         {"tables" : ["users"]}

        Returns null in the case of a DML statement.

    Since:
      3.3

  - ### getKind

    StatementResult.Kind getKind()
    Returns the Kind of StatementResult.
    Since:
      4.0

  - ### iterator

    TableIterator<RecordValue> iterator() throws IllegalStateException

    Returns a TableIterator over the records in this result. If the statement is DDL, an iterator with an empty result will be returned.

    `close()` will close this iterator, any subsequent calls to hasNext() will return false and any calls to next() will throw a java.util.IllegalStateException.

    Note: Multiple calls to this method will return the same iterator object.

    Specified by:
      `iterator` in interface `Iterable<RecordValue>`
    Throws:
      `IllegalStateException` - if the result is closed.
    Since:
      4.0

  - ### close

    void close()
    Closes the result including the iterator and releases all the resources related to this result. This method is idempotent. For query statements any subsequent calls to `getResultDef()` will trigger an IllegalStateException. Applications should discard all references to this object after it has been closed. When a `StatementResult` is closed, any metadata instances that were created by calling the `getResultDef()` method remain accessible.
    Since:
      4.0

  - ### getResultDef

    RecordDef getResultDef() throws IllegalStateException, FaultException
    Returns the definition of the result of this statement if the statement is a query, otherwise null.
    Throws:
      `IllegalStateException` - if the result is closed.
      `FaultException` - if the operation cannot be completed for any reason
    Since:
      4.0

  - ### printTrace

    default void printTrace(PrintStream out)