パッケージ jakarta.interceptor

インターセプターメソッドとインターセプタークラスを定義し、インターセプタークラスをターゲットクラスにバインドするためのアノテーションとインターフェースが含まれています。

インターセプターメソッド

インターセプターメソッドは、インターセプタークラスまたはターゲットクラスのメソッドであり、ターゲットクラスのメソッド、ターゲットクラスのコンストラクター、ターゲットクラスのライフサイクルイベント、ターゲットクラスのタイムアウトメソッドの呼び出しに割り込むために呼び出されます。

ターゲットクラスのインターセプターメソッドは、ターゲットクラス、ターゲットクラスに関連付けられたインターセプタークラス、ターゲットクラスまたはインターセプタークラスのスーパークラスで宣言できます。

AroundConstruct インターセプターメソッドは、インターセプタークラスまたはインターセプタークラスのスーパークラスでのみ定義できます。

Jakarta Interceptors 仕様では、以下にリストするインターセプターメソッド型を定義しています。拡張仕様では、追加のインターセプターメソッド型を定義できます。

  • AroundInvoke インターセプターメソッド。ターゲットクラスのビジネスメソッドに割り込みます。
  • タイマーイベントにレスポンスしてタイムアウトメソッドの呼び出しを中断する AroundTimeout インターセプターメソッド。
  • PostConstruct インターセプターメソッド。ターゲットインスタンスで依存関係の注入が完了した後に呼び出されます。
  • PreDestroy インターセプターメソッド。ターゲットインスタンスとそれに関連付けられているすべてのインターセプターインスタンスが破棄される前に呼び出されます。
  • AroundConstruct インターセプターメソッド。ターゲットインスタンスのコンストラクターの呼び出しに介入します。
PostConstruct、PreDestroy、AroundConstruct インターセプターメソッドは、まとめてライフサイクルコールバックインターセプターメソッドと呼ばれます。

インターセプターメソッドは、アノテーションを使用して、またはオプションでデプロイ記述子を使用して定義できます。インターセプターメソッドは、abstract、static、final として宣言することはできません。

インターセプタークラスまたはターゲットクラスは、複数のインターセプターメソッドを持つことができます。ただし、インターセプタークラスまたはターゲットクラスは、特定のインターセプターメソッド型の AroundInvoke、AroundTimeout、PostConstruct、PreDestroy、AroundConstruct のインターセプターメソッドを 1 つだけ持つことができます。

インターセプタークラス

インターセプタークラスは、（ターゲットクラスとは異なる）クラスで、そのメソッドは、ターゲットクラスの呼び出しやライフサイクルイベント、あるいはその両方にレスポンスして呼び出されます。任意の数のインターセプタークラスをターゲットクラスに関連付けることができます。

インターセプタークラスには、パラメーターのない public コンストラクターが必要です。

インターセプターメソッドとインターセプタークラスは、メタデータアノテーションを使用して、またはオプションでデプロイ記述子を使用して、クラスに対して定義できます。

インターセプタークラスとターゲットクラスの関連付け

インターセプタークラスは、いくつかの方法でターゲットクラスまたはターゲットクラスのメソッドに関連付けることができます。

  • インターセプタークラスとターゲットクラスの両方にインターセプターバインディングアノテーションを付けます。インターセプターのインターセプターバインディングのセットは、インターセプタークラスにバインディング型と Interceptor アノテーションを付けることによって指定されます。
  • Interceptors アノテーションを使用して、1 つ以上のインターセプタークラスを指定し、ターゲットクラスまたはターゲットクラスのメソッドまたはコンストラクターに関連付けます。
  • デプロイ記述子がサポートされている場合、それを使用してインターセプタークラスをターゲットクラスやターゲットクラスのメソッドに関連付け、インターセプター呼び出しの順序を指定したり、アノテーションで指定されたメタデータをオーバーライドしたりできます。

インターセプタークラスは、クラスレベルでターゲットクラスに適用するように定義できます。アラウンド呼び出しメソッドインターセプターの場合、インターセプターはターゲットクラスのすべてのビジネスメソッドに適用されます。タイムアウトメソッドインターセプターの場合、インターセプターはターゲットクラスのすべてのタイムアウトメソッドに適用されます。

ExcludeClassInterceptors アノテーションまたはサポートされている場合はデプロイ記述子を使用して、ターゲットクラスのメソッドまたはコンストラクターの Interceptors アノテーションによって定義されたクラスレベルのインターセプターの呼び出しを除外できます。

アラウンド呼び出しインターセプターは、ターゲットクラスの特定のメソッドにのみ適用されるように定義できます。同様に、around-timeout インターセプターは、ターゲットクラスの特定のタイムアウトメソッドにのみ適用されるように定義できます。ただし、ライフサイクルコールバックインターセプターメソッドを定義するインターセプタークラスが、メソッドレベルでターゲットクラスに適用されるように定義されている場合、ライフサイクルコールバックインターセプターメソッドは呼び出されません。

デフォルトのインターセプター

デフォルトのインターセプターは、一連のターゲットクラスに適用されるインターセプターです。デプロイ記述子がサポートされている場合、それを使用してデフォルトのインターセプターとその相対的な順序を定義できます。

ExcludeDefaultInterceptors アノテーションを使用して、ターゲットクラスのデフォルトインターセプターまたはメソッドまたはターゲットクラスのコンストラクターの呼び出しを除外できます。

インターセプターのライフサイクル

インターセプターインスタンスのライフサイクルは、インターセプターが関連付けられているターゲットクラスインスタンスのライフサイクルと同じです。以下に示す AroundConstruct ライフサイクルコールバックインターセプターを除き、ターゲットインスタンスが作成されると、対応するインターセプターインスタンスが、関連付けられたインターセプタークラスごとに作成されます。これらのインターセプターインスタンスは、ターゲットインスタンスの作成に失敗した場合、または削除された場合に破棄されます。

インターセプタークラスは、関連するターゲットクラスのエンタープライズ名前付けコンテキストを共有します。依存性注入または直接ネーミングとディレクトリインターフェースルックアップのアノテーションまたは XML デプロイ記述子要素は、この共有ネーミングコンテキストを参照します。

インターセプタインスタンスは状態を保持する場合があります。インターセプターインスタンスは、依存性注入のターゲットになる場合があります。依存性注入は、関連するターゲットクラスの名前付けコンテキストを使用して、インターセプターインスタンスが作成されるときに実行されます。

AroundConstruct ライフサイクルコールバックインターセプターを除いて、インターセプターインスタンスとターゲットインスタンスの両方で依存関係の注入が完了するまで、インターセプターメソッドは呼び出されません。

PostConstruct インターセプターメソッドがある場合は、インターセプターインスタンスとターゲットインスタンスの両方で依存関係の注入が行われた後に呼び出されます。

PreDestroy インターセプターメソッドがある場合は、ターゲットインスタンスとそれに関連付けられているすべてのインターセプターインスタンスが破棄される前に呼び出されます。

AroundConstruct ライフサイクルコールバックインターセプターが使用される場合、次のルールが適用されます。

  • AroundConstruct ライフサイクルコールバックは、ターゲットクラスに関連付けられているすべてのインターセプタークラスのインスタンスで依存関係の注入が完了した後に呼び出されます。AroundConstruct ライフサイクルコールバック中に呼び出されるインターセプターインスタンスへのターゲットコンポーネントの挿入はサポートされていません。
  • AroundConstruct インターセプターの最後のインターセプターメソッドチェーンが InvocationContext.proceed() メソッドを呼び出した後、該当する場合、ターゲットインスタンスが作成され、そのコンストラクターインジェクションが実行されます。InvocationContext.proceed() メソッドがインターセプターメソッドによって呼び出されない場合、ターゲットインスタンスは作成されません。
  • AroundConstruct インターセプターメソッドは、InvocationContext.proceed() の完了後に InvocationContext.getTarget() メソッドを使用して、構築されたインスタンスにアクセスできます。
  • AroundConstruct インターセプターチェーンのすべてのインターセプターメソッドの呼び出しが正常に完了するまで、ターゲットインスタンスへの依存関係の注入は完了しません。
  • ターゲットインスタンスの PostConstruct ライフサイクルコールバックチェーン（存在する場合）は、ターゲットインスタンスで依存関係の注入が完了した後に呼び出されます。
  • AroundConstruct ライフサイクルコールバックインターセプターメソッドは、依存関係の注入が完了していない可能性があるため、ターゲットインスタンスのメソッドを呼び出すときは注意が必要です。

ライフサイクルコールバックのインターセプター

ライフサイクルコールバックインターセプターメソッドは、非最終的な非静的メソッドです。ターゲットクラス（またはスーパークラス）によって宣言されたライフサイクルコールバックインターセプターメソッドは、パラメーターを持っていてはなりません。インターセプタークラスによって宣言されたライフサイクルコールバックインターセプターメソッドには、型 InvocationContext の単一のパラメーターが必要です。

@PostConstruct
public void interceptPostConstruct(InvocationContext ctx) { ... }

単一のライフサイクルコールバックインターセプターメソッドを使用して、複数のコールバックイベントに割り込むことができます。

@PostConstruct @PreDestroy
public void interceptLifecycle(InvocationContext ctx) { ... }

クラスは、特定のライフサイクルイベントに対して複数のライフサイクルコールバックインターセプタメソッドを宣言することはできません。

ライフサイクルコールバックインターセプターメソッドは、未指定のセキュリティコンテキストで呼び出されます。ライフサイクルコールバックインターセプターメソッドは、ターゲットクラスやメソッドによって決定されるトランザクションコンテキストで呼び出されます。トランザクションコンテキストは、呼び出しチェーンのトランザクションインターセプターによっても変更できます。

ライフサイクルコールバックインターセプターメソッドは実行時例外をスローできますが、チェック例外はスローできません。ただし、AroundConstruct メソッドは例外であり、これらはスローしている可能性がある例外を、それらが介入しているコンストラクターの throws 句で許可されています。

関連事項:
AroundConstruct, AroundInvoke, AroundTimeout, Interceptors, InvocationContext