Interface Client
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.
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
Default non-admin port number for volt cluster instances. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Blocks the current thread until there is no more backpressure, or there are no more connections to the databasecallAllPartitionProcedure
(String procedureName, Object... params) Synchronously execute a stored procedure on a set of partitions, one partition at a time.boolean
callAllPartitionProcedure
(AllPartitionProcedureCallback callback, String procedureName, Object... params) Asynchronously execute a stored procedure on a set of partitions, one partition at a time.callProcedure
(String procName, Object... parameters) Invoke a procedure.boolean
callProcedure
(ProcedureCallback callback, String procName, Object... parameters) Asynchronously invoke a procedure.callProcedureWithClientTimeout
(int queryTimeout, String procName, long clientTimeout, TimeUnit unit, Object... parameters) Synchronously invoke a procedure call, blocking until a result is available, with caller-specified client timeout and query timeout.boolean
callProcedureWithClientTimeout
(ProcedureCallback callback, int queryTimeout, String procName, long clientTimeout, TimeUnit clientTimeoutUnit, Object... parameters) Asynchronously invoke a procedure call with specified client and query timeouts.callProcedureWithTimeout
(int queryTimeout, String procName, Object... parameters) Invoke a procedure with specified query timeout.boolean
callProcedureWithTimeout
(ProcedureCallback callback, int queryTimeout, String procName, Object... parameters) Asynchronously invoke a procedure with specified query timeout.void
close()
Shut down this Client, closing all network connections and releasing all memory resources.void
createAnyConnection
(String hostList) Create a connection to the first available VoltDB node from a specified list.void
createAnyConnection
(String hostList, long timeout, long delay) Create a connection to the first available VoltDB node from a specified list.void
createConnection
(String host) Create a connection to a VoltDB node, and add it to the set of connections.void
createConnection
(String host, int port) Create a connection to a VoltDB node, and add it to the set of connections.Get aClientStatsContext
instance to fetch and process performance statistics.void
drain()
Block the current thread until all queued stored procedure invocations have received responses, or there are no more connections to the cluster.Retrieve the build string that was provided by the server at connection time.Get the list of VoltDB server hosts to which this client has open TCP connections.Object[]
Get an identifier for the cluster to which this client is currently connected.org.voltdb.client.VoltBulkLoader.VoltBulkLoader
getNewBulkLoader
(String tableName, int maxBatchSize, boolean upsert, org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback) Creates a new instance of a VoltBulkLoader that is bound to this Client.org.voltdb.client.VoltBulkLoader.VoltBulkLoader
getNewBulkLoader
(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 that is bound to this Client.org.voltdb.client.VoltBulkLoader.VoltBulkLoader
getNewBulkLoader
(String tableName, int maxBatchSize, org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback) int[]
Get the instantaneous values of the rate-limiting values for this client.boolean
This returns the same value as theisTopologyChangeAwareEnabled()
method, which is now preferred.boolean
Tell whether Client has turned on the topologyChangeAware feature.updateClasses
(File jarPath, String classesToDelete) Synchronously updates class definitions in the VoltDB database.boolean
updateClasses
(ProcedureCallback callback, File jarPath, String classesToDelete) Asynchronously updates class definitions in the VoltDB database.boolean
waitForTopology
(long timeout) Wait until the VoltDB cluster topology has been determined, which may take a few seconds after the initial connection.void
writeSummaryCSV
(String statsRowName, ClientStats stats, String path) Append a single line of comma-separated values to the file specified.void
writeSummaryCSV
(ClientStats stats, String path) Append a single line of comma separated values to the file specified.
-
Field Details
-
VOLTDB_SERVER_PORT
static final int VOLTDB_SERVER_PORTDefault non-admin port number for volt cluster instances.- See Also:
-
-
Method Details
-
createConnection
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
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
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 forcreateConnection(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
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 forcreateConnection(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 includingUnknownHostException
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
. TheconnectionCreated
method will be invoked with a status of eitherUNABLE_TO_CONNECT
orSUCCESS
.- Parameters:
hostList
- comma-list of host specificationstimeout
- 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 thisClient
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 returnfalse
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 andfalse
otherwise.- Throws:
NoConnectionsException
- if thisClient
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 thisClient
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 andfalse
otherwise.- Throws:
NoConnectionsException
- if thisClient
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 queriesprocName
- class name (not qualified by package) of the procedure to execute.clientTimeout
- timeout for the procedureunit
- TimeUnit of procedure timeoutparameters
- vararg list of procedure's parameter values.- Returns:
- ClientResponse for execution.
- Throws:
ProcCallException
- on any VoltDB-specific failure.NoConnectionsException
- if thisClient
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 queriesprocName
- class name (not qualified by package) of the procedure to execute.clientTimeout
- query timeoutclientTimeoutUnit
- units for query timeoutparameters
- vararg list of procedure's parameter values.- Returns:
- True if the procedure was queued and false otherwise
- Throws:
NoConnectionsException
- if thisClient
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. AProcCallException
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 thisClient
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 andfalse
otherwise.- Throws:
IOException
- If the files cannot be serialized or if there is a Java network error.NoConnectionsException
- if thisClient
instance is not connected to any servers.
-
drain
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
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
Blocks the current thread until there is no more backpressure, or there are no more connections to the databaseThis method may be used to block execution after one of the async
callProceedure
methods has returnedfalse
, indicating that the procedure could not be queued.- Throws:
InterruptedException
- if this blocking call is interrupted.
-
createStatsContext
ClientStatsContext createStatsContext()Get aClientStatsContext
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 theisTopologyChangeAwareEnabled()
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
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 namestats
-ClientStats
instance with relevant statspath
- path of CSV file- Throws:
IOException
- on any file write error
-
writeSummaryCSV
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 statspath
- 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 insertfailureCallback
- 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 insertfailureCallback
- 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 byPARAMETER
, usecallProcedure(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 thisClient
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 andtrue
otherwise.- Throws:
NoConnectionsException
- if thisClient
instance is not connected to any servers.IOException
- if there is a Java network or connection problem.ProcCallException
- on any VoltDB specific failure.
-