第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 ヘッダー、クエリーパラメーター、メディアタイプ、その他のメタデータ) を処理するのに適しています。フィルターには、メッセージ呼び出しを中断する機能があります (セキュリティープラグインなどに役立ちます)。

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

インターセプター

JAX-RS 2.0 インターセプター は、開発者が読み取りまたは書き込み中のメッセージボディーへのアクセス権限を付与するプラグインの一種です。インターセプターは、MessageBodyReader.readFrom メソッド呼び出し (リーダーインターセプターの場合) または MessageBodyWriter.writeTo メソッド呼び出し (ライターインターセプターの場合) のいずれかにラップされます。

必要に応じて、各拡張ポイントに複数のインターセプターをインストールできます。その場合には、インターセプターがチェーンで実行されます (ただし、インストールしたフィルターごとに priority の値が指定されていない限り、実行の順番は未定義のままです)。

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

図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 アノテーションを使用) によって異なります。優先度は整数値として表されます。通常、優先度が 高い フィルターはサーバー側でリソースメソッド呼び出しの近くに配置され、優先順位が 低い フィルターはクライアント呼び出しの近くに配置されます。つまり、要求 メッセージに作用するフィルターとインターセプターは、優先順位番号の 昇順 で実行されますが、応答 メッセージに作用するフィルターとインターセプターは、優先順位番号の 降順 で実行されます。

フィルタークラス

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

インターセプタークラス

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