Menu Close

47.2.2. リクエスト URI からのデータの注入

概要

RESTful Web サービスを設計するためのベストプラクティスの 1 つは、各リソースに一意の URI を持つ必要があることです。開発者は、この原則を使用して、基礎となるリソースの実装に大量の情報を提供できます。リソースの URI テンプレートを設計する場合、開発者はテンプレートを構築して、リソースの実装に注入できるパラメーター情報を含めることができます。開発者は、リソースの実装に情報を提供するために、クエリーおよびマトリックスパラメーターを活用することもできます。

URI のパスからのデータの取得

リソースに関する情報を取得するためのより一般的なメカニズムの 1 つは、リソースの URI テンプレートの作成に使用される変数を使用することです。これは、javax.ws.rs.PathParamアノテーションを使用して実現します。@PathParam アノテーションには、データの注入元となる URI テンプレート変数を識別する単一のパラメーターがあります。

例47.1「URI テンプレート変数からのデータの注入」 では、@PathParam アノテーションは URI テンプレート変数 color の値が itemColor フィールドにインジェクトされることを指定します。

例47.1 URI テンプレート変数からのデータの注入

import javax.ws.rs.Path;
import javax.ws.rs.PathParam
...

@Path("/boxes/{shape}/{color}")
class Box
{
  ...

  @PathParam("color")
  String itemColor;

  ...
}

@PathParam アノテーションでサポートされるデータ型は、「サポートされるデータ型」 で説明されているものとは異なります。@PathParam アノテーションがデータを注入するエンティティーは、以下の型のいずれかでなければなりません。

  • PathSegment

    この値は、パスの一致する部分の最後のセグメントになります。

  • List<PathSegment>

    この値は、名前付きテンプレートパラメーターに一致するパスセグメントに対応する PathSegment オブジェクトのリストです。

  • intcharlong などのプリミティブ。
  • 単一の String 引数を受け入れるコンストラクターを持つオブジェクト
  • 単一の String 引数を受け入れる静的 valueOf() メソッドを持つオブジェクト

クエリーパラメーターの使用

Web で情報を渡す一般的な方法は、URI で クエリーパラメーター を使用することです。クエリーパラメーターは URI の最後に表示され、疑問符 (?) で URI のリソース場所部分から区切られます。これらは、名前と値が等号 (=) で区切られた 1 つ以上の名前と値のペアで構成されます。複数のクエリーパラメーターを指定すると、ペアはセミコロン (;) またはアンパサンド (&) で区切られます。例47.2「クエリー文字列のある URI」 は、クエリーパラメーターのある URI の構文を表しています。

例47.2 クエリー文字列のある URI

http://fusesource.org?name=value;name2=value2;...
注記

セミコロンまたはアンパサンドの いずれか を使用して、クエリーパラメーターを区切ることはできますが、両方を使用することはできません。

javax.ws.rs.QueryParam アノテーションは、クエリーパラメーターの値を抽出し、それを JAX-RS リソースに注入します。アノテーションは、値が抽出され、指定されたフィールド、Bean プロパティー、またはパラメーターにインジェクトされるクエリーパラメーターの名前を特定する単一のパラメーターを取ります。@QueryParam アノテーションは、「サポートされるデータ型」 で説明されている型をサポートします。

例47.3「クエリーパラメーターからのデータを使用したリソースメソッド」 は、クエリーパラメーター id の値をメソッドの id パラメーターに注入するリソースメソッドを示しています。

例47.3 クエリーパラメーターからのデータを使用したリソースメソッド

import javax.ws.rs.QueryParam;
import javax.ws.rs.PathParam;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
...

@Path("/monstersforhire/")
public class MonsterService
{
  ...
  @POST
  @Path("/{type}")
  public void updateMonster(@PathParam("type") String type,
                            @QueryParam("id") String id)
  {
    ...
  }
  ...
}

HTTP POST/monstersforhire/daikaiju?id=jonas に処理するには、updateMonster() メソッドの typedaikaiju に設定され、idjonas に設定されます。

マトリクスパラメーターの使用

URI マトリクスパラメーターは、URI クエリパラメーターと同様に、リソースの選択に関する追加情報を提供できる名前と値のペアです。クエリーパラメーターとは異なり、マトリクスパラメーターは URI のどこにでも置くことができ、セミコロン (;) を使用して URI の階層パスセグメントから区別されます。/mostersforhire/daikaiju;id=jonas には id という 1 つのマトリクスパラメーターがあり、/monstersforhire/japan;type=daikaiju/flying;wingspan=40 には type および wingspan という 2 つのマトリクスパラメーターがあります。

注記

マトリクスパラメーターは、リソースの URI を計算する際に評価されません。そのため、リクエスト URI /monstersforhire/japan;type=daikaiju/flying;wingspan=40 を処理する適切なリソースを見つけるために使用される URI は /monstersforhire/japan/flying です。

マトリクスパラメーターの値は、javax.ws.rs.MatrixParam アノテーションを使用してフィールド、パラメーター、または Bean プロパティーに注入されます。アノテーションは、値が抽出され、指定されたフィールド、bean プロパティー、またはパラメーターにインジェクトされるマトリクスパラメーターの名前を特定する単一のパラメーターを取ります。@MatrixParam アノテーションは、「サポートされるデータ型」 で説明されている型をサポートします。

例47.4「マトリックスパラメーターのデータを使用するリソースメソッド」 は、マトリクスパラメーター type および id の値をメソッドのパラメーターに注入するリソースメソッドを表しています。

例47.4 マトリックスパラメーターのデータを使用するリソースメソッド

import javax.ws.rs.MatrixParam;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
...

@Path("/monstersforhire/")
public class MonsterService
{
  ...
  @POST
  public void updateMonster(@MatrixParam("type") String type,
                            @MatrixParam("id") String id)
  {
    ...
  }
  ...
}

HTTP POST/monstersforhire;type=daikaiju;id=whale に処理するには、updateMonster() メソッドの typedaikaiju に設定され、idwhale に設定されます。

注記

JAX-RS は URI のマトリックスパラメーターをすべて一度に評価します。そのため、URI のマトリックスパラメーターの場所に制約を適用することはできません。たとえば、/monstersforhire/japan;type=daikaiju/flying;wingspan=40/monstersforhire/japan/flying;type=daikaiju;wingspan=40、および /monstersforhire/japan;type=daikaiju;wingspan=40/flying は、すべて JAX-RS API を使用して実装される RESTful Web サービスによって同等として扱われます。

URI デコードの無効化

デフォルトでは、すべてのリクエスト URI がデコードされます。URI /monster/night%20stalker と URI /monster/night stalker は同等のものに なります。自動 URI デコードにより、ASCII 文字セットの外部に文字をパラメーターとして簡単に送信できます。

URI を自動的にデコードしたくない場合は、javax.ws.rs.Encoded アノテーションを使用して URI のデコードを非アクティブ化できます。アノテーションは、以下のレベルで URI をデコードするために使用できます。

  • クラスレベル - @Encoded アノテーションでクラスをデコードすると、クラス内のすべてのパラメーター、フィールド、および Bean プロパティーの URI デコードが無効になります。
  • メソッドレベル - @Encoded アノテーションでメソッドをデコードすると、クラスのすべてのパラメーターの URI デコードが無効になります。
  • パラメータ/フィールドレベル - パラメーターまたはフィールドを @Encoded アノテーションでデコレートすると、クラスのすべてのパラメーターの URI デコードが無効になります。

例47.5「URI デコードの無効化」 は、getMonster() メソッドが URI デコードを使用しないリソースを示しています。addMonster() メソッドは、type パラメーターの URI デコードのみを無効にします。

例47.5 URI デコードの無効化

@Path("/monstersforhire/")
public class MonsterService
{
  ...

  @GET
  @Encoded
  @Path("/{type}")
  public Monster getMonster(@PathParam("type") String type,
                            @QueryParam("id") String id)
  {
    ...
  }

  @PUT
  @Path("/{id}")
  public void addMonster(@Encoded @PathParam("type") String type,
                         @QueryParam("id") String id)
  {
    ...
  }
  ...
}

エラー処理

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