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_RESPONSE_TIMEOUT

      public static final long DEFAULT_CONNECTION_RESPONSE_TIMEOUT

    • DEFAULT_PROCEDURE_TIMEOUT

      public static final long DEFAULT_PROCEDURE_TIMEOUT

    • DEFAULT_CLIENT_REQUEST_HARD_LIMIT

      public static final int DEFAULT_CLIENT_REQUEST_HARD_LIMIT
      See Also:

    • DEFAULT_CLIENT_REQUEST_WARNING_LEVEL

      public static final int DEFAULT_CLIENT_REQUEST_WARNING_LEVEL
      See Also:

    • DEFAULT_CLIENT_REQUEST_RESUME_LEVEL

      public static final int DEFAULT_CLIENT_REQUEST_RESUME_LEVEL
      See Also:

    • DEFAULT_OUTSTANDING_TRANSACTION_LIMIT

      public static final int DEFAULT_OUTSTANDING_TRANSACTION_LIMIT
      See Also:

    • DEFAULT_NETWORK_BACKPRESSURE_LEVEL

      public static final int DEFAULT_NETWORK_BACKPRESSURE_LEVEL
      See Also:

    • DEFAULT_RECONNECT_DELAY

      public static final long DEFAULT_RECONNECT_DELAY

    • DEFAULT_RECONNECT_RETRY_DELAY

      public static final long DEFAULT_RECONNECT_RETRY_DELAY

    • DEFAULT_REQUEST_PRIORITY

      public static final int DEFAULT_REQUEST_PRIORITY
      See Also:

    • DEFAULT_RESPONSE_THREADS

      public static final int DEFAULT_RESPONSE_THREADS
      See Also:

    • HIGHEST_PRIORITY

      public static final int HIGHEST_PRIORITY
      See Also:

    • LOWEST_PRIORITY

      public static final int LOWEST_PRIORITY
      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

      public Client2Config hashedPassword(String password, org.voltdb.client.ClientAuthScheme hashScheme)
      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
      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 sent 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 client queue length will likely grow to the point at which request backpressure is signaled. Queued requests may be timed out in the usual manner.

      Any throttling of sends imposed by setting this configuration parameter is applied before, and independently of, that implied by outstandingTransactionLimit.

      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:
      • trustStore trust store file specification
      • trustStorePassword trust store password (optional)

      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 configire a TLS/SSL trust store from a specified 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 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 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 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:

    • 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