oracle.kv

Class KVStoreConfig

java.lang.Object

oracle.kv.KVStoreConfig

All Implemented Interfaces:

Serializable, Cloneable

public class KVStoreConfig
extends Object
implements Serializable, Cloneable

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.

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)
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	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	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)

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.

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.

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

toString

public String toString()

Overrides:

toString in class Object