Menu Close

第61章 JAX-RS 2.0 フィルターおよびインターセプター

概要

JAX-RS 2.0 は、REST 呼び出しの処理パイプラインにフィルターおよびインターセプターをインストールするために標準の API とセマンティクスを定義します。フィルターやインターセプターは、ロギング、認証、承認、メッセージ圧縮、メッセージの暗号化などを行うために一般的に使用されます。

61.1. JAX-RS フィルターおよびインターセプターの概要

概要

このセクションでは、JAX-RS フィルターおよびインターセプターの処理パイプラインの概要を説明し、フィルターチェーンまたはインターセプターチェーンをインストールするできる拡張ポイントに重点を置きます。

フィルター

JAX-RS 2.0 フィルター は、CXF クライアントまたはサーバーを通過するすべての JAX-RS メッセージに開発者がアクセスできるようにするプラグインの一種です。フィルターは、HTTP ヘッダー、クエリーパラメーター、メディア型、その他のメタデータなど、メッセージに関連付けられたメタデータの処理に適しています。フィルターには、メッセージ呼び出しを中止する機能があります (たとえば、セキュリティープラグインに役立ちます)。

必要に応じて、各拡張ポイントに複数のフィルターをインストールできます。この場合、フィルターはチェーンで実行されます (ただし、インストールされている各フィルターの優先順位を指定しない限り、実行順序は未定義です)。

インターセプター

JAX-RS 2.0 インターセプターは、読み書き中のメッセージ本文に開発者がアクセスできるようにするプラグインの一種です。インターセプターは、MessageBodyReader.readFrom メソッド呼び出し (リーダーインターセプターの場合) または MessageBodyWriter.writeTo メソッド呼び出し (ライターインターセプターの場合) のいずれかにラップされます。

必要に応じて、各拡張ポイントに複数のインターセプターをインストールできます。この場合、インターセプターはチェーンで実行されます (ただし、インストールされている各インターセプターの優先順位を指定しない限り、実行順序は未定義です)。

サーバー処理パイプライン

図61.1「サーバー側フィルターおよびインターセプター拡張ポイント」 は、サーバー側でインストールされた JAX-RS フィルターおよびインターセプターの処理のパイプラインの概要を示しています。

図61.1 サーバー側フィルターおよびインターセプター拡張ポイント

jaxrs20filters 01

サーバー拡張ポイント

サーバー処理パイプラインでは、以下のエクステンションポイントにフィルター (またはインターセプター) を追加できます。

  1. PreMatchContainerRequest フィルター
  2. ContainerRequest フィルター
  3. ReadInterceptor
  4. ContainerResponse フィルター
  5. WriteInterceptor

PreMatchContainerRequest エクステンションポイントは、リソース一致の発生 に到達されるため、この時点で一部のコンテキストメタデータが使用できなくなることに注意してください。

クライアント処理パイプライン

図61.2「クライアント側フィルターおよびインターセプター拡張ポイント」 は、クライアント側でインストールされた JAX-RS フィルターおよびインターセプターの処理のパイプラインの概要を示しています。

図61.2 クライアント側フィルターおよびインターセプター拡張ポイント

jaxrs20filters 02

クライアント拡張ポイント

クライアント処理パイプラインでは、以下のエクステンションポイントにフィルター (またはインターセプター) を追加できます。

  1. ClientRequest フィルター
  2. WriteInterceptor
  3. ClientResponse フィルター
  4. ReadInterceptor

フィルターとインターセプターの順序

複数のフィルターまたはインターセプターを同じ拡張ポイントにインストールする場合、フィルターの実行順序はそれらに割り当てられた優先順位 (Java ソースの @Priority アノテーションを使用) によって異なります。優先度は整数値で表されます。通常、より優先度の高い 数値のあるフィルターは、サーバー側でリソースメソッド呼び出しの近くに配置されます。より優先度の低い数値を持つフィルターはクライアント呼び出しの近くに配置されます。つまり、リクエスト メッセージに対応するフィルターとインターセプターは、優先順位の 昇順 で実行されます。一方、レスポンス メッセージに対応するフィルターとインターセプターは、優先順位の 降順 で実行されます。

フィルタークラス

カスタムの REST メッセージフィルターを作成するには、以下の Java インターフェースを実装できます。

インターセプタークラス

カスタムの REST メッセージインターセプターを作成するには、以下の Java インターフェースを実装できます。