kv-4.0.9.src.oracle.kv.StatementResult Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of oracle-nosql-client Show documentation
Show all versions of oracle-nosql-client Show documentation
Oracle NoSQL Database Client - supplies build and runtime support for the client side of the Oracle NoSQL Database. Note that a running Oracle NoSQL Database Server (store) is required to do anything meaningful with this client.
/*-
*
* This file is part of Oracle NoSQL Database
* Copyright (C) 2011, 2016 Oracle and/or its affiliates. All rights reserved.
*
* If you have received this file as part of Oracle NoSQL Database the
* following applies to the work as a whole:
*
* Oracle NoSQL Database server software is free software: you can
* redistribute it and/or modify it under the terms of the GNU Affero
* General Public License as published by the Free Software Foundation,
* version 3.
*
* Oracle NoSQL Database is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Affero General Public License for more details.
*
* If you have received this file as part of Oracle NoSQL Database Client or
* distributed separately the following applies:
*
* Oracle NoSQL Database client software is free software: you can
* redistribute it and/or modify it under the terms of the Apache License
* as published by the Apache Software Foundation, version 2.0.
*
* You should have received a copy of the GNU Affero General Public License
* and/or the Apache License in the LICENSE file along with Oracle NoSQL
* Database client or server distribution. If not, see
* .
*
* An active Oracle commercial licensing agreement for this product supersedes
* these licenses and in such case the license notices, but not the copyright
* notice, may be removed by you in connection with your distribution that is
* in accordance with the commercial licensing terms.
*
* For more information please contact:
*
* [email protected]
*
*/
package oracle.kv;
import oracle.kv.table.RecordDef;
import oracle.kv.table.RecordValue;
import oracle.kv.table.TableIterator;
/**
* A StatementResult provides information about the execution and outcome of a
* table statement. If obtained via {@link ExecutionFuture#updateStatus}, it can
* represent information about either a completed or in progress operation. If
* obtained via {@link ExecutionFuture#get} or {@link KVStore#executeSync}, it
* represents the final status of a finished operation.
*
* @since 3.2
*/
public interface StatementResult extends Iterable {
/**
* Shows the kind of StatementResult.
* @see #getKind()
* @since 4.0
*/
enum Kind {
/**
* Results of data definition language statements: create or remove
* table, a create or remove index or an alter index, or other
* statements that don't return data records. In this case the
* iterator().hasNext() will always return false.
*/
DDL,
/**
* Query statements that return records, for example SELECT FROM ....
*/
QUERY
}
/**
* 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.
*/
int getPlanId();
/**
* 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.
*/
String getInfo();
/**
* Returns the same information as {@link #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.
*/
String getInfoAsJson();
/**
* If {@link #isSuccessful} is false, return a description of the
* problem. Will be null if {@link #isSuccessful} is true.
*/
String getErrorMessage();
/**
* Returns true if this statement has finished and was successful.
*/
boolean isSuccessful();
/**
* Returns true if the statement completed. This is the equivalent of
* {@link ExecutionFuture#isDone}
*/
boolean isDone();
/**
* Returns true if the statement had been cancelled. This is the equivalent
* of {@link ExecutionFuture#isCancelled}
*
* @see ExecutionFuture#cancel
*/
boolean isCancelled();
/**
* 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
*/
String getResult();
/**
* Returns the Kind of StatementResult.
*
* @since 4.0
*/
Kind getKind();
/**
* Returns a TableIterator over the records in this result. If the
* statement is DDL, an iterator with an empty result will be
* returned.
*
* {@link StatementResult#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.
*
* @throws IllegalStateException if the result is closed.
*
* @since 4.0
*/
@Override
TableIterator iterator() throws IllegalStateException;
/**
* 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 {@link #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 {@link #getResultDef()}
* method remain accessible.
*
* @since 4.0
*/
void close();
/**
* Returns the definition of the result of this statement if the
* statement is a query, otherwise null.
*
* @throws IllegalStateException if the result is closed.
* @throws FaultException if the operation cannot be completed for any
* reason
* @since 4.0
*/
RecordDef getResultDef() throws IllegalStateException, FaultException;
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy