Package org.springframework.transaction.annotation

Annotation Interface Transactional

@Target({TYPE,METHOD}) @Retention(RUNTIME) @Inherited @Documented @Reflective public @interface Transactional
Describes a transaction attribute on an individual method or on a class.

When this annotation is declared at the class level, it applies as a default to all methods of the declaring class and its subclasses. Note that it does not apply to ancestor classes up the class hierarchy; inherited methods need to be locally redeclared in order to participate in a subclass-level annotation. For details on method visibility constraints, consult the Transaction Management section of the reference manual.

This annotation is generally directly comparable to Spring's RuleBasedTransactionAttribute class, and in fact AnnotationTransactionAttributeSource will directly convert this annotation's attributes to properties in RuleBasedTransactionAttribute, so that Spring's transaction support code does not have to know about annotations.

Attribute Semantics

If no custom rollback rules are configured in this annotation, the transaction will roll back on RuntimeException and Error but not on checked exceptions.

Rollback rules determine if a transaction should be rolled back when a given exception is thrown, and the rules are based on types or patterns. Custom rules may be configured via rollbackFor()/noRollbackFor() and rollbackForClassName()/noRollbackForClassName(), which allow rules to be specified as types or patterns, respectively.

When a rollback rule is defined with an exception type, that type will be used to match against the type of a thrown exception and its super types, providing type safety and avoiding any unintentional matches that may occur when using a pattern. For example, a value of jakarta.servlet.ServletException.class will only match thrown exceptions of type jakarta.servlet.ServletException and its subclasses.

When a rollback rule is defined with an exception pattern, the pattern can be a fully qualified class name or a substring of a fully qualified class name for an exception type (which must be a subclass of Throwable), with no wildcard support at present. For example, a value of "jakarta.servlet.ServletException" or "ServletException" will match jakarta.servlet.ServletException and its subclasses.

WARNING: You must carefully consider how specific a pattern is and whether to include package information (which isn't mandatory). For example, "Exception" will match nearly anything and will probably hide other rules. "java.lang.Exception" would be correct if "Exception" were meant to define a rule for all checked exceptions. With more unique exception names such as "BaseBusinessException" there is likely no need to use the fully qualified class name for the exception pattern. Furthermore, rollback rules defined via patterns may result in unintentional matches for similarly named exceptions and nested classes. This is due to the fact that a thrown exception is considered to be a match for a given pattern-based rollback rule if the name of thrown exception contains the exception pattern configured for the rollback rule. For example, given a rule configured to match against "com.example.CustomException", that rule will match against an exception named com.example.CustomExceptionV2 (an exception in the same package as CustomException but with an additional suffix) or an exception named com.example.CustomException$AnotherException (an exception declared as a nested class in CustomException).

For specific information about the semantics of other attributes in this annotation, consult the TransactionDefinition and TransactionAttribute javadocs.

Transaction Management

This annotation commonly works with thread-bound transactions managed by a PlatformTransactionManager, exposing a transaction to all data access operations within the current execution thread. Note: This does NOT propagate to newly started threads within the method.

Alternatively, this annotation may demarcate a reactive transaction managed by a ReactiveTransactionManager which uses the Reactor context instead of thread-local variables. As a consequence, all participating data access operations need to execute within the same Reactor context in the same reactive pipeline.

Note: When configured with a ReactiveTransactionManager, all transaction-demarcated methods are expected to return a reactive pipeline. Void methods or regular return types need to be associated with a regular PlatformTransactionManager, e.g. through transactionManager().

Since:
1.2
Author:
Colin Sampaleanu, Juergen Hoeller, Sam Brannen, Mark Paluch
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    Isolation
    isolation
    The transaction isolation level.
    String[]
    label
    Defines zero (0) or more transaction labels.
    Class<? extends Throwable>[]
    noRollbackFor
    Defines zero (0) or more exception types, which must be subclasses of Throwable, indicating which exception types must not cause a transaction rollback.
    String[]
    noRollbackForClassName
    Defines zero (0) or more exception name patterns (for exceptions which must be a subclass of Throwable) indicating which exception types must not cause a transaction rollback.
    Propagation
    propagation
    The transaction propagation type.
    boolean
    readOnly
    A boolean flag that can be set to true if the transaction is effectively read-only, allowing for corresponding optimizations at runtime.
    Class<? extends Throwable>[]
    rollbackFor
    Defines zero (0) or more exception types, which must be subclasses of Throwable, indicating which exception types must cause a transaction rollback.
    String[]
    rollbackForClassName
    Defines zero (0) or more exception name patterns (for exceptions which must be a subclass of Throwable), indicating which exception types must cause a transaction rollback.
    int
    timeout
    The timeout for this transaction (in seconds).
    String
    timeoutString
    The timeout for this transaction (in seconds).
    String
    transactionManager
    A qualifier value for the specified transaction.
    String
    value
    Alias for transactionManager().