The following enhancements were made in JDBC 4.0 in order to provide a better developer's experience when dealing with SQLExceptions: 
  • Support for causal relationships
  • For-each loop support
  • New SQLException sub-classes

Causal Relationship Support

We have added support for the Java SE chained exception mechanism by adding additional constructors allowing for the cause to be specified. The cause could be a non-SQLException, it is just what resulted in the SQLException being thrown. 

This feature does not reduce the need for the getSQLException() method as it is possible for multiple unique SQLExceptions to be generated (not all DBs do this currently but could going forward and is allowed by the SQL Standard) due to executing a statement on the backend.

Your code would look something like the following to process the causal relationships:

catch(SQLException ex) {
     while(ex != null) {
        System.out.println("SQLState:" + ex.getSQLState());
        System.out.println("Error Code:" + ex.getErrorCode());
        System.out.println("Message:" + ex.getMessage());
        Throwable t = ex.getCause();
        while(t != null) {
            System.out.println("Cause:" + t);
            t = t.getCause();
        ex = ex.getNextException();

For Each Loop Support

The SQLException class now implements the Iterable interface providing support for the For each loop feature added in J2SE 5.0. The navigation of the loop will walk through the SQLException and its cause (if any): 


catch(SQLException ex) {
     for(Throwable e : ex ) {
        System.out.println("Error encountered: " + e);

Categorization of SQLExceptions

JDBC 4.0 has introduced two categories of SQLException: SQLTransientException and SQLNonTransientException. 

A SQLNonTransientException would be thrown in instances where a retry of the same operation would fail unless the cause of the SQLException is corrected. The following Exceptions have been added, each extending SQLNonTransientException:


  • SQLFeatureNotSupportedException
  • SQLNonTransientConnectionException
  • SQLDataException
  • SQLIntegrityConstraintViolationException
  • SQLInvalidAuthorizationException
  • SQLSyntaxErrorException

A SQLTransientException will be thrown in situations where a previously failed operation might be able to succeed when the operation is retried without any intervention by application-level functionality. The following Exceptions have been added, each extending SQLTransientException:


  • SQLTransientConnectionException
  • SQLTransactionRollbackException
  • SQLTimeoutException

Please refer to the JDBC specification to see the SQLState Class value code that is associated with the new SQLExceptions.


Correct SQLState for a DataTruncation on a write operation

We have also fixed a long outstanding JDBC bug so that the SQLState of 22001 is now returned for a DataTruncation Exception during a write operation to a data source.