Package oracle.nosql.driver

## Class NoSQLHandleConfig

- java.lang.Object
- - oracle.nosql.driver.NoSQLHandleConfig

- All Implemented Interfaces:
    `Cloneable`

      public class NoSQLHandleConfig
      extends Object
      implements Cloneable

  NoSQLHandleConfig groups parameters used to configure a `NoSQLHandle`. It also provides a way to default common parameters for use by `NoSQLHandle` methods. When creating a `NoSQLHandle` the NoSQLHandleConfig instance is copied so modification operations on the instance have no effect on existing handles which are immutable. Handle state with default values can be overridden in individual operations.

  Most of the configuration parameters are optional and have default values if not specified. The only required configuration is the service endpoint required by the constructor.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `NoSQLHandleConfig​(String endpoint)` | Specifies an endpoint or region id to use to connect to the Oracle NoSQL Database Cloud Service or, if on-premise, the Oracle NoSQL Database proxy server.
    `NoSQLHandleConfig​(String endpoint, AuthorizationProvider provider)` | Specifies an endpoint or region id to use to connect to the Oracle NoSQL Database Cloud Service or, if on-premise, the Oracle NoSQL Database proxy server.
    `NoSQLHandleConfig​(URL serviceURL)` | Sets the URL to use to connect to the service, as alternative to setting the endpont.
    `NoSQLHandleConfig​(AuthorizationProvider provider)` | Cloud service only.
    `NoSQLHandleConfig​(Region region, AuthorizationProvider provider)` | Cloud service only.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `NoSQLHandleConfig` | `clone()` |
    `NoSQLHandleConfig` | `configureDefaultRetryHandler​(int numRetries, int delayMS)` | Sets the `RetryHandler` using a default retry handler configured with the specified number of retries and a static delay.
    `AuthorizationProvider` | `getAuthorizationProvider()` | Returns the `AuthorizationProvider` configured for the handle, or null if none is set.
    `int` | `getConnectionPoolSize()` | Returns the maximum number of individual connections to use to connect to the service.
    `Consistency` | `getConsistency()` | Returns the configured default consistency
    `String` | `getDefaultCompartment()` | Cloud service only.
    `Consistency` | `getDefaultConsistency()` | Returns the default Consistency value that will be used by the system.
    `int` | `getDefaultRequestTimeout()` | Returns the default value for request timeout.
    `int` | `getDefaultTableRequestTimeout()` | Returns the default value for a table request timeout.
    `static String` | `getLibraryVersion()` | Returns the version of the driver implemented by this library.
    `Logger` | `getLogger()` | Returns the Logger, or null if not configured by user.
    `int` | `getMaxContentLength()` | Returns the maximum size, in bytes, of a request operation payload.
    `int` | `getNumThreads()` | Returns the number of threads to use for handling network traffic.
    `int` | `getPoolMaxPending()` | Returns the maximum number of pending acquire operations allowed on the connection pool.
    `Region` | `getRegion()` | Cloud service only.
    `int` | `getRequestTimeout()` | Returns the configured request timeout value, in milliseconds.
    `RetryHandler` | `getRetryHandler()` | Returns the `RetryHandler` configured for the handle, or null if none is set.
    `URL` | `getServiceURL()` | Returns the URL to use for the `NoSQLHandle` connection
    `List<String>` | `getSSLCipherSuites()` | Returns the SSL cipher suites to enable.
    `String[]` | `getSSLProtocols()` | Returns the SSL protocols to enable.
    `int` | `getSSLSessionCacheSize()` | Returns the configured size of cache used to store SSLSession objects.
    `int` | `getSSLSessionTimeout()` | Returns the configured SSLSession objects timeout, in seconds.
    `int` | `getTableRequestTimeout()` | Returns the configured table request timeout value, in milliseconds.
    `NoSQLHandleConfig` | `setAuthorizationProvider​(AuthorizationProvider provider)` | Sets the `AuthorizationProvider` to use for the handle.
    `NoSQLHandleConfig` | `setConnectionPoolSize​(int poolSize)` | Sets the maximum number of individual connections to use to connect to the service.
    `NoSQLHandleConfig` | `setConsistency​(Consistency consistency)` | Sets the default request `Consistency`.
    `NoSQLHandleConfig` | `setDefaultCompartment​(String compartment)` | Cloud service only.
    `void` | `setDefaultRateLimitingPercentage​(double percent)` | Sets a default rate limiter use percentage.
    `NoSQLHandleConfig` | `setLogger​(Logger logger)` | Sets the Logger used for the driver.
    `NoSQLHandleConfig` | `setMaxContentLength​(int maxContentLength)` | Sets the maximum size in bytes of request/response payloads.
    `NoSQLHandleConfig` | `setNumThreads​(int numThreads)` | Sets the number of threads to use for handling network traffic.
    `NoSQLHandleConfig` | `setPoolMaxPending​(int poolMaxPending)` | Sets the maximum number of pending acquire operations allowed on the connection pool.
    `NoSQLHandleConfig` | `setProxyHost​(String proxyHost)` | Sets an HTTP proxy host to be used for the session.
    `NoSQLHandleConfig` | `setProxyPassword​(String proxyPassword)` | Sets an HTTP proxy password if the configured proxy host requires authentication.
    `NoSQLHandleConfig` | `setProxyPort​(int proxyPort)` | Sets an HTTP proxy port to be used for the session.
    `NoSQLHandleConfig` | `setProxyUsername​(String proxyUsername)` | Sets an HTTP proxy user name if the configured proxy host requires authentication.
    `NoSQLHandleConfig` | `setRateLimitingEnabled​(boolean enable)` | Enables internal rate limiting.
    `NoSQLHandleConfig` | `setRequestTimeout​(int timeout)` | Sets the default request timeout.
    `NoSQLHandleConfig` | `setRetryHandler​(RetryHandler retryHandler)` | Sets the `RetryHandler` to use for the handle.
    `NoSQLHandleConfig` | `setSSLCipherSuites​(String... cipherSuites)` | Set SSL cipher suites to enable, in the order of preference.
    `NoSQLHandleConfig` | `setSSLProtocols​(String... sslProtocols)` | Set SSL protocols to enable, in the order of preference.
    `NoSQLHandleConfig` | `setSSLSessionCacheSize​(int cacheSize)` | Sets the size of the cache used for storing SSL session objects, 0 to use the default value, no size limit.
    `NoSQLHandleConfig` | `setSSLSessionTimeout​(int timeout)` | Set the timeout for the cached SSL session objects, in seconds.
    `NoSQLHandleConfig` | `setTableRequestTimeout​(int tableRequestTimeout)` | Sets the default table request timeout.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### NoSQLHandleConfig

          public NoSQLHandleConfig​(String endpoint)

      Specifies an endpoint or region id to use to connect to the Oracle NoSQL Database Cloud Service or, if on-premise, the Oracle NoSQL Database proxy server.

      There is flexibility in how endpoints are specified. A fully specified endpoint is of the format:

              http[s]://host:port

      This interface accepts portions of a fully specified endpoint, including a region id (see `Region`) string if using the Cloud service.

      A valid endpoint is one of these:

      1. region id string (cloud service only)
      2. a string with the syntax [http[s]://]host[:port]

      For example, these are valid endpoint arguments:

      - us-ashburn-1
      - nosql.us-ashburn-1.oci.oraclecloud.com
      - https://nosql.us-ashburn-1.oci.oraclecloud.com:443
      - localhost:8080
      - https://machine-hosting-proxy:443

      If using the endpoint (vs region id) syntax, if the port is omitted, the endpoint defaults to 443. If the protocol is omitted, the endpoint uses https if the port is 443, and http in all other cases.

      If using the Cloud Service see `Region` for information on available regions. If using the Cloud Service the constructor, `NoSQLHandleConfig(Region,AuthorizationProvider)`, is available rather than using a Region's id string.

      Parameters:
        `endpoint` - identifies a region id or server for use by the NoSQLHandle. This is a required parameter.
      Throws:
        `IllegalArgumentException` - if the endpoint is null or malformed.

    - #### NoSQLHandleConfig

          public NoSQLHandleConfig​(String endpoint,
                                   AuthorizationProvider provider)

      Specifies an endpoint or region id to use to connect to the Oracle NoSQL Database Cloud Service or, if on-premise, the Oracle NoSQL Database proxy server. In addition an `AuthorizationProvider` is specified.

      There is flexibility in how endpoints are specified. A fully specified endpoint is of the format:

              http[s]://host:port

      This interface accepts portions of a fully specified endpoint, including a region id (see `Region`) string if using the Cloud service.

      A valid endpoint is one of these:

      1. region id string (cloud service only)
      2. a string with the syntax [http[s]://]host[:port]

      For example, these are valid endpoint arguments:

      - us-ashburn-1
      - nosql.us-ashburn-1.oci.oraclecloud.com
      - https://nosql.us-ashburn-1.oci.oraclecloud.com:443
      - localhost:8080
      - https://machine-hosting-proxy:443

      If using the endpoint (vs region id) syntax, if the port is omitted, the endpoint defaults to 443. If the protocol is omitted, the endpoint uses https if the port is 443, and http in all other cases.

      If using the Cloud Service see `Region` for information on available regions. If using the Cloud Service the constructor, `NoSQLHandleConfig(Region,AuthorizationProvider)`, is available rather than using a Region's id string.

      Parameters:
        `endpoint` - identifies a region id or server for use by the NoSQLHandle. This is a required parameter.
        `provider` - the `AuthorizationProvider` to use for the handle
      Throws:
        `IllegalArgumentException` - if the endpoint is null or malformed.

    - #### NoSQLHandleConfig

          public NoSQLHandleConfig​(Region region,
                                   AuthorizationProvider provider)

      Cloud service only.

      Specify a region to use to connect to the Oracle NoSQL Database Cloud Service. The service endpoint will be inferred from the given region. This is the recommended constructor for applications using the Oracle NoSQL Database Cloud Service.

      Parameters:
        `region` - identifies the region will be accessed by the NoSQLHandle.
        `provider` - the `AuthorizationProvider` to use for the handle
      Throws:
        `IllegalArgumentException` - if the region is null or malformed.

    - #### NoSQLHandleConfig

          public NoSQLHandleConfig​(AuthorizationProvider provider)

      Cloud service only.

      Specify a `AuthorizationProvider` to use to connect to the Oracle NoSQL Database Cloud Service. The service endpoint will be inferred from the given provider. This is the recommended constructor for applications using the Oracle NoSQL Database Cloud Service.

      Parameters:
        `provider` - the `AuthorizationProvider` to use for the handle
      Throws:
        `IllegalArgumentException` - if the region is null or malformed.

    - #### NoSQLHandleConfig

          public NoSQLHandleConfig​(URL serviceURL)

      Sets the URL to use to connect to the service, as alternative to setting the endpont.
      Parameters:
        `serviceURL` - a URL to locate a server for use by the NoSQLHandle. It is used and validated in `NoSQLHandleFactory.createNoSQLHandle(oracle.nosql.driver.NoSQLHandleConfig)`. This is a required parameter.
      Throws:
        `IllegalArgumentException` - if the URL is null or malformed.

  - ### Method Detail

    - #### getLibraryVersion

          public static String getLibraryVersion()

      Returns the version of the driver implemented by this library.
      Returns:
        the version as a string

    - #### getServiceURL

          public URL getServiceURL()

      Returns the URL to use for the `NoSQLHandle` connection
      Returns:
        the URL.

    - #### getRegion

          public Region getRegion()

      Cloud service only.

      Returns the region will be accessed by the NoSQLHandle.

      Returns:
        the region.

    - #### getRequestTimeout

          public int getRequestTimeout()

      Returns the configured request timeout value, in milliseconds.
      Returns:
        the timeout, in milliseconds, or 0 if it has not been set

    - #### getDefaultRequestTimeout

          public int getDefaultRequestTimeout()

      Returns the default value for request timeout. If there is no configured timeout or it is configured as 0, a "default" default value of 5000 milliseconds is used.
      Returns:
        the default timeout, in milliseconds

    - #### getTableRequestTimeout

          public int getTableRequestTimeout()

      Returns the configured table request timeout value, in milliseconds. The table request timeout default can be specified independently to allow it to be larger than a typical data request. If it is not specified the default table request timeout of 10000 is used.
      Returns:
        the timeout, in milliseconds, or 0 if it has not been set

    - #### getDefaultTableRequestTimeout

          public int getDefaultTableRequestTimeout()

      Returns the default value for a table request timeout. If there is no configured timeout or it is configured as 0, a "default" default value of 10000 milliseconds is used.
      Returns:
        the default timeout, in milliseconds

    - #### getConsistency

          public Consistency getConsistency()

      Returns the configured default consistency
      Returns:
        the Consistency, or null if it has not been configured

    - #### getDefaultConsistency

          public Consistency getDefaultConsistency()

      Returns the default Consistency value that will be used by the system. If Consistency has been set using `setConsistency(oracle.nosql.driver.Consistency)` that will be returned. If not a default value of `Consistency.EVENTUAL` is returned
      Returns:
        the default Consistency

    - #### getRetryHandler

          public RetryHandler getRetryHandler()

      Returns the `RetryHandler` configured for the handle, or null if none is set.
      Returns:
        the handler

    - #### getAuthorizationProvider

          public AuthorizationProvider getAuthorizationProvider()

      Returns the `AuthorizationProvider` configured for the handle, or null if none is set.
      Returns:
        the AuthorizationProvider

    - #### setRequestTimeout

          public NoSQLHandleConfig setRequestTimeout​(int timeout)

      Sets the default request timeout. The default timeout is 5 seconds.
      Parameters:
        `timeout` - the timeout value, in milliseconds
      Returns:
        this

    - #### setTableRequestTimeout

          public NoSQLHandleConfig setTableRequestTimeout​(int tableRequestTimeout)

      Sets the default table request timeout. The table request timeout can be specified independently of that specified by `setRequestTimeout(int)` because table requests can take longer and justify longer timeouts. The default timeout is 10 seconds (10000 milliseconds).
      Parameters:
        `tableRequestTimeout` - the timeout value, in milliseconds
      Returns:
        this

    - #### setConsistency

          public NoSQLHandleConfig setConsistency​(Consistency consistency)

      Sets the default request `Consistency`. If not set in this object or by a specific request the default consistency used is `Consistency.EVENTUAL`
      Parameters:
        `consistency` - the Consistency
      Returns:
        this

    - #### setNumThreads

          public NoSQLHandleConfig setNumThreads​(int numThreads)

      Sets the number of threads to use for handling network traffic. This number affects the performance of concurrent requests in a multithreaded application.
      Parameters:
        `numThreads` - the number
      Returns:
        this

    - #### setConnectionPoolSize

          public NoSQLHandleConfig setConnectionPoolSize​(int poolSize)

      Sets the maximum number of individual connections to use to connect to the service. Each request/response pair uses a connection. The pool exists to allow concurrent requests and will bound the number of concurrent requests. Additional requests will wait for a connection to become available.
      Parameters:
        `poolSize` - the pool size
      Returns:
        this

    - #### setPoolMaxPending

          public NoSQLHandleConfig setPoolMaxPending​(int poolMaxPending)

      Sets the maximum number of pending acquire operations allowed on the connection pool. This number is used if the degree of concurrency desired exceeds the size of the connection pool temporarily.
      Parameters:
        `poolMaxPending` - the maximum number allowed
      Returns:
        this

    - #### setMaxContentLength

          public NoSQLHandleConfig setMaxContentLength​(int maxContentLength)

      Sets the maximum size in bytes of request/response payloads. On-premise only. This setting is ignored for cloud operations. If not set, or set to zero, the default value of 32MB is used.
      Parameters:
        `maxContentLength` - the maximum bytes allowed in requests/responses. Pass zero to use the default.
      Returns:
        this

    - #### getMaxContentLength

          public int getMaxContentLength()

      Returns the maximum size, in bytes, of a request operation payload. On-premise only. This value is ignored for cloud operations.
      Returns:
        the size

    - #### getConnectionPoolSize

          public int getConnectionPoolSize()

      Returns the maximum number of individual connections to use to connect to the service. Each request/response pair uses a connection. The pool exists to allow concurrent requests and will bound the number of concurrent requests. Additional requests will wait for a connection to become available.
      Returns:
        the pool size

    - #### getPoolMaxPending

          public int getPoolMaxPending()

      Returns the maximum number of pending acquire operations allowed on the connection pool.
      Returns:
        the maximum pending acquire size

    - #### getNumThreads

          public int getNumThreads()

      Returns the number of threads to use for handling network traffic.
      Returns:
        the pool size

    - #### setRetryHandler

          public NoSQLHandleConfig setRetryHandler​(RetryHandler retryHandler)

      Sets the `RetryHandler` to use for the handle. If no handler is configured a default is used. The handler must be safely usable by multiple threads.
      Parameters:
        `retryHandler` - the handler
      Returns:
        this

    - #### setAuthorizationProvider

          public NoSQLHandleConfig setAuthorizationProvider​(AuthorizationProvider provider)

      Sets the `AuthorizationProvider` to use for the handle. The provider must be safely usable by multiple threads.
      Parameters:
        `provider` - the AuthorizationProvider
      Returns:
        this

    - #### setRateLimitingEnabled

          public NoSQLHandleConfig setRateLimitingEnabled​(boolean enable)

      Enables internal rate limiting. Cloud service only.
      Parameters:
        `enable` - If true, enable internal rate limiting. If false, disable internal rate limiting.
      Returns:
        this

    - #### setDefaultRateLimitingPercentage

          public void setDefaultRateLimitingPercentage​(double percent)

      Sets a default rate limiter use percentage. Cloud service only.

      Sets a default percentage of table limits to use. This may be useful for cases where a client should only use a portion of full table limits. This only applies if rate limiting is enabled using `setRateLimitingEnabled(boolean)`.

      The default for this value is 100.0 (full table limits).

      Parameters:
        `percent` - the percentage of table limits to use. This value must be positive.

    - #### configureDefaultRetryHandler

          public NoSQLHandleConfig configureDefaultRetryHandler​(int numRetries,
                                                                int delayMS)

      Sets the `RetryHandler` using a default retry handler configured with the specified number of retries and a static delay. A delay of 0 means "use the default delay algorithm" which is an incremental backoff algorithm. A non-zero delay will work but is not recommended for production systems as it is not flexible.

      The default retry handler will not retry exceptions of type `OperationThrottlingException`. The reason is that these operations are long-running, and while technically they can be retried, an immediate retry is unlikely to succeed because of the low rates allowed for these operations.

      Parameters:
        `numRetries` - the number of retries to perform automatically. This parameter may be 0 for no retries.
        `delayMS` - the delay, in milliseconds. Pass 0 to use the default delay algorithm.
      Returns:
        this

    - #### setLogger

          public NoSQLHandleConfig setLogger​(Logger logger)

      Sets the Logger used for the driver.
      Parameters:
        `logger` - the Logger.
      Returns:
        this

    - #### getLogger

          public Logger getLogger()

      Returns the Logger, or null if not configured by user.
      Returns:
        the Logger

    - #### setDefaultCompartment

          public NoSQLHandleConfig setDefaultCompartment​(String compartment)

      Cloud service only. Sets the default compartment to use for requests sent using the handle. Setting the default is optional and if set it is overridden by any compartment specified in a request or table name. If no compartment is set for a request, either using this default or by specification in a request, the behavior varies with how the application is authenticated.
      - If authenticated with a user identity the default is the root compartment of the tenancy
      - If authenticated as an instance principal (see `SignatureProvider.createWithInstancePrincipal()`) the compartment id (OCID )must be specified by either using this method or in each Request object. If not an exception is thrown
      Parameters:
        `compartment` - may be either the name of a compartment or the id (OCID) of a compartment.
      Returns:
        this

    - #### getDefaultCompartment

          public String getDefaultCompartment()

      Cloud service only. Returns the default compartment to use for requests or null if not set. The value may be a compartment name or id, as set by `setDefaultCompartment(java.lang.String)`.
      Returns:
        the compartment

    - #### getSSLCipherSuites

          public List<String> getSSLCipherSuites()

      Returns the SSL cipher suites to enable.
      Returns:
        cipher suites.

    - #### getSSLProtocols

          public String[] getSSLProtocols()

      Returns the SSL protocols to enable.
      Returns:
        cipher suites.

    - #### getSSLSessionTimeout

          public int getSSLSessionTimeout()

      Returns the configured SSLSession objects timeout, in seconds.
      Returns:
        the timeout, in seconds, or 0 if it has not been set

    - #### getSSLSessionCacheSize

          public int getSSLSessionCacheSize()

      Returns the configured size of cache used to store SSLSession objects.
      Returns:
        the cache size

    - #### setSSLCipherSuites

          public NoSQLHandleConfig setSSLCipherSuites​(String... cipherSuites)

      Set SSL cipher suites to enable, in the order of preference. null to use default cipher suites.
      Parameters:
        `cipherSuites` - cipher suites list
      Returns:
        this

    - #### setSSLProtocols

          public NoSQLHandleConfig setSSLProtocols​(String... sslProtocols)

      Set SSL protocols to enable, in the order of preference. null to use default protocols.
      Parameters:
        `sslProtocols` - SSL protocols list
      Returns:
        this

    - #### setSSLSessionCacheSize

          public NoSQLHandleConfig setSSLSessionCacheSize​(int cacheSize)

      Sets the size of the cache used for storing SSL session objects, 0 to use the default value, no size limit.
      Parameters:
        `cacheSize` - the size of SSLSession objects.
      Returns:
        this

    - #### setSSLSessionTimeout

          public NoSQLHandleConfig setSSLSessionTimeout​(int timeout)

      Set the timeout for the cached SSL session objects, in seconds. 0 to use the default value, no limit. When the timeout limit is exceeded for a session, the SSLSession object is invalidated and future connections cannot resume or rejoin the session.
      Parameters:
        `timeout` - the session timeout
      Returns:
        this

    - #### setProxyHost

          public NoSQLHandleConfig setProxyHost​(String proxyHost)

      Sets an HTTP proxy host to be used for the session. If a proxy host is specified a proxy port must also be specified, using `setProxyPort(int)`.
      Parameters:
        `proxyHost` - the proxy host
      Returns:
        this

    - #### setProxyUsername

          public NoSQLHandleConfig setProxyUsername​(String proxyUsername)

      Sets an HTTP proxy user name if the configured proxy host requires authentication. If a proxy host is not configured this configuration is ignored. If a proxy user name is configure a proxy password must also be configured, using `setProxyPassword(java.lang.String)`.
      Parameters:
        `proxyUsername` - the user name
      Returns:
        this

    - #### setProxyPassword

          public NoSQLHandleConfig setProxyPassword​(String proxyPassword)

      Sets an HTTP proxy password if the configured proxy host requires authentication. If a proxy password is configured a proxy user name must also be configured using `setProxyUsername(java.lang.String)`.
      Parameters:
        `proxyPassword` - the password
      Returns:
        this

    - #### setProxyPort

          public NoSQLHandleConfig setProxyPort​(int proxyPort)

      Sets an HTTP proxy port to be used for the session. If a proxy port is specified a proxy host must also be specified, using `setProxyHost(java.lang.String)`.
      Parameters:
        `proxyPort` - the proxy port
      Returns:
        this

    - #### clone

          public NoSQLHandleConfig clone()