Exception handling

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

Checked vs. unchecked exceptions

Pros and cons have been discussed time and again, and it is mostly still a matter of taste, today. In this topic, 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). Other languages may have union types or monads to implement the same behaviour, minus the control flow implications of exceptions.

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 most methods in jOOQ that may cause such a DataAccessException document this both in the Javadoc as well as in their method signature, even if this isn't a requirement for unchecked exceptions in the Java language.

DataAccessException is subtyped several times as follows:

• ConfigurationException: The org.jooq.Configuration was set up in a way that does not allow for a particular operation.
• 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)
• DataDefinitionException: An exception occurred when interpreting DDL statements.
• DataTypeException: Something went wrong during type conversion
• DataException: jOOQ's equivalent to JDBC's java.sql.SQLDataException.
• DetachedException: A SQL statement was executed on a "detached" UpdatableRecord or a "detached" SQL statement.
• IntegrityConstraintViolationException: jOOQ's equivalent to JDBC's java.sql.SQLIntegrityConstraintViolationException.
• InvalidResultException: An operation was performed expecting only one result, but several results were returned.
• LoaderConfigurationException: The Loader API was executed with an illegal loader configuration.
• MappingException: Something went wrong when loading a record from a POJO or when mapping a record into a POJO
• NoDataFoundException: No rows were returned from an org.jooq.ResultQuery when exactly one row was expected.
• TemplatingException: An exception occurred when doing plain SQL templating.
• TooManyRowsException: More than one rows were returned from an org.jooq.ResultQuery when at most one row was expected.

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.