Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

HHH-13012 - JDBC default connection release mode does not match documentation

This commit is contained in:
Vlad Mihalcea 2018-10-11 16:39:46 +03:00 committed by Guillaume Smet
parent 3fec3b930b
commit b46a277619
2 changed files with 89 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
documentation/src/main/asciidoc/userguide/appendices/Configurations.adoc
View File

@ -129,6 +129,39 @@ from the provider do not, in fact, have auto-commit disabled.
Doing so will lead to Hibernate executing SQL operations outside of any JDBC/SQL transaction.
====
`*hibernate.connection.handling_mode*`::
Specifies how Hibernate should manage JDBC connections in terms of acquiring and releasing.
This configuration property supersedes `*hibernate.connection.acquisition_mode*` and
`*hibernate.connection.release_mode*`.
+
The connection handling mode strategies are defined by the
https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/resource/jdbc/spi/PhysicalConnectionHandlingMode.html[`PhysicalConnectionHandlingMode`] enumeration.
+
The configuration can be either a `PhysicalConnectionHandlingMode` reference or its case-insensitive `String` representation.
+
For more details about the `PhysicalConnectionHandlingMode` and Hibernate connection handling, check out the
<<chapters/jdbc/Database_Access.adoc#database-connection-handling,Connection handling>> section.
[line-through]#`*hibernate.connection.acquisition_mode*`# (e.g. `immediate`)::
[NOTE]
====
This setting is deprecated. You should use the `*hibernate.connection.handling_mode*` instead.
====
+
Specifies how Hibernate should acquire JDBC connections. The possible values are given by `org.hibernate.ConnectionAcquisitionMode`.
+
Should generally only configure this or `hibernate.connection.release_mode`, not both.
[line-through]#`*hibernate.connection.release_mode*`# (e.g. `auto` (default value))::
[NOTE]
====
This setting is deprecated. You should use the `*hibernate.connection.handling_mode*` instead.
====
+
Specifies how Hibernate should release JDBC connections. The possible values are given by the current transaction mode (`after_transaction` for JDBC transactions and `after_statement` for JTA transactions).
+
Should generally only configure this or `hibernate.connection.acquisition_mode`, not both.
`*hibernate.connection.datasource*`::
Either a `javax.sql.DataSource` instance or a JNDI name under which to locate the `DataSource`.
+
@ -159,16 +192,6 @@ Names a prefix used to define arbitrary JNDI `javax.naming.InitialContext` prope
+
These properties are passed along to `javax.naming.InitialContext#InitialContext(java.util.Hashtable)`
`*hibernate.connection.acquisition_mode*` (e.g. `immediate`)::
Specifies how Hibernate should acquire JDBC connections. The possible values are given by `org.hibernate.ConnectionAcquisitionMode`.
+
Should generally only configure this or `hibernate.connection.release_mode`, not both.
`*hibernate.connection.release_mode*` (e.g. `auto` (default value))::
Specifies how Hibernate should release JDBC connections. The possible values are given by the current transaction mode (`after_transaction` for JDBC transactions and `after_statement` for JTA transactions).
+
Should generally only configure this or `hibernate.connection.acquisition_mode`, not both.
==== Hibernate internal connection pool options
`*hibernate.connection.initial_pool_size*` (e.g. 1 (default value))::

56
documentation/src/main/asciidoc/userguide/chapters/jdbc/Database_Access.adoc
View File

@ -187,6 +187,62 @@ Not that this is only supported for JDBC standard isolation levels, not for isol
* a short-name version of the java.sql.Connection constant field without the `TRANSACTION_` prefix. For example, `REPEATABLE_READ` for https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html#TRANSACTION_REPEATABLE_READ[`java.sql.Connection#TRANSACTION_REPEATABLE_READ`].
Again, this is only supported for JDBC standard isolation levels, not for isolation levels specific to a particular JDBC driver.
[[database-connection-handling]]
=== Connection handling
The connection handling mode is defined by the
https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/resource/jdbc/spi/PhysicalConnectionHandlingMode.html[`PhysicalConnectionHandlingMode`] enumeration which provides the following strategies:
`IMMEDIATE_ACQUISITION_AND_HOLD`::
The `Connection` will be acquired as soon as the `Session` is opened and held until the `Session` is closed.
`DELAYED_ACQUISITION_AND_HOLD`::
The `Connection` will be acquired as soon as it is needed and then held until the `Session` is closed.
`DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT`::
The `Connection` will be acquired as soon as it is needed and will be released after each statement is executed.
`DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION`::
The `Connection` will be acquired as soon as it is needed and will be released after each transaction is completed.
If you don't want to use the default connection handling mode, you can specify a connection handling mode via the `hibernate.connection.handling_mode` configuration property. For more details, check out the
<<appendices/Configurations.adoc#configurations-database-connection,Database connection properties>> section.
==== Transaction type and connection handling
By default, the connection handling mode is given by the underlying transaction coordinator. There are two types of transactions: `RESOURCE_LOCAL` (which involves a single database `Connection` and the transaction is controlled via the `commit` and `rollback` `Connection` methods) and `JTA` (which may involve multiple resources either database connections, JMS queues, etc).
===== RESOURCE_LOCAL transaction connection handling
For `RESOURCE_LOCAL` transactions, the connection handling mode is `DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION` meaning that the database connection is acquired when needed and released after the current running transaction is either committed or rolled back.
However, because Hibernate needs to make sure that the default autocommit mode is disabled on the JDBC `Connection`
when starting a new transaction, the `Connection` is acquired and the autocommit mode is set to `false`.
[NOTE]
====
If you are using a connection pool `DataSource` that already disabled the autocommit mode for every pooled `Connection`, you can set the `hibernate.connection.provider_disables_autocommit` to `true` and the database connection acquisition will be, indeed, delayed until Hibernate needs to execute an SQL statement.
====
===== JTA transaction connection handling
For `JTA` transactions, the connection handling mode is `DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT` meaning that the database connection is acquired when needed and released after each statement execution.
The reason for releasing the database connection after statement execution is because some Java EE application servers
report a connection leak when a method call goes from one EJB to another. However, even if the JDBC `Connection` is released to the pool, the `Connection` is still allocated to the current executing `Thread`, hence when executing a subsequent statement in the current running transaction, the same `Connection` object reference will be obtained from the pool.
[NOTE]
====
If the Java EE application server or JTA transaction manager supports switching from one EJB to another while the transaction gets propagated from the outer EJB to the inner one,
and no connection leak false positive is being reported, then you should consider switching to `DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION` via the `hibernate.connection.handling_mode` configuration property.
====
==== User-provided connections
If the current `Session` was created using the
https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/SessionBuilder.html[`SessionBuilder`] and a JDBC `Connection` was provided via the
https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/SessionBuilder.html#connection-java.sql.Connection-[`SessionBuilder#connection`] method, then the user-provided `Connection` is going to be used, and
the connection handling mode will be `IMMEDIATE_ACQUISITION_AND_HOLD`.
Therefore for user-provided connection, the connection is acquired right away and held until the current `Session` is closed, without being influenced by the JPA or Hibernate transaction context.
[[database-dialect]]
=== Database Dialect