Package org.voltdb.client

Interface Client

public interface Client
Java client API, version 1; see also the more recent Client2 API.

A Client that connects to one or more nodes in a VoltDB cluster and provides methods for invoking stored procedures and receiving responses.

Each client instance is normally backed by a single thread that is responsible for writing requests to, and reading responses from the network, as well as invoking callbacks for stored procedures that are invoked asynchronously.

There is an upper limit on the capacity of a single client instance, and it may be necessary to use a pool of instances to get the best throughput and latency. If a heavyweight client instance is requested it will be backed by multiple threads, but under the current implementation it is better to use multiple single threaded instances.

Because callbacks are invoked directly on the network thread, the performance of the client is sensitive to the amount of work and blocking done in callbacks. If there is any question about whether callbacks will block or take a long time, then an application should have callbacks hand off processing to a thread pool controlled by the application.

See Also:

  • Field Details

    • VOLTDB_SERVER_PORT

      static final int VOLTDB_SERVER_PORT
      Default non-admin port number for volt cluster instances.
      See Also:

  • Method Details

    • createConnection

      void createConnection(String host) throws UnknownHostException, IOException
      Create a connection to a VoltDB node, and add it to the set of connections. This is a synchronous operation.
      Parameters:
      host - Hostname or IP address of the target host, including optional port in host:port format.
      Throws:
      UnknownHostException - if the hostname can't be resolved.
      IOException - if there is a Java network or connection problem.

    • createConnection

      void createConnection(String host, int port) throws UnknownHostException, IOException
      Create a connection to a VoltDB node, and add it to the set of connections. This is a synchronous operation.
      Parameters:
      host - Hostname or IP address of the target host.
      port - Port number on target host to.
      Throws:
      UnknownHostException - if the hostname can't be resolved.
      IOException - if there is a Java network or connection problem.

    • createAnyConnection

      void createAnyConnection(String hostList) throws IOException
      Create a connection to the first available VoltDB node from a specified list. Each entry in the list is an address or hostname, optionally followed by a port number, as for createConnection(String). Entries are separated by commas.
      Parameters:
      hostList - comma-list of host specifications
      Throws:
      IOException - if there is a Java network or connection problem.

    • createAnyConnection

      void createAnyConnection(String hostList, long timeout, long delay) throws IOException
      Create a connection to the first available VoltDB node from a specified list. Each entry in the list is an address or hostname, optionally followed by a port number, as for createConnection(String). Entries are separated by commas.

      If no connection can be made to any of the specified hosts, then this method can retry connecting after a specified delay and until a timeout has expired. The timeout is only checked at the end of each complete pass through the host list.

      Not all errors are likely to be recoverable on retry. Therefore, only IOException, not including UnknownHostException will be retried. If a particular host produces such an error, it will be ignored on subsequent retries.

      Connection progress may be monitored via a ClientStatusListenerExt. The connectionCreated method will be invoked with a status of either UNABLE_TO_CONNECT or SUCCESS.

      Parameters:
      hostList - comma-list of host specifications
      timeout - approximate limit on retrying (millisecs)
      delay - wait time between retries (millisecs)
      Throws:
      IOException - if there is a Java network or connection problem.

    • callProcedure

      ClientResponse callProcedure(String procName, Object... parameters) throws IOException, NoConnectionsException, ProcCallException
      Invoke a procedure. This is a synchronous call: it blocks until a result is available.

      A ProcCallException is thrown if the response is anything other than success.

      Parameters:
      procName - class name (not qualified by package) of the procedure to execute.
      parameters - vararg list of procedure's parameter values.
      Returns:
      ClientResponse instance of procedure call results.
      Throws:
      ProcCallException - on any VoltDB-specific failure.
      NoConnectionsException - if this Client instance is not connected to any servers.
      IOException - if there is a Java network or connection problem.

    • callProcedure

      boolean callProcedure(ProcedureCallback callback, String procName, Object... parameters) throws IOException, NoConnectionsException
      Asynchronously invoke a procedure. This call will return when the request has been queued, or if the request cannot be queued within the configured timeout. Check the return value to determine if queueing actually took place.

      The caller provides a callback procedure that will be invoked when a result is available. The callback is executed in a dedicated network thread. See the Client class documentation for information on the negative performance impact of slow or blocking callbacks.

      If there is backpressure this call can in some circumstances block until the invocation is queued. This can be avoided by using setNonblockingAsync in the client configuration, in which case callProcedure will return false immediately.

      Parameters:
      callback - ProcedureCallback that will be invoked with procedure results.
      procName - class name (not qualified by package) of the procedure to execute.
      parameters - vararg list of procedure's parameter values.
      Returns:
      true if the procedure was queued and false otherwise.
      Throws:
      NoConnectionsException - if this Client instance is not connected to any servers.
      IOException - if there is a Java network or connection problem.

    • callProcedureWithTimeout

      ClientResponse callProcedureWithTimeout(int queryTimeout, String procName, Object... parameters) throws IOException, NoConnectionsException, ProcCallException
      Invoke a procedure with specified query timeout. This is a synchronous call: it blocks until a result is available.

      The specified query timeout applies to a read-only query or batch of read-only queries, and may override the global querytimeout value in the VoltDB cluster's configuration file. Only callers with admin privilege are permitted to use a timeout longer than the global setting.

      A query timeout of zero means there is no timeout applied to the query or batch of queries.

      For more details, refer to callProcedure(String, Object...).

      Parameters:
      queryTimeout - timeout (in milliseconds) for read-only queries or batches of queries.
      procName - class name (not qualified by package) of the procedure to execute.
      parameters - vararg list of procedure's parameter values.
      Returns:
      ClientResponse instance of procedure call results.
      Throws:
      ProcCallException - on any VoltDB-specific failure.
      NoConnectionsException - if this Client instance is not connected to any servers.
      IOException - if there is a Java network or connection problem.

    • callProcedureWithTimeout

      boolean callProcedureWithTimeout(ProcedureCallback callback, int queryTimeout, String procName, Object... parameters) throws IOException, NoConnectionsException
      Asynchronously invoke a procedure with specified query timeout. This call will return when the request has been queued, or if the request cannot be queued within the configured timeout. Check the return value to determine if queueing actually took place.

      The specified query timeout applies to a read-only query or batch of read-only queries, and may override the global querytimeout value in the VoltDB cluster's configuration file. Only callers with admin privilege are permitted to use a timeout longer than the global setting.

      A query timeout of zero means there is no timeout applied to the query or batch of queries.

      For more details, refer to callProcedure(ProcedureCallback, String, Object...).

      Parameters:
      callback - ProcedureCallback that will be invoked with procedure results.
      queryTimeout - timeout (in milliseconds) for read-only queries or batches of queries.
      procName - class name (not qualified by package) of the procedure to execute.
      parameters - vararg list of procedure's parameter values.
      Returns:
      true if the procedure was queued and false otherwise.
      Throws:
      NoConnectionsException - if this Client instance is not connected to any servers.
      IOException - if there is a Java network or connection problem.

    • callProcedureWithClientTimeout

      ClientResponse callProcedureWithClientTimeout(int queryTimeout, String procName, long clientTimeout, TimeUnit unit, Object... parameters) throws IOException, NoConnectionsException, ProcCallException
      Synchronously invoke a procedure call, blocking until a result is available, with caller-specified client timeout and query timeout.

      The client timeout overrides the default set up by ClientConfig.setProcedureCallTimeout(long).

      See callProcedureWithTimeout(int, String, Object...) for details of the query timeout.

      Parameters:
      queryTimeout - timeout (in milliseconds) for read-only queries or batches of queries
      procName - class name (not qualified by package) of the procedure to execute.
      clientTimeout - timeout for the procedure
      unit - TimeUnit of procedure timeout
      parameters - vararg list of procedure's parameter values.
      Returns:
      ClientResponse for execution.
      Throws:
      ProcCallException - on any VoltDB-specific failure.
      NoConnectionsException - if this Client instance is not connected to any servers.
      IOException - if there is a Java network or connection problem.

    • callProcedureWithClientTimeout

      boolean callProcedureWithClientTimeout(ProcedureCallback callback, int queryTimeout, String procName, long clientTimeout, TimeUnit clientTimeoutUnit, Object... parameters) throws IOException, NoConnectionsException
      Asynchronously invoke a procedure call with specified client and query timeouts.

      The client timeout overrides the default set up by ClientConfig.setProcedureCallTimeout(long).

      See callProcedureWithTimeout(ProcedureCallback, int, String, Object...) for details of the query timeout.

      Parameters:
      callback - TransactionCallback that will be invoked with procedure results.
      queryTimeout - timeout (in milliseconds) for read-only queries or batches of queries
      procName - class name (not qualified by package) of the procedure to execute.
      clientTimeout - query timeout
      clientTimeoutUnit - units for query timeout
      parameters - vararg list of procedure's parameter values.
      Returns:
      True if the procedure was queued and false otherwise
      Throws:
      NoConnectionsException - if this Client instance is not connected to any servers.
      IOException - if there is a Java network or connection problem.

    • updateClasses

      ClientResponse updateClasses(File jarPath, String classesToDelete) throws IOException, NoConnectionsException, ProcCallException
      Synchronously updates class definitions in the VoltDB database. Blocks until a result is available. A ProcCallException is thrown if the response is anything other than success.

      This method is a convenience method that calls through to UpdateClasses.update(Client,File,String)

      Parameters:
      jarPath - Path to the jar file containing new/updated classes.
      classesToDelete - comma-separated list of classes to delete.
      Returns:
      ClientResponse instance of procedure call results.
      Throws:
      IOException - If the files cannot be serialized or if there is a Java network error.
      NoConnectionsException - if this Client instance is not connected to any servers.
      ProcCallException - on any VoltDB specific failure.

    • updateClasses

      boolean updateClasses(ProcedureCallback callback, File jarPath, String classesToDelete) throws IOException, NoConnectionsException
      Asynchronously updates class definitions in the VoltDB database. Does not guarantee that the invocation was actually queued: check the return value to determine if queuing actually took place.

      This method is a convenience method that calls through to UpdateClasses.update(Client,ProcedureCallback,File,String)

      Parameters:
      callback - ProcedureCallback that will be invoked with procedure results.
      jarPath - Path to the jar file containing new/updated classes. May be null.
      classesToDelete - comma-separated list of classes to delete. May be null.
      Returns:
      true if the procedure was queued and false otherwise.
      Throws:
      IOException - If the files cannot be serialized or if there is a Java network error.
      NoConnectionsException - if this Client instance is not connected to any servers.

    • drain

      void drain() throws NoConnectionsException, InterruptedException
      Block the current thread until all queued stored procedure invocations have received responses, or there are no more connections to the cluster.
      Throws:
      NoConnectionsException - never; declared only for backward compatibility.
      InterruptedException - if this blocking call is interrupted.

    • close

      void close() throws InterruptedException
      Shut down this Client, closing all network connections and releasing all memory resources. A client cannot be used once it has been closed.

      You should call this before the Ciient is garbage-collected. Failure to do so can generate errors, as finalization is used to detect resource leaks.

      Throws:
      InterruptedException - if call is interrupted before it finishes.

    • backpressureBarrier

      void backpressureBarrier() throws InterruptedException
      Blocks the current thread until there is no more backpressure, or there are no more connections to the database

      This method may be used to block execution after one of the async callProceedure methods has returned false, indicating that the procedure could not be queued.

      Throws:
      InterruptedException - if this blocking call is interrupted.

    • createStatsContext

      ClientStatsContext createStatsContext()
      Get a ClientStatsContext instance to fetch and process performance statistics. Each instance is linked to this client, but provides a custom view of statistics for a desired time period.
      Returns:
      Statistics context object linked to this client.
      See Also:

    • getInstanceId

      Object[] getInstanceId()
      Get an identifier for the cluster to which this client is currently connected. This will be null if the client has not been connected. Currently these values have logical meaning, but they should just be interpreted as a unique per-cluster value.
      Returns:
      An array of a Long and Integer containing the millisecond timestamp when the cluster was started and the leader IP address (mapped as an unsigned int).

    • getBuildString

      String getBuildString()
      Retrieve the build string that was provided by the server at connection time.
      Returns:
      Volt server build string.

    • getThroughputAndOutstandingTxnLimits

      int[] getThroughputAndOutstandingTxnLimits()
      Get the instantaneous values of the rate-limiting values for this client.
      Returns:
      An array of two integers, representing max throughput/sec and max outstanding txns.

    • getConnectedHostList

      List<InetSocketAddress> getConnectedHostList()
      Get the list of VoltDB server hosts to which this client has open TCP connections. Note that this doesn't guarantee that those nodes are actually alive at the precise moment this method is called. There is also a race condition between calling this method and acting on the results.
      Returns:
      A list of InetSocketAddress representing the connected hosts.

    • isAutoReconnectEnabled

      boolean isAutoReconnectEnabled()
      This returns the same value as the isTopologyChangeAwareEnabled() method, which is now preferred. Auto-reconnection is part of topology-change awareness.
      Returns:
      if topology change awareness is enabled.
      See Also:

    • isTopologyChangeAwareEnabled

      boolean isTopologyChangeAwareEnabled()
      Tell whether Client has turned on the topologyChangeAware feature. If it is on, Client attempts to connect to all nodes in the cluster as they are discovered, and will automatically try to reconnect failed connections.
      Returns:
      true if the client wants to use topologyChangeAware feature.

    • writeSummaryCSV

      void writeSummaryCSV(String statsRowName, ClientStats stats, String path) throws IOException
      Append a single line of comma-separated values to the file specified. Used mainly for collecting results from benchmarks.

      This is a convenience method that calls through to ClientStatsUtil.writeSummaryCSV(String,ClientStats,String), which you should see for details of the output format.

      Parameters:
      statsRowName - give the client stats row an identifiable name
      stats - ClientStats instance with relevant stats
      path - path of CSV file
      Throws:
      IOException - on any file write error

    • writeSummaryCSV

      void writeSummaryCSV(ClientStats stats, String path) throws IOException
      Append a single line of comma separated values to the file specified. Used mainly for collecting results from benchmarks.

      This is a convenience method that calls through to ClientStatsUtil.writeSummaryCSV(ClientStats,String), which you should see for details of the output format.

      Parameters:
      stats - ClientStats instance with relevant stats
      path - path of CSV file
      Throws:
      IOException - on any file write error

    • getNewBulkLoader

      org.voltdb.client.VoltBulkLoader.VoltBulkLoader getNewBulkLoader(String tableName, int maxBatchSize, boolean upsert, org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback) throws Exception
      Creates a new instance of a VoltBulkLoader that is 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 - Name of table that bulk inserts are to be applied to.
      maxBatchSize - Batch size to collect for the table before pushing a bulk insert.
      upsert - set to true if want upsert instead of insert
      failureCallback - Callback procedure used for notification any failures.
      Returns:
      instance of VoltBulkLoader
      Throws:
      Exception - if tableName can't be found in the catalog.

    • getNewBulkLoader

      org.voltdb.client.VoltBulkLoader.VoltBulkLoader getNewBulkLoader(String tableName, int maxBatchSize, org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback) throws Exception
      Throws:
      Exception

    • getNewBulkLoader

      org.voltdb.client.VoltBulkLoader.VoltBulkLoader getNewBulkLoader(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 that is 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 - Name of table that bulk inserts are to be applied to.
      maxBatchSize - Batch size to collect for the table before pushing a bulk insert.
      upsertMode - set to true if want upsert instead of insert
      failureCallback - Callback procedure used for notification any failures.
      successCallback - Callback for notifications on successful load operations.
      Returns:
      instance of VoltBulkLoader
      Throws:
      Exception - if tableName can't be found in the catalog.

    • waitForTopology

      boolean waitForTopology(long timeout)
      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.
      Parameters:
      timeout - timeout in milliseconds
      Returns:
      true if client has determined cluster topology.

    • callAllPartitionProcedure

      ClientResponseWithPartitionKey[] callAllPartitionProcedure(String procedureName, Object... params) throws IOException, NoConnectionsException, ProcCallException
      Synchronously execute a stored procedure on a set of partitions, one partition at a time.

      The method uses system procedure @GetPartitionKeys to get a set of partition values, and then execute the stored procedure one partition at a time, returning an aggregated response. It blocks until results are available.

      The set of partition values is cached to avoid repeated requests to fetch them. The cached set will be updated when database cluster topology is updated, but it is possibly for it to be briefly out of sync. Exactly once per partition cannot be guaranteed.

      There may be undesirable impact on latency and throughput as a result of running a multi-partition procedure. This is particularly true for longer running procedures. Using multiple, smaller procedures can also help reducing latency and increasing throughput, for queries that modify large volumes of data, such as large deletes. For example, multiple smaller single partition procedures are particularly useful to age out large stale data where strong global consistency is not required.

      When creating a single-partitioned procedure, you can use the PARAMETER clause to specify the partitioning parameter which is used to determine the target partition. PARAMETER should not be specified in the stored procedure used in this call, since the stored procedure will be executed on every partition. If you only want to execute the procedure in the partition designated by PARAMETER, use callProcedure(String, Object...) instead.

      When creating a stored procedure class, the first argument in the procedure's run method must be the partition key, which matches the partition column type, followed by the parameters as declared in the procedure. The argument partition key, not part of procedure's parameters, is assigned during the iteration of the partition set.

      Example: A stored procedure with a parameter of long type and partition column of string type 

         CREATE TABLE tableWithStringPartition (id bigint NOT NULL,value_string varchar(50) NOT NULL,
                                          value1 bigint NOT NULL,value2 bigint NOT NULL);
   PARTITION TABLE tableWithStringPartition ON COLUMN value_string;
   CREATE PROCEDURE FROM CLASS example.Everywhere;
   PARTITION PROCEDURE Everywhere ON TABLE tableWithStringPartition COLUMN value_string;
 
          public class Everywhere extends VoltProcedure {
         public final SQLStmt stmt = new SQLStmt("SELECT count(*) FROM tableWithStringPartition where value1 > ?;");
         public VoltTable[] run(String partitionKey, long value1) {
              voltQueueSQL(stmt, value1);
              return voltExecuteSQL(true);
         }
    }

      The execution of the stored procedure may fail on one or more partitions. Thus check the status of the response on every partition.

      Parameters:
      procedureName - class name (not qualified by package) of the partitioned java procedure to execute.
      params - vararg list of procedure's parameter values.
      Returns:
      ClientResponseWithPartitionKey instances of procedure call results.
      Throws:
      ProcCallException - on any VoltDB specific failure.
      NoConnectionsException - if this Client instance is not connected to any servers.
      IOException - if there is a Java network or connection problem.

    • callAllPartitionProcedure

      boolean callAllPartitionProcedure(AllPartitionProcedureCallback callback, String procedureName, Object... params) throws IOException, NoConnectionsException, ProcCallException
      Asynchronously execute a stored procedure on a set of partitions, one partition at a time.

      See the synchronous form, callAllPartitionProcedure(String, Object...), for more details.

      Parameters:
      callback - AllPartitionProcedureCallback that will be invoked with procedure results.
      procedureName - class name (not qualified by package) of the partitioned java procedure to execute.
      params - vararg list of procedure's parameter values.
      Returns:
      false if the procedures on all partition are not queued and true otherwise.
      Throws:
      NoConnectionsException - if this Client instance is not connected to any servers.
      IOException - if there is a Java network or connection problem.
      ProcCallException - on any VoltDB specific failure.