Package org.springframework.transaction.event

Annotation Interface TransactionalEventListener

@Target({METHOD,ANNOTATION_TYPE})
@Retention(RUNTIME)
@Documented
@EventListener
public @interface TransactionalEventListener

An EventListener that is invoked according to a TransactionPhase. This is an annotation-based equivalent of TransactionalApplicationListener.

If the event is not published within an active transaction, the event is discarded unless the fallbackExecution() flag is explicitly set. If a transaction is running, the event is handled according to its TransactionPhase.

Adding @Order to your annotated method 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.

WARNING: if the TransactionPhase is set to AFTER_COMMIT (the default), AFTER_ROLLBACK, or AFTER_COMPLETION, the transaction will have been committed or rolled back already, but the transactional resources might still be active and accessible. As a consequence, any data access code triggered at this point will still "participate" in the original transaction, but changes will not be committed to the transactional resource. See TransactionSynchronization.afterCompletion(int) for details.

Since:

4.2

Author:

Stephane Nicoll, Sam Brannen, Oliver Drotbohm

See Also:

• TransactionalApplicationListener
• TransactionalApplicationListenerMethodAdapter

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
Class<?>[]	classes	The event classes that this listener handles.
String	condition	Spring Expression Language (SpEL) attribute used for making the event handling conditional.
boolean	fallbackExecution	Whether the event should be handled if no transaction is running.
String	id	An optional identifier for the listener, defaulting to the fully-qualified signature of the declaring method (e.g.
TransactionPhase	phase	Phase to bind the handling of an event to.
Class<?>[]	value	Alias for classes().

Element Details

phase

TransactionPhase phase

Phase to bind the handling of an event to.

The default phase is TransactionPhase.AFTER_COMMIT.

If no transaction is in progress, the event is not processed at all unless fallbackExecution() has been enabled explicitly.

Default:

AFTER_COMMIT

fallbackExecution

boolean fallbackExecution

Whether the event should be handled if no transaction is running.

Default:

false

value

@AliasFor(annotation=EventListener.class,
          attribute="classes")
Class<?>[] value

Alias for classes().

Default:

{}

classes

@AliasFor(annotation=EventListener.class,
          attribute="classes")
Class<?>[] classes

The event classes that this listener handles.

If this attribute is specified with a single value, the annotated method may optionally accept a single parameter. However, if this attribute is specified with multiple values, the annotated method must not declare any parameters.

Default:

{}

condition

@AliasFor(annotation=EventListener.class,
          attribute="condition")
String condition

Spring Expression Language (SpEL) attribute used for making the event handling conditional.

The default is "", meaning the event is always handled.

See Also:

• EventListener.condition()

Default:

""

id

@AliasFor(annotation=EventListener.class,
          attribute="id")
String id

An optional identifier for the listener, defaulting to the fully-qualified signature of the declaring method (e.g. "mypackage.MyClass.myMethod()").

Since:

5.3

See Also:

• EventListener.id()
• TransactionalApplicationListener.getListenerId()

Default:

""