org.springframework.transaction.event

## Interface TransactionalApplicationListener<E extends ApplicationEvent>

- Type Parameters:
    `E` - the specific `ApplicationEvent` subclass to listen to
  All Superinterfaces:
    ApplicationListener<E>, EventListener, Ordered
  All Known Implementing Classes:
    TransactionalApplicationListenerAdapter, TransactionalApplicationListenerMethodAdapter

      public interface TransactionalApplicationListener<E extends ApplicationEvent>
      extends ApplicationListener<E>, Ordered

  An `ApplicationListener` that is invoked according to a `TransactionPhase`. This is a programmatic equivalent of the `TransactionalEventListener` annotation.

  Adding `Ordered` to your listener implementation allows you to prioritize that listener amongst other listeners running before or after transaction completion.

  NOTE: Transactional event listeners only work with thread-bound transactions managed by a `PlatformTransactionManager`. A reactive transaction managed by a `ReactiveTransactionManager` uses the Reactor context instead of thread-local variables, so from the perspective of an event listener, there is no compatible active transaction that it can participate in.

  Since:
    5.3
  Author:
    Juergen Hoeller, Oliver Drotbohm
  See Also:
    `TransactionalEventListener`, `TransactionalApplicationListenerAdapter`, `forPayload(java.util.function.Consumer<T>)`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `TransactionalApplicationListener.SynchronizationCallback` Callback to be invoked on synchronization-driven event processing, wrapping the target listener invocation (`processEvent(E)`).

  - ### Field Summary

    - ### Fields inherited from interface org.springframework.core.Ordered

      `HIGHEST_PRECEDENCE, LOWEST_PRECEDENCE`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addCallback(TransactionalApplicationListener.SynchronizationCallback callback)` Add a callback to be invoked on processing within transaction synchronization, i.e.
    `static <T> TransactionalApplicationListener<PayloadApplicationEvent<T>>` | `forPayload(Consumer<T> consumer)` Create a new `TransactionalApplicationListener` for the given payload consumer, to be applied in the default phase `TransactionPhase.AFTER_COMMIT`.
    `static <T> TransactionalApplicationListener<PayloadApplicationEvent<T>>` | `forPayload(TransactionPhase phase, Consumer<T> consumer)` Create a new `TransactionalApplicationListener` for the given payload consumer.
    `default String` | `getListenerId()` Return an identifier for the listener to be able to refer to it individually.
    `default int` | `getOrder()` Return the execution order within transaction synchronizations.
    `default TransactionPhase` | `getTransactionPhase()` Return the `TransactionPhase` in which the listener will be invoked.
    `void` | `processEvent(E event)` Immediately process the given `ApplicationEvent`.

    - ### Methods inherited from interface org.springframework.context.ApplicationListener

      `onApplicationEvent`

- - ### Method Detail

    - #### getOrder

          default int getOrder()

      Return the execution order within transaction synchronizations.

      Default is `Ordered.LOWEST_PRECEDENCE`.

      Specified by:
        `getOrder` in interface `Ordered`
      Returns:
        the order value
      See Also:
        `TransactionSynchronization.getOrder()`

    - #### getListenerId

          default String getListenerId()

      Return an identifier for the listener to be able to refer to it individually.

      It might be necessary for specific completion callback implementations to provide a specific id, whereas for other scenarios an empty String (as the common default value) is acceptable as well.

      See Also:
        `SmartApplicationListener.getListenerId()`, `TransactionalEventListener.id()`, `addCallback(org.springframework.transaction.event.TransactionalApplicationListener.SynchronizationCallback)`

    - #### getTransactionPhase

          default TransactionPhase getTransactionPhase()

      Return the `TransactionPhase` in which the listener will be invoked.

      The default phase is `TransactionPhase.AFTER_COMMIT`.

    - #### addCallback

          void addCallback(TransactionalApplicationListener.SynchronizationCallback callback)

      Add a callback to be invoked on processing within transaction synchronization, i.e. when `processEvent(E)` is being triggered during actual transactions.
      Parameters:
        `callback` - the synchronization callback to apply

    - #### processEvent

          void processEvent(E event)

      Immediately process the given `ApplicationEvent`. In contrast to `ApplicationListener.onApplicationEvent(ApplicationEvent)`, a call to this method will directly process the given event without deferring it to the associated `transaction phase`.
      Parameters:
        `event` - the event to process through the target listener implementation

    - #### forPayload

          static <T> TransactionalApplicationListener<PayloadApplicationEvent<T>> forPayload(Consumer<T> consumer)

      Create a new `TransactionalApplicationListener` for the given payload consumer, to be applied in the default phase `TransactionPhase.AFTER_COMMIT`.
      Specified by:
        `forPayload` in interface `ApplicationListener<E extends ApplicationEvent>`
      Type Parameters:
        `T` - the type of the event payload
      Parameters:
        `consumer` - the event payload consumer
      Returns:
        a corresponding `TransactionalApplicationListener` instance
      See Also:
        `PayloadApplicationEvent.getPayload()`, `TransactionalApplicationListenerAdapter`

    - #### forPayload

          static <T> TransactionalApplicationListener<PayloadApplicationEvent<T>> forPayload(TransactionPhase phase,
                                                                                             Consumer<T> consumer)

      Create a new `TransactionalApplicationListener` for the given payload consumer.
      Type Parameters:
        `T` - the type of the event payload
      Parameters:
        `phase` - the transaction phase in which to invoke the listener
        `consumer` - the event payload consumer
      Returns:
        a corresponding `TransactionalApplicationListener` instance
      See Also:
        `PayloadApplicationEvent.getPayload()`, `TransactionalApplicationListenerAdapter`