Understanding Spring Transaction Management: Mechanisms, Common Pitfalls, and Best Practices

Spring Framework is the standard for Java projects, and its transaction management is a core feature; however, without understanding its implementation principles, developers can easily encounter pitfalls.

1. Ways to Integrate Spring Transactions

Spring transactions can be used in two major categories:

1. Declarative

Based on <tx:advice> with TransactionProxyFactoryBean

Using the <tx> and <aop> namespace tags

Annotating methods or classes with @Transactional

2. Programmatic

Using the TransactionManager API directly

Using TransactionTemplate

Most projects adopt the latter two declarative approaches because they leverage powerful pointcut expressions and simple annotation configuration.

2. Spring Transaction Implementation Mechanism

The core of Spring transaction handling is the TransactionInterceptor class, which extends TransactionAspectSupport . The interceptor opens a transaction, executes the target method, and commits or rolls back based on the outcome.

@Override
public void init() {
    registerBeanDefinitionParser("advice", new TxAdviceBeanDefinitionParser());
    registerBeanDefinitionParser("annotation-driven", new AnnotationDrivenBeanDefinitionParser());
    registerBeanDefinitionParser("jta-transaction-manager", new JtaTransactionManagerBeanDefinitionParser());
}

class TxAdviceBeanDefinitionParser extends AbstractSingleBeanDefinitionParser {
    @Override
    protected Class
getBeanClass(Element element) {
        return TransactionInterceptor.class;
    }
}

The invoke method of TransactionInterceptor delegates to invokeWithinTransaction of TransactionAspectSupport :

public Object invoke(final MethodInvocation invocation) throws Throwable {
    Class
targetClass = (invocation.getThis() != null ? AopUtils.getTargetClass(invocation.getThis()) : null);
    return invokeWithinTransaction(invocation.getMethod(), targetClass, new InvocationCallback() {
        @Override
        public Object proceedWithInvocation() throws Throwable {
            return invocation.proceed();
        }
    });
}

TransactionAspectSupport obtains the transaction attributes, determines the appropriate PlatformTransactionManager , and manages commit/rollback logic. It also handles transaction propagation, suspension, and resumption via TransactionSynchronizationManager .

protected Object invokeWithinTransaction(Method method, Class
targetClass, final InvocationCallback invocation) throws Throwable {
    final TransactionAttribute txAttr = getTransactionAttributeSource().getTransactionAttribute(method, targetClass);
    final PlatformTransactionManager tm = determineTransactionManager(txAttr);
    final String joinpointIdentification = methodIdentification(method, targetClass, txAttr);
    if (txAttr == null || !(tm instanceof CallbackPreferringPlatformTransactionManager)) {
        TransactionInfo txInfo = createTransactionIfNecessary(tm, txAttr, joinpointIdentification);
        Object retVal = null;
        try {
            retVal = invocation.proceedWithInvocation();
        } catch (Throwable ex) {
            completeTransactionAfterThrowing(txInfo, ex);
            throw ex;
        } finally {
            cleanupTransactionInfo(txInfo);
        }
        commitTransactionAfterReturning(txInfo);
        return retVal;
    }
    // ... other branches omitted for brevity
}

Connection handling is performed by DataSourceUtils , which binds a ConnectionHolder to the current thread via TransactionSynchronizationManager :

public static Connection getConnection(DataSource dataSource) throws CannotGetJdbcConnectionException {
    try {
        return doGetConnection(dataSource);
    } catch (SQLException ex) {
        throw new CannotGetJdbcConnectionException("Could not get JDBC Connection", ex);
    }
}

The transaction manager ( AbstractPlatformTransactionManager ) deals with propagation behaviors such as PROPAGATION_REQUIRES_NEW by suspending the current transaction and creating a new one.

private TransactionStatus handleExistingTransaction(TransactionDefinition definition, Object transaction, boolean debugEnabled) throws TransactionException {
    if (definition.getPropagationBehavior() == TransactionDefinition.PROPAGATION_REQUIRES_NEW) {
        if (debugEnabled) {
            logger.debug("Suspending current transaction, creating new transaction with name [" + definition.getName() + "]");
        }
        SuspendedResourcesHolder suspendedResources = suspend(transaction);
        try {
            boolean newSynchronization = (getTransactionSynchronization() != SYNCHRONIZATION_NEVER);
            DefaultTransactionStatus status = newTransactionStatus(definition, transaction, true, newSynchronization, debugEnabled, suspendedResources);
            doBegin(transaction, definition);
            prepareSynchronization(status, definition);
            return status;
        } catch (RuntimeException beginEx) {
            resumeAfterBeginException(transaction, suspendedResources, beginEx);
            throw beginEx;
        } catch (Error beginErr) {
            resumeAfterBeginException(transaction, suspendedResources, beginErr);
            throw beginErr;
        }
    }
    // ... other propagation handling omitted
}

Spring creates AOP proxies using either JDK dynamic proxies or CGLIB. By default, if an interface is present, JDK proxies are used; otherwise, CGLIB is employed.

public class DefaultAopProxyFactory implements AopProxyFactory, Serializable {
    @Override
    public AopProxy createAopProxy(AdvisedSupport config) throws AopConfigException {
        if (config.isOptimize() || config.isProxyTargetClass() || hasNoUserSuppliedProxyInterfaces(config)) {
            Class
targetClass = config.getTargetClass();
            if (targetClass == null) {
                throw new AopConfigException("TargetSource cannot determine target class: Either an interface or a target is required for proxy creation.");
            }
            if (targetClass.isInterface() || Proxy.isProxyClass(targetClass)) {
                return new JdkDynamicAopProxy(config);
            }
            return new ObjenesisCGLIBAopProxy(config);
        } else {
            return new JdkDynamicAopProxy(config);
        }
    }
}

3. Common Pitfalls in Spring Transactions

3.1 Transaction Not Effective

When a method is called directly within the same class, the call bypasses the proxy, so the transaction advice is not applied. Example output shows that without proxy the connection hash codes differ, indicating separate connections.

<tx:advice id="txAdvice" transaction-manager="myTxManager">
    <tx:attributes>
        <tx:method name="openAccount" isolation="DEFAULT" propagation="REQUIRED"/>
        <tx:method name="openStock" isolation="DEFAULT" propagation="REQUIRED"/>
        <tx:method name="openStockInAnotherDb" isolation="DEFAULT" propagation="REQUIRES_NEW"/>
        <tx:method name="openTx" isolation="DEFAULT" propagation="REQUIRED"/>
        <tx:method name="openWithoutTx" isolation="DEFAULT" propagation="NEVER"/>
        <tx:method name="openWithMultiTx" isolation="DEFAULT" propagation="REQUIRED"/>
    </tx:attributes>
</tx:advice>

Solutions include injecting the bean itself, using AopContext.currentProxy() , or configuring the proxy correctly.

3.2 Transaction Not Rolled Back

Spring rolls back only on RuntimeException or Error by default. Checked exceptions such as IOException will not trigger a rollback unless rollback-for is specified.

protected void completeTransactionAfterThrowing(TransactionInfo txInfo, Throwable ex) {
    if (txInfo != null && txInfo.hasTransaction()) {
        if (txInfo.transactionAttribute.rollbackOn(ex)) {
            try {
                txInfo.getTransactionManager().rollback(txInfo.getTransactionStatus());
            } catch (TransactionSystemException ex2) {
                logger.error("Application exception overridden by rollback exception", ex);
                ex2.initApplicationException(ex);
                throw ex2;
            }
        }
        // ... other handling omitted
    }
}

public class DefaultTransactionAttribute extends DefaultTransactionDefinition implements TransactionAttribute {
    @Override
    public boolean rollbackOn(Throwable ex) {
        return (ex instanceof RuntimeException || ex instanceof Error);
    }
}

To roll back on a custom checked exception, add rollback-for="StockException" to the <tx:method> definition.

3.3 Transaction Timeout Not Effective

Transaction timeout is only checked when a JDBC operation via JdbcTemplate (or DataSourceUtils ) occurs. If the timeout expires before any JDBC call, Spring cannot detect it, and the transaction will not be rolled back.

public long getTimeToLiveInMillis() throws TransactionTimedOutException {
    if (this.deadline == null) {
        throw new IllegalStateException("No timeout specified for this resource holder");
    }
    long timeToLive = this.deadline.getTime() - System.currentTimeMillis();
    checkTransactionTimeout(timeToLive <= 0);
    return timeToLive;
}

private void checkTransactionTimeout(boolean deadlineReached) throws TransactionTimedOutException {
    if (deadlineReached) {
        setRollbackOnly();
        throw new TransactionTimedOutException("Transaction timed out: deadline was " + this.deadline);
    }
}

Therefore, timeout configuration should be used with care, especially when using MyBatis or manual Connection handling.

4. Summary

Spring’s declarative transaction management abstracts low‑level JDBC commit/rollback, propagation, and connection handling, making backend development much simpler. However, developers must understand the underlying mechanisms to avoid common pitfalls such as missing proxy invocation, improper rollback configuration, and ineffective timeout settings.

Key take‑aways:

Ensure transaction advice is applied (use proxies, avoid self‑invocation).

Configure rollback-for for checked exceptions and avoid swallowing exceptions.

Be aware that timeout checks rely on JDBC template calls; they may not work with MyBatis or raw JDBC.