程序包 cn.taketoday.context.event

Annotation Interface EventListener

@Target({TYPE,METHOD}) @Retention(RUNTIME) 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 value attribute.

Events can be ApplicationEvent instances as well as arbitrary objects.

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.

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 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 common @Order annotation alongside this event listener annotation.

从以下版本开始:
3.0
作者:
TODAY 2021/3/16 10:53

  • 可选元素概要

    可选元素
    修饰符和类型
    可选元素
    说明
    String
    condition
    Expression Language (SpEL) expression used for making the event handling conditional.
    Class<?>[]
    event
    The event classes that this listener handles.
    String
    id
    An optional identifier for the listener, defaulting to the fully-qualified signature of the declaring method (e.g.
    Class<?>[]
    value
    event types

  • 元素详细资料

    • value

      @AliasFor("event") Class<?>[] value
      event types
      默认值:
      {}

    • event

      @AliasFor("value") Class<?>[] event
      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.

      从以下版本开始:
      4.0
      默认值:
      {}

    • condition

      String condition
      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 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.
      从以下版本开始:
      4.0
      默认值:
      ""

    • id

      String id
      An optional identifier for the listener, defaulting to the fully-qualified signature of the declaring method (e.g. "mypackage.MyClass.myMethod()").
      从以下版本开始:
      4.0
      另请参阅:
      默认值:
      ""