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 and no additional settings.

    • ClientConfig

      public ClientConfig(String username, String password)
      Configuration for a client that specifies cleartext authentication credentials and no additional settings.
      Parameters:
      username - optional cleartext username.
      password - optional cleartext password.

    • ClientConfig

      public ClientConfig(String username, String password, ClientStatusListenerExt listener)
      Configuration for a client that specifies cleartext authentication credentials, and an optional listener to process callbacks.
      Parameters:
      username - optional cleartext username.
      password - optional 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, an optional listener to process callbacks, and a specific password hash scheme.
      Parameters:
      username - optional cleartext username.
      password - optional cleartext password.
      listener - ClientStatusListenerExt implementation to receive callbacks.
      scheme - password hash scheme; HASH_SHA256 strongly recommended.

    • 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, and an optional listener to process callbacks.
      Parameters:
      username - optional cleartext username.
      password - optional 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, an optional listener to process callbacks, and a specific password hash scheme.
      Parameters:
      username - optional cleartext username.
      password - optional cleartext or hashed password.
      cleartext - whether the password is hashed.
      listener - ClientStatusListenerExt implementation to receive callbacks.
      scheme - password hash scheme; HASH_SHA256 strongly recommended.

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

      Although the procedure call is terminated from the point of view of the client application, the request may still be queued or executing at the VoltDB cluster.

      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 connection activity. If a connection receives no responses for the specified time interval, either from procedure calls or automatic pings on an otherwise-idle connection, 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.

      Although procedure calls may be terminated from the point of view of the client application, the corresponding requests may still be queued or executing at the VoltDB cluster.

      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. This is used for performance modeling, and is not generally useful in production.

      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)
      Configures trust store for TLS/SSL using a specified trust store file and an optional password. The trust store can be a Java keystore (JKS) or PKCS#12 binary file, or a PEM text file containing a sequence of X.509 certificates.

      The password only applies to JKS and PKCS#12 files, is optional, and if present is used only for an integrity check. A trust store contains no secret information.

      If the path 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:

    • setTrustStoreWithMutualAuth

      public void setTrustStoreWithMutualAuth(String trustPath, String trustPass, String keyPath, String keyPass)
      Configures trust store for TLS/SSL using a specified trust store file and an optional password, and a key store which may be used for mutual TLS, when required by the server.

      The trust store file can be in Java keystore (JKS), PKCS#12, or PEM format, containing one or more X.509 certificates. The password is ignored for PEM files; for the other file types, if supplied then it is used to check file integrity.

      The keystore file supplies a client private key and certificate for mutual TLS. This file can be a JKS, PKCS#12, or PEM file, containing a private key entry and an X.509 certificate chain. For PEM, the key is in PKCS#8 form.The password is required; it is used to decrypt the private key.

      If either path is missing or empty, a default is used.

      Parameters:
      trustPath - trust store file specification
      trustPass - optional trust store file password
      keyPath - key store file specification
      keyPass - required key store file password
      See Also:

    • setTrustStoreConfigFromPropertyFile

      public void setTrustStoreConfigFromPropertyFile(String propFile)
      Configure a TLS/SSL trust store via a property file. The file must contain property entries for a trust store. in Java keystore (JKS), PKCS#12, or PEM format, containing one or more X.509 certificates. The trust store properties are:

      • trustStore trust store file specification
      • trustStorePassword trust store password (optional)

      The password is ignored for PEM files; for the other types, if supplied then it is used to check file integrity.

      Optionally, there may also be entries for a key store, which supplies a client private key and certificate for mutual TLS. This file can be a JKS, PKCS#12, or PEM file, containing a private key entry and an X.509 certificate chain. For PEM, the key is in PKCS#8 form. The keystore properties are:

      • keyStore key store file specification
      • keyStorePassword key store password (required)

      If the path 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)
      A generalized routine to configure a TLS/SSL trust store, and in one case an optional key store, from a specified file.

      The file can be:

      • A Java keystore (JKS) or PKCS#12 file. No password is provided; the truststore file can still be opened but no integrity check is done.
      • A PEM file containing X.509 certificate entries, functioning as a trust store.
      • A properties file containing a path and optional password for a trust store file, and optionally a path and password for a key store file.

      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.
      See Also:

    • 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