Declarative Transaction Management: How @Transactional Works Under the Hood

Why You Need This in Real Life

Here is a 5-line Java bug that has cost banking engineering teams thousands of dollars in un-reconciled account balances:

@Service
public class TransferService {

    @Autowired
    private AccountRepository accountRepository;

    public void transferFunds(String fromId, String toId, BigDecimal amount) {
        deduct(fromId, amount); // Deducts $500 from Account A
        credit(toId, amount);  // Fails due to NullPointerException!
    }

    @Transactional
    public void deduct(String accountId, BigDecimal amount) {
        Account account = accountRepository.findById(accountId).orElseThrow();
        account.setBalance(account.getBalance().subtract(amount));
    }

    @Transactional
    public void credit(String accountId, BigDecimal amount) {
        Account account = accountRepository.findById(accountId).orElseThrow();
        account.setBalance(account.getBalance().add(amount));
    }
}

During a live transaction, deduct() succeeds, but credit() throws a NullPointerException. Money vanishes from Account A, but never arrives in Account B.

Why didn’t @Transactional roll back the entire fund transfer? Because transferFunds() was called without @Transactional, and internal method invocations (this.deduct()) bypass Spring’s AOP dynamic proxy completely. Account A’s deduction committed to the database in its own isolated transaction!

To prevent financial loss and silent data corruption, you must understand how Spring’s transaction management interceptors work under the hood.

Part 1: Architecture of Spring Transaction Management

Spring decouples transaction management from specific transaction APIs (JDBC, JPA, Hibernate, JTA) using three core components:

+-----------------------------------------------------------------------------+
|                Spring Transaction Architecture Stack                        |
|                                                                             |
|  1. @Transactional Annotation (Declarative Metadata)                        |
|        |                                                                    |
|        v                                                                    |
|  2. TransactionInterceptor (AOP Advice)                                     |
|        |                                                                    |
|        v                                                                    |
|  3. PlatformTransactionManager (Abstraction Strategy)                       |
|     - JpaTransactionManager / DataSourceTransactionManager                  |
|        |                                                                    |
|        v                                                                    |
|  4. TransactionSynchronizationManager (ThreadLocal Storage)                 |
|     - Binds DB Connection to current Thread                                 |
+-----------------------------------------------------------------------------+

The `PlatformTransactionManager` Interface

public interface PlatformTransactionManager {
    TransactionStatus getTransaction(TransactionDefinition definition) throws TransactionException;
    void commit(TransactionStatus status) throws TransactionException;
    void rollback(TransactionStatus status) throws TransactionException;
}

Part 2: Dissecting `TransactionInterceptor` Execution

When a method annotated with @Transactional is invoked through a Spring proxy, TransactionInterceptor executes the following operational steps:

Caller ---> [ Spring CGLIB Proxy ] ---> TransactionInterceptor.invoke()
                                                |
    +-------------------------------------------+-------------------------------------------+
    |                                                                                       |
    v                                                                                       v
1. Obtain Transaction (getTransaction())                                    3. Handle Exception / Rollback
   - Fetch DB connection from HikariCP                                         - Catch Throwable
   - Set autocommit = false                                                    - Check if rollbackFor matches
   - Bind connection to ThreadLocal                                            - Execute rollback()
    |                                                                                       |
    v                                                                                       |
2. Execute Business Logic (Invocation.proceed())                                            |
    |                                                                                       |
    v                                                                                       |
4. Commit Transaction (commit())                                                            |
   - Flush PersistenceContext to DB                                                         |
   - Execute SQL COMMIT                                                                     |
   - Restore autocommit = true                                                              |
   - Unbind connection from ThreadLocal & return to Pool <----------------------------------+

`TransactionSynchronizationManager` & ThreadLocal Connection Storage

How do JdbcTemplate or Hibernate repositories know which database connection to use inside a @Transactional block without passing Connection parameters through every Java method signature?

Spring stores active database connections in TransactionSynchronizationManager using Java ThreadLocal storage:

public abstract class TransactionSynchronizationManager {
    // ThreadLocal map storing Connection resources per thread
    private static final ThreadLocal<Map<Object, Object>> resources =
            new NamedThreadLocal<>("Transactional resources");

    public static Object getResource(Object key) { ... }
    public static void bindResource(Object key, Object value) { ... }
}

When JpaRepository.save() executes, it calls DataSourceUtils.getConnection(dataSource), which inspects TransactionSynchronizationManager. If an active connection is bound to the current thread, it reuses that connection instead of fetching a new one from HikariCP.

Part 3: Transaction Propagation Behaviors

Spring supports seven propagation behaviors (Propagation enum) defining how transaction boundaries interact when one transactional method calls another:

Propagation Strategy	Behavior
`REQUIRED` (Default)	Joins existing transaction if present; creates a new transaction if none exists.
`REQUIRES_NEW`	Always creates a fresh transaction, suspending any existing transaction until completion.
`NESTED`	Executes within a nested transaction using database Savepoints (`SAVEPOINT`).
`SUPPORTS`	Executes within transaction if present; executes non-transactionally if none exists.
`NOT_SUPPORTED`	Suspends existing transaction and executes non-transactionally.
`MANDATORY`	Throws `IllegalTransactionStateException` if no active transaction exists.
`NEVER`	Throws exception if an active transaction exists.

Part 4: Production Gotchas & Silent Rollback Traps

Trap 1: The Self-Invocation Bypassing Proxy Trap

As demonstrated in our introductory banking example, calling an @Transactional method from within the same class (this.method()) completely bypasses the Spring proxy:

@Service
public class OrderService {

    // NOT AN ANNOTATED METHOD
    public void processOrder(Order order) {
        // Direct internal call bypasses CGLIB proxy! @Transactional is IGNORED!
        saveOrderWithTransaction(order); 
    }

    @Transactional
    public void saveOrderWithTransaction(Order order) {
        // Executes without an active transaction!
    }
}

Fix: Move the transactional method to a separate @Service bean, or self-inject the proxy using @Autowired / ApplicationContext.

Trap 2: Checked Exception Rollback Default Behavior

By default, Spring transactions ONLY roll back on unchecked exceptions (RuntimeException and Error). Checked exceptions (Exception) DO NOT trigger a rollback!

// DANGEROUS: Checked exception DOES NOT trigger rollback!
@Transactional
public void processPayment() throws InsufficientFundsException {
    accountRepository.deduct(500);
    if (balance < 0) {
        throw new InsufficientFundsException("Low balance"); // Checked Exception! Transaction COMMITS!
    }
}

Fix: Explicitly specify rollbackFor = Exception.class:
```
@Transactional(rollbackFor = Exception.class)
```

Trap 3: Long-Running External I/O inside `@Transactional`

If an @Transactional method performs a slow HTTP REST API call or third-party payment gateway integration, the database connection remains locked for the entire duration of the HTTP call.

@Transactional
public void ProcessOrder(Order order) {
    orderRepository.save(order);
    
    // BAD: Database connection is held captive while waiting for slow HTTP API (5000ms latency)!
    paymentGatewayClient.chargeCreditCard(order.getAmount()); 
}

Fix: Keep transactions short. Perform external HTTP calls outside the @Transactional boundary, then open a brief transaction to update database state.

Next Steps

Now that we understand how Spring manages transactions using AOP proxies, we will enter Module 6 (AOP, Dynamic Proxies & Production): starting with Aspect-Oriented Programming (AOP) JoinPoints, Pointcuts, and Advices.

References & Further Reading

Spring.io. Spring Framework Reference Manual — Transaction Management & @Transactional. Spring Docs.
Gray, J., & Reuter, A. (1992). Transaction Processing: Concepts and Techniques. Morgan Kaufmann.
King, G., & Bauer, C. (2015). Java Persistence with Hibernate (2nd Edition). Manning.