Package org.voltdb.client

Interface Client2

All Superinterfaces:
AutoCloseable, Closeable
public interface Client2 extends Closeable
Java client API, version 2: a more modern replacement for the earlier Client API.

The advantages of Client2 include:

  • Use of CompletableFuture for familiarity and flexibility.
  • Asynchronous calls that queue a request and immediately return.
  • Internal handling of network backpressure events.
  • A simple and comprehensive set of event notifications.
  • A builder pattern for the associated Client2Config class.

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:

  • 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 requests
      warning - the level at which backpressure starts
      resume - 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

      void connectSync(String servers, long timeout, long delay, TimeUnit unit) throws 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:
      IOException - server communication error

    • connectSync

      void connectSync(String servers) throws 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:
      IOException - server communication error

    • connectSync

      void connectSync(String host, int port, long timeout, long delay, TimeUnit unit) throws 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:
      IOException - server communication error

    • connectSync

      void connectSync(String host, int port) throws IOException
      Convenient form of connectSync(String,int,long,long,TimeUnit) that specifies no retry.
      Parameters:
      host - as address or hostname
      port - port number
      Throws:
      IOException - server communication error

    • connectAsync

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

      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

      CompletableFuture<Void> connectAsync(String servers)
      Convenient form of connectAsync(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 hostname
      port - port number
      timeout - overall timeout
      delay - time between retries
      unit - units in which timeout and delay are expressed
      Returns:
      a CompletableFuture

    • connectAsync

      CompletableFuture<Void> connectAsync(String host, int port)
      Convenient form of connectAsync(String,int,long,long,TimeUnit) that specifies no retry.
      Parameters:
      host - as address or hostname
      port - 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

      CompletableFuture<ClientResponse> callProcedureAsync(String procName, 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:

    • 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 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:
      IOException - server communication error
      ProcCallException - 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 - a Client2CallOptions object
      procName - procedure name
      parameters - 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 - a Client2CallOptions object
      procName - procedure name
      parameters - as required by the procedure
      Returns:
      the ClientResponse
      Throws:
      IOException - server communication error
      ProcCallException - 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 - a Client2CallOptions object (null if not needed)
      procName - procedure name
      parameters - 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 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:
      IOException - server communication error
      See Also:

    • drain

      void drain() throws InterruptedException
      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 interface AutoCloseable
      Specified by:
      close in interface Closeable

    • 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 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:
      Exception - if tableName can't be found in the catalog.

    • waitForTopology

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