spring-projects/spring-framework

spring-tx

Active contributors: Juergen Hoeller, Sam Brannen

Purpose

spring-tx provides the transaction management abstraction used across the framework. It defines PlatformTransactionManager (imperative) and ReactiveTransactionManager (reactive), the @Transactional annotation, transaction propagation/isolation semantics, and exception translation common to all data-access modules. This module turns "begin/commit/rollback" into one-line boundaries.

Directory layout

spring-tx/
└── src/main/java/org/springframework/transaction/
    ├── PlatformTransactionManager.java
    ├── ReactiveTransactionManager.java
    ├── TransactionDefinition.java
    ├── TransactionStatus.java
    ├── TransactionException.java
    ├── annotation/                                # @Transactional, @EnableTransactionManagement
    ├── config/                                    # XML <tx:annotation-driven>
    ├── event/                                     # @TransactionalEventListener
    ├── interceptor/                               # TransactionInterceptor (the AOP advice)
    ├── jta/                                       # JTA support (legacy)
    ├── reactive/                                  # ReactiveTransactionManager support
    └── support/
        ├── AbstractPlatformTransactionManager.java
        ├── DefaultTransactionDefinition.java
        ├── TransactionTemplate.java
        └── TransactionSynchronization.java

Key abstractions

Type	File	Role
`PlatformTransactionManager`	`spring-tx/src/main/java/org/springframework/transaction/PlatformTransactionManager.java`	Imperative tx abstraction
`ReactiveTransactionManager`	`spring-tx/src/main/java/org/springframework/transaction/ReactiveTransactionManager.java`	Reactive tx abstraction
`AbstractPlatformTransactionManager`	`spring-tx/src/main/java/org/springframework/transaction/support/AbstractPlatformTransactionManager.java`	Template for resource-specific tx managers
`TransactionDefinition`	`spring-tx/src/main/java/org/springframework/transaction/TransactionDefinition.java`	Propagation, isolation, timeout, read-only flag
`TransactionStatus`	`spring-tx/src/main/java/org/springframework/transaction/TransactionStatus.java`	Live transaction handle (rollback-only, completion, …)
`@Transactional`	`spring-tx/src/main/java/org/springframework/transaction/annotation/Transactional.java`	Annotation read by post-processors
`TransactionInterceptor`	`spring-tx/src/main/java/org/springframework/transaction/interceptor/TransactionInterceptor.java`	The AOP advice that begins/commits/rollbacks transactions
`TransactionTemplate`	`spring-tx/src/main/java/org/springframework/transaction/support/TransactionTemplate.java`	Programmatic alternative to `@Transactional`
`TransactionSynchronization`	`spring-tx/src/main/java/org/springframework/transaction/support/TransactionSynchronization.java`	Hooks into commit/rollback
`TransactionSynchronizationManager`	`spring-tx/src/main/java/org/springframework/transaction/support/TransactionSynchronizationManager.java`	Thread-bound (or context-bound) tx state

How it works

`@Transactional` end-to-end

sequenceDiagram
    participant App
    participant Proxy as Bean (proxied)
    participant TxInt as TransactionInterceptor
    participant Mgr as PlatformTransactionManager
    participant DS as DataSource (or other resource)
    App->>Proxy: doWork()
    Proxy->>TxInt: invoke(method)
    TxInt->>Mgr: getTransaction(definition)
    Mgr->>DS: open connection, set autoCommit=false
    Mgr->>TxInt: TransactionStatus
    TxInt->>Proxy: target.doWork()
    Proxy-->>TxInt: result or exception
    alt success
        TxInt->>Mgr: commit(status)
        Mgr->>DS: COMMIT, return connection
    else rollback-trigger exception
        TxInt->>Mgr: rollback(status)
        Mgr->>DS: ROLLBACK, return connection
    end
    TxInt-->>App: result (or rethrow)

Propagation behaviors

Propagation enum values (defined on Transactional):

Behavior	Meaning
`REQUIRED`	Use existing transaction or create a new one
`REQUIRES_NEW`	Suspend any existing transaction and create a new one
`NESTED`	Nested transaction (savepoint) within an outer one
`MANDATORY`	An existing transaction must exist; otherwise throw
`NEVER`	Must run without a transaction; otherwise throw
`NOT_SUPPORTED`	Run non-transactionally; suspend any existing transaction
`SUPPORTS`	Run in a transaction if one exists, otherwise non-transactionally

The handling logic is in AbstractPlatformTransactionManager.handleExistingTransaction(...).

Resource-specific tx managers

spring-tx is the abstraction; concrete implementations live elsewhere:

Manager	Module	Resource
`DataSourceTransactionManager`	`spring-jdbc`	JDBC `DataSource`
`JpaTransactionManager`	`spring-orm`	JPA `EntityManagerFactory`
`R2dbcTransactionManager`	`spring-r2dbc`	R2DBC connection factory
`JtaTransactionManager`	`spring-tx`	JTA `UserTransaction`
`JmsTransactionManager`	`spring-jms`	JMS session

A typical app picks one and registers it as a bean. @Transactional finds it by name (default transactionManager) or qualifier.

Reactive transactions

ReactiveTransactionManager operates on a Reactor Mono<ReactiveTransaction>. The @Transactional annotation is shared, but methods returning Mono or Flux flow through the reactive infrastructure (TransactionalOperator, R2dbcTransactionManager). State is held in Reactor Context (not ThreadLocal) so it survives async hops.

Transaction synchronization

TransactionSynchronization provides beforeCommit, afterCommit, afterCompletion callbacks. Used by JPA flushing and for @TransactionalEventListener (events deferred until commit).

Integration points

Depends on spring-beans, spring-core, optionally spring-aop (for the interceptor).
AOP integration: TransactionInterceptor is woven via either proxies (spring-aop) or AspectJ (spring-aspects).
@TransactionalEventListener: events scheduled to fire after commit; provided in spring-tx itself.
Reactive bridge: TransactionalOperator for non-AOP-style reactive transaction boundaries.

Entry points for modification

New transaction manager — Subclass AbstractPlatformTransactionManager and implement doBegin/doCommit/doRollback. The class is well-commented.
Custom propagation rules — Override hooks in AbstractPlatformTransactionManager.
Cross-resource transactions — Use JtaTransactionManager (with a JTA provider) or, more commonly, "chained" transactions for best-effort semantics.

Notable internals

Rollback rules — By default, @Transactional rolls back on RuntimeException or Error, not checked exceptions. Override with rollbackFor / noRollbackFor attributes.
TransactionSynchronizationManager.bind/unbindResource — How JDBC, JPA, and JMS resources are stored per-thread (or per-Reactor-context) for participation in the active transaction.