Class ClientConfig
-
Field Summary
-
Constructor Summary
ConstructorDescriptionConfiguration for a client with no authentication credentials.ClientConfig
(String username, String password) Configuration for a client that specifies cleartext authentication credentials.ClientConfig
(String username, String password, boolean cleartext, ClientStatusListenerExt listener) Configuration for a client that specifies authentication credentials, the password being optionally hashed prior to the call.ClientConfig
(String username, String password, boolean cleartext, ClientStatusListenerExt listener, org.voltdb.client.ClientAuthScheme scheme) Configuration for a client that specifies authentication credentials, the password being optionally hashed prior to the call.ClientConfig
(String username, String password, ClientStatusListenerExt listener) Configuration for a client that specifies cleartext authentication credentials.ClientConfig
(String username, String password, ClientStatusListenerExt listener, org.voltdb.client.ClientAuthScheme scheme) Configuration for a client that specifies cleartext authentication credentials.ClientConfig
(Subject subject, ClientStatusListenerExt listener) Configuration for a client that specifies an already authenticatedSubject
. -
Method Summary
Modifier and TypeMethodDescriptionvoid
enableKerberosAuthentication
(String loginContextEntryKey) Enable Kerberos authentication, using the provided JAAS login context entry key to get the authentication credentials held by the caller.void
enableKerberosAuthentication
(Subject subject) Enable Kerberos authentication with the provided subject credentials.void
Enables TLS/SSL with previously-configured trust store.void
If TLS/SSL is enabled, this enables verification of the host identification (either dnsName or IP address) in the X.509 certificate's SubjectAlternativeName extension.int[]
Get thresholds for backpressure reporting, as set bysetBackpressureQueueThresholds(int, int)
.int
Returns the maximum number of outstanding requests as set bysetMaxOutstandingTxns(int)
.long
Returns non-blocking async setting, as established by a priorsetNonblockingAsync()
.void
setBackpressureQueueThresholds
(int reqLimit, int byteLimit) Set thresholds for backpressure reporting based on pending request count and pending byte count.void
setConnectionResponseTimeout
(long ms) Set the timeout for reading from a connection.void
setHeavyweight
(boolean heavyweight) Specifies that the client wants additional network threads.void
setInitialConnectionRetryInterval
(long ms) Set the initial connection retry interval for automatic reconnection when topology-change awareness is enabled.void
setMaxConnectionRetryInterval
(long ms) Set the maximum connection retry interval for automatic reconnection when topology-change awareness is enabled.void
setMaxOutstandingTxns
(int maxOutstanding) Set the maximum number of outstanding requests that will be submitted before blocking.void
setMaxTransactionsPerSecond
(int maxTxnsPerSecond) Set a limit on the number of transactions that can be executed per second.void
Sets nonblocking mode for asynchronous procedure invocations.void
setNonblockingAsync
(long blockingTimeout) Sets nonblocking mode for asynchronous procedure invocations, with provision for user-supplied blocking time limit.void
setProcedureCallTimeout
(long ms) Set the timeout for procedure calls.void
setRequestPriority
(int prio) Sets the request priority for all procedure calls from aClient
created using this configuration.static void
setRoundingConfig
(boolean isEnabled, RoundingMode mode) Enable or disable the rounding mode in the client.void
setTopologyChangeAware
(boolean enabled) Configures the client so that it attempts to connect to all nodes in the cluster as they are discovered, and will reconnect if those connections fail.void
setTrustStore
(String pathToTrustStore, String trustStorePassword) Configure trust store with specified path and password.void
Configure trust store using installation defaults, determined as follows: If the system propertyjavax.net.ssl.trustStore
is set, then its value, along with that ofjavax.net.ssl.trustStorePassword
, will be used.void
setTrustStoreConfigFromFile
(String filename) This is a generalized routine to create a truststore from a provided file.void
setTrustStoreConfigFromPropertyFile
(String propFile) Configure trust store via a property file.
-
Field Details
-
ENABLE_SSL_FOR_TEST
public static final boolean ENABLE_SSL_FOR_TEST
-
-
Constructor Details
-
ClientConfig
public ClientConfig()Configuration for a client with no authentication credentials. -
ClientConfig
Configuration for a client that specifies cleartext authentication credentials. The username and password can be null or the empty string.- Parameters:
username
- Cleartext username.password
- Cleartext password.
-
ClientConfig
Configuration for a client that specifies cleartext authentication credentials. The username and password can be null or the empty string.- Parameters:
username
- Cleartext username.password
- Cleartext password.listener
-ClientStatusListenerExt
implementation to receive callbacks.
-
ClientConfig
public ClientConfig(String username, String password, ClientStatusListenerExt listener, org.voltdb.client.ClientAuthScheme scheme) Configuration for a client that specifies cleartext authentication credentials. The username and password can be null or the empty string.- Parameters:
username
- Cleartext username.password
- Cleartext password.listener
-ClientStatusListenerExt
implementation to receive callbacks.scheme
- Client password hash scheme.
-
ClientConfig
public ClientConfig(String username, String password, boolean cleartext, ClientStatusListenerExt listener) Configuration for a client that specifies authentication credentials, the password being optionally hashed prior to the call. The username and password can be null or the empty string.- Parameters:
username
- Cleartext username.password
- A cleartext or hashed password.cleartext
- Whether the password is hashed.listener
-ClientStatusListenerExt
implementation to receive callbacks.
-
ClientConfig
Configuration for a client that specifies an already authenticatedSubject
.- Parameters:
subject
- an authenticatedSubject
.listener
-ClientStatusListenerExt
implementation to receive callbacks.
-
ClientConfig
public ClientConfig(String username, String password, boolean cleartext, ClientStatusListenerExt listener, org.voltdb.client.ClientAuthScheme scheme) Configuration for a client that specifies authentication credentials, the password being optionally hashed prior to the call. The username and password can be null or the empty string.- Parameters:
username
- Cleartext username.password
- A cleartext or hashed password.cleartext
- Whether the password is hashed.listener
-ClientStatusListenerExt
implementation to receive callbacks.scheme
- Client password hash scheme
-
-
Method Details
-
setProcedureCallTimeout
public void setProcedureCallTimeout(long ms) Set the timeout for procedure calls. The default timeout is 2 minutes. A zero or negative value indicates no timeout.If the timeout expires before the procedure call could even be queued for transmission, because of backpressure:
- Synchronous procedures will throw a
ProcCallException
. The response status will beClientResponse.GRACEFUL_FAILURE
. - Asynchronous procedures will return
false
.
If the timeout expires after the call is queued for transmission:
- Synchronous procedures will throw a
ProcCallException
. The response status will beClientResponse.CONNECTION_TIMEOUT
. - Asynchronous procedures will invoke a callback. The response
status will be
ClientResponse.CONNECTION_TIMEOUT
.
Note that while specified in mSec, this timeout is only accurate to within a second or so.
- Parameters:
ms
- Timeout value in milliseconds.
- Synchronous procedures will throw a
-
setConnectionResponseTimeout
public void setConnectionResponseTimeout(long ms) Set the timeout for reading from a connection. If a connection receives no responses for the specified time interval, either from procedure calls or pings, then the connection will be assumed dead. Lost-connection callbacks will be executed, and in-progress requests will be completed.The default timeout is 2 minutes. A zero or negative value indicates no timeout.
Note that while specified in mSec, this timeout is only accurate to within a second or so.
- Parameters:
ms
- Timeout value in milliseconds.
-
setHeavyweight
public void setHeavyweight(boolean heavyweight) Specifies that the client wants additional network threads.By default a single network thread is created to do IO and invoke callbacks. When
heavyweight
is set to true, additional threads are created. This results in multiple connections to each server.The number of network threads depends on the number of processors available. Specifically, there will be
Runtime.getRuntime().availableProcessors() / 2
threads.- Parameters:
heavyweight
- Whether to create additional threads for high IO or high processing workloads.
-
setMaxOutstandingTxns
public void setMaxOutstandingTxns(int maxOutstanding) Set the maximum number of outstanding requests that will be submitted before blocking. The default value is 3000.- Parameters:
maxOutstanding
- The maximum outstanding transactions before calls toClient.callProcedure(ProcedureCallback, String, Object...)
will block or return false (depending on settings). Use 0 to reset to default.
-
getMaxOutstandingTxns
public int getMaxOutstandingTxns()Returns the maximum number of outstanding requests as set bysetMaxOutstandingTxns(int)
.- Returns:
- max outstanding transaction count
-
setMaxTransactionsPerSecond
public void setMaxTransactionsPerSecond(int maxTxnsPerSecond) Set a limit on the number of transactions that can be executed per second. This operates by stalling the client so as to keep the rate from exceeding the target limit.Usage notes:
The limit should be less than 1,073,741,823 (half of
Integer.MAX_VALUE
); larger values disable rate-limiting. The default isInteger.MAX_VALUE
.Transactions will not be timed out while they are stalled waiting for the average rate to permit transmission.
You cannot use
setMaxTransactionsPerSecond
whensetNonblockingAsync
is in effect, since rate-limiting potentially needs to block.- Parameters:
maxTxnsPerSecond
- Requested limit in transaction per second.
-
setNonblockingAsync
public void setNonblockingAsync()Sets nonblocking mode for asynchronous procedure invocations.The default behavior for queueing of asynchronous procedure invocations is to block until it is possible to queue the invocation. If non-blocking async is configured, then an async callProcedure will return immediately if it is not possible to queue the procedure invocation due to backpressure. There is no effect on the synchronous variants of callProcedure.
Performance is sometimes improved if the callProcedure is permitted to block for a short while, say a few hundred microseconds, to ride out a short blip in backpressure. By default, this timeout is set to 500 microseconds.
Not supported if rate-limiting has been configured by setMaxTransactionsPerSecond.
-
setNonblockingAsync
public void setNonblockingAsync(long blockingTimeout) Sets nonblocking mode for asynchronous procedure invocations, with provision for user-supplied blocking time limit. See alsosetNonblockingAsync()
.- Parameters:
blockingTimeout
- limit on blocking time, in nanoseconds; zero if immediate return is desired.
-
getNonblockingAsync
public long getNonblockingAsync()Returns non-blocking async setting, as established by a priorsetNonblockingAsync()
.- Returns:
- negative if non-blocking async is not enabled, otherwise the blocking timeout in nanoseconds.
-
setBackpressureQueueThresholds
public void setBackpressureQueueThresholds(int reqLimit, int byteLimit) Set thresholds for backpressure reporting based on pending request count and pending byte count.Reducing limit below current queue length will not cause backpressure indication until next callProcedure.
- Parameters:
reqLimit
- request limit, greater than 0 for actual limit, 0 to reset to defaultbyteLimit
- byte limit, greater than 0 for actual limit, 0 to reset to default
-
getBackpressureQueueThresholds
public int[] getBackpressureQueueThresholds()Get thresholds for backpressure reporting, as set bysetBackpressureQueueThresholds(int, int)
.- Returns:
- integer array: reqLimit, byteLimit, in that order.
-
setTopologyChangeAware
public void setTopologyChangeAware(boolean enabled) Configures the client so that it attempts to connect to all nodes in the cluster as they are discovered, and will reconnect if those connections fail. Defaults to false.The interval between retries is subject to exponential backoff between user-supplied limits. See
setInitialConnectionRetryInterval(long)
andsetMaxConnectionRetryInterval(long)
.- Parameters:
enabled
- Enable or disable the topology awareness feature.
-
setInitialConnectionRetryInterval
public void setInitialConnectionRetryInterval(long ms) Set the initial connection retry interval for automatic reconnection when topology-change awareness is enabled. This is the delay between the first and second reconnect attempts.- Parameters:
ms
- initial connection retry interval in milliseconds.
-
setMaxConnectionRetryInterval
public void setMaxConnectionRetryInterval(long ms) Set the maximum connection retry interval for automatic reconnection when topology-change awareness is enabled. After each reconnection failure, the interval before the next retry is doubled, but will never exceed this maximum.- Parameters:
ms
- max connection retry interval in milliseconds.
-
enableKerberosAuthentication
Enable Kerberos authentication with the provided subject credentials.- Parameters:
subject
- Identity of the authenticated user.
-
enableKerberosAuthentication
Enable Kerberos authentication, using the provided JAAS login context entry key to get the authentication credentials held by the caller.- Parameters:
loginContextEntryKey
- JAAS login context config entry designation
-
setRoundingConfig
Enable or disable the rounding mode in the client. This must match the rounding mode set in the server, which is set using system properties.- Parameters:
isEnabled
- True iff rounding is enabled.mode
- The rounding mode, with values taken from java.math.RoundingMode.
-
setTrustStore
Configure trust store with specified path and password. The trust store can be a Java Key Store (JKS) binary file, or a PEM text file containing a sequence of X.509 certificates, each bracketed by-----BEGIN CERTIFICATE-----
and-----END CERTIFICATE-----
markers.The password only applies to JKS files, is optional, and if present is used only for an integrity check. A trust store contains no secret information.
If the file name is missing or empty then the installation default will be used, as if
setTrustStoreConfigFromDefault()
had been called.- Parameters:
pathToTrustStore
- file specification for the trust storetrustStorePassword
- optional trust store file password- See Also:
-
setTrustStoreConfigFromPropertyFile
Configure trust store via a property file. The file must contain property entries for a trust store:trustStore
trust store file specificationtrustStorePassword
trust store password (optional)
If the file name is missing or empty then the installation default will be used, as if
setTrustStoreConfigFromDefault()
had been called.- Parameters:
propFile
- property file name- See Also:
-
setTrustStoreConfigFromFile
This is a generalized routine to create a truststore from a provided file. The file can be:- A Java Key Store file. No password is provided; the truststore file can still be opened but no integrity check is done.
- A properties file containing a path and optional password for a Java Key Store file.
- A PEM file containing certificate entries. PEM truststore
If the file name is missing or empty then the installation default will be used, as if
setTrustStoreConfigFromDefault()
had been called.- Parameters:
filename
- file name- See Also:
-
setTrustStoreConfigFromDefault
public void setTrustStoreConfigFromDefault()Configure trust store using installation defaults, determined as follows:- If the system property
javax.net.ssl.trustStore
is set, then its value, along with that ofjavax.net.ssl.trustStorePassword
, will be used. - If that is not set, then the Java default will be used based on where Java is installed, and a default password.
- If the system property
-
enableSSL
public void enableSSL()Enables TLS/SSL with previously-configured trust store. If no call has been made to configure a trust store, we provide the installation default, as ifsetTrustStoreConfigFromDefault()
had been called. -
enableSSLHostCheck
public void enableSSLHostCheck()If TLS/SSL is enabled, this enables verification of the host identification (either dnsName or IP address) in the X.509 certificate's SubjectAlternativeName extension. -
setRequestPriority
public void setRequestPriority(int prio) Sets the request priority for all procedure calls from aClient
created using this configuration.This will be used only if priorities are enabled by the VoltDB cluster, and then it affects the order in which requests are dispatched.
The valid priority range is from 1 to 8, inclusive. Higher priorities have lower numerical values.
- Parameters:
prio
- priority
-