Calling stored procedures synchronously simplifies the program logic because your client application waits for the procedure to complete before continuing. However, for high performance applications looking to maximize throughput, it is better to queue stored procedure invocations asynchronously.
To invoke stored procedures asynchronously, use the callProcedure() method with an additional first
argument, a callback that will be notified when the procedure completes (or an error occurs). For example, to invoke a
NewCustomer() stored procedure asynchronously, the call to callProcedure() might look
like the following:
Documentationclient.callProcedure(new MyCallback(),
"NewCustomer",
firstname,
lastname,
custID};The following are other important points to note when making asynchronous invocations of stored procedures:
Asynchronous calls to callProcedure() return control to the calling application as soon as the
procedure call is queued.
If the database server queue is full, callProcedure() will block until it is able to queue the
procedure call. This is a condition known as backpressure. This situation does not normally happen unless the database
cluster is not scaled sufficiently for the workload or there are abnormal spikes in the workload. See Section 6.5.3, “Writing a Status Listener to Interpret Other Errors” for more information.
Once the procedure is queued, any subsequent errors (such as an exception in the stored procedure itself or loss of connection to the database) are returned as error conditions to the callback procedure.
The callback procedure (MyCallback() in this example) is invoked after the stored procedure
completes on the server. The following is an example of a callback procedure implementation:
static class MyCallback implements ProcedureCallback {
@Override
public void clientCallback(ClientResponse clientResponse) {
if (clientResponse.getStatus() != ClientResponse.SUCCESS) {
System.err.println(clientResponse.getStatusString());
} else {
myEvaluateResultsProc(clientResponse.getResults());
}
}
}The callback procedure is passed the same ClientResponse structure that is returned in a
synchronous invocation. ClientResponse contains information about the results of execution. In
particular, the methods getStatus() and getResults() let your callback procedure
determine whether the stored procedure was successful and evaluate the results of the procedure.
The VoltDB Java client is single threaded, so callback procedures are processed one at a time. Consequently, it is a good practice to keep processing in the callback to a minimum, returning control to the main thread as soon as possible. If more complex processing is required by the callback, creating a separate thread pool and spawning worker methods on a separate thread from within the asynchronous callback is recommended.