Difference between getCause and getNextException in SQLException?

Question

Looking at the SQLException javadocs, there seems to be an overlap between getCause and getNextException. The first returns a Throwable, but otherwise they seem to be pretty much interchangeable.

What is the difference between the two? When developing a JDBC driver, are there guidelines about when to choose one over the other as the exception chaining mechanism?

Answer 1

The method getCause() gives you the cause - if any - of that specific SQLException. On the other hand during processing it is entirely possible that multiple exceptions occur, think of batch processing, serverside errors for multiple query parameters (eg too long, conversion errors etc).

These multiple exceptions are on the same level (they are not each others cause), so they are added to a chain of SQLExceptions. The head of this chain is the exception that is thrown. To get to the other SQLExceptions in the chain, you use getNextException(). Eg

try {
   // Something that produces multiple SQLExceptions
} catch (SQLException e) {
   SQLException current = e;
   do {
      // do something with current
   } while ((current = current.getNextException()) != null)
}

On the other hand, a SQLException also has a method public Iterator<Throwable> iterator() (introduced in Java 6/JDBC4), this iterates over each SQLException and their causes before proceeding to the next SQLException in the chain.