Discuss JdbcTransactionManager vs DataSourceTransactionManager

Includes doc update for 6.0 default exception translation etc.

Closes gh-30802

framework-docs/modules/ROOT/pages/data-access/dao.adoc

@@ -151,10 +151,10 @@ Kotlin::
 ----
 ======
 
-The last example we show here is for typical JDBC support. You could have the
+The last example we show here is for typical JDBC support. You could have the `DataSource`
-`DataSource` injected into an initialization method or a constructor, where you would create a
+injected into an initialization method or a constructor, where you would create a `JdbcTemplate`
-`JdbcTemplate` and other data access support classes (such as `SimpleJdbcCall` and others) by using
+and other data access support classes (such as `SimpleJdbcCall` and others) by using this
-this `DataSource`. The following example autowires a `DataSource`:
+`DataSource`. The following example autowires a `DataSource`:
 
 [tabs]
 ======

framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc

@@ -9,13 +9,13 @@ to the database.
 [[jdbc-batch-classic]]
 == Basic Batch Operations with `JdbcTemplate`
 
-You accomplish `JdbcTemplate` batch processing by implementing two methods of a special
+You accomplish `JdbcTemplate` batch processing by implementing two methods of a special interface,
-interface, `BatchPreparedStatementSetter`, and passing that implementation in as the second parameter
+`BatchPreparedStatementSetter`, and passing that implementation in as the second parameter
 in your `batchUpdate` method call. You can use the `getBatchSize` method to provide the size of
 the current batch. You can use the `setValues` method to set the values for the parameters of
-the prepared statement. This method is called the number of times that you
+the prepared statement. This method is called the number of times that you specified in the
-specified in the `getBatchSize` call. The following example updates the `t_actor` table
+`getBatchSize` call. The following example updates the `t_actor` table based on entries in a list,
-based on entries in a list, and the entire list is used as the batch:
+and the entire list is used as the batch:
 
 [tabs]
 ======

framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc

@@ -10,7 +10,7 @@ This section covers:
 * xref:data-access/jdbc/connections.adoc#jdbc-SingleConnectionDataSource[Using `SingleConnectionDataSource`]
 * xref:data-access/jdbc/connections.adoc#jdbc-DriverManagerDataSource[Using `DriverManagerDataSource`]
 * xref:data-access/jdbc/connections.adoc#jdbc-TransactionAwareDataSourceProxy[Using `TransactionAwareDataSourceProxy`]
-* xref:data-access/jdbc/connections.adoc#jdbc-DataSourceTransactionManager[Using `DataSourceTransactionManager`]
+* xref:data-access/jdbc/connections.adoc#jdbc-DataSourceTransactionManager[Using `DataSourceTransactionManager` / `JdbcTransactionManager`]
 
 
 [[jdbc-datasource]]
@@ -125,8 +125,12 @@ The following example shows C3P0 configuration:
 == Using `DataSourceUtils`
 
 The `DataSourceUtils` class is a convenient and powerful helper class that provides
-`static` methods to obtain connections from JNDI and close connections if necessary. It
+`static` methods to obtain connections from JNDI and close connections if necessary.
-supports thread-bound connections with, for example, `DataSourceTransactionManager`.
+It supports a thread-bound JDBC `Connection` with `DataSourceTransactionManager` but
+also with `JtaTransactionManager` and `JpaTransactionManager`.
+
+Note that `JdbcTemplate` implies `DataSourceUtils` connection access, using it
+behind every JDBC operation, implicitly participating in an ongoing transaction.
 
 
 [[jdbc-SmartDataSource]]
@@ -165,7 +169,6 @@ In contrast to `DriverManagerDataSource`, it reuses the same connection all the
 avoiding excessive creation of physical connections.
 
 
-
 [[jdbc-DriverManagerDataSource]]
 == Using `DriverManagerDataSource`
 
@@ -201,29 +204,44 @@ javadoc for more details.
 
 
 [[jdbc-DataSourceTransactionManager]]
-== Using `DataSourceTransactionManager`
+== Using `DataSourceTransactionManager` / `JdbcTransactionManager`
 
 The `DataSourceTransactionManager` class is a `PlatformTransactionManager`
-implementation for single JDBC data sources. It binds a JDBC connection from the
+implementation for a single JDBC `DataSource`. It binds a JDBC `Connection`
-specified data source to the currently executing thread, potentially allowing for one
+from the specified `DataSource` to the currently executing thread, potentially
-thread connection per data source.
+allowing for one thread-bound `Connection` per `DataSource`.
 
-Application code is required to retrieve the JDBC connection through
+Application code is required to retrieve the JDBC `Connection` through
-`DataSourceUtils.getConnection(DataSource)` instead of Jakarta EE's standard
+`DataSourceUtils.getConnection(DataSource)` instead of Java EE's standard
 `DataSource.getConnection`. It throws unchecked `org.springframework.dao` exceptions
-instead of checked `SQLExceptions`. All framework classes (such as `JdbcTemplate`) use this
+instead of checked `SQLExceptions`. All framework classes (such as `JdbcTemplate`) use
-strategy implicitly. If not used with this transaction manager, the lookup strategy
+this strategy implicitly. If not used with a transaction manager, the lookup strategy
-behaves exactly like the common one. Thus, it can be used in any case.
+behaves exactly like `DataSource.getConnection` and can therefore be used in any case.
-
+
-The `DataSourceTransactionManager` class supports custom isolation levels and timeouts
+The `DataSourceTransactionManager` class supports savepoints (`PROPAGATION_NESTED`),
-that get applied as appropriate JDBC statement query timeouts. To support the latter,
+custom isolation levels, and timeouts that get applied as appropriate JDBC statement
-application code must either use `JdbcTemplate` or call the
+query timeouts. To support the latter, application code must either use `JdbcTemplate` or
-`DataSourceUtils.applyTransactionTimeout(..)` method for each created statement.
+call the `DataSourceUtils.applyTransactionTimeout(..)` method for each created statement.
-
+
-You can use this implementation instead of `JtaTransactionManager` in the single-resource
+You can use `DataSourceTransactionManager` instead of `JtaTransactionManager` in the
-case, as it does not require the container to support JTA. Switching between
+single-resource case, as it does not require the container to support a JTA transaction
-both is just a matter of configuration, provided you stick to the required connection lookup
+coordinator. Switching between these transaction managers is just a matter of configuration,
-pattern. JTA does not support custom isolation levels.
+provided you stick to the required connection lookup pattern. Note that JTA does not support
+savepoints or custom isolation levels and has a different timeout mechanism but otherwise
+exposes similar behavior in terms of JDBC resources and JDBC commit/rollback management.
+
+NOTE: As of 5.3, Spring provides an extended `JdbcTransactionManager` variant which adds
+exception translation capabilities on commit/rollback (aligned with `JdbcTemplate`).
+Where `DataSourceTransactionManager` will only ever throw `TransactionSystemException`
+(analogous to JTA), `JdbcTransactionManager` translates database locking failures etc to
+corresponding `DataAccessException` subclasses. Note that application code needs to be
+prepared for such exceptions, not exclusively expecting `TransactionSystemException`.
+In scenarios where that is the case, `JdbcTransactionManager` is the recommended choice.
+
+In terms of exception behavior, `JdbcTransactionManager` is roughly equivalent to
+`JpaTransactionManager` and also to `R2dbcTransactionManager`, serving as an immediate
+companion/replacement for each other. `DataSourceTransactionManager` on the other hand
+is equivalent to `JtaTransactionManager` and can serve as a direct replacement there.
 
 
 

framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc

@@ -718,12 +718,22 @@ See also xref:data-access/jdbc/core.adoc#jdbc-JdbcTemplate-idioms[`JdbcTemplate`
 between ``SQLException``s and Spring's own `org.springframework.dao.DataAccessException`,
 which is agnostic in regard to data access strategy. Implementations can be generic (for
 example, using SQLState codes for JDBC) or proprietary (for example, using Oracle error
-codes) for greater precision.
+codes) for greater precision. This exception translation mechanism is used behind the
+the common `JdbcTemplate` and `JdbcTransactionManager` entry points which do not
+propagate `SQLException` but rather `DataAccessException`.
+
+NOTE: As of 6.0, the default exception translator is `SQLExceptionSubclassTranslator`,
+detecting JDBC 4 `SQLException` subclasses with a few extra checks, and with a fallback
+to `SQLState` introspection through `SQLStateSQLExceptionTranslator`. This is usually
+sufficient for common database access and does not require vendor-specific detection.
+For backwards compatibility, consider using `SQLErrorCodeSQLExceptionTranslator` as
+described below, potentially with custom error code mappings.
 
 `SQLErrorCodeSQLExceptionTranslator` is the implementation of `SQLExceptionTranslator`
-that is used by default. This implementation uses specific vendor codes. It is more
+that is used by default when a file named `sql-error-codes.xml` is present in the root
-precise than the `SQLState` implementation. The error code translations are based on
+of the classpath. This implementation uses specific vendor codes. It is more precise than
-codes held in a JavaBean type class called `SQLErrorCodes`. This class is created and
+`SQLState` or `SQLException` subclass translation. The error code translations are based
+on codes held in a JavaBean type class called `SQLErrorCodes`. This class is created and
 populated by an `SQLErrorCodesFactory`, which (as the name suggests) is a factory for
 creating `SQLErrorCodes` based on the contents of a configuration file named
 `sql-error-codes.xml`. This file is populated with vendor codes and based on the
@@ -744,8 +754,8 @@ The `SQLErrorCodeSQLExceptionTranslator` applies matching rules in the following
   translator. If this translation is not available, the next fallback translator is
   the `SQLStateSQLExceptionTranslator`.
 
-NOTE: The `SQLErrorCodesFactory` is used by default to define `Error` codes and custom exception
+NOTE: The `SQLErrorCodesFactory` is used by default to define error codes and custom
-translations. They are looked up in a file named `sql-error-codes.xml` from the
+exception translations. They are looked up in a file named `sql-error-codes.xml` from the
 classpath, and the matching `SQLErrorCodes` instance is located based on the database
 name from the database metadata of the database in use.
 
@@ -784,12 +794,12 @@ Kotlin::
 ----
 ======
 
-In the preceding example, the specific error code (`-12345`) is translated, while other errors are
+In the preceding example, the specific error code (`-12345`) is translated while
-left to be translated by the default translator implementation. To use this custom
+other errors are left to be translated by the default translator implementation.
-translator, you must pass it to the `JdbcTemplate` through the method
+To use this custom translator, you must pass it to the `JdbcTemplate` through the
-`setExceptionTranslator`, and you must use this `JdbcTemplate` for all of the data access
+method `setExceptionTranslator`, and you must use this `JdbcTemplate` for all of the
-processing where this translator is needed. The following example shows how you can use this custom
+data access processing where this translator is needed. The following example shows
-translator:
+how you can use this custom translator:
 
 [tabs]
 ======
@@ -800,7 +810,6 @@ Java::
 	private JdbcTemplate jdbcTemplate;
 
 	public void setDataSource(DataSource dataSource) {
-
 		// create a JdbcTemplate and set data source
 		this.jdbcTemplate = new JdbcTemplate();
 		this.jdbcTemplate.setDataSource(dataSource);
@@ -809,7 +818,6 @@ Java::
 		CustomSQLErrorCodesTranslator tr = new CustomSQLErrorCodesTranslator();
 		tr.setDataSource(dataSource);
 		this.jdbcTemplate.setExceptionTranslator(tr);
-
 	}
 
 	public void updateShippingCharge(long orderId, long pct) {

framework-docs/modules/ROOT/pages/data-access/jdbc/packages.adoc

@@ -3,30 +3,30 @@
 
 The Spring Framework's JDBC abstraction framework consists of four different packages:
 
-* `core`: The `org.springframework.jdbc.core` package contains the `JdbcTemplate` class and its
+* `core`: The `org.springframework.jdbc.core` package contains the `JdbcTemplate` class
-various callback interfaces, plus a variety of related classes. A subpackage named
+and its various callback interfaces, plus a variety of related classes. A subpackage
-`org.springframework.jdbc.core.simple` contains the `SimpleJdbcInsert` and
+named `org.springframework.jdbc.core.simple` contains the `SimpleJdbcInsert` and
 `SimpleJdbcCall` classes. Another subpackage named
 `org.springframework.jdbc.core.namedparam` contains the `NamedParameterJdbcTemplate`
 class and the related support classes. See xref:data-access/jdbc/core.adoc[Using the JDBC Core Classes to Control Basic JDBC Processing and Error Handling], xref:data-access/jdbc/advanced.adoc[JDBC Batch Operations], and
 xref:data-access/jdbc/simple.adoc[Simplifying JDBC Operations with the `SimpleJdbc` Classes].
 
-* `datasource`: The `org.springframework.jdbc.datasource` package contains a utility class for easy
+* `datasource`: The `org.springframework.jdbc.datasource` package contains a utility class
-`DataSource` access and various simple `DataSource` implementations that you can use for
+for easy `DataSource` access and various simple `DataSource` implementations that you can
-testing and running unmodified JDBC code outside of a Jakarta EE container. A subpackage
+use for testing and running unmodified JDBC code outside of a Jakarta EE container. A subpackage
-named `org.springfamework.jdbc.datasource.embedded` provides support for creating
+named `org.springframework.jdbc.datasource.embedded` provides support for creating
 embedded databases by using Java database engines, such as HSQL, H2, and Derby. See
 xref:data-access/jdbc/connections.adoc[Controlling Database Connections] and xref:data-access/jdbc/embedded-database-support.adoc[Embedded Database Support].
 
-* `object`: The `org.springframework.jdbc.object` package contains classes that represent RDBMS
+* `object`: The `org.springframework.jdbc.object` package contains classes that represent
-queries, updates, and stored procedures as thread-safe, reusable objects. See
+RDBMS queries, updates, and stored procedures as thread-safe, reusable objects. See
 xref:data-access/jdbc/object.adoc[Modeling JDBC Operations as Java Objects]. This approach is modeled by JDO, although objects returned by queries
 are naturally disconnected from the database. This higher-level of JDBC abstraction
 depends on the lower-level abstraction in the `org.springframework.jdbc.core` package.
 
-* `support`: The `org.springframework.jdbc.support` package provides `SQLException` translation
+* `support`: The `org.springframework.jdbc.support` package provides `SQLException`
-functionality and some utility classes. Exceptions thrown during JDBC processing are
+translation functionality and some utility classes. Exceptions thrown during JDBC processing
-translated to exceptions defined in the `org.springframework.dao` package. This means
+are translated to exceptions defined in the `org.springframework.dao` package. This means
 that code using the Spring JDBC abstraction layer does not need to implement JDBC or
 RDBMS-specific error handling. All translated exceptions are unchecked, which gives you
 the option of catching the exceptions from which you can recover while letting other

framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc

@@ -495,7 +495,7 @@ features supported by Spring, usually in a vendor-specific manner:
 * Applying specific transaction semantics (such as custom isolation level or transaction
   timeout)
 * Retrieving the transactional JDBC `Connection` (for exposure to JDBC-based DAOs)
-* Advanced translation of `PersistenceExceptions` to Spring `DataAccessExceptions`
+* Advanced translation of `PersistenceException` to Spring's `DataAccessException`
 
 This is particularly valuable for special transaction semantics and for advanced
 translation of exception. The default implementation (`DefaultJpaDialect`) does

framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc

@@ -718,19 +718,15 @@ javadoc for more details.
 === Using `R2dbcTransactionManager`
 
 The `R2dbcTransactionManager` class is a `ReactiveTransactionManager` implementation for
-single R2DBC data sources. It binds an R2DBC connection from the specified connection factory
+a single R2DBC `ConnectionFactory`. It binds an R2DBC `Connection` from the specified
-to the subscriber `Context`, potentially allowing for one subscriber connection for each
+`ConnectionFactory` to the subscriber `Context`, potentially allowing for one subscriber
-connection factory.
+`Connection` for each `ConnectionFactory`.
 
-Application code is required to retrieve the R2DBC connection through
+Application code is required to retrieve the R2DBC `Connection` through
 `ConnectionFactoryUtils.getConnection(ConnectionFactory)`, instead of R2DBC's standard
-`ConnectionFactory.create()`.
+`ConnectionFactory.create()`. All framework classes (such as `DatabaseClient`) use this
-
+strategy implicitly. If not used with a transaction manager, the lookup strategy behaves
-All framework classes (such as `DatabaseClient`) use this strategy implicitly.
+exactly like `ConnectionFactory.create()` and can therefore be used in any case.
-If not used with this transaction manager, the lookup strategy behaves exactly like the common one.
-Thus, it can be used in any case.
-
-The `R2dbcTransactionManager` class supports custom isolation levels that get applied to the connection.
 
 
 

framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc

@@ -124,7 +124,6 @@ In XML configuration, the `<tx:annotation-driven/>` tag provides similar conveni
 ----
 <1> The line that makes the bean instance transactional.
 
-
 TIP: You can omit the `transaction-manager` attribute in the `<tx:annotation-driven/>`
 tag if the bean name of the `TransactionManager` that you want to wire in has the name
 `transactionManager`. If the `TransactionManager` bean that you want to dependency-inject
@@ -522,17 +521,17 @@ The following listing shows the bean declarations:
 ----
 	<tx:annotation-driven/>
 
-		<bean id="transactionManager1" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
+		<bean id="transactionManager1" class="org.springframework.jdbc.support.JdbcTransactionManager">
 			...
 			<qualifier value="order"/>
 		</bean>
 
-		<bean id="transactionManager2" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
+		<bean id="transactionManager2" class="org.springframework.jdbc.support.JdbcTransactionManager">
 			...
 			<qualifier value="account"/>
 		</bean>
 
-		<bean id="transactionManager3" class="org.springframework.data.r2dbc.connectionfactory.R2dbcTransactionManager">
+		<bean id="transactionManager3" class="org.springframework.data.r2dbc.connection.R2dbcTransactionManager">
 			...
 			<qualifier value="reactive-account"/>
 		</bean>

spring-tx/src/main/java/org/springframework/transaction/PlatformTransactionManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2023 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -31,10 +31,10 @@ import org.springframework.lang.Nullable;
  * template methods for specific states of the underlying transaction,
  * for example: begin, suspend, resume, commit.
  *
- * <p>The default implementations of this strategy interface are
+ * <p>A classic implementation of this strategy interface is
- * {@link org.springframework.transaction.jta.JtaTransactionManager} and
+ * {@link org.springframework.transaction.jta.JtaTransactionManager}. However,
- * {@link org.springframework.jdbc.datasource.DataSourceTransactionManager},
+ * in common single-resource scenarios, Spring's specific transaction managers
- * which can serve as an implementation guide for other transaction strategies.
+ * for e.g. JDBC, JPA, JMS are preferred choices.
  *
  * @author Rod Johnson
  * @author Juergen Hoeller
@@ -81,12 +81,9 @@ public interface PlatformTransactionManager extends TransactionManager {
 	 * <p>Note that when the commit call completes, no matter if normally or
 	 * throwing an exception, the transaction must be fully completed and
 	 * cleaned up. No rollback call should be expected in such a case.
-	 * <p>If this method throws an exception other than a TransactionException,
+	 * <p>Depending on the concrete transaction manager setup, {@code commit}
-	 * then some before-commit error caused the commit attempt to fail. For
+	 * may propagate {@link org.springframework.dao.DataAccessException} as well,
-	 * example, an O/R Mapping tool might have tried to flush changes to the
+	 * either from before-commit flushes or from the actual commit step.
-	 * database right before commit, with the resulting DataAccessException
-	 * causing the transaction to fail. The original exception will be
-	 * propagated to the caller of this commit method in such a case.
 	 * @param status object returned by the {@code getTransaction} method
 	 * @throws UnexpectedRollbackException in case of an unexpected rollback
 	 * that the transaction coordinator initiated
@@ -110,6 +107,8 @@ public interface PlatformTransactionManager extends TransactionManager {
 	 * The transaction will already have been completed and cleaned up when commit
 	 * returns, even in case of a commit exception. Consequently, a rollback call
 	 * after commit failure will lead to an IllegalTransactionStateException.
+	 * <p>Depending on the concrete transaction manager setup, {@code rollback}
+	 * may propagate {@link org.springframework.dao.DataAccessException} as well.
 	 * @param status object returned by the {@code getTransaction} method
 	 * @throws TransactionSystemException in case of rollback or system errors
 	 * (typically caused by fundamental resource failures)