In-depth Analysis of Spring Transaction Propagation and UnexpectedRollbackException

Problem Background and Phenomenon Analysis

In enterprise application development based on Spring and Hibernate, transaction management is the core mechanism for ensuring data consistency. The scenario discussed in this article involves a message processing system that includes key processes such as reading messages from the IncomingMessage table, processing business logic, and inserting records into the OutgoingMessage table based on processing results. When exceptions occur in nested transaction environments, the system throws org.springframework.transaction.UnexpectedRollbackException: Transaction rolled back because it has been marked as rollback-only.

Core Principles of Transaction Propagation Mechanism

The Spring Framework provides declarative transaction management support through the @Transactional annotation. When a transactional method is called by another transactional method, the transaction propagation behavior determines how the new transaction interacts with the existing transaction. The default propagation level is PROPAGATION_REQUIRED, which means if a transaction currently exists, join it; otherwise, create a new transaction.

In the example code, both the ProcessMessageMediatorImpl.processNextRegistrationMessage() method and the SqlCommandHandlerServiceImpl.persist() method are annotated with @Transactional. When the persist() method is called by processNextRegistrationMessage(), since both use the default PROPAGATION_REQUIRED propagation level, they share the same transaction context.

Exception Handling and Transaction Status Marking

When an operation within a transaction throws an exception, the Spring transaction manager marks the current transaction as rollback-only status. Once this mark is set, it cannot be revoked, even if the exception is caught and handled in the call chain. In the example scenario, when the sqlCommandHandlerService.persist() method throws ConstraintViolationException:

try {
    sqlCommandHandlerService.persist(incomingXmlModel);
} catch (Exception e) {
    // Although the exception is caught, the transaction has been marked as rollback-only
    OutgoingXmlModel outgoingXmlModel = new OutgoingXmlModel(refrenceId, 
        ProcessResultStateEnum.FAILED.getCode(), e.getMessage());
    saveOutgoingMessage(outgoingXmlModel, registrationMessageType);
    return;
}

Although the developer catches the exception in the catch block and attempts to record error information, since the transaction has been marked as rollback-only, UnexpectedRollbackException is still thrown during the transaction commit phase.

Solution: Rational Use of Transaction Propagation Levels

To solve this problem, transaction boundaries need to be redesigned. It is recommended to use the PROPAGATION_REQUIRES_NEW propagation level to ensure that internal methods execute in independent transactions:

@Override
@Transactional(propagation = Propagation.REQUIRES_NEW)
public void persist(IncomingXmlModel incomingXmlModel) {
    Collections.sort(incomingXmlModel.getTables());
    List<ParametricQuery> queries = generateSqlQueries(incomingXmlModel.getTables());
    for (ParametricQuery query : queries) {
        queryExecuter.executeQuery(query);
    }
}

After using REQUIRES_NEW, the persist() method executes in a new transaction. If this method throws an exception, only its own transaction is rolled back, without affecting the state of the outer transaction. This way, the outer transaction can normally commit error records to the OutgoingMessage table.

Transaction Configuration Best Practices

In Spring configuration, ensure the transaction manager is correctly configured:

<bean id="transactionManager"
    class="org.springframework.orm.hibernate4.HibernateTransactionManager">
    <property name="sessionFactory" ref="sessionFactory" />
</bean>

<tx:annotation-driven transaction-manager="transactionManager"
    proxy-target-class="true" />

Key configuration points include:

• Using HibernateTransactionManager integrated with Hibernate SessionFactory
• Enabling annotation-based transaction management
• Setting proxy-target-class="true" to ensure CGLIB proxy works correctly

Error Handling Strategy Optimization

In addition to adjusting transaction propagation levels, exception handling strategies should also be optimized:

@Override
@Transactional
public void processNextRegistrationMessage() throws ProcessIncomingMessageException {
    String refrenceId = null;
    MessageTypeEnum registrationMessageType = MessageTypeEnum.REGISTRATION;
    
    try {
        String messageContent = incomingMessageService.fetchNextMessageContent(registrationMessageType);
        if (messageContent == null) {
            return;
        }
        
        IncomingXmlModel incomingXmlModel = incomingXmlDeserializer.fromXml(messageContent);
        refrenceId = incomingXmlModel.getRefrenceId();
        
        if (!StringUtil.hasText(refrenceId)) {
            throw new ProcessIncomingMessageException(
                "Can not proceed processing incoming-message. refrence-code field is null.");
        }
        
        // Use REQUIRES_NEW to ensure independent transaction
        sqlCommandHandlerService.persistInNewTransaction(incomingXmlModel);
        
    } catch (ProcessIncomingMessageException e) {
        // Business exception, throw directly
        throw e;
    } catch (Exception e) {
        // System exception, record error information
        OutgoingXmlModel outgoingXmlModel = new OutgoingXmlModel(refrenceId,
            ProcessResultStateEnum.FAILED.getCode(), e.getMessage());
        saveOutgoingMessage(outgoingXmlModel, registrationMessageType);
        return;
    }
    
    // Successful processing, record success information
    OutgoingXmlModel outgoingXmlModel = new OutgoingXmlModel(refrenceId, 
        ProcessResultStateEnum.SUCCEED.getCode());
    saveOutgoingMessage(outgoingXmlModel, registrationMessageType);
}

Performance Considerations and Applicable Scenarios

Using PROPAGATION_REQUIRES_NEW solves transaction conflict issues but also introduces some performance overhead:

• Each new transaction requires establishing a new database connection (or obtaining from connection pool)
• Increases the complexity of transaction management
• May affect overall system performance

Therefore, it is recommended to use in the following scenarios:

• Auxiliary operations that require independent commits
• Operations that do not affect the main business process, such as logging and audit tracking
• Error handling and compensation mechanisms

Summary and Recommendations

Spring transaction management provides powerful functionality but also requires developers to deeply understand its working principles. When handling nested transactions, rationally selecting transaction propagation levels is key. PROPAGATION_REQUIRES_NEW is suitable for scenarios requiring independent transaction boundaries, while PROPAGATION_REQUIRED is suitable for scenarios requiring unified transaction management.

In actual development, it is recommended to:

• Carefully design transaction boundaries to avoid unnecessary transaction nesting
• Clearly annotate transaction propagation levels in code
• Write complete transaction rollback test cases
• Monitor transaction performance metrics and optimize timely

By correctly understanding and using Spring transaction propagation mechanisms, more robust and reliable enterprise-level applications can be built.