public 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.
Modifier and Type | Field and Description |
---|---|
static int |
VOLTDB_SERVER_PORT
Default non-admin port number for volt cluster instances.
|
Modifier and Type | Method and Description |
---|---|
void |
backpressureBarrier()
Blocks the current thread until there is no more backpressure,
or there are no more connections to the database
|
boolean |
callAllPartitionProcedure(AllPartitionProcedureCallback callback,
java.lang.String procedureName,
java.lang.Object... params)
Asynchronously execute a stored procedure on a set of partitions, one partition at a time.
|
ClientResponseWithPartitionKey[] |
callAllPartitionProcedure(java.lang.String procedureName,
java.lang.Object... params)
Synchronously execute a stored procedure on a set of partitions, one partition at a time.
|
boolean |
callProcedure(ProcedureCallback callback,
java.lang.String procName,
java.lang.Object... parameters)
Asynchronously invoke a procedure.
|
ClientResponse |
callProcedure(java.lang.String procName,
java.lang.Object... parameters)
Invoke a procedure.
|
ClientResponse |
callProcedureWithClientTimeout(int queryTimeout,
java.lang.String procName,
long clientTimeout,
java.util.concurrent.TimeUnit unit,
java.lang.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,
java.lang.String procName,
long clientTimeout,
java.util.concurrent.TimeUnit clientTimeoutUnit,
java.lang.Object... parameters)
Asynchronously invoke a procedure call with specified client and query timeouts.
|
ClientResponse |
callProcedureWithTimeout(int queryTimeout,
java.lang.String procName,
java.lang.Object... parameters)
Invoke a procedure with specified query timeout.
|
boolean |
callProcedureWithTimeout(ProcedureCallback callback,
int queryTimeout,
java.lang.String procName,
java.lang.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(java.lang.String hostList)
Create a connection to the first available VoltDB node
from a specified list.
|
void |
createAnyConnection(java.lang.String hostList,
long timeout,
long delay)
Create a connection to the first available VoltDB node
from a specified list.
|
void |
createConnection(java.lang.String host)
Create a connection to a VoltDB node, and add it to the set
of connections.
|
void |
createConnection(java.lang.String host,
int port)
Create a connection to a VoltDB node, and add it to the set
of connections.
|
ClientStatsContext |
createStatsContext()
Get a
ClientStatsContext 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.
|
java.lang.String |
getBuildString()
Retrieve the build string that was provided by the server at connection time.
|
java.util.List<java.net.InetSocketAddress> |
getConnectedHostList()
Get the list of VoltDB server hosts to which this client has open TCP
connections.
|
java.lang.Object[] |
getInstanceId()
Get an identifier for the cluster to which this client is currently connected.
|
org.voltdb.client.VoltBulkLoader.VoltBulkLoader |
getNewBulkLoader(java.lang.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(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 that is bound to this Client.
|
org.voltdb.client.VoltBulkLoader.VoltBulkLoader |
getNewBulkLoader(java.lang.String tableName,
int maxBatchSize,
org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback) |
int[] |
getThroughputAndOutstandingTxnLimits()
Get the instantaneous values of the rate-limiting values for this client.
|
boolean |
isAutoReconnectEnabled()
Tell whether Client has turned on the auto-reconnect feature.
|
boolean |
isTopologyChangeAwareEnabled()
Tell whether Client has turned on the topologyChangeAware feature.
|
ClientResponse |
updateClasses(java.io.File jarPath,
java.lang.String classesToDelete)
Synchronously updates class definitions in the VoltDB database.
|
boolean |
updateClasses(ProcedureCallback callback,
java.io.File jarPath,
java.lang.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(ClientStats stats,
java.lang.String path)
Append a single line of comma separated values to the file specified.
|
void |
writeSummaryCSV(java.lang.String statsRowName,
ClientStats stats,
java.lang.String path)
Append a single line of comma-separated values to the file specified.
|
static final int VOLTDB_SERVER_PORT
void createConnection(java.lang.String host) throws java.net.UnknownHostException, java.io.IOException
host
- Hostname or IP address of the target host, including
optional port in host:port format.java.net.UnknownHostException
- if the hostname can't be resolved.java.io.IOException
- if there is a Java network or connection problem.void createConnection(java.lang.String host, int port) throws java.net.UnknownHostException, java.io.IOException
host
- Hostname or IP address of the target host.port
- Port number on target host to.java.net.UnknownHostException
- if the hostname can't be resolved.java.io.IOException
- if there is a Java network or connection problem.void createAnyConnection(java.lang.String hostList) throws java.io.IOException
createConnection(String)
.
Entries are separated by commas.hostList
- comma-list of host specificationsjava.io.IOException
- if there is a Java network or connection problem.void createAnyConnection(java.lang.String hostList, long timeout, long delay) throws java.io.IOException
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
.
hostList
- comma-list of host specificationstimeout
- approximate limit on retrying (millisecs)delay
- wait time between retries (millisecs)java.io.IOException
- if there is a Java network or connection problem.ClientResponse callProcedure(java.lang.String procName, java.lang.Object... parameters) throws java.io.IOException, NoConnectionsException, ProcCallException
A ProcCallException
is thrown if the response is anything
other than success.
procName
- class
name (not qualified by package) of the procedure to execute.parameters
- vararg list of procedure's parameter values.ClientResponse
instance of procedure call results.ProcCallException
- on any VoltDB-specific failure.NoConnectionsException
- if this Client
instance is not connected to any servers.java.io.IOException
- if there is a Java network or connection problem.boolean callProcedure(ProcedureCallback callback, java.lang.String procName, java.lang.Object... parameters) throws java.io.IOException, NoConnectionsException
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.
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.true
if the procedure was queued and false
otherwise.NoConnectionsException
- if this Client
instance is not connected to any servers.java.io.IOException
- if there is a Java network or connection problem.ClientResponse callProcedureWithTimeout(int queryTimeout, java.lang.String procName, java.lang.Object... parameters) throws java.io.IOException, NoConnectionsException, ProcCallException
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...)
.
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.ClientResponse
instance of procedure call results.ProcCallException
- on any VoltDB-specific failure.NoConnectionsException
- if this Client
instance is not connected to any servers.java.io.IOException
- if there is a Java network or connection problem.boolean callProcedureWithTimeout(ProcedureCallback callback, int queryTimeout, java.lang.String procName, java.lang.Object... parameters) throws java.io.IOException, NoConnectionsException
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...)
.
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.true
if the procedure was queued and false
otherwise.NoConnectionsException
- if this Client
instance is not connected to any servers.java.io.IOException
- if there is a Java network or connection problem.ClientResponse callProcedureWithClientTimeout(int queryTimeout, java.lang.String procName, long clientTimeout, java.util.concurrent.TimeUnit unit, java.lang.Object... parameters) throws java.io.IOException, NoConnectionsException, ProcCallException
The client timeout overrides the default set up by ClientConfig.setProcedureCallTimeout(long)
.
See callProcedureWithTimeout(int, String, Object...)
for details
of the query timeout.
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.ProcCallException
- on any VoltDB-specific failure.NoConnectionsException
- if this Client
instance is not connected to any servers.java.io.IOException
- if there is a Java network or connection problem.boolean callProcedureWithClientTimeout(ProcedureCallback callback, int queryTimeout, java.lang.String procName, long clientTimeout, java.util.concurrent.TimeUnit clientTimeoutUnit, java.lang.Object... parameters) throws java.io.IOException, NoConnectionsException
The client timeout overrides the default set up by ClientConfig.setProcedureCallTimeout(long)
.
See callProcedureWithTimeout(ProcedureCallback, int, String, Object...)
for details
of the query timeout.
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.NoConnectionsException
- if this Client
instance is not connected to any servers.java.io.IOException
- if there is a Java network or connection problem.ClientResponse updateClasses(java.io.File jarPath, java.lang.String classesToDelete) throws java.io.IOException, NoConnectionsException, ProcCallException
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)
jarPath
- Path to the jar file containing new/updated classes.classesToDelete
- comma-separated list of classes to delete.ClientResponse
instance of procedure call results.java.io.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.boolean updateClasses(ProcedureCallback callback, java.io.File jarPath, java.lang.String classesToDelete) throws java.io.IOException, NoConnectionsException
This method is a convenience method that calls through to
UpdateClasses.update(Client,ProcedureCallback,File,String)
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.true
if the procedure was queued and false
otherwise.java.io.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.void drain() throws NoConnectionsException, java.lang.InterruptedException
NoConnectionsException
- never; declared only for backward compatibility.java.lang.InterruptedException
- if this blocking call is interrupted.void close() throws java.lang.InterruptedException
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.
java.lang.InterruptedException
- if call is interrupted before it finishes.void backpressureBarrier() throws java.lang.InterruptedException
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.
java.lang.InterruptedException
- if this blocking call is interrupted.ClientStatsContext createStatsContext()
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.ClientStatsContext
java.lang.Object[] getInstanceId()
java.lang.String getBuildString()
int[] getThroughputAndOutstandingTxnLimits()
java.util.List<java.net.InetSocketAddress> getConnectedHostList()
InetSocketAddress
representing the connected hosts.boolean isAutoReconnectEnabled()
This will always return true in topology-change-aware clients.
isTopologyChangeAwareEnabled()
boolean isTopologyChangeAwareEnabled()
isAutoReconnectEnabled()
void writeSummaryCSV(java.lang.String statsRowName, ClientStats stats, java.lang.String path) throws java.io.IOException
This is a convenience method that calls through to
ClientStatsUtil.writeSummaryCSV(String,ClientStats,String)
,
which you should see for details of the output format.
statsRowName
- give the client stats row an identifiable namestats
- ClientStats
instance with relevant statspath
- path of CSV filejava.io.IOException
- on any file write errorvoid writeSummaryCSV(ClientStats stats, java.lang.String path) throws java.io.IOException
This is a convenience method that calls through to
ClientStatsUtil.writeSummaryCSV(ClientStats,String)
,
which you should see for details of the output format.
stats
- ClientStats
instance with relevant statspath
- path of CSV filejava.io.IOException
- on any file write errororg.voltdb.client.VoltBulkLoader.VoltBulkLoader getNewBulkLoader(java.lang.String tableName, int maxBatchSize, boolean upsert, org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback) throws java.lang.Exception
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.java.lang.Exception
- if tableName can't be found in the catalog.org.voltdb.client.VoltBulkLoader.VoltBulkLoader getNewBulkLoader(java.lang.String tableName, int maxBatchSize, org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback) throws java.lang.Exception
java.lang.Exception
org.voltdb.client.VoltBulkLoader.VoltBulkLoader getNewBulkLoader(java.lang.String tableName, int maxBatchSize, boolean upsertMode, org.voltdb.client.VoltBulkLoader.BulkLoaderFailureCallBack failureCallback, org.voltdb.client.VoltBulkLoader.BulkLoaderSuccessCallback successCallback) throws java.lang.Exception
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.java.lang.Exception
- if tableName can't be found in the catalog.boolean waitForTopology(long timeout)
timeout
- timeout in millisecondsClientResponseWithPartitionKey[] callAllPartitionProcedure(java.lang.String procedureName, java.lang.Object... params) throws java.io.IOException, NoConnectionsException, ProcCallException
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.
procedureName
- class
name (not qualified by package) of the partitioned java procedure to execute.params
- vararg list of procedure's parameter values.ClientResponseWithPartitionKey
instances of procedure call results.ProcCallException
- on any VoltDB specific failure.NoConnectionsException
- if this Client
instance is not connected to any servers.java.io.IOException
- if there is a Java network or connection problem.boolean callAllPartitionProcedure(AllPartitionProcedureCallback callback, java.lang.String procedureName, java.lang.Object... params) throws java.io.IOException, NoConnectionsException, ProcCallException
See the synchronous form, callAllPartitionProcedure(String, Object...)
, for more details.
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.false
if the procedures on all partition are not queued and true
otherwise.NoConnectionsException
- if this Client
instance is not connected to any servers.java.io.IOException
- if there is a Java network or connection problem.ProcCallException
- on any VoltDB specific failure.