Package oracle.nosql.driver

# Interface NoSQLHandle

All Superinterfaces:
  `AutoCloseable`

public interface NoSQLHandle extends AutoCloseable
NoSQLHandle is a handle that can be used to access Oracle NoSQL tables. To create a connection represented by NoSQLHandle, request an instance using `NoSQLHandleFactory.createNoSQLHandle(oracle.nosql.driver.NoSQLHandleConfig)` and `NoSQLHandleConfig`, which allows an application to specify default values and other configuration information to be used by the handle.

The same interface is available to both users of the Oracle NoSQL Database Cloud Service and the on-premises Oracle NoSQL Database; however, some methods and/or parameters are specific to each environment. The documentation has notes about whether a class, method, or parameter is environment-specific. Unless otherwise noted they are applicable to both environments.

A handle has 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 handle.

To minimize network activity as well as resource allocation and deallocation overheads, it's best to avoid repeated creation and closing of handles. For example, creating and closing a handle around each 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 tables in a multi-threaded application. The creation of multiple handles incurs additional resource overheads without providing any performance benefit.

With the exception of `close()` the operations on this interface follow a similar pattern. They accept a `Request` object containing parameters, both required and optional. They return a `Result` object containing results. Operation failures throw exceptions. Unique subclasses of `Request` and `Result` exist for most operations, containing information specific to the operation. All of these operations result in remote calls across a network.

All `Request` instances support specification of parameters for the operation as well as the ability to override default parameters which may have been specified in `NoSQLHandleConfig`, such as request timeouts, `Consistency`, etc.

Objects returned by methods of this interface can only be used safely by one thread at a time unless synchronized externally. `Request` objects are not copied and must not be modified by the application while a method on this interface is using them.

## Error and Exception Handling

On success all methods in this interface return `Result` objects. Errors are thrown as exceptions. Some Java exceptions, such as `IllegalArgumentException` and `NullPointerException` are thrown directly. All other exceptions are instances of `NoSQLException`, which serves as a base class for NoSQL Database exceptions.

`NoSQLException` instances are split into 2 broad categories:

1. Exceptions that may be retried with the expectation that they may succeed on retry. These are instances of `RetryableException`
2. Exceptions that may not be retried and if retried, will fail again

Exceptions that may be retried return true for `NoSQLException.okToRetry()` while those that may not will return false. Examples of retryable exceptions are those which indicate resource consumption violations such as `ThrottlingException`. Examples of exceptions that should not be retried are `IllegalArgumentException`, `TableNotFoundException`, and any other exception indicating a syntactic or semantic error.

Instances of NoSQLHandle are thread-safe and expected to be shared among threads.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `TableResult`
  `addReplica(AddReplicaRequest request)`
  Cloud service only.
  `void`
  `close()`
  Closes the handle, releasing its memory and network resources.
  `DeleteResult`
  `delete(DeleteRequest request)`
  Deletes a row from a table.
  `SystemResult`
  `doSystemRequest(String statement, int timeoutMs, int pollIntervalMs)`
  On-premises only.
  `TableResult`
  `doTableRequest(TableRequest request, int timeoutMs, int pollIntervalMs)`
  A convenience method that performs a TableRequest and waits for completion of the operation.
  `TableResult`
  `dropReplica(DropReplicaRequest request)`
  Cloud service only.
  `GetResult`
  `get(GetRequest request)`
  Gets the row associated with a primary key.
  `GetIndexesResult`
  `getIndexes(GetIndexesRequest request)`
  Returns information about and index, or indexes on a table.
  `ReplicaStatsResult`
  `getReplicaStats(ReplicaStatsRequest request)`
  Cloud service only.
  `StatsControl`
  `getStatsControl()`
  Returns an object that allows control over how SDK statistics are collected.
  `TableResult`
  `getTable(GetTableRequest request)`
  Gets static information about the specified table including its state, provisioned throughput and capacity and schema.
  `TableUsageResult`
  `getTableUsage(TableUsageRequest request)`
  Cloud service only.
  `String[]`
  `listNamespaces()`
  On-premises only.
  `String[]`
  `listRoles()`
  On-premises only.
  `ListTablesResult`
  `listTables(ListTablesRequest request)`
  Lists tables, returning table names.
  `UserInfo[]`
  `listUsers()`
  On-premises only.
  `MultiDeleteResult`
  `multiDelete(MultiDeleteRequest request)`
  Deletes multiple rows from a table in an atomic operation.
  `PrepareResult`
  `prepare(PrepareRequest request)`
  Prepares a query for execution and reuse.
  `PutResult`
  `put(PutRequest request)`
  Puts a row into a table.
  `QueryResult`
  `query(QueryRequest request)`
  Queries a table based on the query statement specified in the `QueryRequest`.
  `QueryIterableResult`
  `queryIterable(QueryRequest request)`
  Queries a table based on the query statement specified in the `QueryRequest` while returning an iterable result.
  `SystemResult`
  `systemRequest(SystemRequest request)`
  On-premises only.
  `SystemResult`
  `systemStatus(SystemStatusRequest request)`
  On-premises only.
  `TableResult`
  `tableRequest(TableRequest request)`
  Performs an operation on a table.
  `WriteMultipleResult`
  `writeMultiple(WriteMultipleRequest request)`
  Executes a sequence of operations associated with a table that share the same shard key portion of their primary keys, all the specified operations are executed within the scope of a single transaction.

- ## Method Details

  - ### delete

    DeleteResult delete(DeleteRequest request)
    Deletes a row from a table. The row is identified using a primary key value supplied in `DeleteRequest.setKey(oracle.nosql.driver.values.MapValue)`

    By default a delete operation is unconditional and will succeed if the specified row exists. Delete operations can be made conditional based on whether the `Version` of an existing row matches that supplied by `DeleteRequest.setMatchVersion(oracle.nosql.driver.Version)`.

    It is also possible to return information about the existing row. The row, including it's `Version` and modification time can be optionally returned. The existing row information will only be returned if `DeleteRequest.setReturnRow(boolean)` is true and one of the following occurs:

    - The `DeleteRequest.setMatchVersion(oracle.nosql.driver.Version)` is used and the operation fails because the row exists and its version does not match.
    - The `DeleteRequest.setMatchVersion(oracle.nosql.driver.Version)` is not used and the operation succeeds provided that the server supports providing the existing row.
    Use of `DeleteRequest.setReturnRow(boolean)` may result in additional consumed read capacity.
    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### get

    GetResult get(GetRequest request)
    Gets the row associated with a primary key. On success the value of the row is available using the `GetResult.getValue()` operation. If there are no matching rows that method will return null.

    The default `Consistency` used for the operation is `Consistency.EVENTUAL` unless an explicit value is has been set using `NoSQLHandleConfig.setConsistency(oracle.nosql.driver.Consistency)` or `GetRequest.setConsistency(oracle.nosql.driver.Consistency)`. Use of `Consistency.ABSOLUTE` may affect latency of the operation and may result in additional cost for the operation.

    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### put

    PutResult put(PutRequest request)
    Puts a row into a table. This method creates a new row or overwrites an existing row entirely. The value used for the put is in the `PutRequest` object and must contain a complete primary key and all required fields.

    It is not possible to put part of a row. Any fields that are not provided will be defaulted, overwriting any existing value. Fields that are not nullable or defaulted must be provided or an exception will be thrown.

    By default a put operation is unconditional, but put operations can be conditional based on existence, or not, of a previous value as well as conditional on the `Version` of the existing value.

    - Use `PutRequest.Option.IfAbsent` to do a put only if there is no existing row that matches the primary key
    - Use `PutRequest.Option.IfPresent` to do a put only if there is an existing row that matches the primary key
    - Use `PutRequest.Option.IfVersion` to do a put only if there is an existing row that matches the primary key and its `Version` matches that provided

    It is also possible to return information about the existing row. The existing row, including it's `Version` and modification time can be optionally returned. The existing row information will only be returned if `PutRequest.setReturnRow(boolean)` is true and one of the following occurs:

    - The `PutRequest.Option.IfAbsent` is used and the operation fails because the row already exists.
    - The `PutRequest.Option.IfVersion` is used and the operation fails because the row exists and its version does not match.
    - The `PutRequest.Option.IfPresent` is used and the operation succeeds provided that the server supports providing the existing row.
    - The `PutRequest.Option` is not used and put operation replaces the existing row provided that the server supports providing the existing row.
    Use of `PutRequest.setReturnRow(boolean)` may result in additional consumed read capacity.
    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### writeMultiple

    WriteMultipleResult writeMultiple(WriteMultipleRequest request)
    Executes a sequence of operations associated with a table that share the same shard key portion of their primary keys, all the specified operations are executed within the scope of a single transaction. `WriteMultipleRequest`.

    There are some size-based limitations on this operation:

    - The max number of individual operations (put, delete) in a single WriteMultiple request is 50.
    - The total request size is limited to 25MB.
    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `RowSizeLimitException` - if data size in an operation exceeds the limit.
      `BatchOperationNumberLimitException` - if the number of operations exceeds this limit.
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### multiDelete

    MultiDeleteResult multiDelete(MultiDeleteRequest request)
    Deletes multiple rows from a table in an atomic operation. The key used may be partial but must contain all of the fields that are in the shard key. A range may be specified to delete a range of keys.
    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### query

    QueryResult query(QueryRequest request)
    Queries a table based on the query statement specified in the `QueryRequest`.

    Queries that include a full shard key will execute much more efficiently than more distributed queries that must go to multiple shards.

    Table- and system-style queries such as "CREATE TABLE ..." or "DROP TABLE .." are not supported by this interface. Those operations must be performed using `tableRequest(oracle.nosql.driver.ops.TableRequest)` or `systemRequest(oracle.nosql.driver.ops.SystemRequest)` as appropriate.

    The amount of data read by a single query request is limited by a system default and can be further limited using `QueryRequest.setMaxReadKB(int)`. This limits the amount of data read and not the amount of data returned, which means that a query can return zero results but still have more data to read. This situation is detected by checking if the `QueryResult` has a continuation key, using `QueryResult.getContinuationKey()`. For this reason queries should always operate in a loop, acquiring more results, until the continuation key is null, indicating that the query is done. Inside the loop the continuation key is applied to the `QueryRequest` using `QueryRequest.setContinuationKey(byte[])`.

    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### queryIterable

    QueryIterableResult queryIterable(QueryRequest request)
    Queries a table based on the query statement specified in the `QueryRequest` while returning an iterable result.

    Queries that include a full shard key will execute much more efficiently than more distributed queries that must go to multiple shards.

    Remote calls, including preparation of a query statement, will not occur until the iteration starts. This means that errors such as an invalid statement or network issue will be thrown from the iterator and not this method.

    Table- and system-style queries such as "CREATE TABLE ..." or "DROP TABLE .." are not supported by this interface. Those operations must be performed using `tableRequest(oracle.nosql.driver.ops.TableRequest)` or `systemRequest(oracle.nosql.driver.ops.SystemRequest)` as appropriate.

    The results are returned through an iterator, if connected to the cloud, the SDK uses the read/write rate limits set in the NoSQLHandleConfig or they can be overwritten using the `Request.setReadRateLimiter(RateLimiter)` and `Request.setWriteRateLimiter(RateLimiter)`.

    Note: Since iterators might use resources until they reach the end, it is necessary to close the QueryIterableResult or use the try-with-resources statement:

            try (
                QueryRequest qreq = new QueryRequest()
                    .setStatement("select * from MyTable");
                QueryIterableResult qir = handle.queryIterable(qreq)) {
                for( MapValue row : qir) {
                    // do something with row
                }
            }

    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the iterable result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### prepare

    PrepareResult prepare(PrepareRequest request)
    Prepares a query for execution and reuse. See `query(oracle.nosql.driver.ops.QueryRequest)` for general information and restrictions. It is recommended that prepared queries are used when the same query will run multiple times as execution is much more efficient than starting with a query string every time. The query language and API support query variables to assist with re-use.
    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### tableRequest

    TableResult tableRequest(TableRequest request)
    Performs an operation on a table. This method is used for creating and dropping tables and indexes as well as altering tables. Only one operation is allowed on a table at any one time.

    This operation is implicitly asynchronous. The caller must poll using methods on `TableResult` to determine when it has completed.

    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### doTableRequest

    TableResult doTableRequest(TableRequest request, int timeoutMs, int pollIntervalMs)
    A convenience method that performs a TableRequest and waits for completion of the operation. This is the same as calling `tableRequest(oracle.nosql.driver.ops.TableRequest)` then calling `TableResult.waitForCompletion(oracle.nosql.driver.NoSQLHandle, int, int)`. If the operation fails an exception is thrown. All parameters are required.
    Parameters:
      `request` - the `TableRequest` to perform.
      `timeoutMs` - the amount of time to wait for completion, in milliseconds.
      `pollIntervalMs` - the polling interval for the wait operation.
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `RequestTimeoutException` - if the operation times out.
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### systemRequest

    SystemResult systemRequest(SystemRequest request)
    On-premises only.

    Performs a system operation on the system, such as administrative operations that don't affect a specific table. For table-specific operations use `tableRequest(oracle.nosql.driver.ops.TableRequest)` or `doTableRequest(oracle.nosql.driver.ops.TableRequest, int, int)`.

    Examples of statements in the `SystemRequest` passed to this method include:

    - CREATE NAMESPACE mynamespace
    - CREATE USER some_user IDENTIFIED BY password
    - CREATE ROLE some_role
    - GRANT ROLE some_role TO USER some_user

    This operation is implicitly asynchronous. The caller must poll using methods on `SystemResult` to determine when it has completed.

    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### systemStatus

    SystemResult systemStatus(SystemStatusRequest request)
    On-premises only.

    Checks the status of an operation previously performed using `systemRequest(oracle.nosql.driver.ops.SystemRequest)`.

    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### getTable

    TableResult getTable(GetTableRequest request)
    Gets static information about the specified table including its state, provisioned throughput and capacity and schema. Dynamic information such as usage is obtained using `getTableUsage(oracle.nosql.driver.ops.TableUsageRequest)`. Throughput, capacity and usage information is only available when using the Cloud Service and will be null or not defined on-premises.
    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `TableNotFoundException` - if the specified table does not exist
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### getTableUsage

    TableUsageResult getTableUsage(TableUsageRequest request)
    Cloud service only.

    Gets dynamic information about the specified table such as the current throughput usage. Usage information is collected in time slices and returned in individual usage records. It is possible to specify a time-based range of usage records using input parameters.

    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `TableNotFoundException` - if the specified table does not exist
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### listTables

    ListTablesResult listTables(ListTablesRequest request)
    Lists tables, returning table names. If further information about a specific table is desired the `getTable(oracle.nosql.driver.ops.GetTableRequest)` interface may be used. If a given identity has access to a large number of tables the list may be paged using input parameters.
    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### getIndexes

    GetIndexesResult getIndexes(GetIndexesRequest request)
    Returns information about and index, or indexes on a table. If no index name is specified in the `GetIndexesRequest`, then information on all indexes is returned.
    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### listNamespaces

    String[] listNamespaces()
    On-premises only.

    Returns the namespaces in a store as an array of String.

    Returns:
      the namespaces or null if none are found

  - ### listRoles

    String[] listRoles()
    On-premises only.

    Returns the roles in a store as an array of String.

    Returns:
      the list of roles or null if none are found

  - ### listUsers

    UserInfo[] listUsers()
    On-premises only.

    Returns the users in a store as an array of `UserInfo`.

    Returns:
      the users or null if none are found

  - ### doSystemRequest

    SystemResult doSystemRequest(String statement, int timeoutMs, int pollIntervalMs)
    On-premises only.

    A convenience method that performs a SystemRequest and waits for completion of the operation. This is the same as calling `systemRequest(oracle.nosql.driver.ops.SystemRequest)` then calling `SystemResult.waitForCompletion(oracle.nosql.driver.NoSQLHandle, int, int)`. If the operation fails an exception is thrown. All parameters are required.

    System requests are those related to namespaces and security and are generally independent of specific tables. Examples of statements include:

    - CREATE NAMESPACE mynamespace
    - CREATE USER some_user IDENTIFIED BY password
    - CREATE ROLE some_role
    - GRANT ROLE some_role TO USER some_user
    Parameters:
      `statement` - the system statement for the operation.
      `timeoutMs` - the amount of time to wait for completion, in milliseconds.
      `pollIntervalMs` - the polling interval for the wait operation.
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `RequestTimeoutException` - if the operation times out.
      `NoSQLException` - if the operation cannot be performed for any other reason

  - ### addReplica

    TableResult addReplica(AddReplicaRequest request)
    Cloud service only.

    Add replica to a table.

    This operation is implicitly asynchronous. The caller must poll using methods on `TableResult` to determine when it has completed.

    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `NoSQLException` - if the operation cannot be performed for any other reason
    Since:
      5.4.13

  - ### dropReplica

    TableResult dropReplica(DropReplicaRequest request)
    Cloud service only.

    Drop replica from a table.

    This operation is implicitly asynchronous. The caller must poll using methods on `TableResult` to determine when it has completed.

    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `NoSQLException` - if the operation cannot be performed for any other reason
    Since:
      5.4.13

  - ### getReplicaStats

    ReplicaStatsResult getReplicaStats(ReplicaStatsRequest request)
    Cloud service only.

    Gets replica statistics information

    Parameters:
      `request` - the input parameters for the operation
    Returns:
      the result of the operation
    Throws:
      `IllegalArgumentException` - if any of the parameters are invalid or required parameters are missing
      `TableNotFoundException` - if the specified table does not exist
      `NoSQLException` - if the operation cannot be performed for any other reason
    Since:
      5.4.13

  - ### getStatsControl

    StatsControl getStatsControl()
    Returns an object that allows control over how SDK statistics are collected.
    Returns:
      the StatsControl object
    Since:
      5.2.30

  - ### close

    void close()
    Closes the handle, releasing its memory and network resources. Once this method is closed the handle is no longer usable. Any attempt to use a closed handle will throw `IllegalArgumentException`.
    Specified by:
      `close` in interface `AutoCloseable`