From f60cb843eb83311d84b49825e2537da9f50df3d7 Mon Sep 17 00:00:00 2001 From: Gail Badner Date: Mon, 22 Aug 2016 19:11:45 -0700 Subject: [PATCH] HHH-11059 : Improve documentation for JTA configuration in user guide (cherry picked from commit b3d2c0fc90488d5fd9cef0c7e057d46a14203395) --- .../userguide/appendices/Configurations.adoc | 16 +++++++++++++++- .../chapters/transactions/Transactions.adoc | 11 ++++++++++- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/documentation/src/main/asciidoc/userguide/appendices/Configurations.adoc b/documentation/src/main/asciidoc/userguide/appendices/Configurations.adoc index 579bb6a2ad..daf59efd35 100644 --- a/documentation/src/main/asciidoc/userguide/appendices/Configurations.adoc +++ b/documentation/src/main/asciidoc/userguide/appendices/Configurations.adoc @@ -430,7 +430,21 @@ Can be * `TransactionCoordinatorBuilder` instance * `TransactionCoordinatorBuilder` implementation `Class` reference -* `TransactionCoordinatorBuilder` implementation class name (fully-qualified name) or short-name +* `TransactionCoordinatorBuilder` implementation class name (fully-qualified name) or short name + +The following short names are defined for this setting: + +`jdbc`:: Manages transactions via calls to `java.sql.Connection` (default for non-JPA applications) +`jta`:: Manages transactions via JTA. See <> + +If a JPA application does not provide a setting for `hibernate.transaction.coordinator_class`, Hibernate will +automatically build the proper transaction coordinator based on the transaction type for the persistence unit. + +If a non-JPA application does not provide a setting for `hibernate.transaction.coordinator_class`, Hibernate +will use `jdbc` as the default. This default will cause problems if the application actually uses JTA-based transactions. +A non-JPA application that uses JTA-based transactions should explicitly set `hibernate.transaction.coordinator_class=jta` +or provide a custom `org.hibernate.resource.transaction.TransactionCoordinatorBuilder` that builds a +`org.hibernate.resource.transaction.TransactionCoordinator` that properly coordinates with JTA-based transactions. |`hibernate.jta.track_by_thread` | `true` (default value) or `false` | diff --git a/documentation/src/main/asciidoc/userguide/chapters/transactions/Transactions.adoc b/documentation/src/main/asciidoc/userguide/chapters/transactions/Transactions.adoc index d79e562c76..a0b88cae75 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/transactions/Transactions.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/transactions/Transactions.adoc @@ -24,9 +24,18 @@ Transaction handling per `Session` is handled by the `org.hibernate.resource.tra `TransactionCoordinatorBuilder` represents a strategy for dealing with transactions whereas TransactionCoordinator represents one instance of that strategy related to a Session. Which `TransactionCoordinatorBuilder` implementation to use is defined by the `hibernate.transaction.coordinator_class` setting. -`jdbc` (the default):: Manages transactions via calls to `java.sql.Connection` +`jdbc` (the default for non-JPA applications):: Manages transactions via calls to `java.sql.Connection` `jta`:: Manages transactions via JTA. See <> +If a JPA application does not provide a setting for `hibernate.transaction.coordinator_class`, Hibernate will +automatically build the proper transaction coordinator based on the transaction type for the persistence unit. + +If a non-JPA application does not provide a setting for `hibernate.transaction.coordinator_class`, Hibernate +will use `jdbc` as the default. This default will cause problems if the application actually uses JTA-based transactions. +A non-JPA application that uses JTA-based transactions should explicitly set `hibernate.transaction.coordinator_class=jta` +or provide a custom `org.hibernate.resource.transaction.TransactionCoordinatorBuilder` that builds a +`org.hibernate.resource.transaction.TransactionCoordinator` that properly coordinates with JTA-based transactions. + [NOTE] ==== For details on implementing a custom `TransactionCoordinatorBuilder`, or simply better understanding how it works, see the Integrations Guide.