Exception handling

Applies to ✅ Open Source Edition   ✅ Express Edition   ✅ Professional Edition   ✅ Enterprise Edition

Checked vs. unchecked exceptions

This is an eternal and religious debate. Pros and cons have been discussed time and again, and it still is a matter of taste, today. In this case, jOOQ clearly takes a side. jOOQ's exception strategy is simple:

• All "system exceptions" are unchecked. If in the middle of a transaction involving business logic, there is no way that you can recover sensibly from a lost database connection, or a constraint violation that indicates a bug in your understanding of your database model.
• All "business exceptions" are checked. Business exceptions are true exceptions that you should handle (e.g. not enough funds to complete a transaction).

With jOOQ, it's simple. All of jOOQ's exceptions are "system exceptions", hence they are all unchecked.

jOOQ's DataAccessException

jOOQ uses its own org.jooq.exception.DataAccessException to wrap any underlying java.sql.SQLException that might have occurred. Note that all methods in jOOQ that may cause such a DataAccessException document this both in the Javadoc as well as in their method signature.

DataAccessException is subtyped several times as follows:

• DataAccessException: General exception usually originating from a java.sql.SQLException
• DataChangedException: An exception indicating that the database's underlying record has been changed in the mean time (see optimistic locking)
• DataTypeException: Something went wrong during type conversion
• DetachedException: A SQL statement was executed on a "detached" UpdatableRecord or a "detached" SQL statement.
• InvalidResultException: An operation was performed expecting only one result, but several results were returned.
• MappingException: Something went wrong when loading a record from a POJO or when mapping a record into a POJO

Override jOOQ's exception handling

The following section about execute listeners documents means of overriding jOOQ's exception handling, if you wish to deal separately with some types of constraint violations, or if you raise business errors from your database, etc.