Package 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.

As of 6.1, transactional event listeners can work with thread-bound transactions managed by a PlatformTransactionManager as well as reactive transactions managed by a ReactiveTransactionManager. For the former, listeners are guaranteed to see the current thread-bound transaction. Since the latter uses the Reactor context instead of thread-local variables, the transaction context needs to be included in the published event instance as the event source: see TransactionalEventPublisher.

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	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

Modifier and Type	Method	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.
default boolean	supportsAsyncExecution()	Transaction-synchronized listeners do not support asynchronous execution, only their target listener (processEvent(E)) potentially does.

Methods inherited from interface org.springframework.context.ApplicationListener

onApplicationEvent

Method Details

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()

supportsAsyncExecution

default boolean supportsAsyncExecution()

Transaction-synchronized listeners do not support asynchronous execution, only their target listener (processEvent(E)) potentially does.

Specified by:

supportsAsyncExecution in interface ApplicationListener<E extends ApplicationEvent>

Returns:

true if this listener instance can be executed asynchronously depending on the multicaster configuration (the default), or false if it needs to immediately run within the original thread which published the event

Since:

6.1

See Also:

• SimpleApplicationEventMulticaster.setTaskExecutor(java.util.concurrent.Executor)

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.

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