Exception Handling

NuoDB supports mapping from common error states to categorized SQL exceptions. This allows the JDBC programmer to better handle specific SQL error states. There are two types of categorized SQL exceptions thrown by NuoDB: SQLNonTransientException and SQLTransientException. To obtain more information about an error, use SQLException#getErrorCode().

An exception’s SQL State value (a string, often numeric) consists of a class (first two characters) and a subclass (the remaining characters). For example a deadlock has SQL State 40001, where 40 is the class and 001 is the subclass.

Non-Transient SQL Exceptions

A non-transient SQLException is thrown when a retry of the same operation would fail unless the cause of the SQL exception is corrected. Upon receiving a non-transient SQL exception, the application can assume that the connection is still valid.

SQLState Class NonTransient SQLException

08

SQLNonTransientConnectionException on initial attempt (i.e. Driver#connect())

0A

SQLFeatureNotSupportedException

22

SQLDataException

23

SQLIntegrityConstraintViolationException

28

SQLInvalidAuthorizationException

42

SQLSyntaxErrorException

Transient SQL Exceptions

A transient SQLException is thrown when a previously failed operation might be able to succeed when the operation is retried without any intervention by application-level functionality.

Common transient exceptions are deadlock, query timeout and loss of connection to the TE.

SQLState Class Transient SQLException

08

SQLTransientConnectionException on attempt where we once had a connection but no longer do

40

SQLTransactionRollbackException — for example, due to deadlock

Obtaining Error Information

You can use the SQLException.getErrorCode() function to obtain more information about an error.

  • For example, you might need to distinguish between a unique constraint violation and a check constraint violation. When handling the exception, check the error code.

    • For a unique constraint violation the error code is -27.

    • For a check constraint violation the error code is -45.

  • See SQL Error Codes.

  • All the SQL States recognized by NuoDB are enumerators on the com.nuodb.jdbc.SqlState enum.

For example:

try {
    preparedStatement.execute();
} catch (SQLException e) {
    if (e.getErrorCode() == SQLState.UNIQUE_DUPLICATE.getCode()) {
        System.err.println("Unexpected duplicate");
    } else if (e.getErrorCode() == SQLState.CONSTRAINT_ERROR.getCode()) {
        System.err.println("Constraint violation");
    } else {
        System.err.println("Unexpected error: \"" + e.getMessage() + "\"");
    }
}

BatchUpdateException

BatchUpdateException supports exception chaining. Invoking getNextException() repeatedly on a BatchUpdateException object, it will traverse the list of exceptions that were generated.

Here is an example catch clause for a BatchUpdateException:

   ....
    } catch (BatchUpdateException bue) {

        int[] updateCounts = bue.getUpdateCounts();
        SQLException exception = bue;
        for (int i = 0; i < updateCounts.length; i++) {
            System.out.println(
                "** BatchUpdateException updateCounts[" + i + "]=\"" +
                updateCounts[i] + "\"" );
            if (updateCounts[i] == java.sql.Statement.EXECUTE_FAILED) {
                exception = exception.getNextException();
                System.out.println("   SQLException \"" + exception + "\"");
            }
        }
    }

Suppose the output from this example looked as follows:

** BatchUpdateException updateCounts[0]="1"
** BatchUpdateException updateCounts[1]="1"
** BatchUpdateException updateCounts[2]="-3"
   SQLException "java.sql.SQLIntegrityConstraintViolationException: violation of constraint "GENDER""
** BatchUpdateException updateCounts[3]="1"
** BatchUpdateException updateCounts[4]="-3"
   SQLException "java.sql.SQLIntegrityConstraintViolationException: duplicate value in unique index MEMBERS..PRIMARY_KEY, key = '4'"
** BatchUpdateException updateCounts[5]="1"

This would tell us that

  • Six statements were executed by this batch update.

    • NuoDB will always continue executing statements in a batch update, even after an error has occurred.

  • The 3rd statement in the batch resulted in the error
    java.sql.SQLIntegrityConstraintViolationException: violation of constraint "GENDER"

  • The 5th statement in the batch resulted in the error
    java.sql.SQLIntegrityConstraintViolationException: duplicate value in unique index MEMBERS..PRIMARY_KEY, key = '4'.