Class Client2Config
Client2
VoltDB client. A Client2Config
object is passed
as input to ClientFactory.createClient()
, which
generates a Client2
with the desired characteristics.- See Also:
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
static final int
static final int
static final long
static final long
static final int
static final int
static final long
static final long
static final long
static final int
static final int
static final int
static final int
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionauthenticatedSubject
(Subject subject) Sets the authenticated subject to be used for connections to VoltDB.clientRequestBackpressureLevel
(int warning, int resume) Sets levels for controlling backpressure notifications.clientRequestLimit
(int limit) Sets the limit on the number of requests that can be pending in a client at any one time.Registers a handler for connection-establishment failures.Registers a handler for connection-down events.connectionResponseTimeout
(long timeout, TimeUnit unit) Sets the connection response timeout.connectionSetupTimeout
(long timeout, TimeUnit unit) Sets the timeout for connection setup, including authentication to the server.Registers a handler for connection-up events.Configures trust store for TLS/SSL using installation defaults.Disable automatic connection management.Enables TLS/SSL for server connections.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.Registers an error-log handler.hashedPassword
(String password) Set hashed password for connections to VoltDB.hashedPassword
(String password, org.voltdb.client.ClientAuthScheme hashScheme) Set hashed password for connections to VoltDB.Registers a handler for late server responses.loginContext
(String name) Creates a new login context and authenticates the user, then adds the authenticated subject to this client configuration.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.outstandingTransactionLimit
(int limit) Sets the limit on the number of transactions that can be outstanding at the VoltDB server at any one time.Set cleartext password for connections to VoltDB.procedureCallTimeout
(long timeout, TimeUnit unit) Sets the timeout for procedure calls.reconnectDelay
(long initialDelay, long retryDelay, TimeUnit unit) Sets delay times for attempts to reconnect failed connections.Registers a handler to be notified about changes in request backpressure.requestPriority
(int prio) Sets the default priority for procedure calls from aClient2
created using this configuration.responseExecutorService
(ExecutorService execService, boolean stopOnClose) Provides anExecutorService
with which to completecallProcedure
requests.responseThreadCount
(int count) Sets the fixed number of 'response' threads to be available in the pool of such threads.roundingMode
(boolean enable, RoundingMode mode) Enables or disables the rounding mode in the client.transactionRateLimit
(int tpsLimit) Limits the rate at which transactions can be sent to the VoltDB server.trustStore
(String path, String password) Configures trust store for TLS/SSL using a specified trust store file and an optional password.trustStoreFromFile
(String path) A generalized routine to configire a TLS/SSL trust store from a specified file.Configure a TLS/SSL trust store via a property file.Set username for connections to VoltDB.
-
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
returnthis
, so calls can be chained.
-
-
Method Details
-
username
Set username for connections to VoltDB.- Parameters:
username
- username- Returns:
- this
-
password
Set cleartext password for connections to VoltDB.- Parameters:
password
- password- Returns:
- this
-
hashedPassword
Set hashed password for connections to VoltDB.- Parameters:
password
- hashed password- Returns:
- this
-
hashedPassword
Set hashed password for connections to VoltDB. The password was hashed using a specified hash scheme.- Parameters:
password
- hashed passwordhashScheme
- hash scheme used to hash the password- Returns:
- this
-
authenticatedSubject
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
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
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 intervalunit
- the units in which the timeout was expressed- Returns:
- this
-
connectionResponseTimeout
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 intervalunit
- the units in which the timeout was expressed- Returns:
- this
-
procedureCallTimeout
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 intervalunit
- the units in which the timeout was expressed- Returns:
- this
-
clientRequestLimit
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 thatcallProcedure()
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
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 downresume
- the level at which application slow-down can end- Returns:
- this
- See Also:
-
outstandingTransactionLimit
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
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
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
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 attemptretryDelay
- delay between subsequent retriesunit
- time units used for both delay values- Returns:
- this
-
disableConnectionMgmt
Disable automatic connection management.Normally, after the application connects to at least one VoltDB server using
connectSync
orconnectAsync
, 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
Sets the default priority for procedure calls from aClient2
created using this configuration.The value given here can be overridden by individual procedure calls.
The valid priority range is from
HIGHEST_PRIORITY
toLOWEST_PRIORITY
, inclusive. Higher priorities have lower numerical values.- Parameters:
prio
- priority- Returns:
- this
-
trustStoreFromPropertyFile
Configure a TLS/SSL trust store via a property file. The file must contain property entries for a trust store:trustStore
trust store file specificationtrustStorePassword
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
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
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 ofjavax.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:
- If the system property
-
trustStore
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 specificationpassword
- optional trust store file password- Returns:
- this
- See Also:
-
enableSSL
Enables TLS/SSL for server connections. If a trust store has not already been configured, a default is supplied as ifdefaultTrustStore()
had been called.- Returns:
- this
-
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
Registers a handler for connection-establishment failures. This will be called when an attempt to connect to a VoltDB server fails.- Parameters:
handler
- aClient2Notification.ConnectionStatus
- Returns:
- this
- See Also:
-
connectionUpHandler
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
- aClient2Notification.ConnectionStatus
- Returns:
- this
- See Also:
-
connectionDownHandler
Registers a handler for connection-down events. This will be called when a previously-up connection is lost for any reason.- Parameters:
handler
- aClient2Notification.ConnectionStatus
- Returns:
- this
- See Also:
-
lateResponseHandler
Registers a handler for late server responses.- Parameters:
handler
- aClient2Notification.LateResponse
- Returns:
- this
- See Also:
-
requestBackpressureHandler
Registers a handler to be notified about changes in request backpressure.Backpressure trigger levels are configurable via
clientRequestBackpressureLevel(int, int)
.- Parameters:
handler
- aClient2Notification.RequestBackpressure
- Returns:
- this
- See Also:
-
errorLogHandler
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
- aClient2Notification.ErrorLog
- Returns:
- this
- See Also:
-
responseThreadCount
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 byresponseExecutorService
then the count specified here is not used.- Parameters:
count
- number of response threads to create- Returns:
- this
-
responseExecutorService
Provides anExecutorService
with which to completecallProcedure
requests. This replaces the default provided by theClient2
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 ashutdown
on the executor service.- Parameters:
execService
- anExecutorService
stopOnClose
- true to stop the service on client close- Returns:
- this
-
roundingMode
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 enabledmode
- the rounding mode (java.math.RoundingMode
)- Returns:
- this
-