The legacy (2.x) behavior of Hibernate in regards to JDBC connection management
was that a Session would obtain a connection when it was first
needed and then hold unto that connection until the session was closed.
Hibernate 3.x introduced the notion of connection release modes to tell a session
how to handle its JDBC connections. Note that the following discussion is pertinent
only to connections provided through a configured ConnectionProvider;
user-supplied connections are outside the breadth of this discussion. The different
release modes are identified by the enumerated values of
org.hibernate.ConnectionReleaseMode:
ON_CLOSE - is essentially the legacy behavior described above. The
Hibernate session obtains a connection when it first needs to perform some JDBC access
and holds unto that connection until the session is closed.
AFTER_TRANSACTION - says to release connections after a
org.hibernate.Transaction has completed.
AFTER_STATEMENT (also referred to as aggressive release) - says to
release connections after each and every statement execution. This aggressive releasing
is skipped if that statement leaves open resources associated with the given session;
currently the only situation where this occurs is through the use of
org.hibernate.ScrollableResults.
The configuration parameter hibernate.connection.release_mode is used
to specify which release mode to use. The possible values:
auto (the default) - this choice delegates to the release mode
returned by the org.hibernate.transaction.TransactionFactory.getDefaultReleaseMode()
method. For JTATransactionFactory, this returns ConnectionReleaseMode.AFTER_STATEMENT; for
JDBCTransactionFactory, this returns ConnectionReleaseMode.AFTER_TRANSACTION. It is rarely
a good idea to change this default behavior as failures due to the value of this setting
tend to indicate bugs and/or invalid assumptions in user code.
on_close - says to use ConnectionReleaseMode.ON_CLOSE. This setting
is left for backwards compatibility, but its use is highly discouraged.
after_transaction - says to use ConnectionReleaseMode.AFTER_TRANSACTION.
This setting should not be used in JTA environments. Also note that with
ConnectionReleaseMode.AFTER_TRANSACTION, if a session is considered to be in auto-commit
mode connections will be released as if the release mode were AFTER_STATEMENT.
after_statement - says to use ConnectionReleaseMode.AFTER_STATEMENT. Additionally,
the configured ConnectionProvider is consulted to see if it supports this
setting (supportsAggressiveRelease()). If not, the release mode is reset
to ConnectionReleaseMode.AFTER_TRANSACTION. This setting is only safe in environments where
we can either re-acquire the same underlying JDBC connection each time we make a call into
ConnectionProvider.getConnection() or in auto-commit environments where
it does not matter whether we get back the same connection.