ClientConfig (VoltDB Client APIs)

java.lang.Object
- org.voltdb.client.ClientConfig

public class ClientConfig
extends java.lang.Object

Container for configuration settings for a Client

Field Summary

Fields
Modifier and Type Field and Description

static boolean ENABLE_SSL_FOR_TEST

Fields
Modifier and Type	Field and Description
`static boolean`	`ENABLE_SSL_FOR_TEST`

Constructor Summary

Constructors
Constructor and Description
`ClientConfig()` Configuration for a client with no authentication credentials.
`ClientConfig(java.lang.String username, java.lang.String password)` Configuration for a client that specifies cleartext authentication credentials.
`ClientConfig(java.lang.String username, java.lang.String password, boolean cleartext, ClientStatusListenerExt listener)` Configuration for a client that specifies authentication credentials, the password being optionally hashed prior to the call.
`ClientConfig(java.lang.String username, java.lang.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(java.lang.String username, java.lang.String password, ClientStatusListenerExt listener)` Configuration for a client that specifies cleartext authentication credentials.
`ClientConfig(java.lang.String username, java.lang.String password, ClientStatusListenerExt listener, org.voltdb.client.ClientAuthScheme scheme)` Configuration for a client that specifies cleartext authentication credentials.
`ClientConfig(javax.security.auth.Subject subject, ClientStatusListenerExt listener)` Configuration for a client that specifies an already authenticated `Subject`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`enableKerberosAuthentication(java.lang.String loginContextEntryKey)` Enable Kerberos authentication, using the provided JAAS login context entry key to get the authentication credentials held by the caller.
`void`	`enableKerberosAuthentication(javax.security.auth.Subject subject)` Enable Kerberos authentication with the provided subject credentials.
`void`	`enableSSL()` Enables SSL with previously-configured trust store.
`int[]`	`getBackpressureQueueThresholds()` Get thresholds for backpressure reporting, as set by `setBackpressureQueueThresholds(int, int)`.
`int`	`getMaxOutstandingTxns()` Returns the maximum number of outstanding requests as set by `setMaxOutstandingTxns(int)`.
`long`	`getNonblockingAsync()` Returns non-blocking async setting, as established by a prior `setNonblockingAsync()`.
`void`	`setBackpressureQueueThresholds(int reqLimit, int byteLimit)` Set thresholds for backpressure reporting based on pending request count and pending byte count.
`void`	`setClientAffinity(boolean on)` Deprecated. client affinity is now always `true`: transactions are always routed to the correct master partition improving latency and throughput. (Deprecated in v11.0, 2021-03-23)
`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.
`void`	`setMaxConnectionRetryInterval(long ms)` Set the maximum connection retry interval.
`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`	`setNonblockingAsync()` 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`	`setReconnectOnConnectionLoss(boolean on)` Deprecated. prefer using a topology-change-aware client, which provides more automatic handling of connections to VoltDB cluster nodes. (Deprecated in v11.1, 2021-07-30)
`void`	`setRequestPriority(int prio)` Sets the request priority for all procedure calls from a `Client` created using this configuration.
`static void`	`setRoundingConfig(boolean isEnabled, java.math.RoundingMode mode)` Enable or disable the rounding mode in the client.
`void`	`setSendReadsToReplicasByDefault(boolean on)` Deprecated. no longer meaningful: reads are always sent to the leader; sending to a replica would not have resulted in better performance. (Deprecated in v11.0, 2021-04-16)
`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(java.lang.String pathToTrustStore, java.lang.String trustStorePassword)` Configure trust store with specified path and password.
`void`	`setTrustStoreConfigFromDefault()` Configure trust store from default file with default password.
`void`	`setTrustStoreConfigFromPropertyFile(java.lang.String propFN)` Configure trust store via a property file.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - ENABLE_SSL_FOR_TEST
```
public static final boolean ENABLE_SSL_FOR_TEST
```
- Constructor Detail
  - ClientConfig
```
public ClientConfig()
```
    Configuration for a client with no authentication credentials.
  - ClientConfig
```
public ClientConfig(java.lang.String username,
                    java.lang.String password)
```
    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
```
public ClientConfig(java.lang.String username,
                    java.lang.String password,
                    ClientStatusListenerExt listener)
```
    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(java.lang.String username,
                    java.lang.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(java.lang.String username,
                    java.lang.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
```
public ClientConfig(javax.security.auth.Subject subject,
                    ClientStatusListenerExt listener)
```
    Configuration for a client that specifies an already authenticated Subject.
    
    Parameters:
    
    subject - an authenticated Subject.
    
    listener - ClientStatusListenerExt implementation to receive callbacks.
  - ClientConfig
```
public ClientConfig(java.lang.String username,
                    java.lang.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 Detail
  - 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:
    1. Synchronous procedures will throw a ProcCallException. The response status will be ClientResponse.GRACEFUL_FAILURE.
    2. Asynchronous procedures will return false.
    If the timeout expires after the call is queued for transmission:
    1. Synchronous procedures will throw a ProcCallException. The response status will be ClientResponse.CONNECTION_TIMEOUT.
    2. 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.
  - 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 to Client.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 by setMaxOutstandingTxns(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 is Integer.MAX_VALUE.
    Transactions will not be timed out while they are stalled waiting for the average rate to permit transmission.
    You cannot use setMaxTransactionsPerSecond when setNonblockingAsync 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 also setNonblockingAsync().
    
    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 prior setNonblockingAsync().
    
    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 default
    
    byteLimit - byte limit, greater than 0 for actual limit, 0 to reset to default
  - getBackpressureQueueThresholds
```
public int[] getBackpressureQueueThresholds()
```
    Get thresholds for backpressure reporting, as set by setBackpressureQueueThresholds(int, int).
    
    Returns:
    
    integer array: reqLimit, byteLimit, in that order.
  - setClientAffinity
```
@Deprecated
public void setClientAffinity(boolean on)
```
    Deprecated. client affinity is now always true: transactions are always routed to the correct master partition improving latency and throughput.
    (Deprecated in v11.0, 2021-03-23)
    
    Enables or disables client affinity.
    
    Parameters:
    
    on - unused
  - 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) and setMaxConnectionRetryInterval(long).
    
    Parameters:
    
    enabled - Enable or disable the topology awareness feature.
  - setSendReadsToReplicasByDefault
```
@Deprecated
public void setSendReadsToReplicasByDefault(boolean on)
```
    Deprecated. no longer meaningful: reads are always sent to the leader; sending to a replica would not have resulted in better performance.
    (Deprecated in v11.0, 2021-04-16)
    
    Controls whether reads are set to replicas.
    
    Parameters:
    
    on - unused
  - setReconnectOnConnectionLoss
```
@Deprecated
public void setReconnectOnConnectionLoss(boolean on)
```
    Deprecated. prefer using a topology-change-aware client, which provides more automatic handling of connections to VoltDB cluster nodes.
    (Deprecated in v11.1, 2021-07-30)
    
    Attempts to automatically reconnect to a node after connection loss, with retry until successful. The interval between retries is subject to exponential backoff between user-supplied limits. See setInitialConnectionRetryInterval(long) and setMaxConnectionRetryInterval(long).
    
    Parameters:
    
    on - Enable or disable the reconnection feature. Default is off.
    
    See Also:
    
    setTopologyChangeAware(boolean)
  - setInitialConnectionRetryInterval
```
public void setInitialConnectionRetryInterval(long ms)
```
    Set the initial connection retry interval for automatic reconnection. 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. 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
```
public void enableKerberosAuthentication(javax.security.auth.Subject subject)
```
    Enable Kerberos authentication with the provided subject credentials.
    
    Parameters:
    
    subject - Identity of the authenticated user.
  - enableKerberosAuthentication
```
public void enableKerberosAuthentication(java.lang.String loginContextEntryKey)
```
    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
```
public static void setRoundingConfig(boolean isEnabled,
                                     java.math.RoundingMode mode)
```
    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
```
public void setTrustStore(java.lang.String pathToTrustStore,
                          java.lang.String trustStorePassword)
```
    Configure trust store with specified path and password.
    
    Parameters:
    
    pathToTrustStore - file specification for the trust store
    
    trustStorePassword - trust store key file password
  - setTrustStoreConfigFromPropertyFile
```
public void setTrustStoreConfigFromPropertyFile(java.lang.String propFN)
```
    Configure trust store via a property file.
    Parameters:
    propFN - property file name containing trust store properties:
    
    trustStore trust store file specification
    trustStorePassword trust store password
  - setTrustStoreConfigFromDefault
```
public void setTrustStoreConfigFromDefault()
```
    Configure trust store from default file with default password.
  - enableSSL
```
public void enableSSL()
```
    Enables SSL with previously-configured trust store. If no call has been made to configure a trust store, we process without one.
  - setRequestPriority
```
public void setRequestPriority(int prio)
```
    Sets the request priority for all procedure calls from a Client 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

Class ClientConfig

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ENABLE_SSL_FOR_TEST

Constructor Detail

ClientConfig

ClientConfig

ClientConfig

ClientConfig

ClientConfig

ClientConfig

ClientConfig

Method Detail

setProcedureCallTimeout

setConnectionResponseTimeout

setHeavyweight

setMaxOutstandingTxns

getMaxOutstandingTxns

setMaxTransactionsPerSecond

setNonblockingAsync

setNonblockingAsync

getNonblockingAsync

setBackpressureQueueThresholds

getBackpressureQueueThresholds

setClientAffinity

setTopologyChangeAware

setSendReadsToReplicasByDefault

setReconnectOnConnectionLoss

setInitialConnectionRetryInterval

setMaxConnectionRetryInterval

enableKerberosAuthentication

enableKerberosAuthentication

setRoundingConfig

setTrustStore

setTrustStoreConfigFromPropertyFile

setTrustStoreConfigFromDefault

enableSSL

setRequestPriority