パッケージ org.springframework.context.event

アノテーションインターフェース EventListener

@TargetSE({METHODSE,ANNOTATION_TYPESE}) @RetentionSE(RUNTIMESE) @DocumentedSE @Reflective public @interface EventListener
メソッドをアプリケーションイベントのリスナーとしてマークするアノテーション。

アノテーション付きメソッドが単一のイベント型をサポートする場合、メソッドは、リッスンするイベント型を反映する単一のパラメーターを宣言する場合があります。アノテーション付きメソッドが複数のイベント型をサポートする場合、このアノテーションは classes 属性を使用して、サポートされている 1 つ以上のイベント型を参照する場合があります。詳細については、classes() javadoc を参照してください。

イベントは、ApplicationEvent インスタンスや任意のオブジェクトにすることができます。

@EventListener アノテーションの処理は、Java 構成を使用する場合は自動的に登録され、XML 構成を使用する場合は <context:annotation-config/> または <context:component-scan/> 要素を介して手動で登録される内部 EventListenerMethodProcessor Bean を介して実行されます。

アノテーション付きメソッドには、void 以外の戻り値の型が含まれる場合があります。その場合、メソッド呼び出しの結果は新しいイベントとして送信されます。戻り値の型が配列またはコレクションの場合、各要素は新しい個別のイベントとして送信されます。

このアノテーションは、カスタム構成アノテーションを作成するためのメタアノテーションとして使用することができます。

例外処理

イベントリスナが任意の例外型をスローすることを宣言することは可能ですが、イベントパブリッシャーはランタイム例外しか処理できないため、イベントリスナからスローされるチェック済み例外は UndeclaredThrowableExceptionSE にラップされます。

非同期リスナー

特定のリスナーでイベントを非同期に処理する場合は、Spring の @Async サポートを使用できますが、非同期イベントを使用する場合は次の制限に注意してください。

  • 非同期イベントリスナーが例外をスローした場合、呼び出し元に伝達されません。詳細については、AsyncUncaughtExceptionHandler を参照してください。
  • 非同期イベントリスナーメソッドは、値を返すことで後続のイベントを発行できません。処理の結果として別のイベントを公開する必要がある場合は、ApplicationEventPublisher を挿入してイベントを手動で公開します。

リスナーの順序付け

特定のイベントのリスナーが呼び出される順序を定義することもできます。そのためには、Spring の共通 @Order アノテーションをこのイベントリスナーアノテーションと一緒に追加します。

導入:
4.2
作成者:
Stephane Nicoll, Sam Brannen
関連事項:

  • オプション要素のサマリー

    オプション要素
    修飾子と型
    オプションの要素
    説明
    ClassSE<?>[]
    classes
    このリスナーが処理するイベントクラス。
    StringSE
    condition
    イベント処理を条件付きにするために使用される Spring 式言語（SpEL）式。
    StringSE
    id
    リスナーのオプションの識別子。デフォルトでは、宣言メソッドの完全修飾署名になります（例:
    ClassSE<?>[]
    value
    classes() のエイリアス。

  • 要素の詳細

    • value

      @AliasFor("classes") ClassSE<?>[] value
      classes() のエイリアス。
      デフォルト:
      {}

    • classes

      @AliasFor("value") ClassSE<?>[] classes
      このリスナーが処理するイベントクラス。

      この属性が単一の値で指定されている場合、アノテーション付きメソッドはオプションで単一のパラメーターを受け入れることができます。ただし、この属性が複数の値で指定されている場合、アノテーション付きメソッドはパラメーターを宣言してはなりません。

      デフォルト:
      {}

    • condition

      StringSE condition
      イベント処理を条件付きにするために使用される Spring 式言語（SpEL）式。

      式がブール true または文字列 "true"、"on"、"yes" または "1" のいずれかに評価された場合、イベントが処理されます。

      デフォルトの式は "" です。つまり、イベントは常に処理されます。

      SpEL 式は、次のメタデータを提供する専用のコンテキストに対して評価されます。

      • ApplicationEvent への参照には #root.event または event 
      • メソッド引数配列への参照には #root.args または args 
      • メソッドの引数はインデックスでアクセスできます。例: 最初の引数は #root.args[0]、args[0]、#a0 または #p0 を介してアクセスできます。
      • コンパイルされたバイトコードでパラメーター名が使用可能な場合、メソッドの引数は名前で（前にハッシュタグを付けて）アクセスできます。
      デフォルト:
      ""

    • id

      StringSE id
      リスナーのオプションの識別子。デフォルトでは、宣言メソッドの完全修飾署名（"mypackage.MyClass.myMethod()" など）になります。
      導入:
      5.3.5
      関連事項:
      デフォルト:
      ""