When @Transactional and TransactionTemplate Clash: How to Choose the Right Spring Transaction Management

Spring Transaction Management Options

Spring provides three ways to manage transactions: the declarative @Transactional annotation, the programmatic TransactionTemplate, and direct use of PlatformTransactionManager (or TransactionManager).

@Transactional – Declarative

Applying @Transactional to a method creates a proxy via Spring AOP. The proxy starts, commits, or rolls back a transaction around the method execution, keeping business code free of transaction boilerplate. Limitations:

Internal method calls bypass the proxy, so a self‑invoked @Transactional method never starts a transaction.

Only public methods are intercepted; private, protected or package‑private methods are ignored.

Rollback is triggered automatically only for RuntimeException and Error. Checked exceptions require explicit configuration.

@Service
public class UserService {
    @Transactional
    public void createUser(User user) {
        userRepository.save(user);
        // if an exception is thrown here, the transaction rolls back
        sendWelcomeEmail(user);
    }
}

TransactionTemplate – Programmatic but Concise

TransactionTemplate

balances declarative convenience with explicit control. It executes a callback within a transaction and allows the code to decide whether to roll back by calling status.setRollbackOnly().

@Service
public class AccountService {
    @Autowired
    private TransactionTemplate transactionTemplate;

    public void transfer(String from, String to, BigDecimal amount) {
        transactionTemplate.execute(status -> {
            try {
                accountRepository.debit(from, amount);
                accountRepository.credit(to, amount);
                return null;
            } catch (InsufficientFundsException e) {
                status.setRollbackOnly();
                throw e;
            }
        });
    }
}

The drawback is that transaction logic is mixed with business logic, which can reduce readability, especially with deep nesting.

PlatformTransactionManager – Full Control

Using PlatformTransactionManager directly gives complete control over isolation level, propagation behavior, timeout, and explicit commit/rollback steps.

@Service
public class PaymentService {
    @Autowired
    private PlatformTransactionManager transactionManager;

    public void processPayment(Payment payment) {
        DefaultTransactionDefinition def = new DefaultTransactionDefinition();
        def.setIsolationLevel(TransactionDefinition.ISOLATION_READ_COMMITTED);
        def.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRED);
        TransactionStatus status = transactionManager.getTransaction(def);
        try {
            paymentRepository.save(payment);
            notificationService.sendPaymentConfirmation(payment);
            transactionManager.commit(status);
        } catch (Exception e) {
            transactionManager.rollback(status);
            throw e;
        }
    }
}

This approach is powerful but verbose; forgetting to commit or roll back leads to data inconsistency.

Choosing the Appropriate Approach

In most applications @Transactional solves about 90 % of scenarios with minimal code. Use TransactionTemplate when you need fine‑grained control such as conditional rollbacks or managing multiple transactions inside a single method. Resort to PlatformTransactionManager only for framework‑level code or highly specialized requirements.

Practical Example: Batch User Import

Goal: import many users; a failure for one user must not affect others.

@Service
public class UserImportService {
    public void importUsers(List<User> users) {
        for (User user : users) {
            try {
                // ❌ internal call – transaction will NOT start
                createUserWithTransaction(user);
            } catch (Exception e) {
                log.error("Import failed for {}", user.getUsername(), e);
            }
        }
    }

    @Transactional
    public void createUserWithTransaction(User user) {
        userRepository.save(user);
        userProfileRepository.save(user.getProfile());
    }
}

Because createUserWithTransaction is invoked from within the same class, the @Transactional annotation is ignored (internal method call). Fixes:

Extract the transactional method into a separate service so the call goes through a Spring proxy.

Obtain the current proxy via AopContext.currentProxy() and invoke the method on it.

@Service
public class UserImportService {
    @Autowired
    private UserTransactionService userTransactionService;

    public void importUsers(List<User> users) {
        for (User user : users) {
            try {
                userTransactionService.createUserWithTransaction(user); // ✅ works
            } catch (Exception e) {
                log.error("Import failed for {}", user.getUsername(), e);
            }
        }
    }
}

@Service
public class UserTransactionService {
    @Transactional
    public void createUserWithTransaction(User user) {
        userRepository.save(user);
        userProfileRepository.save(user.getProfile());
    }
}

Common Pitfalls

Internal method calls : self‑invocation bypasses the proxy, rendering @Transactional ineffective.

Only public methods are intercepted : private or protected methods annotated with @Transactional have no effect.

Exception matching : by default only RuntimeException and Error trigger rollback; checked exceptions require explicit rollbackFor configuration.

Read‑only transactions : may not improve performance depending on the underlying connection‑pool configuration.

Transaction timeout : setting an excessively long timeout can hide deadlocks and cause the system to hang.

Mixed‑Usage Problems

Combining @Transactional and TransactionTemplate in the same service can produce confusing transaction boundaries and propagation mismatches, making debugging difficult. Keeping a single transaction‑management style per service simplifies reasoning about transaction scope.

@Service
public class OrderService {
    @Autowired
    private TransactionTemplate transactionTemplate;

    @Transactional
    public void processOrder(Order order) {
        orderRepository.save(order);
        // The following template starts a new transaction with default propagation
        transactionTemplate.execute(status -> {
            auditRepository.save(new OrderAudit(order));
            return null;
        });
    }
}