Package org.voltdb.client

Class Client2Config

java.lang.Object
org.voltdb.client.Client2Config
public class Client2Config extends Object
Container for configuration settings for a Client2 VoltDB client. A Client2Config object is passed as input to ClientFactory.createClient(), which generates a Client2 with the desired characteristics.
See Also:

  • Field Details

    • DEFAULT_CONNECTION_SETUP_TIMEOUT

      public static final long DEFAULT_CONNECTION_SETUP_TIMEOUT
      Default connection setup timeout (30 seconds)

    • DEFAULT_CONNECTION_RESPONSE_TIMEOUT

      public static final long DEFAULT_CONNECTION_RESPONSE_TIMEOUT
      Default timeout on seeing any response on a connection (2 minutes)

    • DEFAULT_PROCEDURE_TIMEOUT

      public static final long DEFAULT_PROCEDURE_TIMEOUT
      Default timeout for each procedue call (2 minutes)

    • DEFAULT_CLIENT_REQUEST_HARD_LIMIT

      public static final int DEFAULT_CLIENT_REQUEST_HARD_LIMIT
      Default hard limit on requests pending in client; further requests refused (1000)
      See Also:

    • DEFAULT_CLIENT_REQUEST_WARNING_LEVEL

      public static final int DEFAULT_CLIENT_REQUEST_WARNING_LEVEL
      Default soft limit on requests pending in client; application gets backpressure-on notification (800)
      See Also:

    • DEFAULT_CLIENT_REQUEST_RESUME_LEVEL

      public static final int DEFAULT_CLIENT_REQUEST_RESUME_LEVEL
      Default level at which application gets backpressure-off notification (200)
      See Also:

    • DEFAULT_OUTSTANDING_TRANSACTION_LIMIT

      public static final int DEFAULT_OUTSTANDING_TRANSACTION_LIMIT
      Default limit for transactions posted to server on connection (100)
      See Also:

    • DEFAULT_NETWORK_BACKPRESSURE_LEVEL

      public static final int DEFAULT_NETWORK_BACKPRESSURE_LEVEL
      Default level at which Volt network layer reports backpressure to Volt client internally (100)
      See Also:

    • DEFAULT_RECONNECT_DELAY

      public static final long DEFAULT_RECONNECT_DELAY
      Default delay before first attempt to recover a failed connection (1 second)

    • DEFAULT_RECONNECT_RETRY_DELAY

      public static final long DEFAULT_RECONNECT_RETRY_DELAY
      Default delay between reconnection retries (15 seconds)

    • DEFAULT_REQUEST_PRIORITY

      public static final int DEFAULT_REQUEST_PRIORITY
      Default priority for requests that do not explicitly set a priority (4)
      See Also:

    • DEFAULT_RESPONSE_THREADS

      public static final int DEFAULT_RESPONSE_THREADS
      Default size of thread pool for dispatching responses (4)
      See Also:

    • HIGHEST_PRIORITY

      public static final int HIGHEST_PRIORITY
      Highest priority allowed for procedure calls (1)
      See Also:

    • LOWEST_PRIORITY

      public static final int LOWEST_PRIORITY
      Lowest priority allowed for procedure calls (8)
      See Also:

  • Constructor Details

    • Client2Config

      public Client2Config()
      Constructs a configuration with default values. Various methods can be used to override the defaults. You'll likely need authentication information (username and password) at a minimum.

      All configuration methods in Client2Config return this, so calls can be chained.

  • Method Details

    • username

      public Client2Config username(String username)
      Set username for connections to VoltDB.
      Parameters:
      username - username
      Returns:
      this

    • password

      public Client2Config password(String password)
      Set cleartext password for connections to VoltDB.
      Parameters:
      password - password
      Returns:
      this

    • hashedPassword

      public Client2Config hashedPassword(String password)
      Set hashed password for connections to VoltDB.
      Parameters:
      password - hashed password
      Returns:
      this

    • hashedPassword

      @Deprecated public Client2Config hashedPassword(String password, org.voltdb.client.ClientAuthScheme hashScheme)
      Deprecated.
      no longer useful since there is only one valid value for scheme
      Set hashed password for connections to VoltDB. The password was hashed using a specified hash scheme.
      Parameters:
      password - hashed password
      hashScheme - hash scheme used to hash the password; must be HASH_256
      Returns:
      this

    • authenticatedSubject

      public Client2Config authenticatedSubject(Subject subject)
      Sets the authenticated subject to be used for connections to VoltDB. This can be used as an alternative to a username and password combination.
      Parameters:
      subject - subject (javax.security.auth.Subject)
      Returns:
      this

    • loginContext

      public Client2Config loginContext(String name)
      Creates a new login context and authenticates the user, then adds the authenticated subject to this client configuration.

      See package javax.security.auth.login for details.

      Parameters:
      name - as used as key to locate the login context entry
      Returns:
      this
      See Also:

    • connectionSetupTimeout

      public Client2Config connectionSetupTimeout(long timeout, TimeUnit unit)
      Sets the timeout for connection setup, including authentication to the server. A zero or negative value means there is no limit.
      Parameters:
      timeout - the timeout interval
      unit - the units in which the timeout was expressed
      Returns:
      this

    • connectionResponseTimeout

      public Client2Config connectionResponseTimeout(long timeout, TimeUnit unit)
      Sets the connection response timeout. A zero or negative value means there is no limit.

      If no response has been received on a connection within the specified time, the connection will be considered lost. A 'ping' request will be periodically executed on an otherwise-idle connection in order to ensure keep the connection alive.

      Parameters:
      timeout - the timeout interval
      unit - the units in which the timeout was expressed
      Returns:
      this

    • procedureCallTimeout

      public Client2Config procedureCallTimeout(long timeout, TimeUnit unit)
      Sets the timeout for procedure calls. A zero or negative value means there is no limit.

      If a call has received no response from VoltDB in the specified time, it will be completed with a timeout error.

      Parameters:
      timeout - the timeout interval
      unit - the units in which the timeout was expressed
      Returns:
      this

    • clientRequestLimit

      public Client2Config clientRequestLimit(int limit)
      Sets the limit on the number of requests that can be pending in a client at any one time. Requests are pending from the time that callProcedure() is called, up to when the response has been delivered to the application or the call has failed.

      Calls which exceed this limit will be rejected by the API. This is an absolute limit on resource consumption. It should be set somewhat larger than the warning level established by a call to clientRequestBackpressureLevel(int, int) in order to give the application headroom to react to the warning.

      Parameters:
      limit - the desired request limit
      Returns:
      this
      See Also:

    • clientRequestBackpressureLevel

      public Client2Config clientRequestBackpressureLevel(int warning, int resume)
      Sets levels for controlling backpressure notifications.

      When the pending count reaches the warning level or greater, the application is warned to slow down: backpressure starts. When the pending count subsequently drops to the resume level (or lower), the application is informed that it no longer needs to slow down: backpressure ends.

      For predictable operation, the implementation will adjust values such that:

      • resume level ≤ warning level
      • warning level ≤ hard limit
      Parameters:
      warning - the level at which the application is warned to slow down
      resume - the level at which application slow-down can end
      Returns:
      this
      See Also:

    • outstandingTransactionLimit

      public Client2Config outstandingTransactionLimit(int limit)
      Sets the limit on the number of transactions that can be outstanding at the VoltDB server at any one time. Requests are outstanding from the time they are handed over to the networking code, up to when the response is received.

      Requests will be queued in the Client2 API after this limit is reached, to avoid overwhelming the VoltDB cluster.

      Parameters:
      limit - the desired request limit
      Returns:
      this

    • transactionRateLimit

      public Client2Config transactionRateLimit(int tpsLimit)
      Limits the rate at which transactions can be queued for transmission to the VoltDB server. This is intended for performance modelling, and is not recommended for production use.

      If the application is making requests to callProcedure in excess of the target rate, then the application's calling thread may block without a timeout, even when using asynchronous calls.

      By default there is no rate limiting.

      Parameters:
      tpsLimit - target rate limit in transactions per second
      Returns:
      this

    • networkBackpressureLevel

      public Client2Config networkBackpressureLevel(int level)
      This setting controls the maximum number of requests that the Client2 API can have queued at the VoltDB network layer for a single connection. At that point, the network interface will backpressure the API; this backpressure is not directly visible to the application using the API, since the API has internal queueing.

      Transmission order is fixed before a request is queued to the network layer. Thus, setting this value too high can adversely affect the ability of high-priority requests to overtake lower-priority requests.

      VoltDB recommends changing the default only after careful measurement in a realistic scenario.

      Parameters:
      level - the desired backpressure level
      Returns:
      this

    • reconnectDelay

      public Client2Config reconnectDelay(long initialDelay, long retryDelay, TimeUnit unit)
      Sets delay times for attempts to reconnect failed connections. There are two settings: one for the time to wait before the first reconnect attempt, and the other for the time to wait between retries, if the first attempt fails.

      In typical use, the initial delay will be fairly small, in order to recover from a momentary glitch; the retryDelay will be somewhat longer.

      VoltDB recommends changing delay times from the defaults only when default settings have been shown to be problematic in your specific use-case.

      Parameters:
      initialDelay - delay before first reconnect attempt
      retryDelay - delay between subsequent retries
      unit - time units used for both delay values
      Returns:
      this

    • disableConnectionMgmt

      public Client2Config disableConnectionMgmt()
      Disable automatic connection management.

      Normally, after the application connects to at least one VoltDB server using connectSync or connectAsync, the API will manage connections to the VoltDB cluster. Connections will be created to available cluster nodes as they are discovered, and failed connections will be reconnected when possible.

      The application can disable this, and assume all responsibility for making initial connections, and for recovery from loss of connection.

      Returns:
      this

    • requestPriority

      public Client2Config requestPriority(int prio)
      Sets the default priority for procedure calls from a Client2 created using this configuration.

      The value given here can be overridden by individual procedure calls.

      The valid priority range is from HIGHEST_PRIORITY to LOWEST_PRIORITY, inclusive. Higher priorities have lower numerical values.

      Parameters:
      prio - priority
      Returns:
      this

    • trustStoreFromPropertyFile

      public Client2Config trustStoreFromPropertyFile(String path)
      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 key store properties are:

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

      If the path is missing or empty, a default is supplied as if defaultTrustStore() had been called.

      Parameters:
      path - property file name
      Returns:
      this
      See Also:

    • trustStoreFromFile

      public Client2Config trustStoreFromFile(String path)
      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 defaultTrustStore() had been called.

      Parameters:
      path - file name
      Returns:
      this
      See Also:

    • defaultTrustStore

      public Client2Config defaultTrustStore()
      Configures trust store for TLS/SSL using installation defaults. The defaults are 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.
      Returns:
      this
      See Also:

    • trustStore

      public Client2Config trustStore(String path, String password)
      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, a default is supplied as if defaultTrustStore() had been called.

      Parameters:
      path - trust store file specification
      password - optional trust store file password
      Returns:
      this
      See Also:

    • trustStoreWithMutualAuth

      public Client2Config trustStoreWithMutualAuth(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. The password is required for JKS or PKCS#12; it is used to decrypt the private key. For PEM, the key is in PKCS#8 form, and the password is only needed if the key is encrypted.

      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 - key store file password
      Returns:
      this
      See Also:

    • trustStoreWithMutualAuth

      public Client2Config trustStoreWithMutualAuth(String trustPath, String trustPass, String keyPath, String keyPass, String keyCertFile)
      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.

      This variation of trustStoreWithMutualAuth adds an argument for a separate cert file; it can be used when the key store file contains only the private key, not the certificate chain. Separate key and cert files are applicable only to the PEM format.

      Parameters:
      trustPath - trust store file specification
      trustPass - optional trust store file password
      keyPath - key store file specification
      keyPass - key store file password
      keyCertFile - separate certificate file for key store
      Returns:
      this
      See Also:

    • enableSSL

      public Client2Config enableSSL()
      Enables TLS/SSL for server connections. If a trust store has not already been configured, a default is supplied as if defaultTrustStore() had been called.
      Returns:
      this

    • enableSSLHostCheck

      public Client2Config 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.
      Returns:
      this

    • connectFailureHandler

      public Client2Config connectFailureHandler(Client2Notification.ConnectionStatus handler)
      Registers a handler for connection-establishment failures. This will be called when an attempt to connect to a VoltDB server fails.
      Parameters:
      handler - a Client2Notification.ConnectionStatus
      Returns:
      this
      See Also:

    • connectionUpHandler

      public Client2Config connectionUpHandler(Client2Notification.ConnectionStatus handler)
      Registers a handler for connection-up events. This will be called when an attempt to connect to a VoltDB server has successfully completed, including any necessary authentication.
      Parameters:
      handler - a Client2Notification.ConnectionStatus
      Returns:
      this
      See Also:

    • connectionDownHandler

      public Client2Config connectionDownHandler(Client2Notification.ConnectionStatus handler)
      Registers a handler for connection-down events. This will be called when a previously-up connection is lost for any reason.
      Parameters:
      handler - a Client2Notification.ConnectionStatus
      Returns:
      this
      See Also:

    • lateResponseHandler

      public Client2Config lateResponseHandler(Client2Notification.LateResponse handler)
      Registers a handler for late server responses.
      Parameters:
      handler - a Client2Notification.LateResponse
      Returns:
      this
      See Also:

    • requestBackpressureHandler

      public Client2Config requestBackpressureHandler(Client2Notification.RequestBackpressure handler)
      Registers a handler to be notified about changes in request backpressure.

      Backpressure trigger levels are configurable via clientRequestBackpressureLevel(int, int).

      Parameters:
      handler - a Client2Notification.RequestBackpressure
      Returns:
      this
      See Also:

    • errorLogHandler

      public Client2Config errorLogHandler(Client2Notification.ErrorLog handler)
      Registers an error-log handler.

      The Client2 implementation may print messages on its standard error when certain unexpected situations arise. The application can choose to handle the message instead, perhaps writing to its own log.

      Applications are cautioned against attempting to interpret the text of a log message. The wording is subject to change without notice.

      Parameters:
      handler - a Client2Notification.ErrorLog
      Returns:
      this
      See Also:

    • responseThreadCount

      public Client2Config responseThreadCount(int count)
      Sets the fixed number of 'response' threads to be available in the pool of such threads. Response messages from the VoltDB cluster are handled by these threads.

      This setting is only meaningful for the internal client response ExecutorService. If you provide a custom service by responseExecutorService then the count specified here is not used.

      Parameters:
      count - number of response threads to create
      Returns:
      this

    • responseExecutorService

      public Client2Config responseExecutorService(ExecutorService execService, boolean stopOnClose)
      Provides an ExecutorService with which to complete callProcedure requests. This replaces the default provided by the Client2 interface.

      When a response message is received from the VoltDB cluster, it is handed over to a thread from this service for processing. The eventual setting of the call's CompletableFuture into the 'completed' state will occur on this thread.

      The caller chooses whether or not Client2.close() will automatically execute a shutdown on the executor service.

      Parameters:
      execService - an ExecutorService
      stopOnClose - true to stop the service on client close
      Returns:
      this

    • roundingMode

      public Client2Config roundingMode(boolean enable, RoundingMode mode)
      Enables or disables the rounding mode in the client. This must match the rounding mode set in the server, which is set using system properties.
      Parameters:
      enable - true iff rounding is enabled
      mode - the rounding mode (java.math.RoundingMode)
      Returns:
      this