oracle.kv

## Class KVStoreConfig

- java.lang.Object
- - oracle.kv.KVStoreConfig

- All Implemented Interfaces:
    Serializable, Cloneable, KVSecurityConstants

      public class KVStoreConfig
      extends Object
      implements Serializable, Cloneable, KVSecurityConstants

  Represents the configuration parameters used to create a handle to an existing KV store.
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_LOB_TIMEOUT` The default timeout value (10000 ms) associated with internal LOB access during operations on LOBs.
    `static int` | `DEFAULT_OPEN_TIMEOUT` The default open timeout in ms associated with the sockets used to make KVStore requests.
    `static int` | `DEFAULT_READ_TIMEOUT` The default read timeout in ms associated with the sockets used to make KVStore requests.
    `static int` | `DEFAULT_REQUEST_TIMEOUT` The default timeout in ms associated with KVStore requests.

    - ### Fields inherited from interface oracle.kv.KVSecurityConstants

      `AUTH_PWDFILE_PROPERTY, AUTH_USERNAME_PROPERTY, AUTH_WALLET_PROPERTY, SECURITY_FILE_PROPERTY, SSL_CIPHER_SUITES_PROPERTY, SSL_HOSTNAME_VERIFIER_PROPERTY, SSL_PROTOCOLS_PROPERTY, SSL_TRANSPORT_NAME, SSL_TRUSTSTORE_FILE_PROPERTY, SSL_TRUSTSTORE_TYPE_PROPERTY, TRANSPORT_PROPERTY`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `KVStoreConfig(String storeName, String... helperHostPort)` Creates a config object with the minimum required properties.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `KVStoreConfig` | `clone()`
    `Consistency` | `getConsistency()` Returns the default read Consistency.
    `Durability` | `getDurability()` Returns the default write Durability.
    `String[]` | `getHelperHosts()` Returns the helper host/port pairs.
    `String` | `getLOBSuffix()` Returns the default suffix associated with LOB keys.
    `long` | `getLOBTimeout(TimeUnit unit)` Returns the default timeout value (in ms) associated with chunk access during operations on LOBs.
    `long` | `getLOBVerificationBytes()` Returns the number of trailing bytes of a partial LOB that must be verified against the user supplied LOB stream when resuming a LOB `put` operation.
    `long` | `getOpenTimeout(TimeUnit unit)` Deprecated. replaced by `getSocketOpenTimeout(java.util.concurrent.TimeUnit)`
    `String[]` | `getReadZones()` Returns the zones in which nodes must be located to be used for read operations, or `null` if read operations can be performed on nodes in any zone.
    `RequestLimitConfig` | `getRequestLimit()` Returns the configuration describing how the number of active requests to a node are limited.
    `long` | `getRequestTimeout(TimeUnit unit)` Returns the default request timeout.
    `long` | `getSocketOpenTimeout(TimeUnit unit)` Returns the socket open timeout.
    `long` | `getSocketReadTimeout(TimeUnit unit)` Returns the read timeout associated with the sockets used to make requests.
    `String` | `getStoreName()` Returns the store name.
    `KVStoreConfig` | `setConsistency(Consistency consistency)` Configures the default read Consistency to be used when a Consistency is not specified for a particular read operation.
    `KVStoreConfig` | `setDurability(Durability durability)` Configures the default write Durability to be used when a Durability is not specified for a particular write operation.
    `KVStoreConfig` | `setHelperHosts(String... helperHostPort)` Configures the helper host/port pairs.
    `KVStoreConfig` | `setLOBSuffix(String lobSuffix)` Configures the default suffix associated with LOB keys.
    `KVStoreConfig` | `setLOBTimeout(long timeout, TimeUnit unit)` Configures default timeout value associated with chunk access during operations on LOBs.
    `KVStoreConfig` | `setLOBVerificationBytes(long lobVerificationBytes)` Configures the number of trailing bytes of a partial LOB that must be verified against the user supplied LOB stream when resuming a `putLOB` operation.
    `KVStoreConfig` | `setOpenTimeout(long timeout, TimeUnit unit)` Deprecated. replaced by `setSocketOpenTimeout(long, java.util.concurrent.TimeUnit)`
    `KVStoreConfig` | `setReadZones(String... zones)` Sets the zones in which nodes must be located to be used for read operations.
    `KVStoreConfig` | `setRequestLimit(RequestLimitConfig requestLimitConfig)` Configures the maximum number of requests that can be active for a node in the KVStore.
    `KVStoreConfig` | `setRequestTimeout(long timeout, TimeUnit unit)` Configures the default request timeout.
    `KVStoreConfig` | `setSecurityProperties(Properties securityProps)` Configures security properties for the client.
    `KVStoreConfig` | `setSocketOpenTimeout(long timeout, TimeUnit unit)` Configures the open timeout used when establishing sockets used to make client requests.
    `KVStoreConfig` | `setSocketReadTimeout(long timeout, TimeUnit unit)` Configures the read timeout associated with the underlying sockets used to make client requests.
    `KVStoreConfig` | `setStoreName(String storeName)` Configures the store name.
    `String` | `toString()`

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

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

- - ### Field Detail

    - #### DEFAULT_REQUEST_TIMEOUT

          public static final int DEFAULT_REQUEST_TIMEOUT

      The default timeout in ms associated with KVStore requests.
      See Also:
        Constant Field Values

    - #### DEFAULT_OPEN_TIMEOUT

          public static final int DEFAULT_OPEN_TIMEOUT

      The default open timeout in ms associated with the sockets used to make KVStore requests.
      See Also:
        Constant Field Values

    - #### DEFAULT_READ_TIMEOUT

          public static final int DEFAULT_READ_TIMEOUT

      The default read timeout in ms associated with the sockets used to make KVStore requests.

      The default read timeout value must be larger than `DEFAULT_REQUEST_TIMEOUT` to ensure that read requests are not timed out by the socket.

      See Also:
        Constant Field Values

    - #### DEFAULT_LOB_TIMEOUT

          public static final int DEFAULT_LOB_TIMEOUT

      The default timeout value (10000 ms) associated with internal LOB access during operations on LOBs.
      Since:
        2.0
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### KVStoreConfig

          public KVStoreConfig(String storeName,
                       String... helperHostPort)
                        throws IllegalArgumentException

      Creates a config object with the minimum required properties.
      Parameters:
        `storeName` - the name of the KVStore. The store name is used to guard against accidental use of the wrong host or port. The store name must consist entirely of upper or lowercase, letters and digits.
        `helperHostPort` - one or more strings containing the host and port of an active node in the KVStore. Each string has the format: hostname:port. It is good practice to pass multiple hosts so that if one host is down, the system will attempt to open the next one, and so on.
      Throws:
        `IllegalArgumentException` - if an argument has an illegal value. This may be thrown if the "oracle.kv.security" property is set and an error occurs while attempting to read that file.

  - ### Method Detail

    - #### clone

          public KVStoreConfig clone()

      Overrides:
        `clone` in class `Object`

    - #### setStoreName

          public KVStoreConfig setStoreName(String storeName)
                                     throws IllegalArgumentException

      Configures the store name.
      Parameters:
        `storeName` - the name of the KVStore. The store name is used to guard against accidental use of the wrong host or port. The store name must consist entirely of upper or lowercase, letters and digits.
      Returns:
        this
      Throws:
        `IllegalArgumentException`

    - #### getStoreName

          public String getStoreName()

      Returns the store name.

      If it is not overridden by calling `setStoreName(java.lang.String)`, the default value is the one specified to the `KVStoreConfig` constructor.

      Returns:
        the store name.

    - #### setHelperHosts

          public KVStoreConfig setHelperHosts(String... helperHostPort)
                                       throws IllegalArgumentException

      Configures the helper host/port pairs.
      Parameters:
        `helperHostPort` - one or more strings containing the host and port of an active node in the KVStore. Each string has the format: hostname:port. It is good practice to pass multiple hosts so that if one host is down, the system will attempt to open the next one, and so on.
      Returns:
        this
      Throws:
        `IllegalArgumentException` - if no helperHostPort is specified.

    - #### getHelperHosts

          public String[] getHelperHosts()

      Returns the helper host/port pairs.

      If it is not overridden by calling `setHelperHosts(java.lang.String...)`, the default value is the one specified to the `KVStoreConfig` constructor.

      Returns:
        the helper hosts.

    - #### setSocketOpenTimeout

          public KVStoreConfig setSocketOpenTimeout(long timeout,
                                           TimeUnit unit)
                                             throws IllegalArgumentException

      Configures the open timeout used when establishing sockets used to make client requests. Shorter timeouts result in more rapid failure detection and recovery. The default open timeout (5000 milliseconds) should be adequate for most applications.

      The client does not directly open sockets when making requests. KVStore manages the network connections used to make client requests opening and closing connections as needed.

      Please note that the socket timeout applies to any duplicate KVStore handles to the same KVStore within this process.

      Parameters:
        `timeout` - the socket open timeout.
        `unit` - the `TimeUnit` of the timeout value.
      Returns:
        this
      Throws:
        `IllegalArgumentException` - if the timeout value is negative or zero.
      Since:
        2.0
      See Also:
        `DEFAULT_OPEN_TIMEOUT`

    - #### setOpenTimeout

          @Deprecated
          public KVStoreConfig setOpenTimeout(long timeout,
                                                TimeUnit unit)
                                       throws IllegalArgumentException

      Deprecated. replaced by `setSocketOpenTimeout(long, java.util.concurrent.TimeUnit)`
      Throws:
        `IllegalArgumentException`

    - #### getSocketOpenTimeout

          public long getSocketOpenTimeout(TimeUnit unit)

      Returns the socket open timeout.

      If it is not overridden by calling `setOpenTimeout(long, java.util.concurrent.TimeUnit)`, the default value is 5000 milliseconds.

      Parameters:
        `unit` - the `TimeUnit` of the returned value. May not be null.
      Returns:
        The socket open timeout.
      Since:
        2.0

    - #### getOpenTimeout

          @Deprecated
          public long getOpenTimeout(TimeUnit unit)

      Deprecated. replaced by `getSocketOpenTimeout(java.util.concurrent.TimeUnit)`

    - #### setSocketReadTimeout

          public KVStoreConfig setSocketReadTimeout(long timeout,
                                           TimeUnit unit)
                                             throws IllegalArgumentException

      Configures the read timeout associated with the underlying sockets used to make client requests. Shorter timeouts result in more rapid failure detection and recovery. However, this timeout should be sufficiently long so as to allow for the longest timeout associated with a request.

      The client does not directly manage sockets when making requests. KVStore manages the network connections used to make client requests opening and closing connections as needed.

      Please note that the socket timeout applies to any duplicate KVStore handles to the same KVStore within this process.

      Parameters:
        `timeout` - the socket read timeout
        `unit` - the `TimeUnit` of the timeout value
      Returns:
        this
      Throws:
        `IllegalArgumentException` - if the timeout is invalid
      Since:
        2.0

    - #### getSocketReadTimeout

          public long getSocketReadTimeout(TimeUnit unit)

      Returns the read timeout associated with the sockets used to make requests.

      If it is not overridden by calling `setSocketReadTimeout(long, java.util.concurrent.TimeUnit)`, the default value is 30000 milliseconds.

      Parameters:
        `unit` - the `TimeUnit` of the returned value. May not be null.
      Returns:
        The socket read timeout
      Since:
        2.0

    - #### setRequestTimeout

          public KVStoreConfig setRequestTimeout(long timeout,
                                        TimeUnit unit)
                                          throws IllegalArgumentException

      Configures the default request timeout.
      Parameters:
        `timeout` - the default request timeout.
        `unit` - the `TimeUnit` of the timeout value.
      Returns:
        this
      Throws:
        `IllegalArgumentException` - if the timeout value is negative or zero.

    - #### getRequestTimeout

          public long getRequestTimeout(TimeUnit unit)

      Returns the default request timeout.

      If it is not overridden by calling `setRequestTimeout(long, java.util.concurrent.TimeUnit)`, the default value is `DEFAULT_REQUEST_TIMEOUT`.

      Parameters:
        `unit` - the `TimeUnit` of the returned value. May not be null.
      Returns:
        The transaction timeout.

    - #### setConsistency

          public KVStoreConfig setConsistency(Consistency consistency)
                                       throws IllegalArgumentException

      Configures the default read Consistency to be used when a Consistency is not specified for a particular read operation.
      Parameters:
        `consistency` - the default read Consistency.
      Returns:
        this
      Throws:
        `IllegalArgumentException`

    - #### getConsistency

          public Consistency getConsistency()

      Returns the default read Consistency.

      If it is not overridden by calling `setConsistency(oracle.kv.Consistency)`, the default value is `Consistency.NONE_REQUIRED`.

      Returns:
        the default read Consistency.

    - #### setDurability

          public KVStoreConfig setDurability(Durability durability)
                                      throws IllegalArgumentException

      Configures the default write Durability to be used when a Durability is not specified for a particular write operation.
      Parameters:
        `durability` - the default write Durability.
      Returns:
        this
      Throws:
        `IllegalArgumentException`

    - #### getDurability

          public Durability getDurability()

      Returns the default write Durability.

      If it is not overridden by calling `setDurability(oracle.kv.Durability)`, the default value is `Durability.COMMIT_NO_SYNC`.

      Returns:
        the default write Durability.

    - #### setRequestLimit

          public KVStoreConfig setRequestLimit(RequestLimitConfig requestLimitConfig)

      Configures the maximum number of requests that can be active for a node in the KVStore. Limiting requests in this way helps minimize the possibility of thread starvation in situations where one or more nodes in the KVStore exhibits long service times and as a result retains threads, making them unavailable to service requests to other reachable and healthy nodes.

      The long service times can be due to problems at the node itself, or in the network path to that node. The KVStore request dispatcher will, whenever possible, minimize use of nodes with long service times automatically, by re-routing requests to other nodes that can handle them. So this mechanism provides an additional margin of safety when such re-routing of requests is not possible.

      Returns:
        this

    - #### getRequestLimit

          public RequestLimitConfig getRequestLimit()

      Returns the configuration describing how the number of active requests to a node are limited.

      It returns the default value, documented in `RequestLimitConfig`, if it was not overridden by calling `setRequestLimit(oracle.kv.RequestLimitConfig)`.

      Returns:
        this

    - #### getLOBTimeout

          public long getLOBTimeout(TimeUnit unit)

      Returns the default timeout value (in ms) associated with chunk access during operations on LOBs.
      Since:
        2.0
      See Also:
        `KVLargeObject.getLOB(oracle.kv.Key, oracle.kv.Consistency, long, java.util.concurrent.TimeUnit)`, `KVLargeObject.putLOB(oracle.kv.Key, java.io.InputStream, oracle.kv.Durability, long, java.util.concurrent.TimeUnit)`

    - #### setLOBTimeout

          public KVStoreConfig setLOBTimeout(long timeout,
                                    TimeUnit unit)

      Configures default timeout value associated with chunk access during operations on LOBs.
      Parameters:
        `timeout` - the open timeout.
        `unit` - the `TimeUnit` of the timeout value.
      Returns:
        this
      Since:
        2.0
      See Also:
        `KVLargeObject.getLOB(oracle.kv.Key, oracle.kv.Consistency, long, java.util.concurrent.TimeUnit)`, `KVLargeObject.putLOB(oracle.kv.Key, java.io.InputStream, oracle.kv.Durability, long, java.util.concurrent.TimeUnit)`

    - #### getLOBSuffix

          public String getLOBSuffix()

      Returns the default suffix associated with LOB keys.
      Since:
        2.0
      See Also:
        `KVLargeObject`

    - #### setLOBSuffix

          public KVStoreConfig setLOBSuffix(String lobSuffix)

      Configures the default suffix associated with LOB keys. The application must ensure that the suffix is used consistently across all KVStore handles. The suffix is used by the KVStore APIs to ensure that any value-changing non-LOB APIs are not invoked on LOB objects and vice versa. Failure to use the LOB suffix consistently can result in `IllegalArgumentException` being thrown if a LOB object is created with one LOB suffix and is subsequently accessed when a different suffix is in effect. Write operations using inconsistent LOB suffixes may result in LOB storage not being reclaimed.

      This method should only be used in the rare case that the default LOB suffix value ".lob" is unsuitable.

      Parameters:
        `lobSuffix` - the LOB suffix string. It must be non-null and have a length > 0.
      Returns:
        this
      Since:
        2.0
      See Also:
        `KVLargeObject`

    - #### getLOBVerificationBytes

          public long getLOBVerificationBytes()

      Returns the number of trailing bytes of a partial LOB that must be verified against the user supplied LOB stream when resuming a LOB `put` operation.
      Since:
        2.0
      See Also:
        `KVLargeObject`

    - #### setLOBVerificationBytes

          public KVStoreConfig setLOBVerificationBytes(long lobVerificationBytes)

      Configures the number of trailing bytes of a partial LOB that must be verified against the user supplied LOB stream when resuming a `putLOB` operation.
      Parameters:
        `lobVerificationBytes` - the number of bytes to be verified. A value <=0 disables verification.
      Returns:
        this
      Since:
        2.0
      See Also:
        `KVLargeObject`

    - #### getReadZones

          public String[] getReadZones()

      Returns the zones in which nodes must be located to be used for read operations, or `null` if read operations can be performed on nodes in any zone.
      Returns:
        the zones or `null`
      Since:
        3.0

    - #### setReadZones

          public KVStoreConfig setReadZones(String... zones)

      Sets the zones in which nodes must be located to be used for read operations. If the argument is `null`, or this method has not been called, then read operations can be performed on nodes in any zone.

      The specified zones must exist at the time that this configuration object is used to create a store, or else `KVStoreFactory.getStore(oracle.kv.KVStoreConfig)` will throw an `IllegalArgumentException`.

      Zones specified for read operations can include primary and secondary zones. If the master is not located in any of the specified zones, either because the zones are all secondary zones or because the master node is not currently in one of the specified primary zones, then read operations with `Consistency.ABSOLUTE` will fail.

      Parameters:
        `zones` - the zones or `null`
      Returns:
        this
      Throws:
        `IllegalArgumentException` - if the array argument is not `null` and is either empty or contains `null` or duplicate elements
      Since:
        3.0

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### setSecurityProperties

          public KVStoreConfig setSecurityProperties(Properties securityProps)

      Configures security properties for the client. The supported properties include both authentication properties and transport properties. See `KVSecurityConstants` for the supported properties.
      Returns:
        this

Copyright (c) 2011, 2014 Oracle and/or its affiliates. All rights reserved.