Interface TransactionDefinition

All Known Implementing Classes:
DefaultTransactionDefinition
public interface TransactionDefinition
Describes how a unit of work should run with respect to transactions. A transaction manager reads a definition when a transactional method or callback starts and uses it to decide whether to start a new transaction, join the current one, suspend it, or run without a transaction. A definition consists of: Definitions are usually derived from a @Transactional annotation, or created with of(Propagation) and DefaultTransactionDefinition. The propagation values mirror the transaction attributes of Jakarta EE (REQUIRED, REQUIRES_NEW, MANDATORY, SUPPORTS, NOT_SUPPORTED, NEVER) plus NESTED.

Note that isolation level and timeout settings will not get applied unless an actual new transaction gets started. As only TransactionDefinition.Propagation.REQUIRED, TransactionDefinition.Propagation.REQUIRES_NEW and TransactionDefinition.Propagation.NESTED can cause that, it usually doesn't make sense to specify those settings in other cases. Furthermore, be aware that not all transaction managers will support those advanced features and thus might throw corresponding exceptions when given non-default values.

The read-only flag applies to any transaction context, whether backed by an actual resource transaction or operating non-transactionally at the resource level. In the latter case, the flag will only apply to managed resources within the application, such as a Hibernate Session.

This type is derived from the Spring Framework's TransactionDefinition (Apache License 2.0).

Since:
08.05.2003
Author:
Juergen Hoeller, graemerocher

  • Field Details

    • DEFAULT

      static final TransactionDefinition DEFAULT
      The default transaction definition.

    • READ_ONLY

      static final TransactionDefinition READ_ONLY
      A read only definition.

    • TIMEOUT_DEFAULT

      static final Duration TIMEOUT_DEFAULT
      Use the default timeout of the underlying transaction system, or none if timeouts are not supported.

  • Method Details

    • getPropagationBehavior

      default @NonNull TransactionDefinition.Propagation getPropagationBehavior()
      Return the propagation behavior.

      Must return one of the PROPAGATION_XXX constants defined on this interface.

      The default is TransactionDefinition.Propagation.REQUIRED.

      Returns:
      the propagation behavior
      See Also:

    • getIsolationLevel

      default @NonNull Optional<TransactionDefinition.Isolation> getIsolationLevel()
      Return the isolation level.

      Must return one of the ISOLATION_XXX constants defined on this interface. Those constants are designed to match the values of the same constants on Connection.

      Exclusively designed for use with TransactionDefinition.Propagation.REQUIRED or TransactionDefinition.Propagation.REQUIRES_NEW since it only applies to newly started transactions. When participating in an existing transaction, the setting of the existing transaction applies and this one is ignored.

      The default is TransactionDefinition.Isolation.DEFAULT. Note that a transaction manager that does not support custom isolation levels will throw an exception when given any other level than TransactionDefinition.Isolation.DEFAULT.

      Returns:
      the isolation level
      See Also:

    • getTimeout

      default @NonNull Optional<Duration> getTimeout()
      Return the transaction timeout.

      Must return a number of seconds, or TIMEOUT_DEFAULT.

      Exclusively designed for use with TransactionDefinition.Propagation.REQUIRED or TransactionDefinition.Propagation.REQUIRES_NEW since it only applies to newly started transactions.

      Note that a transaction manager that does not support timeouts will throw an exception when given any other timeout than TIMEOUT_DEFAULT.

      The default is TIMEOUT_DEFAULT.

      Returns:
      the transaction timeout

    • isReadOnly

      default Optional<Boolean> isReadOnly()
      Return whether to optimize as a read-only transaction.

      The read-only flag applies to any transaction context, whether backed by an actual resource transaction (TransactionDefinition.Propagation.REQUIRED/ TransactionDefinition.Propagation.REQUIRES_NEW) or operating non-transactionally at the resource level (TransactionDefinition.Propagation.SUPPORTS). In the latter case, the flag will only apply to managed resources within the application, such as a Hibernate Session.

      This just serves as a hint for the actual transaction subsystem; it will not necessarily cause failure of write access attempts. A transaction manager which cannot interpret the read-only hint will not throw an exception when asked for a read-only transaction.

      Returns:
      true if the transaction is to be optimized as read-only (false by default)

    • getName

      default @Nullable String getName()
      Return the name of this transaction. Can be null.

      The name identifies the transaction in logs and monitoring tools. For methods annotated with @Transactional the name is taken from the annotation's name member if present, and is otherwise simple class name + "." + method name.

      Returns:
      the name of this transaction (null by default)

    • of

      static @NonNull TransactionDefinition of(@NonNull TransactionDefinition.Propagation propagationBehaviour)
      Create a new TransactionDefinition for the given behaviour.
      Parameters:
      propagationBehaviour - The behaviour
      Returns:
      The definition

    • named

      static @NonNull TransactionDefinition named(@NonNull String name)
      Create a new TransactionDefinition with a given name.
      Parameters:
      name - The name
      Returns:
      The definition
      Since:
      3.5.0

    • getRollbackOn

      default @NonNull Collection<Class<? extends Throwable>> getRollbackOn()
      Collection of exception classes that should cause the rollback. Empty if all exception should cause the rollback.
      Returns:
      the exception classes
      Since:
      3.5.0

    • getDontRollbackOn

      default @NonNull Collection<Class<? extends Throwable>> getDontRollbackOn()
      Collection of exception classes that shouldn't cause the rollback.
      Returns:
      the exception classes
      Since:
      3.5.0

    • getProperties

      default @NonNull Map<String,Object> getProperties()
      Additional transaction properties that may be interpreted by specific transaction managers.
      Returns:
      the transaction properties
      Since:
      5.0

    • rollbackOn

      default boolean rollbackOn(Throwable e)
      Check of the transaction should roll back when exception occurs.
      Parameters:
      e - The exception
      Returns:
      true if the transaction should roll back
      Since:
      3.5.0

    • getConnectionDefinition

      default ConnectionDefinition getConnectionDefinition()
      In some cases the transaction can require a new connection or alter the existing connection properties.
      Returns:
      The connection definition that is required for this transaction.