47.2.6. Java Bean へのパラメーターの挿入

REST 経由で HTML フォームを投稿する場合は、サーバー側で一般的なパターンで Java Bean を作成して、フォームで受け取ったすべてのデータをカプセル化します (場合によっては他のパラメーターや HTML ヘッダーからでもデータもカプセル化します)。通常、この Java Bean の作成は 2 段階のプロセスになります。リソースメソッドはインジェクションによって (たとえば、@FormParam メソッドパラメーターにアノテーションを追加することによって) フォームの値を受け取り、リソースメソッドは Bean のコンストラクタを呼び出し、フォームデータを渡します。

JAX-RS 2.0 @BeanParam アノテーションを使用すると、このパターンを 1 段階で実装できます。フォームデータは bean クラスのフィールドに直接挿入でき、Bean 自体は JAX-RS ランタイムによって自動的に作成されます。これは、例を使用することで最も簡単に説明できます。

@BeanParam アノテーションは、リソースメソッドパラメーター、リソースフィールド、または Bean プロパティーに追加できます。ただし、パラメーターターゲットは、すべてのリソースクラスのライフサイクルで使用できる唯一の種類のターゲットです。他の種類のターゲットは、要求別のライフサイクルに制限されます。この状況は、表47.1「@BeanParam Injection Targets」 にまとめられています。

以下の例は、従来のアプローチ (@BeanParam を使用しない) を使用して Java Bean でフォームデータを取得する方法を表しています。

// Java
import javax.ws.rs.POST;
import javax.ws.rs.FormParam;
import javax.ws.rs.core.Response;
...
@POST
public Response orderTable(@FormParam("orderId")  String orderId,
                           @FormParam("color")    String color,
                           @FormParam("quantity") String quantity,
                           @FormParam("price")    String price)
{
    ...
    TableOrder bean = new TableOrder(orderId, color, quantity, price);
    ...
    return Response.ok().build();
}

この例では、orderTable メソッドは家具の Web サイトからある数量のテーブルを注文するために使用されるフォームを処理します。注文フォームが投稿されると、フォームの値は orderTable メソッドのパラメーターに注入され、orderTable メソッドは注入されたフォームデータを使用して TableOrder クラスのインスタンスを明示的に作成します。

上記の例は、@BeanParam アノテーションを利用するためにリファクタリングできます。@BeanParam のアプローチを使用する場合、フォームパラメーターは Bean クラスの TableOrder フィールドに直接注入できます。実際、@PathParam、@QueryParam、@FormParam、@MatrixParam、@CookieParam、および @HeaderParam などの、Bean クラスの標準の JAX-RS パラメーターアノテーションを使用できます。フォームを処理するコードは、以下のようにリファクタリングできます。

// Java
import javax.ws.rs.POST;
import javax.ws.rs.FormParam;
import javax.ws.rs.core.Response;
...
public class TableOrder {
    @FormParam("orderId")
    private String orderId;

    @FormParam("color")
    private String color;

    @FormParam("quantity")
    private String quantity;

    @FormParam("price")
    private String price;

    // Define public getter/setter methods
    // (Not shown)
    ...
}
...
@POST
public Response orderTable(@BeanParam TableOrder orderBean)
{
    ...
    // Do whatever you like with the 'orderBean' bean
    ...
    return Response.ok().build();
}

これでフォームアノテーションが Bean クラス TableOrder に追加され、以下のようにリソースメソッドの署名にある @FormParam アノテーションをすべて単一の @BeanParam アノテーションで置き換えることができるようになりました。フォームが orderTable リソースメソッドに投稿されると、JAX-RS ランタイムは TableOrder インスタンス orderBean を自動的に作成し、Bean クラスのパラメーターアノテーションが指定するすべてのデータを注入するようになりました。