If an error occurs in a stored procedure (such as an SQL constraint violation), VoltDB catches the error and returns information about it to the calling application as part of the ClientResponse class. The ClientResponse class provides several methods to help the calling application determine whether the stored procedure completed successfully and, if not, what caused the failure. The two most important methods are getStatus() and getStatusString().

static class MyCallback implements ProcedureCallback {
  @Override
  public void clientCallback(ClientResponse clientResponse) {
    final byte AppCodeWarm = 1;
    final byte AppCodeFuzzy = 2;
    if (clientResponse.getStatus() != ClientResponse.SUCCESS) {      

        System.err.println(clientResponse.getStatusString());        
    } else {
        
        if (clientResponse.getAppStatus() == AppCodeFuzzy) {         
           System.err.println(clientResponse.getAppStatusString());
        };
        myEvaluateResultsProc(clientResponse.getResults());
    }
  }
}

/* stored procedure code */
final byte AppCodeWarm = 1;
final byte AppCodeFuzzy = 2;
              . . .
setAppStatusCode(AppCodeFuzzy);
setAppStatusString("I'm not sure about that...");
              . . .

One particular error that needs special handling is if a connection or a stored procedure call times out. By default, the client interface only waits a specified amount of time (two minutes) for a stored procedure to complete. If no response is received from the server before the timeout period expires, the client interface returns control to your application, notifying it of the error. For synchronous procedure calls, the client interface returns the error CONNECTION_TIMEOUT to the procedure call. For asynchronous calls, the client interface invokes the callback including the error information in the clientResponse object.

It is important to note that CONNECTION_TIMEOUT does not necessarily mean the synchronous procedure failed. In fact, it is very possible that the procedure may complete and return information after the timeout error is reported. The timeout is provided to avoid locking up the client application when procedures are delayed or the connection to the cluster hangs for any reason.

Similarly, if no response of any kind is returned on a connection (even if no transactions are pending) within the specified timeout period, the client connection will timeout. When this happens, the connection is closed, any open stored procedures on that connection are closed with a return status of CONNECTION_LOST, and then the client status listener callback method connectionLost() is invoked. Unlike a procedure timeout, when the connection times out, the connection no longer exists, so your client application will receive no further notifications concerning pending procedures, whether they succeed or fail.

CONNECTION_LOST does not necessarily mean a pending asynchronous procedure failed. It is possible that the procedure completed but was unable to return its status due to a connection failure. The goal of the connection timeout is to notify the client application of a lost connection in a timely manner, even if there are no outstanding procedures using the connection.

There are several things you can do to address potential timeouts in your application:

Certain types of errors can occur that the ClientResponse class cannot notify you about immediately. In these cases, an error happens and is caught by the client interface outside of the normal stored procedure execution cycle. If you want your application to address these situations, you need to create a listener, which is a special type of asynchronous callback that the client interface will notify whenever such errors occur. The types of errors that a listener addresses include:

For the sake of example, the following status listener does little more than display a message on standard output. However, in real world applications the listener would take appropriate actions based on the circumstances.

/*
*  Declare the status listener
*/
ClientStatusListenerExt mylistener = new ClientStatusListenerExt()       
  {
    @Override
    public void connectionLost(String hostname, int port,                
                               int connectionsLeft,
                               DisconnectCause cause)
      {
        System.out.printf("A connection to the database has been lost."
         + "There are %d connections remaining.\n", connectionsLeft);
      }
    @Override
    public void backpressure(boolean status)
      {
        System.out.println("Backpressure from the database "
         + "is causing a delay in processing requests.");
      }
    @Override
    public void uncaughtException(ProcedureCallback callback,
                                  ClientResponse r, Throwable e)
     {
        System.out.println("An error has occurred in a callback "
         + "procedure. Check the following stack trace for details.");
        e.printStackTrace();
     }
    @Override
    public void lateProcedureResponse(ClientResponse response,
                                   String hostname, int port)
     {
        System.out.printf("A procedure that timed out on host %s:%d"
           + " has now responded.\n", hostname, port);
     }
  };
/*
*  Declare the client configuration, specifying
*  a username, a password, and the status listener
*/
ClientConfig myconfig = new ClientConfig("username",                     
                                       "password",
                                       mylistener);
/*
*  Create the client using the specified configuration.
*/
Client myclient = ClientFactory.createClient(myconfig);                  

By performing the operations in the order as described here, you ensure that all connections to the VoltDB database cluster use the same credentials for authentication and will notify the status listener of any error conditions outside of normal procedure execution.