11.2.3. Exception handling

If the Session throws an exception (including any SQLException), you should immediately rollback the database transaction, call Session.close() and discard the Session instance. Certain methods of Session will not leave the session in a consistent state. No exception thrown by Hibernate can be treated as recoverable. Ensure that the Session will be closed by calling close() in a finally block.
The HibernateException, which wraps most of the errors that can occur in a Hibernate persistence layer, is an unchecked exception (it wasn't in older versions of Hibernate). In our opinion, we shouldn't force the application developer to catch an unrecoverable exception at a low layer. In most systems, unchecked and fatal exceptions are handled in one of the first frames of the method call stack (i.e. in higher layers) and an error message is presented to the application user (or some other appropriate action is taken). Note that Hibernate might also throw other unchecked exceptions which are not a HibernateException. These are, again, not recoverable and appropriate action should be taken.
Hibernate wraps SQLException s thrown while interacting with the database in a JDBCException. In fact, Hibernate will attempt to convert the eexception into a more meningful subclass of JDBCException. The underlying SQLException is always available via JDBCException.getCause(). Hibernate converts the SQLException into an appropriate JDBCException subclass using the SQLExceptionConverter attached to the SessionFactory. By default, the SQLExceptionConverter is defined by the configured dialect; however, it is also possible to plug in a custom implementation (see the javadocs for the SQLExceptionConverterFactory class for details). The standard JDBCException subtypes are:
  • JDBCConnectionException - indicates an error with the underlying JDBC communication.
  • SQLGrammarException - indicates a grammar or syntax problem with the issued SQL.
  • ConstraintViolationException - indicates some form of integrity constraint violation.
  • LockAcquisitionException - indicates an error acquiring a lock level necessary to perform the requested operation.
  • GenericJDBCException - a generic exception which did not fall into any of the other categories.