Interface Client2
- All Superinterfaces:
AutoCloseable
,Closeable
Client2
provides the so-called "version 2" client API.
The overall intent is to provide an easier way to asynchronously
queue procedure calls.
The main public methods often come in two flavours: an Async variety
returns a CompletableFuture
to represent the in-progress
request. A Sync version waits on that future before returning.
The Async/Sync pattern is not followed for methods that are inherently synchronous (for example, changing some settings), or which must block in order to usefully have the desired effect (for example, draining all client requests).
Each client instance can have multiple connections to the VoltDB cluster, one per cluster member. Each connection is backed by a single thread that handles potentially-blocking operations, thus avoiding blocking the caller's thread.
A Client2
instance is created via a call to the
routine ClientFactory.createClient()
, passing a
Client2Config
object which carries configuration
values.
-
Method Summary
Modifier and TypeMethodDescriptioncallAllPartitionProcedureAsync
(Client2CallOptions options, String procName, Object... parameters) Asynchronously call an all-partition stored procedure.callAllPartitionProcedureSync
(Client2CallOptions options, String procName, Object... parameters) Synchronously call an all-partition stored procedure.callProcedureAsync
(String procName, Object... parameters) Asynchronously call stored procedure.callProcedureAsync
(Client2CallOptions options, String procName, Object... parameters) Asynchronously call stored procedure with optional overrides for selected values.callProcedureSync
(String procName, Object... parameters) Synchronously call stored procedure.callProcedureSync
(Client2CallOptions options, String procName, Object... parameters) Synchronously call stored procedure with optional overrides for selected values.void
close()
Shut down client.Returns the 'build string' for the most-recently connected VoltDB cluster.Object[]
Returns the 'instance id' for the most-recently connected VoltDB cluster.connectAsync
(String servers) Convenient form ofconnectAsync(String,long,long,TimeUnit)
that specifies no retry.connectAsync
(String host, int port) Convenient form ofconnectAsync(String,int,long,long,TimeUnit)
that specifies no retry.connectAsync
(String host, int port, long timeout, long delay, TimeUnit unit) Connect to specified host on specified port.connectAsync
(String servers, long timeout, long delay, TimeUnit unit) Connect to first available server in a specified list of servers, each in host:port form, and separated by commas.Gets a list of currently-connected hosts.void
connectSync
(String servers) Convenient form ofconnectSync(String,long,long,TimeUnit)
that specifies no retry.void
connectSync
(String host, int port) Convenient form ofconnectSync(String,int,long,long,TimeUnit)
that specifies no retry.void
connectSync
(String host, int port, long timeout, long delay, TimeUnit unit) Connect to specified host on specified port.void
connectSync
(String servers, long timeout, long delay, TimeUnit unit) Connect to first available server in a specified list of servers, each in host:port form, and separated by commas.Statistics support: returns a statistics context associated with this client.int
Returns an estimate of the number of requests queued (via callProcedure) but not yet completed.void
drain()
Drain all requests.org.voltdb.client.VoltBulkLoader.VoltBulkLoader
newBulkLoader
(String tableName, int maxBatchSize, boolean upsertMode, org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback, org.voltdb.client.VoltBulkLoader.BulkLoaderSuccessCallback successCallback) Creates a new instance of aVoltBulkLoader
bound to this client.int
Returns an estimate of the number of outstanding transactions.int
setOutstandingTxnLimit
(int limit) Set limit on number of transactions that can be outstanding at the VoltDB cluster from this client.void
setRequestLimits
(int limit, int warning, int resume) Set limits on the number of requests that can be pending in the Client2 API at any one time.boolean
waitForTopology
(long timeout, TimeUnit unit) Wait until the VoltDB cluster topology has been determined, which may take a few seconds after the initial connection.
-
Method Details
-
setRequestLimits
void setRequestLimits(int limit, int warning, int resume) Set limits on the number of requests that can be pending in the Client2 API at any one time.Initially set from the client configuration, but may be adjusted dynamically if the application wishes to tune the value.
There is a hard limit, after which requests are refused. 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.
- Parameters:
limit
- the desired hard limit on requestswarning
- the level at which backpressure startsresume
- the level at which backpressure ends- See Also:
-
currentRequestCount
int currentRequestCount()Returns an estimate of the number of requests queued (via callProcedure) but not yet completed. The count is instantaneously valid, but of course is liable to change immediately after being read.- Returns:
- the current request count
-
setOutstandingTxnLimit
int setOutstandingTxnLimit(int limit) Set limit on number of transactions that can be outstanding at the VoltDB cluster from this client.Initially set from the client configuration, but may be adjusted dynamically if the application wishes to tune the value.
Attempting to reduce the limit below the current in-use count will only reduce it by however many permits are currently available, rather than blocking.
- Parameters:
limit
- the desired limit on requests- Returns:
- the actual new limit
- See Also:
-
outstandingTxnCount
int outstandingTxnCount()Returns an estimate of the number of outstanding transactions. This is only useful for debugging, and of course is liable to immediate change.- Returns:
- the outstanding transaction count
-
connectSync
Connect to first available server in a specified list of servers, each in host:port form, and separated by commas.Host can be IPv6, IPv4, or hostname. If IPv6, it must be enclosed in brackets. Port specification is optional.
This method connects to only one server. Other connections may be made as a result of querying the VoltDB cluster topology.
Completion is synchronous. If no connection could be set up to any of the specified servers, a reattempt will be scheduled after a specified delay, until a total timeout has been exceeded. Use zero timeout for no retry.
- Parameters:
servers
- list of servers, each as host and optional porttimeout
- overall timeoutdelay
- time between retriesunit
- units in whichtimeout
anddelay
are expressed- Throws:
IOException
- server communication error
-
connectSync
Convenient form ofconnectSync(String,long,long,TimeUnit)
that specifies no retry.- Parameters:
servers
- list of servers, each as host and optional port- Throws:
IOException
- server communication error
-
connectSync
Connect to specified host on specified port.Completion is synchronous. On a failure to connect, a reattempt will be scheduled after a specified delay, until a total timeout has been exceeded. Use zero timeout for no retry.
- Parameters:
host
- as address or hostnameport
- port numbertimeout
- overall timeoutdelay
- time between retriesunit
- units in whichtimeout
anddelay
are expressed- Throws:
IOException
- server communication error
-
connectSync
Convenient form ofconnectSync(String,int,long,long,TimeUnit)
that specifies no retry.- Parameters:
host
- as address or hostnameport
- port number- Throws:
IOException
- server communication error
-
connectAsync
Connect to first available server in a specified list of servers, each in host:port form, and separated by commas.Host can be IPv6, IPv4, or hostname. If IPv6, it must be enclosed in brackets. Port specification is optional.
This method connects to only one server. Other connections may be made as a result of querying the VoltDB cluster topology.
Completion is asynchronous. If no connection could be set up to any of the specified servers, a reattempt will be scheduled after a specified delay, until a total timeout has been exceeded. Use zero timeout for no retry.
- Parameters:
servers
- list of servers, each as host and optional porttimeout
- overall timeoutdelay
- time between retriesunit
- units in whichtimeout
anddelay
are expressed- Returns:
- a
CompletableFuture
-
connectAsync
Convenient form ofconnectAsync(String,long,long,TimeUnit)
that specifies no retry.- Parameters:
servers
- list of servers, each as host and optional port- Returns:
- a
CompletableFuture
-
connectAsync
CompletableFuture<Void> connectAsync(String host, int port, long timeout, long delay, TimeUnit unit) Connect to specified host on specified port.Completion is asynchronous. On a failure to connect, a reattempt will be scheduled after a specified delay, until a total timeout has been exceeded. Use zero timeout for no retry.
- Parameters:
host
- as address or hostnameport
- port numbertimeout
- overall timeoutdelay
- time between retriesunit
- units in whichtimeout
anddelay
are expressed- Returns:
- a
CompletableFuture
-
connectAsync
Convenient form ofconnectAsync(String,int,long,long,TimeUnit)
that specifies no retry.- Parameters:
host
- as address or hostnameport
- port number- Returns:
- a
CompletableFuture
-
connectedHosts
List<InetSocketAddress> connectedHosts()Gets a list of currently-connected hosts.Address and port will be present; host name may not be, depending on timing of reverse DNS lookup.
- Returns:
- list of
InetSocketAddress
-
clusterBuildString
String clusterBuildString()Returns the 'build string' for the most-recently connected VoltDB cluster.- Returns:
- build string (null if never connected)
-
clusterInstanceId
Object[] clusterInstanceId()Returns the 'instance id' for the most-recently connected VoltDB cluster.- Returns:
- array: formation timestamp, leader address
-
callProcedureAsync
Asynchronously call stored procedure. This call initiates a request and returns immediately. The return value is aCompletableFuture
which can be used to retrieve theClientResponse
when the request completes.- Parameters:
procName
- procedure nameparameters
- as required by the procedure- Returns:
- a
CompletableFuture
- See Also:
-
callProcedureSync
ClientResponse callProcedureSync(String procName, Object... parameters) throws IOException, ProcCallException Synchronously call stored procedure. This call initiates a request and waits for completion. The return value is theClientResponse
. AProcCallException
is raised if the response status was other than success.- Parameters:
procName
- procedure nameparameters
- as required by the procedure- Returns:
- the
ClientResponse
- Throws:
IOException
- server communication errorProcCallException
- the procedure call failed- See Also:
-
callProcedureAsync
CompletableFuture<ClientResponse> callProcedureAsync(Client2CallOptions options, String procName, Object... parameters) Asynchronously call stored procedure with optional overrides for selected values.- Parameters:
options
- aClient2CallOptions
objectprocName
- procedure nameparameters
- as required by the procedure- Returns:
- a
CompletableFuture
- See Also:
-
callProcedureSync
ClientResponse callProcedureSync(Client2CallOptions options, String procName, Object... parameters) throws IOException, ProcCallException Synchronously call stored procedure with optional overrides for selected values.- Parameters:
options
- aClient2CallOptions
objectprocName
- procedure nameparameters
- as required by the procedure- Returns:
- the
ClientResponse
- Throws:
IOException
- server communication errorProcCallException
- the procedure call failed- See Also:
-
callAllPartitionProcedureAsync
CompletableFuture<ClientResponseWithPartitionKey[]> callAllPartitionProcedureAsync(Client2CallOptions options, String procName, Object... parameters) Asynchronously call an all-partition stored procedure.The method uses system procedure
@GetPartitionKeys
to determine target partitions, and then execute the specified procedure on each partition, returning an aggregated response. The call does not complete until all procedure instances have completed.The set of partition values is cached for a short while (around 1 second) to avoid repeated requests to fetch it. It is possibly for it to be momentarily out of sync. "Exactly once" execution of the procedure cannot be guaranteed.
Since each execution of the procedure on a separate partition can succeed or fail, the application should check all response statuses.
- Parameters:
options
- aClient2CallOptions
object (null if not needed)procName
- procedure nameparameters
- as required by the procedure- Returns:
- a
CompletableFuture
- See Also:
-
callAllPartitionProcedureSync
ClientResponseWithPartitionKey[] callAllPartitionProcedureSync(Client2CallOptions options, String procName, Object... parameters) throws IOException Synchronously call an all-partition stored procedure. The call blocks until completion, and then returns the list of responses for all partitions.See
callAllPartitionProcedureAsync(Client2CallOptions, String, Object...)
for more detail.Unlike other synchronous procedure calls,
callAllPartitionProcedureSync
does not throw aProcCallException
on a failure response. The application should check all response statuses.- Parameters:
options
- aClient2CallOptions
object (null if not needed)procName
- procedure nameparameters
- as required by the procedure- Returns:
- an array of client responses, one per partition (
ClientResponseWithPartitionKey
) - Throws:
IOException
- server communication error- See Also:
-
drain
Drain all requests. This may block, and does not return until there are no more requests pending in the client.- Throws:
InterruptedException
- if the wait is interrupted
-
close
void close()Shut down client. This may block, and does not return until resources have been released.May call
drain()
if application did not already do so,- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
-
createStatsContext
ClientStatsContext createStatsContext()Statistics support: returns a statistics context associated with this client.- Returns:
- the
ClientStatsContext
created - See Also:
-
newBulkLoader
org.voltdb.client.VoltBulkLoader.VoltBulkLoader newBulkLoader(String tableName, int maxBatchSize, boolean upsertMode, org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback, org.voltdb.client.VoltBulkLoader.BulkLoaderSuccessCallback successCallback) throws Exception Creates a new instance of aVoltBulkLoader
bound to this client. Multiple instances of aVoltBulkLoader
created by a single client will share some resources, particularly if they are inserting into the same table.- Parameters:
tableName
- table to which bulk inserts are to be appliedmaxBatchSize
- size of a batch for bulk insert callsupsertMode
- set to true for upsert instead of insertfailureCallback
- callback used for failure notificationsuccessCallback
- callback on successful loads (null ok)- Returns:
- the
VoltBulkLoader
instance - Throws:
Exception
- if tableName can't be found in the catalog.
-
waitForTopology
Wait until the VoltDB cluster topology has been determined, which may take a few seconds after the initial connection. This is primarily of internal interest to bulk loaders. It is inherently synchronous.- Parameters:
timeout
- time limit on waitingunit
- time unit for timeout- Returns:
- true if topology information available
-