Discuss JdbcTransactionManager vs DataSourceTransactionManager

Closes gh-30802

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)

src/docs/asciidoc/data-access.adoc

@@ -1455,7 +1455,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
@@ -1835,17 +1834,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>
@@ -3024,10 +3023,10 @@ example shows:
 	}
 ----
 
-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`:
 
 [source,java,indent=0,subs="verbatim,quotes",role="primary"]
 .Java
@@ -3157,30 +3156,30 @@ advanced features require a JDBC 3.0 driver.
 
 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 <<jdbc-core>>, <<jdbc-advanced-jdbc>>, and
 <<jdbc-simple-jdbc>>.
 
-* `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 Java EE container. A subpackage
+use for testing and running unmodified JDBC code outside of a Java 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
 <<jdbc-connections>> and <<jdbc-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
 <<jdbc-object>>. 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
@@ -3804,7 +3803,9 @@ See also <<jdbc-JdbcTemplate-idioms>> for guidelines on using the
 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`.
 
 `SQLErrorCodeSQLExceptionTranslator` is the implementation of `SQLExceptionTranslator`
 that is used by default. This implementation uses specific vendor codes. It is more
@@ -3830,8 +3831,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.
 
@@ -3864,12 +3865,12 @@ You can extend `SQLErrorCodeSQLExceptionTranslator`, as the following example sh
 	}
 ----
 
-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:
 
 [source,java,indent=0,subs="verbatim,quotes",role="primary"]
 .Java
@@ -3877,7 +3878,6 @@ translator:
 	private JdbcTemplate jdbcTemplate;
 
 	public void setDataSource(DataSource dataSource) {
-
 		// create a JdbcTemplate and set data source
 		this.jdbcTemplate = new JdbcTemplate();
 		this.jdbcTemplate.setDataSource(dataSource);
@@ -3886,7 +3886,6 @@ translator:
 		CustomSQLErrorCodesTranslator tr = new CustomSQLErrorCodesTranslator();
 		tr.setDataSource(dataSource);
 		this.jdbcTemplate.setExceptionTranslator(tr);
-
 	}
 
 	public void updateShippingCharge(long orderId, long pct) {
@@ -4260,8 +4259,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]]
@@ -4300,7 +4303,6 @@ In contrast to `DriverManagerDataSource`, it reuses the same connection all the
 avoiding excessive creation of physical connections.
 
 
-
 [[jdbc-DriverManagerDataSource]]
 ==== Using `DriverManagerDataSource`
 
@@ -4336,29 +4338,47 @@ javadoc for more details.
 
 
 [[jdbc-DataSourceTransactionManager]]
-==== Using `DataSourceTransactionManager`
+==== Using `DataSourceTransactionManager` / `JdbcTransactionManager`
 
 The `DataSourceTransactionManager` class is a `PlatformTransactionManager`
-implementation for single JDBC datasources. 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 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 savepoints (`PROPAGATION_NESTED`),
+custom isolation levels, and timeouts that get applied as appropriate JDBC statement
+query timeouts. To support the latter, application code must either use `JdbcTemplate` or
+call the `DataSourceUtils.applyTransactionTimeout(..)` method for each created statement.
+
+You can use `DataSourceTransactionManager` instead of `JtaTransactionManager` in the
+single-resource case, as it does not require the container to support a JTA transaction
+coordinator. Switching between these transaction managers is just a matter of configuration,
+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.
 
-The `DataSourceTransactionManager` class supports custom isolation levels and timeouts
+[NOTE]
-that get applied as appropriate JDBC statement query timeouts. To support the latter,
+====
-application code must either use `JdbcTemplate` or call the
+As of 5.3, Spring provides an extended `JdbcTransactionManager` variant which adds
-`DataSourceUtils.applyTransactionTimeout(..)` method for each created statement.
+exception translation capabilities on commit/rollback (aligned with `JdbcTemplate`).
-
+Where `DataSourceTransactionManager` will only ever throw `TransactionSystemException`
-You can use this implementation instead of `JtaTransactionManager` in the single-resource
+(analogous to JTA), `JdbcTransactionManager` translates database locking failures etc to
-case, as it does not require the container to support JTA. Switching between
+corresponding `DataAccessException` subclasses. Note that application code needs to be
-both is just a matter of configuration, provided you stick to the required connection lookup
+prepared for such exceptions, not exclusively expecting `TransactionSystemException`.
-pattern. JTA does not support custom isolation levels.
+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.
+====
 
 
 
@@ -4373,13 +4393,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:
 
 [source,java,indent=0,subs="verbatim,quotes",role="primary"]
 .Java
@@ -7276,19 +7296,16 @@ javadoc for more details.
 ==== Using `R2dbcTransactionManager`
 
 The `R2dbcTransactionManager` class is a `ReactiveTransactionManager` implementation for
-single R2DBC datasources. 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.
 
 
 
@@ -8457,7 +8474,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