RESTful アプリケーションにおけるリソース要求の表現に関するパラメーターの定義

パラメーターは、要求に追加情報を渡すため、および情報を追加するために 使用されます。パラメーターを URL の一部として使用するか、またはヘッダー内で 使用することができます。追加情報を要求に渡すために、パス・パラメーター、マトリックス・パラメーター、照会パラメーター、 ヘッダー・パラメーター、および Cookie パラメーターを 利用できます。

このタスクについて

パラメーターのタイプは複数あります。Java™ API for RESTful Web Services (JAX-RS) は、 アノテーション付きの、注入されたパラメーターを使用することにより、すべてのタイプのパラメーターへのアクセス を簡単にします。

java.lang.String などの任意の Java 基本型を パラメーターとして使用でき、単一の String または valueOf(String) 静的メソッドを使用するコンストラクターと 共に Java 型を使用することも できます。さらに、ListSortedSet、 および Set インターフェースを使用できます。これらのインターフェースでは、 汎用タイプは前述のタイプの 1 つであり、例えば、1 つのパラメーターが複数の値を持つことが可能な場合は Set を 使用します。要求を構文解析する必要がある場合、 基本的な検査およびエラー・パス応答のカスタマイズを 実行できるよう、パラメーターのタイプとして String を使用してください。

JAX-RS では、 リソース・メソッド・パラメーターで使用するために以下のアノテーションが提供されています。 これらを指定することによって、正しいパラメーター値を用いてリソース・メソッドが起動されます。

javax.ws.rs.PathParam アノテーション

パス・パラメーターは URL の一部です。例えば、URL は /collection/{item} を含むことができます。ここで、{item} は、 コレクション内のアイテムを識別するパス・パラメーターです。パス・パラメーターは、URL の 一部であるため、要求の識別にとても重要です。

URL の部分がパラメーターである 場合、次の例のように、@javax.ws.rs.PathParam アノテーションを付けたパラメーターを使用できます。
@javax.ws.rs.Path(“/bookstore/books/{bookId}”)
public class BooksCollection {
    @javax.ws.rs.GET
        public String getSpecificBookInfo(@javax.ws.rs.PathParam(“bookId”) String theBookId) {
                /* theBookId would contain the next path segment after /bookstore/books/  */
    }
}
この例では、/bookstore/books/12345 に対する要求 は、値 12345theBookId 変数に割り当てます。
javax.ws.rs.MatrixParam アノテーション

マトリックス・パラメーターは URL の一部です。例えば、 URL がパス・セグメント /collection;itemID=itemIDValue を含んでいる とすると、マトリックス・パラメーター名は itemID であり、itemIDValue が 値です。

次の例のように、@javax.ws.rs.MatrixParam アノテーション付きパラメーター でマトリックス・パラメーターを読み取ることができます。
@javax.ws.rs.Path(“/bookstore/books”)
public class BooksCollection {
    @javax.ws.rs.GET
        public String getBookCollectionInfo(@javax.ws.rs.MatrixParam(“page”) int page, @javax.ws.rs.MatrixParam(“filter”) String filter) {
                /* This statement uses the page and filter parameters. */
    }
}
この例では、/bookstore/books;page=25;filter=test への要求 は getBookCollectionInfo パラメーターを起動して、 page 変数の値が 25 に、 filter 変数の値が test に設定されます。
javax.ws.rs.QueryParam アノテーション

照会パラメーターは、「?」の後に名前と値の対で URL に付加 されます。例えば、URL が http://example.com/collection?itemID=itemIDValue の場合、 照会パラメーターの名前は itemID であり、itemIDValue は 値です。照会パラメーターは、HTTP GET 要求でのフィルター操作またはページ送り操作時に、 よく使用されます。

次の例のように、@javax.ws.rs.QueryParam アノテーション付きパラメーターで 照会パラメーターを読み取ることができます。
@javax.ws.rs.Path(“/bookstore/books”)
public class BooksCollection {
    @javax.ws.rs.GET
        public String getBookCollectionInfo(@javax.ws.rs.QueryParam(“page”) int page, @javax.ws.rs.QueryParam(“filter”) String filter) {
                /* This statement uses the page and filter parameters. */
    }
}
この例では、/bookstore/books;page=25;filter=test への要求 は getBookCollectionInfo パラメーターを起動して、 page 変数の値が 25 に、 filter 変数の値が test に設定されます。
javax.ws.rs.HeaderParam アノテーション

ヘッダー・パラメーターは HTTP ヘッダーです。事前定義 された HTTP ヘッダーがありますが、カスタム・ヘッダーを使用することもできます。通常、ヘッダーには、 クライアント、仲介、またはサーバーの制御メタデータ情報が含まれます。

HTTP 要求 ヘッダーを読み取る必要がある場合、次の例のように、@javax.ws.rs.HeaderParam アノテーション を使用します。
@javax.ws.rs.Path(“/bookstore/books/”)
public class BooksCollection {
    @javax.ws.rs.GET
        public String getBookCollectionInfo(@javax.ws.rs.HeaderParam(“Range”) String rangeValue) {
                /* The rangeValue variable contains the value of the HTTP request header "Range" */
    }
}

この例では、/bookstore/books/ への要求 で Range HTTP 要求ヘッダー値が bytes=0-499 のものは、 rangeValue 変数の値として bytes=0-499 を使用してメソッドを起動します。

javax.ws.rs.CookieParam アノテーション

Cookie パラメーターは、特殊な HTTP ヘッダーです。Cookie は セッション識別の保管、または、RESTful として受け入れられないステートフル・データの保管に 関連付けられている一方、ステートレス情報を含むことができます。

例えば mycustomid=customvalue123 のような HTTP Cookie が 送信された場合、次の例を使用して mycustomid 変数の値 を取得できます。
@javax.ws.rs.Path(“/bookstore/books/”)
public class BooksCollection {
    @javax.ws.rs.GET
        public String getBookCollectionInfo(@javax.ws.rs.CookieParam(“mycustomid”) String mycustomid) {
                /* The cookie value is passed to the mycustomid variable. */
    }
}
javax.ws.rs.FormParam アノテーション

フォーム・パラメーターは、 メディア・タイプが application/x-www-form-urlencoded の HTML フォームをブラウザーから送信するときに 使用されます。フォーム・パラメーターと値は、 firstParameter=firstValue&secondParameter=secondValue のような形式で、要求メッセージ本体内でエンコードされます。 javax.ws.rs.FormParam アノテーションにより、個々のフォーム・パラメーター値 に簡単にアクセスすることができます。

フォームが送信され、 エンティティー値が firstName=Bob&lastName=Smith の場合、 次の例を使用して、これらのフォーム・パラメーターの値を取り出すことができます。
@javax.ws.rs.Path(“/customer”)
public class Custommer {
    @javax.ws.rs.POST
        public String postCustomerInfo(@javax.ws.rs.FormParam(“firstName”) String firstName, @javax.ws.rs.FormParam("lastName") String lastName) {
                /* firstName would be "Bob" and secondName would be "Smith" */
    }
}
トラブルの回避 (Avoid trouble) トラブルの回避 (Avoid trouble): アノテーションなしの単一のパラメーターを 使用してメッセージ本体を表すか、または、FormParam アノテーションを付けた複数のパラメーターを 使用することができますが、両方はできません。FormParam は 要求メッセージ本体の読み取りを必要とし、 メッセージ本体はバイト・ストリームとして表現されているため、メッセージ本体の再読み取りは 不可能です。以下のコードは無効です。
@javax.ws.rs.Path(“/bookstore/books”)
public class BooksCollection {
    @javax.ws.rs.POST
        public String postSpecificBookInfo(@javax.ws.rs.FormParam(“bookId”) String theBookId, String theRequestEntity) {
                /* This code is invalid.  Can only use FormParam or a request entity parameter like "String theRequestEntity" and not both */
    }
}
gotcha

パラメーターを読み取るための変数を定義するには、 以下のいずれかの方法を選択してください。

手順

タスクの結果

適切なパラメーター値を使用して起動できるよう、リソース・メソッドが定義 されます。


トピックのタイプを示すアイコン タスク・トピック



タイム・スタンプ・アイコン 最終更新: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxrs_defresource_parmexchdata
ファイル名:twbs_jaxrs_defresource_parmexchdata.html