chained java.lang.SQLException instances vs. Throwable#getCause

Question

What are the semantics behind a "chain" of SQLException objects and how is this different from the similar (implicit) chain that's formed by the getCause method on the Throwable class?

Since a SQLException is also a Throwable , an instance of that class can have two such "chains:

• one defined by a sequence of getNextException() calls - till null is ultimately returned
• the other defined by a sequence of getCause() calls - till null is ultimately returned

... in such a case how would these two chains relate to each other?

Answer 1

The SQLException.setNextException(Exception) and SQLException.getNextException() allows for multiple distinct SQLException s to be reported back from a single method invocation. Those SQLException s are not each others cause.

The actual occurrence is pretty rare, but say that I execute a prepared insert statement with 2 parameters. One of those parameters is too long, and another is null while the column is NOT NULL . A database could (although I believe most databases won't) report both errors back to the driver. But as the executeUpdate method can only throw a single SQLException , these errors are chained together using setNextException . This then allows you to find out both error conditions

Also note that SQLException has an iterator() method which allows you to iterate over each SQLException and their causes (ie: the current SQLException , all causes of the current SQLException , the next SQLException if any etc.

It is similar to the use of getNextWarning() for SQLWarning if multiple warnings occurred (either concurrent or sequentially), they are chained together. SQLWarning is not thrown, but made available on the object that generated the warning (eg Connection.getWarnings() , Statement.getWarnings() etc). This method returns the first warning, and allows you to discover the additional warnings using getNextWarning() .

Answer 2

I guess that's for historical reasons:

• getNextException() is there since jdbc was introduced with Java 1.1
• getCause() states it's there "since 1.4"

So getNextException() seems to be there for compatibility reasons, getCause() is the more recent and more general way to chain Exceptions.