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

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

最も一般的に使用される HTTP ヘッダーの 1 つがクッキーです。クッキーを使用すると、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 つ以上の名前と値のペアで構成されています。最初のリクエストの後、クッキーは各メッセージとともにプロバイダーとコンシューマーの間で送受信されます。リクエストを生成するため、コンシューマーのみがクッキーを変更できます。クッキーは、一般に、複数のリクエスト/レスポンスシーケンスにわたってセッションを維持し、ユーザー設定および永続化できるその他のデータを格納するために使用されます。

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

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

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

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