public interface Client2
extends java.io.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.
ClientFactory
,
Client2Config
,
Client2CallOptions
,
Client2Notification
Modifier and Type | Method and Description |
---|---|
java.util.concurrent.CompletableFuture<ClientResponseWithPartitionKey[]> |
callAllPartitionProcedureAsync(Client2CallOptions options,
java.lang.String procName,
java.lang.Object... parameters)
Asynchronously call an all-partition stored procedure.
|
ClientResponseWithPartitionKey[] |
callAllPartitionProcedureSync(Client2CallOptions options,
java.lang.String procName,
java.lang.Object... parameters)
Synchronously call an all-partition stored procedure.
|
java.util.concurrent.CompletableFuture<ClientResponse> |
callProcedureAsync(Client2CallOptions options,
java.lang.String procName,
java.lang.Object... parameters)
Asynchronously call stored procedure with optional overrides
for selected values.
|
java.util.concurrent.CompletableFuture<ClientResponse> |
callProcedureAsync(java.lang.String procName,
java.lang.Object... parameters)
Asynchronously call stored procedure.
|
ClientResponse |
callProcedureSync(Client2CallOptions options,
java.lang.String procName,
java.lang.Object... parameters)
Synchronously call stored procedure with optional overrides
for selected values.
|
ClientResponse |
callProcedureSync(java.lang.String procName,
java.lang.Object... parameters)
Synchronously call stored procedure.
|
void |
close()
Shut down client.
|
java.lang.String |
clusterBuildString()
Returns the 'build string' for the most-recently
connected VoltDB cluster.
|
java.lang.Object[] |
clusterInstanceId()
Returns the 'instance id' for the most-recently
connected VoltDB cluster.
|
java.util.concurrent.CompletableFuture<java.lang.Void> |
connectAsync(java.lang.String servers)
Convenient form of
connectAsync(String,long,long,TimeUnit)
that specifies no retry. |
java.util.concurrent.CompletableFuture<java.lang.Void> |
connectAsync(java.lang.String host,
int port)
Convenient form of
connectAsync(String,int,long,long,TimeUnit)
that specifies no retry. |
java.util.concurrent.CompletableFuture<java.lang.Void> |
connectAsync(java.lang.String host,
int port,
long timeout,
long delay,
java.util.concurrent.TimeUnit unit)
Connect to specified host on specified port.
|
java.util.concurrent.CompletableFuture<java.lang.Void> |
connectAsync(java.lang.String servers,
long timeout,
long delay,
java.util.concurrent.TimeUnit unit)
Connect to first available server in a specified
list of servers, each in host:port form, and separated
by commas.
|
java.util.List<java.net.InetSocketAddress> |
connectedHosts()
Gets a list of currently-connected hosts.
|
void |
connectSync(java.lang.String servers)
Convenient form of
connectSync(String,long,long,TimeUnit)
that specifies no retry. |
void |
connectSync(java.lang.String host,
int port)
Convenient form of
connectSync(String,int,long,long,TimeUnit)
that specifies no retry. |
void |
connectSync(java.lang.String host,
int port,
long timeout,
long delay,
java.util.concurrent.TimeUnit unit)
Connect to specified host on specified port.
|
void |
connectSync(java.lang.String servers,
long timeout,
long delay,
java.util.concurrent.TimeUnit unit)
Connect to first available server in a specified
list of servers, each in host:port form, and separated
by commas.
|
ClientStatsContext |
createStatsContext()
Statistics support: returns a statistics context associated
with this client.
|
int |
currentRequestCount()
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(java.lang.String tableName,
int maxBatchSize,
boolean upsertMode,
org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback,
org.voltdb.client.VoltBulkLoader.BulkLoaderSuccessCallback successCallback)
Creates a new instance of a
VoltBulkLoader
bound to this client. |
int |
outstandingTxnCount()
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,
java.util.concurrent.TimeUnit unit)
Wait until the VoltDB cluster topology has been determined, which
may take a few seconds after the initial connection.
|
void setRequestLimits(int limit, int warning, int resume)
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.
limit
- the desired hard limit on requestswarning
- the level at which backpressure startsresume
- the level at which backpressure endsClient2Config
,
Client2Notification.RequestBackpressure
int currentRequestCount()
int setOutstandingTxnLimit(int limit)
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.
limit
- the desired limit on requestsClient2Config
int outstandingTxnCount()
void connectSync(java.lang.String servers, long timeout, long delay, java.util.concurrent.TimeUnit unit) throws java.io.IOException
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.
servers
- list of servers, each as host and optional porttimeout
- overall timeoutdelay
- time between retriesunit
- units in which timeout
and delay
are expressedjava.io.IOException
- server communication errorvoid connectSync(java.lang.String servers) throws java.io.IOException
connectSync(String,long,long,TimeUnit)
that specifies no retry.servers
- list of servers, each as host and optional portjava.io.IOException
- server communication errorvoid connectSync(java.lang.String host, int port, long timeout, long delay, java.util.concurrent.TimeUnit unit) throws java.io.IOException
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.
host
- as address or hostnameport
- port numbertimeout
- overall timeoutdelay
- time between retriesunit
- units in which timeout
and delay
are expressedjava.io.IOException
- server communication errorvoid connectSync(java.lang.String host, int port) throws java.io.IOException
connectSync(String,int,long,long,TimeUnit)
that specifies no retry.host
- as address or hostnameport
- port numberjava.io.IOException
- server communication errorjava.util.concurrent.CompletableFuture<java.lang.Void> connectAsync(java.lang.String servers, long timeout, long delay, java.util.concurrent.TimeUnit unit)
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.
servers
- list of servers, each as host and optional porttimeout
- overall timeoutdelay
- time between retriesunit
- units in which timeout
and delay
are expressedCompletableFuture
java.util.concurrent.CompletableFuture<java.lang.Void> connectAsync(java.lang.String servers)
connectAsync(String,long,long,TimeUnit)
that specifies no retry.servers
- list of servers, each as host and optional portCompletableFuture
java.util.concurrent.CompletableFuture<java.lang.Void> connectAsync(java.lang.String host, int port, long timeout, long delay, java.util.concurrent.TimeUnit unit)
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.
host
- as address or hostnameport
- port numbertimeout
- overall timeoutdelay
- time between retriesunit
- units in which timeout
and delay
are expressedCompletableFuture
java.util.concurrent.CompletableFuture<java.lang.Void> connectAsync(java.lang.String host, int port)
connectAsync(String,int,long,long,TimeUnit)
that specifies no retry.host
- as address or hostnameport
- port numberCompletableFuture
java.util.List<java.net.InetSocketAddress> connectedHosts()
Address and port will be present; host name may not be, depending on timing of reverse DNS lookup.
InetSocketAddress
java.lang.String clusterBuildString()
java.lang.Object[] clusterInstanceId()
java.util.concurrent.CompletableFuture<ClientResponse> callProcedureAsync(java.lang.String procName, java.lang.Object... parameters)
CompletableFuture
which can be used to retrieve the ClientResponse
when the
request completes.procName
- procedure nameparameters
- as required by the procedureCompletableFuture
ClientResponse
ClientResponse callProcedureSync(java.lang.String procName, java.lang.Object... parameters) throws java.io.IOException, ProcCallException
ClientResponse
.
A ProcCallException
is raised if the response status was other
than success.procName
- procedure nameparameters
- as required by the procedureClientResponse
java.io.IOException
- server communication errorProcCallException
- the procedure call failedClientResponse
,
ProcCallException
,
NoConnectionsException
java.util.concurrent.CompletableFuture<ClientResponse> callProcedureAsync(Client2CallOptions options, java.lang.String procName, java.lang.Object... parameters)
options
- a Client2CallOptions
objectprocName
- procedure nameparameters
- as required by the procedureCompletableFuture
callProcedureAsync(String,Object...)
,
Client2CallOptions
,
ClientResponse
ClientResponse callProcedureSync(Client2CallOptions options, java.lang.String procName, java.lang.Object... parameters) throws java.io.IOException, ProcCallException
options
- a Client2CallOptions
objectprocName
- procedure nameparameters
- as required by the procedureClientResponse
java.io.IOException
- server communication errorProcCallException
- the procedure call failedcallProcedureSync(String,Object...)
,
Client2CallOptions
,
ClientResponse
,
ProcCallException
,
NoConnectionsException
java.util.concurrent.CompletableFuture<ClientResponseWithPartitionKey[]> callAllPartitionProcedureAsync(Client2CallOptions options, java.lang.String procName, java.lang.Object... parameters)
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.
options
- a Client2CallOptions
object (null if not needed)procName
- procedure nameparameters
- as required by the procedureCompletableFuture
Client2CallOptions
,
ClientResponseWithPartitionKey
ClientResponseWithPartitionKey[] callAllPartitionProcedureSync(Client2CallOptions options, java.lang.String procName, java.lang.Object... parameters) throws java.io.IOException
See callAllPartitionProcedureAsync(Client2CallOptions, String, Object...)
for more detail.
Unlike other synchronous procedure calls, callAllPartitionProcedureSync
does not throw a ProcCallException
on a failure response. The application
should check all response statuses.
options
- a Client2CallOptions
object (null if not needed)procName
- procedure nameparameters
- as required by the procedureClientResponseWithPartitionKey
)java.io.IOException
- server communication errorClient2CallOptions
,
ClientResponse
void drain() throws java.lang.InterruptedException
java.lang.InterruptedException
- if the wait is interruptedvoid close()
May call drain()
if application did not
already do so,
close
in interface java.lang.AutoCloseable
close
in interface java.io.Closeable
ClientStatsContext createStatsContext()
ClientStatsContext
createdClientStatsContext
org.voltdb.client.VoltBulkLoader.VoltBulkLoader newBulkLoader(java.lang.String tableName, int maxBatchSize, boolean upsertMode, org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback, org.voltdb.client.VoltBulkLoader.BulkLoaderSuccessCallback successCallback) throws java.lang.Exception
VoltBulkLoader
bound to this client. Multiple instances of a VoltBulkLoader
created by a single client will share some resources, particularly if
they are inserting into the same table.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)VoltBulkLoader
instancejava.lang.Exception
- if tableName can't be found in the catalog.boolean waitForTopology(long timeout, java.util.concurrent.TimeUnit unit)
timeout
- time limit on waitingunit
- time unit for timeout