47.2.3. HTTP メッセージヘッダーからのデータの注入

通常、要求メッセージの HTTP ヘッダーとメッセージに関する一般的な情報、送信方法、および予想される応答の詳細を渡します。いくつかの標準ヘッダーが一般的に認識されて使用されていますが、HTTP 仕様では、任意の名前/値ペアを HTTP ヘッダーとして使用できます。JAX-RS API には、HTTP ヘッダー情報をリソース実装に注入する簡単なメカニズムがあります。

最も一般的に使用される HTTP ヘッダーの 1 つがクッキーです。Cookie を使用すると、HTTP クライアントとサーバーが複数の要求/応答シーケンスで静的情報を共有できます。JAX-RS API には、クッキーから直接リソース実装にデータを注入するアノテーションがあります。

javax.ws.rs.HeaderParam アノテーションは、HTTP ヘッダーフィールドのデータをパラメーター、フィールド、または Bean プロパティーに注入するために使用されます。値が抽出され、リソース実装にインジェクトされる HTTP ヘッダーフィールドの名前を指定する単一のパラメーターがあります。関連するパラメーター、フィールド、または Bean プロパティーは、「サポートされるデータタイプ」 で説明されているデータタイプに準拠している必要があります。

If-Modified-Since ヘッダーの挿入 は、HTTP If-Modified-Since ヘッダーの値をクラスの oldestDate フィールドに注入するコードを示しています。

import javax.ws.rs.HeaderParam;
...
class RecordKeeper
{
  ...
  @HeaderParam("If-Modified-Since")
  String oldestDate;
  ...
}

クッキーは特別な HTTP ヘッダータイプです。これらは、最初の要求でリソース実装に渡される 1 つ以上の名前と値のペアで設定されます。最初の要求後に、クッキーは各クッキーでプロバイダーとコンシューマーの間を行き来します。コンシューマーだけがリクエストを生成するため、Cookie を変更できます。クッキーは通常、複数の要求/応答シーケンス間でセッションを維持し、ユーザー設定やその他の永続化可能なデータを保存するために使用されます。

javax.ws.rs.CookieParam アノテーションは、クッキーのフィールドから値を抽出し、これをリソース実装に注入します。このアノテーションでは、値が抽出される Cookie のフィールドの名前を指定する単一のパラメーターを使用できます。「サポートされるデータタイプ」に示されているデータ型に加え、@CookieParam が付けられたエンティティーも Cookie オブジェクトになることができます。

例47.6「クッキーの挿入」は、handle クッキーの値を CB クラスのフィールドに注入するためのコードを示しています。

import javax.ws.rs.CookieParam;
...
class CB
{
  ...
  @CookieParam("handle")
  String handle;
  ...
}

HTTP メッセージのインジェクションアノテーションのいずれかを使用してデータを注入しようとすると、元の例外をラップする WebApplicationException 例外が生成されます。WebApplicationException 例外のステータスは 400 に設定されます。