Package org.voltdb.client

Class ClientConfig

java.lang.Object
org.voltdb.client.ClientConfig
public class ClientConfig extends Object
Container for configuration settings for a Client.

If you are using the Client2 class then you must also use Client2Config for configuration.

See Also:

  • 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

      public ClientConfig(String username, 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(String username, 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(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

      public ClientConfig(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(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:

      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.

    • 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.

    • 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

      public void enableKerberosAuthentication(Subject subject)
      Enable Kerberos authentication with the provided subject credentials.
      Parameters:
      subject - Identity of the authenticated user.

    • enableKerberosAuthentication

      public void enableKerberosAuthentication(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, 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(String pathToTrustStore, String trustStorePassword)
      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 store
      trustStorePassword - optional trust store file password
      See Also:

    • setTrustStoreConfigFromPropertyFile

      public void setTrustStoreConfigFromPropertyFile(String propFile)
      Configure trust store via a property file. The file must contain property entries for a trust store:
      • trustStore trust store file specification
      • trustStorePassword 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

      public void setTrustStoreConfigFromFile(String filename)
      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 of javax.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.

    • 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 if setTrustStoreConfigFromDefault() 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 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