Spring Transaction (spring-tx)

Spring Transaction provides comprehensive transaction management infrastructure for both imperative and reactive programming models. It offers declarative transaction management through annotations, programmatic transaction management through template classes, and AOP-based transaction proxying. The module supports multiple transaction APIs including JTA, JDBC, Hibernate, and JPA with a consistent programming model.

Package Information

• Package Name: spring-tx

• Package Type: maven

• Coordinates: org.springframework:spring-tx:7.0.1

• Language: Java

• Installation:

  Maven:

  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-tx</artifactId>
    <version>7.0.1</version>
  </dependency>

  Gradle:

  implementation 'org.springframework:spring-tx:7.0.1'

Core Imports

// Declarative transaction management
import org.springframework.transaction.annotation.Transactional;
import org.springframework.transaction.annotation.EnableTransactionManagement;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Isolation;

// Programmatic transaction management
import org.springframework.transaction.support.TransactionTemplate;
import org.springframework.transaction.support.TransactionCallback;

// Transaction managers
import org.springframework.transaction.PlatformTransactionManager;
import org.springframework.transaction.jta.JtaTransactionManager;

// Reactive transactions
import org.springframework.transaction.reactive.TransactionalOperator;
import org.springframework.transaction.ReactiveTransactionManager;

// Transaction events
import org.springframework.transaction.event.TransactionalEventListener;
import org.springframework.transaction.event.TransactionPhase;

Basic Usage

Declarative Transaction Management (Most Common)

Enable transaction management in your configuration:

import org.springframework.context.annotation.Configuration;
import org.springframework.transaction.annotation.EnableTransactionManagement;

@Configuration
@EnableTransactionManagement
public class AppConfig {
    // Configuration beans
}

Use @Transactional annotation on methods or classes:

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class UserService {

    @Transactional
    public void createUser(User user) {
        // This method executes within a transaction
        userRepository.save(user);
        auditRepository.log("User created: " + user.getId());
        // Transaction commits automatically if no exception is thrown
    }

    @Transactional(readOnly = true)
    public User getUser(Long id) {
        return userRepository.findById(id);
    }
}

Programmatic Transaction Management

Use TransactionTemplate for programmatic control:

import org.springframework.transaction.support.TransactionTemplate;

@Service
public class PaymentService {

    private final TransactionTemplate transactionTemplate;

    public PaymentService(PlatformTransactionManager transactionManager) {
        this.transactionTemplate = new TransactionTemplate(transactionManager);
    }

    public void processPayment(Payment payment) {
        transactionTemplate.executeWithoutResult(status -> {
            paymentRepository.save(payment);
            accountService.debit(payment.getAmount());
            notificationService.sendReceipt(payment);
        });
    }
}

Architecture

Spring Transaction is built around several key components:

• Transaction Managers: Central interfaces (PlatformTransactionManager, ReactiveTransactionManager) that abstract over different transaction APIs (JTA, JDBC, Hibernate, JPA)
• Transaction Definitions: Configuration of transaction properties (propagation, isolation, timeout, read-only)
• Transaction Status: Runtime representation of transaction state with control methods
• Declarative Support: Annotation-driven transaction management using @Transactional with AOP proxying
• Programmatic Support: Template-based transaction execution (TransactionTemplate, TransactionalOperator)
• Synchronization: Callbacks for transaction lifecycle events and resource management
• Exception Translation: Unified exception hierarchy (TransactionException, DataAccessException)

Capabilities

Declarative Transaction Management

Annotation-driven transaction management using @Transactional for method-level or class-level transaction demarcation. Supports all transaction properties including propagation behavior, isolation level, timeout, read-only flag, and rollback rules.

Declarative Transaction Management

Programmatic Transaction Management

Template-based transaction execution providing explicit control over transaction boundaries. Use TransactionTemplate for imperative code that needs programmatic transaction control.

Programmatic Transaction Management

Transaction Managers

Central transaction management interfaces and implementations. PlatformTransactionManager for imperative transactions, JtaTransactionManager for JTA support, and base classes for custom transaction managers.

Transaction Managers

Reactive Transaction Management

Transaction management for reactive applications using Project Reactor. TransactionalOperator provides functional transaction demarcation for Mono and Flux publishers.

Reactive Transaction Management

Transactional Event Listeners

Event listeners that execute at specific transaction phases (before commit, after commit, after rollback, after completion). Enables decoupled handling of transactional events.

Transactional Event Listeners

AOP Transaction Interceptors

Low-level AOP infrastructure for transaction proxying. TransactionInterceptor and TransactionAttributeSource provide the foundation for declarative transaction management.

AOP Transaction Interceptors

Transaction Exception Hierarchy

Complete exception hierarchies for transaction failures (TransactionException) and data access issues (DataAccessException). Provides fine-grained exception types for different failure scenarios.

Exception Hierarchy

DAO Support Utilities

Utility classes and exception translation infrastructure for building technology-agnostic data access layers. Provides result extraction helpers and automatic exception translation from persistence provider exceptions to Spring's DataAccessException hierarchy.

DAO Support

JCA Connector Architecture Support

Support for Java Connector Architecture (JCA) including message endpoint management, connection factory creation, and resource adapter integration for enterprise application servers.

JCA Support

Transaction Synchronization

Low-level synchronization infrastructure for coordinating transactional resources and performing cleanup at transaction boundaries. Provides thread-bound resource management and lifecycle callbacks.

Transaction Synchronization

Transaction Properties

Transaction Propagation

Controls how transactions relate to each other:

• REQUIRED (default): Support current transaction, create new one if none exists
• REQUIRES_NEW: Create new transaction, suspend current if exists
• NESTED: Execute within nested transaction if current exists
• SUPPORTS: Support current transaction, execute non-transactionally if none exists
• MANDATORY: Require existing transaction, throw exception if none exists
• NOT_SUPPORTED: Execute non-transactionally, suspend current if exists
• NEVER: Execute non-transactionally, throw exception if transaction exists

Transaction Isolation

Controls visibility of concurrent transaction changes:

• DEFAULT: Use default isolation level of underlying datastore
• READ_UNCOMMITTED: Lowest isolation, allows dirty reads
• READ_COMMITTED: Prevents dirty reads
• REPEATABLE_READ: Prevents dirty and non-repeatable reads
• SERIALIZABLE: Highest isolation, prevents dirty, non-repeatable, and phantom reads

Core Types

Transaction Definition and Status

public interface TransactionDefinition {
    // Propagation constants
    int PROPAGATION_REQUIRED = 0;
    int PROPAGATION_SUPPORTS = 1;
    int PROPAGATION_MANDATORY = 2;
    int PROPAGATION_REQUIRES_NEW = 3;
    int PROPAGATION_NOT_SUPPORTED = 4;
    int PROPAGATION_NEVER = 5;
    int PROPAGATION_NESTED = 6;

    // Isolation constants
    int ISOLATION_DEFAULT = -1;
    int ISOLATION_READ_UNCOMMITTED = 1;
    int ISOLATION_READ_COMMITTED = 2;
    int ISOLATION_REPEATABLE_READ = 4;
    int ISOLATION_SERIALIZABLE = 8;

    // Timeout
    int TIMEOUT_DEFAULT = -1;

    int getPropagationBehavior();
    int getIsolationLevel();
    int getTimeout();
    boolean isReadOnly();
    String getName();
}

public interface TransactionStatus extends TransactionExecution, SavepointManager, Flushable {
    boolean hasSavepoint();
    void flush();
}

public interface TransactionExecution {
    String getTransactionName();
    boolean hasTransaction();
    boolean isNewTransaction();
    boolean isNested();
    boolean isReadOnly();
    void setRollbackOnly();
    boolean isRollbackOnly();
    boolean isCompleted();
}

Propagation and Isolation Enums

public enum Propagation {
    REQUIRED,
    SUPPORTS,
    MANDATORY,
    REQUIRES_NEW,
    NOT_SUPPORTED,
    NEVER,
    NESTED;

    int value();
}

public enum Isolation {
    DEFAULT,
    READ_UNCOMMITTED,
    READ_COMMITTED,
    REPEATABLE_READ,
    SERIALIZABLE;

    int value();
}