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

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

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

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

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

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

  @PathParam("color")
  String itemColor;

  ...
}

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

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

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

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

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

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() メソッドの type は daikaiju に設定され、id は jonas に設定されます。

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

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

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

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() メソッドの type は daikaiju に設定され、id は whale に設定されます。

デフォルトでは、すべてのリクエスト URI がデコードされます。そのため、URI /monster/night%20stalker と URI /monster/night stalker は同等です。自動 URI デコードを使用すると、ASCII 文字セット以外の文字をパラメーターとして送信しやすくなります。

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

例47.5「URI のデコードの無効化」は、getMonster() メソッドが URI デコードを使用しないリソースを示しています。addMonster() メソッドは、type パラメーターの 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 に設定されます。