Doc: JdbcTransactionManager vs DataSourceTransactionManager

[manueljordan]

Through the javadoc of PlatformTransactionManager I did realize about the JdbcTransactionManager class. The latter is a subclass of DataSourceTransactionManager.

Normally and practically always the DataSourceTransactionManager class is used to define the TX infrastructure for JDBC and MyBatis.

Now, to be honest, is not clear in the javadoc of the JdbcTransactionManager class when it is mandatory over DataSourceTransactionManager or what is/are the advantages over its superclass.

I read all the sections of the Transaction Management section of the Reference documentation and the JdbcTransactionManager term does not appear.

Therefore is not clear with the current documentation when is mandatory use JdbcTransactionManager .

Thanks for your understanding.

[jhoeller]

The only difference is exception translation: Like with JpaTransactionManager, there is DataAccessException translation on commit here. Where DataSourceTransactionManager will only ever throw TransactionSystemException on commit, JdbcTransactionManager is more sophisticated and translates locking failures etc to corresponding DataAccessException subclasses. Note that calling code needs to be prepared for that, not exclusively expecting TransactionSystemException in such scenarios. That's the main reason why those are two separate transaction manager classes to choose from.

It is effectively never mandatory to use JdbcTransactionManager. That said, it is a good idea to use it in application setups that are used to JPA-style exception translation (e.g. having pluggable repository implementations with JPA and JDBC variants). It is also a good idea to use it with callers that are able to handle specific DataAccessException subclasses in catch blocks around transactions, providing clearer and more expressive exceptions for concurrency failures (e.g. with PostgreSQL). I'll make sure to mention this in the reference documentation, generally recommending it over DataSourceTransactionManager these days.

[manueljordan]

Thanks for the feedback/information. Just a friendly observation, pls take it with the best intentions, could be added some Test classes to show in action all the theory explained? Or better if snippet codes are included - the point is make clear how JdbcTransactionManager is better than DataTransactionManager, but as a complement of your current theory through Java code. Thanks for your understanding

[jhoeller]

It's not that straightforward to illustrate since transaction managers are usually kicking in behind an @Transactional method. The caller of such an @Transactional method would receive a TransactionSystemException on commit failures from DataSourceTransactionManager, whereas it would commonly receive DataAccessException subclasses (such as ConcurrencyFailureException) from JdbcTransactionManager. That's the difference in a nutshell.

Of course, the difference won't matter much if the caller is not specifically handling exceptions to begin with. However, if the caller expects to handle ConcurrencyFailureException or the like, this will work reliably with a JdbcTransactionManager setup, consistently propagating ConcurrencyFailureException and co from JdbcTemplate operations (when happening for a specific statement execution) as well as from commit (when happening late in the database commit step).

try {
    myTransactionalMethodCalled();
}
catch (ConcurrencyFailureException ex) {
    // some specific handling
}

[manueljordan]

Thanks for the extra explanation ...