or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-transaction-management.mddao-exceptions.mddeclarative-transactions.mdindex.mdjta-integration.mdprogrammatic-transactions.mdreactive-transactions.mdtransaction-synchronization.mdtransactional-events.md
tile.json

tessl/maven-org-springframework--spring-tx

Spring Framework's comprehensive transaction management APIs and support classes for imperative and reactive applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.springframework/spring-tx@6.2.x

To install, run

npx @tessl/cli install tessl/maven-org-springframework--spring-tx@6.2.0

index.mddocs/

Spring TX

Spring TX provides comprehensive transaction management capabilities for Spring applications, offering a vendor-neutral programming model that abstracts over various transaction management systems including JTA, JDBC, Hibernate, and reactive transactions. It enables both declarative and programmatic transaction management with support for various propagation behaviors, isolation levels, and rollback rules.

Package Information

  • Package Name: org.springframework:spring-tx
  • Package Type: maven
  • Language: Java (with Kotlin support)
  • Installation: implementation 'org.springframework:spring-tx:6.2.8' (Gradle) or <dependency><groupId>org.springframework</groupId><artifactId>spring-tx</artifactId><version>6.2.8</version></dependency> (Maven)

Core Imports

import org.springframework.transaction.PlatformTransactionManager;
import org.springframework.transaction.TransactionDefinition;
import org.springframework.transaction.TransactionStatus;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.transaction.support.TransactionTemplate;

Basic Usage

// Declarative transaction management with @Transactional
@Transactional
public class UserService {
    
    @Transactional(readOnly = true)
    public User findUser(Long id) {
        return userRepository.findById(id);
    }
    
    @Transactional(rollbackFor = Exception.class)
    public User saveUser(User user) {
        return userRepository.save(user);
    }
}

// Programmatic transaction management with TransactionTemplate
@Service
public class OrderService {
    
    private final TransactionTemplate transactionTemplate;
    
    public OrderService(PlatformTransactionManager transactionManager) {
        this.transactionTemplate = new TransactionTemplate(transactionManager);
    }
    
    public Order processOrder(Order order) {
        return transactionTemplate.execute(status -> {
            // Transactional operations
            Order savedOrder = orderRepository.save(order);
            notificationService.sendConfirmation(savedOrder);
            return savedOrder;
        });
    }
}

Architecture

Spring TX is built around several key components:

  • Core Transaction Management: Central interfaces (PlatformTransactionManager, TransactionDefinition, TransactionStatus) providing vendor-neutral transaction abstraction
  • Declarative Transactions: Annotation-based (@Transactional) and XML-based transaction demarcation using AOP
  • Programmatic Transactions: Template-based (TransactionTemplate) and direct API access for explicit transaction control
  • Reactive Support: Reactive transaction management for WebFlux applications using ReactiveTransactionManager
  • JTA Integration: Enterprise transaction management with distributed transaction support
  • Exception Translation: Comprehensive DAO exception hierarchy for consistent error handling across data access technologies

Capabilities

Core Transaction Management

Central interfaces and classes for imperative transaction management, providing the foundation for all transaction operations in Spring.

public interface PlatformTransactionManager extends TransactionManager {
    TransactionStatus getTransaction(@Nullable TransactionDefinition definition) 
        throws TransactionException;
    void commit(TransactionStatus status) throws TransactionException;
    void rollback(TransactionStatus status) throws TransactionException;
}

public interface TransactionDefinition {
    int getPropagationBehavior();
    int getIsolationLevel();
    int getTimeout();
    boolean isReadOnly();
    @Nullable String getName();
}

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

Core Transaction Management

Declarative Transaction Management

Annotation-based and configuration-driven transaction management using AOP for clean separation of business logic and transaction concerns.

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Transactional {
    String value() default "";
    String transactionManager() default "";
    Propagation propagation() default Propagation.REQUIRED;
    Isolation isolation() default Isolation.DEFAULT;
    int timeout() default TransactionDefinition.TIMEOUT_DEFAULT;
    boolean readOnly() default false;
    Class<? extends Throwable>[] rollbackFor() default {};
    String[] rollbackForClassName() default {};
    Class<? extends Throwable>[] noRollbackFor() default {};
    String[] noRollbackForClassName() default {};
}

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

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

Declarative Transaction Management

Programmatic Transaction Management

Template-based and direct API approaches for explicit transaction control when fine-grained transaction management is required.

public class TransactionTemplate extends DefaultTransactionDefinition 
    implements TransactionOperations {
    
    public TransactionTemplate(PlatformTransactionManager transactionManager);
    
    @Nullable
    public <T> T execute(TransactionCallback<T> action) throws TransactionException;
    
    public void executeWithoutResult(TransactionCallbackWithoutResult action) 
        throws TransactionException;
}

@FunctionalInterface
public interface TransactionCallback<T> {
    @Nullable
    T doInTransaction(TransactionStatus status);
}

public abstract class TransactionCallbackWithoutResult implements TransactionCallback<Object> {
    protected abstract void doInTransactionWithoutResult(TransactionStatus status);
}

Programmatic Transaction Management

Reactive Transaction Management

Reactive transaction management support for WebFlux applications using non-blocking transaction operations.

public interface ReactiveTransactionManager extends TransactionManager {
    Mono<ReactiveTransaction> getReactiveTransaction(@Nullable TransactionDefinition definition);
    Mono<Void> commit(ReactiveTransaction transaction);
    Mono<Void> rollback(ReactiveTransaction transaction);
}

public interface TransactionalOperator {
    static TransactionalOperator create(ReactiveTransactionManager transactionManager);
    static TransactionalOperator create(ReactiveTransactionManager transactionManager, 
        TransactionDefinition transactionDefinition);
    
    <T> Mono<T> transactional(Mono<T> mono);
    <T> Flux<T> transactional(Flux<T> flux);
    <T> Flux<T> execute(TransactionCallback<T> action) throws TransactionException;
}

public interface ReactiveTransaction extends TransactionExecution {
    // Reactive transaction representation
}

@FunctionalInterface
public interface TransactionCallback<T> {
    Publisher<T> doInTransaction(ReactiveTransaction status);
}

Reactive Transaction Management

Transaction Synchronization

Thread-safe transaction synchronization utilities for coordinating resources and callbacks within transaction boundaries.

public abstract class TransactionSynchronizationManager {
    public static boolean isSynchronizationActive();
    public static void initSynchronization();
    public static void registerSynchronization(TransactionSynchronization synchronization);
    public static List<TransactionSynchronization> getSynchronizations();
    public static void clearSynchronization();
    
    public static boolean isCurrentTransactionReadOnly();
    public static void setCurrentTransactionReadOnly(boolean readOnly);
    @Nullable
    public static String getCurrentTransactionName();
    public static void setCurrentTransactionName(@Nullable String name);
    
    public static boolean isActualTransactionActive();
    public static void setActualTransactionActive(boolean active);
}

public interface TransactionSynchronization {
    int STATUS_COMMITTED = 0;
    int STATUS_ROLLED_BACK = 1;
    int STATUS_UNKNOWN = 2;
    
    default void suspend() {}
    default void resume() {}
    default void flush() {}
    default void beforeCommit(boolean readOnly) {}
    default void beforeCompletion() {}
    default void afterCommit() {}
    default void afterCompletion(int status) {}
}

Transaction Synchronization

JTA Integration

Java Transaction API integration for distributed transaction management in enterprise environments.

public class JtaTransactionManager extends AbstractPlatformTransactionManager {
    public JtaTransactionManager();
    public JtaTransactionManager(UserTransaction userTransaction);
    public JtaTransactionManager(UserTransaction userTransaction, 
        TransactionManager transactionManager);
    
    public void setUserTransaction(UserTransaction userTransaction);
    public UserTransaction getUserTransaction();
    public void setTransactionManager(TransactionManager transactionManager);
    public TransactionManager getTransactionManager();
    
    public void setAllowCustomIsolationLevels(boolean allowCustomIsolationLevels);
    public void setGlobalRollbackOnParticipationFailure(boolean globalRollbackOnParticipationFailure);
}

public interface TransactionFactory {
    Transaction createTransaction(@Nullable String name, int timeout) throws NotSupportedException, 
        SystemException;
}

public class UserTransactionAdapter implements UserTransaction {
    public UserTransactionAdapter(TransactionManager transactionManager);
    // UserTransaction method implementations
}

JTA Integration

Data Access Exception Translation

Comprehensive exception hierarchy providing consistent error handling across different data access technologies.

public abstract class DataAccessException extends NestedRuntimeException {
    public DataAccessException(String msg);
    public DataAccessException(String msg, @Nullable Throwable cause);
}

// Key exception types
public class DataIntegrityViolationException extends NonTransientDataAccessException {}
public class DataRetrievalFailureException extends NonTransientDataAccessException {}
public class DeadlockLoserDataAccessException extends PessimisticLockingFailureException {}
public class DuplicateKeyException extends DataIntegrityViolationException {}
public class OptimisticLockingFailureException extends ConcurrencyFailureException {}
public class PessimisticLockingFailureException extends ConcurrencyFailureException {}
public class QueryTimeoutException extends TransientDataAccessException {}

public abstract class DataAccessUtils {
    public static <T> T singleResult(@Nullable Collection<T> results) 
        throws IncorrectResultSizeDataAccessException;
    public static <T> T requiredSingleResult(@Nullable Collection<T> results) 
        throws IncorrectResultSizeDataAccessException;
    public static <T> T uniqueResult(@Nullable Collection<T> results) 
        throws IncorrectResultSizeDataAccessException;
}

Data Access Exception Translation

Transactional Events

Event listener support that coordinates with transaction lifecycle for reliable event processing.

@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@EventListener
public @interface TransactionalEventListener {
    TransactionPhase phase() default TransactionPhase.AFTER_COMMIT;
    String condition() default "";
    boolean fallbackExecution() default false;
    String id() default "";
}

public enum TransactionPhase {
    BEFORE_COMMIT, AFTER_COMMIT, AFTER_ROLLBACK, AFTER_COMPLETION
}

public interface TransactionalApplicationListener<E extends ApplicationEvent> 
    extends ApplicationListener<E> {
    TransactionPhase getTransactionPhase();
    boolean getFallbackExecution();
}

Transactional Events

Core Types

// Core interfaces
public interface TransactionManager {} // Marker interface

public interface TransactionExecution {
    boolean isNewTransaction();
    void setRollbackOnly();
    boolean isRollbackOnly();
    boolean isCompleted();
}

public interface SavepointManager {
    Object createSavepoint() throws TransactionException;
    void rollbackToSavepoint(Object savepoint) throws TransactionException;
    void releaseSavepoint(Object savepoint) throws TransactionException;
}

// Transaction definition constants
public interface TransactionDefinition {
    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;
    
    int ISOLATION_DEFAULT = -1;
    int ISOLATION_READ_UNCOMMITTED = 1;
    int ISOLATION_READ_COMMITTED = 2;
    int ISOLATION_REPEATABLE_READ = 4;
    int ISOLATION_SERIALIZABLE = 8;
    
    int TIMEOUT_DEFAULT = -1;
}

// Exception hierarchy
public abstract class TransactionException extends NestedRuntimeException {
    public TransactionException(String msg);
    public TransactionException(String msg, @Nullable Throwable cause);
}

public class CannotCreateTransactionException extends TransactionException {}
public class IllegalTransactionStateException extends TransactionException {}
public class UnexpectedRollbackException extends TransactionException {}
public class TransactionSystemException extends TransactionException {}
public class TransactionTimedOutException extends TransactionException {}