Understanding Spring Transaction Management: Core Concepts, Propagation, and Common Pitfalls

Spring transaction management is widely used via the @Transactional annotation or XML configuration, but many developers only have a superficial understanding; this article dives deeper into the underlying mechanisms and common pitfalls.

Prerequisite knowledge : familiarity with Spring AOP, dynamic proxy (JDK or CGLIB), bean lifecycle, and the singleton nature of Spring beans. Understanding these concepts is necessary to grasp how transactions are applied.

Example 1 – Service exception handling : A service method annotated with @Transactional throws a runtime exception. Despite the controller catching the exception, Spring automatically rolls back the transaction because runtime exceptions trigger rollback, while checked exceptions do not.

// Service method
@Transactional
public Employee addEmployee() throws Exception {
    Employee employee = new Employee("3y", 23);
    employeeRepository.save(employee);
    // Simulate exception
    int i = 1 / 0;
    return employee;
}

// Controller method
@RequestMapping("/add")
public Employee addEmployee() {
    Employee employee = null;
    try {
        employee = employeeService.addEmployee();
    } catch (Exception e) {
        e.printStackTrace();
    }
    return employee;
}

Example 2 – Internal method call without transaction : A non‑transactional method in the same class calls a @Transactional method. Because Spring creates a proxy object, the internal call bypasses the proxy, resulting in no transaction being started.

// Non‑transactional method calling transactional one
public Employee addEmployee2Controller() throws Exception {
    return this.addEmployee();
}

@Transactional
public Employee addEmployee() throws Exception {
    employeeRepository.deleteAll();
    Employee employee = new Employee("3y", 23);
    int i = 1 / 0; // Simulate exception
    return employee;
}

The same principle applies when the transactional method resides in a different service: the proxy is used, so the transaction is active.

Transaction propagation : When a transactional method invokes another method (whether annotated or not), the inner method participates in the outer transaction according to the propagation settings. This is a core part of Spring’s transaction model.

Multithreading safety : Although Spring beans are singletons, thread‑unsafe state is avoided by storing connection/session objects in ThreadLocal . Components such as TransactionSynchronizationManager rely on ThreadLocal to keep per‑thread transaction context.

BeanPostProcessor (BPP) : BPPs allow custom processing of bean instances before and after initialization, and are crucial for creating the proxy objects that enable AOP‑based transaction handling.

Key transaction interfaces :

TransactionDefinition – defines transaction attributes (isolation, propagation, timeout, read‑only).

TransactionStatus – represents the current state of a transaction.

PlatformTransactionManager – the core transaction manager interface implemented by specific resource adapters (e.g., JDBC, JPA).

TransactionProxyFactoryBean, TransactionInterceptor, TransactionAttribute – used in declarative transaction configuration.

The article concludes by summarizing these concepts and providing references for further study.