RESTful アプリケーションにおけるリソース要求の表現に関するパラメーターの定義
パラメーターは、要求に追加情報を渡すため、および情報を追加するために 使用されます。パラメーターを URL の一部として使用するか、またはヘッダー内で 使用することができます。追加情報を要求に渡すために、パス・パラメーター、マトリックス・パラメーター、照会パラメーター、 ヘッダー・パラメーター、および Cookie パラメーターを 利用できます。
このタスクについて
パラメーターのタイプは複数あります。Java™ API for RESTful Web Services (JAX-RS) は、 アノテーション付きの、注入されたパラメーターを使用することにより、すべてのタイプのパラメーターへのアクセス を簡単にします。
java.lang.String などの任意の Java 基本型を パラメーターとして使用でき、単一の String または valueOf(String) 静的メソッドを使用するコンストラクターと 共に Java 型を使用することも できます。さらに、List、SortedSet、 および Set インターフェースを使用できます。これらのインターフェースでは、 汎用タイプは前述のタイプの 1 つであり、例えば、1 つのパラメーターが複数の値を持つことが可能な場合は Set を 使用します。要求を構文解析する必要がある場合、 基本的な検査およびエラー・パス応答のカスタマイズを 実行できるよう、パラメーターのタイプとして String を使用してください。
JAX-RS では、 リソース・メソッド・パラメーターで使用するために以下のアノテーションが提供されています。 これらを指定することによって、正しいパラメーター値を用いてリソース・メソッドが起動されます。
- javax.ws.rs.PathParam アノテーション
パス・パラメーターは URL の一部です。例えば、URL は /collection/{item} を含むことができます。ここで、{item} は、 コレクション内のアイテムを識別するパス・パラメーターです。パス・パラメーターは、URL の 一部であるため、要求の識別にとても重要です。
URL の部分がパラメーターである 場合、次の例のように、@javax.ws.rs.PathParam アノテーションを付けたパラメーターを使用できます。
この例では、/bookstore/books/12345 に対する要求 は、値 12345 を theBookId 変数に割り当てます。@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/ */ } }
- javax.ws.rs.MatrixParam アノテーション
マトリックス・パラメーターは URL の一部です。例えば、 URL がパス・セグメント /collection;itemID=itemIDValue を含んでいる とすると、マトリックス・パラメーター名は itemID であり、itemIDValue が 値です。
次の例のように、@javax.ws.rs.MatrixParam アノテーション付きパラメーター でマトリックス・パラメーターを読み取ることができます。
この例では、/bookstore/books;page=25;filter=test への要求 は getBookCollectionInfo パラメーターを起動して、 page 変数の値が 25 に、 filter 変数の値が test に設定されます。@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. */ } }
- javax.ws.rs.QueryParam アノテーション
照会パラメーターは、「?」の後に名前と値の対で URL に付加 されます。例えば、URL が http://example.com/collection?itemID=itemIDValue の場合、 照会パラメーターの名前は itemID であり、itemIDValue は 値です。照会パラメーターは、HTTP GET 要求でのフィルター操作またはページ送り操作時に、 よく使用されます。
次の例のように、@javax.ws.rs.QueryParam アノテーション付きパラメーターで 照会パラメーターを読み取ることができます。
この例では、/bookstore/books;page=25;filter=test への要求 は getBookCollectionInfo パラメーターを起動して、 page 変数の値が 25 に、 filter 変数の値が test に設定されます。@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. */ } }
- 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): アノテーションなしの単一のパラメーターを 使用してメッセージ本体を表すか、または、FormParam アノテーションを付けた複数のパラメーターを 使用することができますが、両方はできません。FormParam は 要求メッセージ本体の読み取りを必要とし、 メッセージ本体はバイト・ストリームとして表現されているため、メッセージ本体の再読み取りは 不可能です。以下のコードは無効です。
gotcha@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 */ } }
パラメーターを読み取るための変数を定義するには、 以下のいずれかの方法を選択してください。
手順
タスクの結果
適切なパラメーター値を使用して起動できるよう、リソース・メソッドが定義 されます。