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

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

リソースに関する情報を取得するためのより一般的なメカニズムの 1 つは、リソースの 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 リソースに注入します。アノテーションは、値が抽出され、指定されたフィールド、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 プロパティーに注入されます。アノテーションは、値が抽出され、指定されたフィールド、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 に設定されます。