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 Description static int
DEFAULT_LOB_TIMEOUT
The default timeout value (10000 ms) associated with internal LOB access during operations on LOBs.static int
DEFAULT_NETWORK_ROUNDTRIP_TIMEOUT
The default value in milliseconds for the amount of time to allow for a single roundtrip network communication with the server.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_REGISTRY_OPEN_TIMEOUT
The default open timeout in ms associated with the sockets used to make registry requests.static int
DEFAULT_REGISTRY_READ_TIMEOUT
The default read timeout associated with the sockets used to make registry requests.static int
DEFAULT_REQUEST_TIMEOUT
The default timeout in ms associated with KVStore requests.static int
DEFAULT_SG_CACHED_ATTRS_TIMEOUT
Default value for the timeout of cached sequence generator attributes in milliseconds.static boolean
DEFAULT_USE_ASYNC
Whether to use the async network protocol by default.static String
USE_ASYNC
The name of the system property that controls whether to use the async network protocol by default.-
Fields inherited from interface oracle.kv.KVSecurityConstants
AUTH_EXT_MECH_PROPERTY, AUTH_KRB_CCACHE_PROPERTY, AUTH_KRB_KEYTAB_PROPERTY, AUTH_KRB_MUTUAL_PROPERTY, AUTH_KRB_REALM_PROPERTY, AUTH_KRB_SERVICES_PROPERTY, AUTH_PWDFILE_PROPERTY, AUTH_USERNAME_PROPERTY, AUTH_WALLET_PROPERTY, CMD_PASSWORD_NOPROMPT_PROPERTY, JAAS_LOGIN_CONF_NAME, KRB_MECH_NAME, SECURITY_FILE_PROPERTY, SSL_CIPHER_SUITES_PROPERTY, SSL_HOSTNAME_VERIFIER_PROPERTY, SSL_PROTOCOLS_PROPERTY, SSL_TRANSPORT_NAME, SSL_TRUSTSTORE_FILE_PROPERTY, SSL_TRUSTSTORE_PASSWORD_ALIAS_PROPERTY, SSL_TRUSTSTORE_PASSWORD_PROPERTY, SSL_TRUSTSTORE_TYPE_PROPERTY, TRANSPORT_PROPERTY
-
-
Constructor Summary
Constructors Constructor Description KVStoreConfig(String storeName, String... helperHostPort)
Creates a config object with the minimum required properties.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method 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 LOBput
operation.InetSocketAddress
getLocalAddress()
Gets the local address.long
getNetworkRoundtripTimeout(TimeUnit unit)
Returns the amount of time to allow for a single roundtrip network communication with the server.long
getOpenTimeout(TimeUnit unit)
Deprecated.String[]
getReadZones()
Returns the zones in which nodes must be located to be used for read operations, ornull
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.Properties
getSecurityProperties()
Returns a copy of the current security properties.int
getSGAttrsCacheTimeout()
Gets the timeout of cached sequence generator attributes in milliseconds.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.boolean
getUseAsync()
Whether calls to the store should use the async network protocol.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 aputLOB
operation.KVStoreConfig
setLocalAddress(InetSocketAddress localAddr)
Configures the local address used to establish connections to the store.KVStoreConfig
setNetworkRoundtripTimeout(long timeout, TimeUnit unit)
Configures the amount of time to allow for a single roundtrip network communication with the server.KVStoreConfig
setOpenTimeout(long timeout, TimeUnit unit)
Deprecated.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
setSGAttrsCacheTimeout(int sgAttrsCacheTimeout)
Sets the timeout of cached sequence generator attributes in milliseconds.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.KVStoreConfig
setUseAsync(boolean useAsync)
Specifies whether calls to the store should use the async network protocol.String
toString()
-
-
-
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.If the async network protocol is disabled, 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_REGISTRY_OPEN_TIMEOUT
public static final int DEFAULT_REGISTRY_OPEN_TIMEOUT
The default open timeout in ms associated with the sockets used to make registry requests.- See Also:
- Constant Field Values
-
DEFAULT_REGISTRY_READ_TIMEOUT
public static final int DEFAULT_REGISTRY_READ_TIMEOUT
The default read timeout associated with the sockets used to make registry requests.- See Also:
- Constant Field Values
-
DEFAULT_NETWORK_ROUNDTRIP_TIMEOUT
public static final int DEFAULT_NETWORK_ROUNDTRIP_TIMEOUT
The default value in milliseconds for the amount of time to allow for a single roundtrip network communication with the server.- Since:
- 19.5
- See Also:
getNetworkRoundtripTimeout(java.util.concurrent.TimeUnit)
, 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
-
DEFAULT_SG_CACHED_ATTRS_TIMEOUT
public static int DEFAULT_SG_CACHED_ATTRS_TIMEOUT
Default value for the timeout of cached sequence generator attributes in milliseconds.
-
USE_ASYNC
public static final String USE_ASYNC
The name of the system property that controls whether to use the async network protocol by default.- Since:
- 19.5
- See Also:
- Constant Field Values
-
DEFAULT_USE_ASYNC
public static final boolean DEFAULT_USE_ASYNC
Whether to use the async network protocol by default.- Since:
- 19.5
- 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()
-
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 theKVStoreConfig
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 theKVStoreConfig
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 (3000 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
- theTimeUnit
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.- 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 3000 milliseconds.- Parameters:
unit
- theTimeUnit
of the returned value. May not be null.- Returns:
- The socket open timeout.
- Since:
- 2.0
-
getOpenTimeout
@Deprecated public long getOpenTimeout(TimeUnit unit)
Deprecated.
-
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. If the async network protocol is disabled, then 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 timeoutunit
- theTimeUnit
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
- theTimeUnit
of the returned value. May not be null.- Returns:
- The socket read timeout
- Since:
- 2.0
-
setLocalAddress
public KVStoreConfig setLocalAddress(InetSocketAddress localAddr)
Configures the local address used to establish connections to the store. Use this method on machines with multiple NICs to restrict traffic to KVStore to a specific NIC, or to chose a more desirable network path. Setting localAddr can be beneficial in the following circumstances:- When there are multiple network paths through the NICs to the store's nodes and the routing rules are insufficient to disambiguate amongst them. Setting the address explicitly ensures the best choice of network path based on knowledge of the overall application behavior and network configuration.
- To isolate store traffic to a specific NIC, for latency-sensitive applications, for example, when the client is used in the web tier to isolate client/store request response http request traffic.
- Parameters:
localAddr
- the local address identifying the NIC. If null, any local address is chosen. Similarly, if the port is zero any free local port (associated with the address) is used to bind the connection.- Since:
- 18.3
-
getLocalAddress
public InetSocketAddress getLocalAddress()
Gets the local address. If user does not specify it, returns null- Returns:
- the host port of local address or null.
- Since:
- 18.3
-
setRequestTimeout
public KVStoreConfig setRequestTimeout(long timeout, TimeUnit unit) throws IllegalArgumentException
Configures the default request timeout.- Parameters:
timeout
- the default request timeout.unit
- theTimeUnit
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 isDEFAULT_REQUEST_TIMEOUT
.- Parameters:
unit
- theTimeUnit
of the returned value. May not be null.- Returns:
- The transaction timeout.
-
setNetworkRoundtripTimeout
public KVStoreConfig setNetworkRoundtripTimeout(long timeout, TimeUnit unit)
Configures the amount of time to allow for a single roundtrip network communication with the server. This value is added to the request timeout to determine the total amount of time that the client should wait for a request to complete before timing out.Specifying a smaller value, or to zero, will reduce the amount of time it takes for the client to report a request that fails to complete within the requested timeout, but increases the chance that the resulting exception will be a
RequestTimeoutException
rather than an exception the reflects more specific information about the failure on the server, for example, aConsistencyException
. Specifying a longer value will increase the chance that the client will be able to throw an exception based on more specific information from the server in case of longer network communication delays.- Parameters:
timeout
- the roundtrip network communication timeoutunit
- theTimeUnit
of the timeout value- Throws:
IllegalArgumentException
- if the timeout value is negative- Since:
- 19.5
- See Also:
setRequestTimeout(long, java.util.concurrent.TimeUnit)
-
getNetworkRoundtripTimeout
public long getNetworkRoundtripTimeout(TimeUnit unit)
Returns the amount of time to allow for a single roundtrip network communication with the server. This value is added to the request timeout to determine the total amount of time that the client should wait for a request to complete before timing out.If it is not overridden by calling
setNetworkRoundtripTimeout(long, java.util.concurrent.TimeUnit)
, the default value is 25.- Parameters:
unit
- theTimeout
to use for the return value- Returns:
- the network roundtrip timeout
- Since:
- 19.5
-
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 isConsistency.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 isDurability.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 callingsetRequestLimit(oracle.kv.RequestLimitConfig)
.- Returns:
- the request limit configuration
-
getLOBTimeout
public long getLOBTimeout(TimeUnit unit)
Returns the default timeout value (in ms) associated with chunk access during operations on LOBs.
-
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
- theTimeUnit
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 inIllegalArgumentException
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 LOBput
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 aputLOB
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, ornull
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 isnull
, 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 anIllegalArgumentException
.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 ornull
- Returns:
- this
- Throws:
IllegalArgumentException
- if the array argument is notnull
and is either empty or containsnull
or duplicate elements- Since:
- 3.0
-
getUseAsync
public boolean getUseAsync()
Whether calls to the store should use the async network protocol.If it is not overridden by calling
setUseAsync(boolean)
, the default value is true, unless theUSE_ASYNC
system property is set, in which case that value is parsed by callingBoolean.getBoolean(java.lang.String)
.- Since:
- 19.5
-
setUseAsync
public KVStoreConfig setUseAsync(boolean useAsync)
Specifies whether calls to the store should use the async network protocol.- Since:
- 19.5
-
setSecurityProperties
public KVStoreConfig setSecurityProperties(Properties securityProps)
Configures security properties for the client. The supported properties include both authentication properties and transport properties. SeeKVSecurityConstants
for the supported properties.- Returns:
- this
-
getSecurityProperties
public Properties getSecurityProperties()
Returns a copy of the current security properties. This reflects both the properties explicitly set through setSecurityProperties as well as any properties obtained from a security property file. Changes to the returned object have no effect on configuration settings.- Returns:
- the current security properties
-
setSGAttrsCacheTimeout
public KVStoreConfig setSGAttrsCacheTimeout(int sgAttrsCacheTimeout)
Sets the timeout of cached sequence generator attributes in milliseconds.
-
getSGAttrsCacheTimeout
public int getSGAttrsCacheTimeout()
Gets the timeout of cached sequence generator attributes in milliseconds.
-
-