org.voltdb.client

Interface Client2

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable

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.

See Also:

ClientFactory, Client2Config, Client2CallOptions, Client2Notification

Method Summary

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 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.

Method Detail

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 requests

warning - the level at which backpressure starts

resume - the level at which backpressure ends

See Also:

Client2Config, Client2Notification.RequestBackpressure

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:

Client2Config

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

void connectSync(java.lang.String servers,
                 long timeout,
                 long delay,
                 java.util.concurrent.TimeUnit unit)
          throws java.io.IOException

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 port

timeout - overall timeout

delay - time between retries

unit - units in which timeout and delay are expressed

Throws:

java.io.IOException - server communication error

connectSync

void connectSync(java.lang.String servers)
          throws java.io.IOException

Convenient form of connectSync(String,long,long,TimeUnit) that specifies no retry.

Parameters:

servers - list of servers, each as host and optional port

Throws:

java.io.IOException - server communication error

connectSync

void connectSync(java.lang.String host,
                 int port,
                 long timeout,
                 long delay,
                 java.util.concurrent.TimeUnit unit)
          throws java.io.IOException

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 hostname

port - port number

timeout - overall timeout

delay - time between retries

unit - units in which timeout and delay are expressed

Throws:

java.io.IOException - server communication error

connectSync

void connectSync(java.lang.String host,
                 int port)
          throws java.io.IOException

Convenient form of connectSync(String,int,long,long,TimeUnit) that specifies no retry.

Parameters:

host - as address or hostname

port - port number

Throws:

java.io.IOException - server communication error

connectAsync

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.

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 port

timeout - overall timeout

delay - time between retries

unit - units in which timeout and delay are expressed

Returns:

a CompletableFuture

connectAsync

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.

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 hostname

port - port number

timeout - overall timeout

delay - time between retries

unit - units in which timeout and delay are expressed

Returns:

a CompletableFuture

connectedHosts

java.util.List<java.net.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

java.lang.String clusterBuildString()

Returns the 'build string' for the most-recently connected VoltDB cluster.

Returns:

build string (null if never connected)

clusterInstanceId

java.lang.Object[] clusterInstanceId()

Returns the 'instance id' for the most-recently connected VoltDB cluster.

Returns:

array: formation timestamp, leader address

callProcedureAsync

java.util.concurrent.CompletableFuture<ClientResponse> callProcedureAsync(java.lang.String procName,
                                                                          java.lang.Object... parameters)

Asynchronously call stored procedure. This call initiates a request and returns immediately. The return value is a CompletableFuture which can be used to retrieve the ClientResponse when the request completes.

Parameters:

procName - procedure name

parameters - as required by the procedure

Returns:

a CompletableFuture

See Also:

ClientResponse

callProcedureSync

ClientResponse callProcedureSync(java.lang.String procName,
                                 java.lang.Object... parameters)
                          throws java.io.IOException,
                                 ProcCallException

Synchronously call stored procedure. This call initiates a request and waits for completion. The return value is the ClientResponse. A ProcCallException is raised if the response status was other than success.

Parameters:

procName - procedure name

parameters - as required by the procedure

Returns:

the ClientResponse

Throws:

java.io.IOException - server communication error

ProcCallException - the procedure call failed

See Also:

ClientResponse, ProcCallException, NoConnectionsException

callProcedureAsync

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.

Parameters:

options - a Client2CallOptions object

procName - procedure name

parameters - as required by the procedure

Returns:

a CompletableFuture

See Also:

callProcedureAsync(String,Object...), Client2CallOptions, ClientResponse

callProcedureSync

ClientResponse callProcedureSync(Client2CallOptions options,
                                 java.lang.String procName,
                                 java.lang.Object... parameters)
                          throws java.io.IOException,
                                 ProcCallException

Synchronously call stored procedure with optional overrides for selected values.

Parameters:

options - a Client2CallOptions object

procName - procedure name

parameters - as required by the procedure

Returns:

the ClientResponse

Throws:

java.io.IOException - server communication error

ProcCallException - the procedure call failed

See Also:

callProcedureSync(String,Object...), Client2CallOptions, ClientResponse, ProcCallException, NoConnectionsException

callAllPartitionProcedureAsync

java.util.concurrent.CompletableFuture<ClientResponseWithPartitionKey[]> callAllPartitionProcedureAsync(Client2CallOptions options,
                                                                                                        java.lang.String procName,
                                                                                                        java.lang.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 - a Client2CallOptions object (null if not needed)

procName - procedure name

parameters - as required by the procedure

Returns:

a CompletableFuture

See Also:

Client2CallOptions, ClientResponseWithPartitionKey

callAllPartitionProcedureSync

ClientResponseWithPartitionKey[] callAllPartitionProcedureSync(Client2CallOptions options,
                                                               java.lang.String procName,
                                                               java.lang.Object... parameters)
                                                        throws java.io.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 a ProcCallException on a failure response. The application should check all response statuses.

Parameters:

options - a Client2CallOptions object (null if not needed)

procName - procedure name

parameters - as required by the procedure

Returns:

an array of client responses, one per partition (ClientResponseWithPartitionKey)

Throws:

java.io.IOException - server communication error

See Also:

Client2CallOptions, ClientResponse

drain

void drain()
    throws java.lang.InterruptedException

Drain all requests. This may block, and does not return until there are no more requests pending in the client.

Throws:

java.lang.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 interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

createStatsContext

ClientStatsContext createStatsContext()

Statistics support: returns a statistics context associated with this client.

Returns:

the ClientStatsContext created

See Also:

ClientStatsContext

newBulkLoader

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

Creates a new instance of a 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.

Parameters:

tableName - table to which bulk inserts are to be applied

maxBatchSize - size of a batch for bulk insert calls

upsertMode - set to true for upsert instead of insert

failureCallback - callback used for failure notification

successCallback - callback on successful loads (null ok)

Returns:

the VoltBulkLoader instance

Throws:

java.lang.Exception - if tableName can't be found in the catalog.

waitForTopology

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. This is primarily of internal interest to bulk loaders. It is inherently synchronous.

Parameters:

timeout - time limit on waiting

unit - time unit for timeout

Returns:

true if topology information available