Package org.springframework.context.event

# Annotation Interface EventListener

@Target({METHOD,ANNOTATION_TYPE}) @Retention(RUNTIME) @Documented @Reflective public @interface EventListener
Annotation that marks a method as a listener for application events.

If an annotated method supports a single event type, the method may declare a single parameter that reflects the event type to listen to. If an annotated method supports multiple event types, this annotation may refer to one or more supported event types using the `classes` attribute. See the `classes()` javadoc for further details.

Events can be `ApplicationEvent` instances as well as arbitrary objects.

Processing of `@EventListener` annotations is performed via the internal `EventListenerMethodProcessor` bean which gets registered automatically when using Java config or manually via the `<context:annotation-config/>` or `<context:component-scan/>` element when using XML config.

Annotated methods may have a non-`void` return type. When they do, the result of the method invocation is sent as a new event. If the return type is either an array or a collection, each element is sent as a new individual event.

This annotation may be used as a meta-annotation to create custom composed annotations.

### Exception Handling

While it is possible for an event listener to declare that it throws arbitrary exception types, any checked exceptions thrown from an event listener will be wrapped in an `UndeclaredThrowableException` since the event publisher can only handle runtime exceptions.

### Asynchronous Listeners

If you want a particular listener to process events asynchronously, you can use Spring's `@Async` support, but be aware of the following limitations when using asynchronous events.

- If an asynchronous event listener throws an exception, it is not propagated to the caller. See `AsyncUncaughtExceptionHandler` for more details.
- Asynchronous event listener methods cannot publish a subsequent event by returning a value. If you need to publish another event as the result of the processing, inject an `ApplicationEventPublisher` to publish the event manually.

### Ordering Listeners

It is also possible to define the order in which listeners for a certain event are to be invoked. To do so, add Spring's common `@Order` annotation alongside this event listener annotation.

Since:
  4.2
Author:
  Stephane Nicoll, Sam Brannen
See Also:
  - `EventListenerMethodProcessor`
  - `org.springframework.transaction.event.TransactionalEventListener`

## 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) expression used for making the event handling conditional.
`boolean`
`defaultExecution`
Whether the event should be handled by default, without any special pre-conditions such as an active transaction.
`String`
`id`
An optional identifier for the listener, defaulting to the fully-qualified signature of the declaring method (for example, "mypackage.MyClass.myMethod()").
`Class<?>[]`
`value`
Alias for `classes()`.

## Element Details

### value

@AliasFor("classes") Class<?>[] value
Alias for `classes()`.

Default:
  {}

### classes

@AliasFor("value") Class<?>[] classes
The event classes that this listener handles.

The annotated method may optionally accept a single parameter of the given event class, or of a common base class or interface for all given event classes.

Default:
  {}

### condition

String condition
Spring Expression Language (SpEL) expression used for making the event handling conditional.

The event will be handled if the expression evaluates to boolean `true` or one of the following strings: `"true"`, `"on"`, `"yes"`, or `"1"`.

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

The SpEL expression will be evaluated against a dedicated context that provides the following metadata:

- `#root.event` or `event` for references to the `ApplicationEvent`
- `#root.args` or `args` for references to the method arguments array
- Method arguments can be accessed by index. For example, the first argument can be accessed via `#root.args[0]`, `args[0]`, `#a0`, or `#p0`.
- Method arguments can be accessed by name (with a preceding hash tag) if parameter names are available in the compiled byte code.

Default:
  ""

### defaultExecution

boolean defaultExecution
Whether the event should be handled by default, without any special pre-conditions such as an active transaction. Declared here for overriding in composed annotations such as `TransactionalEventListener`.

Since:
  6.2

Default:
  true

### id

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

Since:
  5.3.5
See Also:
  - `SmartApplicationListener.getListenerId()`
  - `ApplicationEventMulticaster.removeApplicationListeners(Predicate)`

Default:
  ""