Pathアノテーションは,ルートリソースクラス,サブリソースメソッド,またはサブリソースロケータがどのURLに対するHTTPリクエストを処理するのかを指定するために使用します。Pathアノテーションの値はURIテンプレートと呼ばれます。
ルートリソースにクラスレベルで指定される場合は,Webリソースを含むWebアプリケーション(WARファイル)のコンテキストルートに対して相対的なURIを示します。また,サブリソースメソッドまたはサブリソースロケータの場合は,ルートリソースクラスのURIテンプレートに対して相対的なURIを示します。
アノテーションの値は,自動的にエンコードされます。例えば,次に示すアノテーションの意味は同じです。
二つ以上のルートリソースクラスのPathアノテーションが同じURIテンプレートを持つ場合,または同じ正規表現に解決されるURIテンプレートを持つ場合,エラーとなり(KDJJ10006-E),ルートリソースクラスはインスタンス化されません。HTTPステータスコードには500が返されます。
二つ以上のサブリソースメソッドのPathアノテーションが同じURIテンプレートを持つ場合,または同じ正規表現に解決されるURIテンプレートを持つ場合,メディアタイプ宣言や要求メソッド識別子などのほかの情報も一致するようなとき,エラーとなります(KDJJ10006-E)。ルートリソースクラスでは,HTTPステータスコード500のHTTPレスポンスが返されます。サブリソースクラスでは,例外マッピングプロバイダで処理できるjava.lang.RuntimeExceptionがスローされます。
二つ以上のサブリソースロケータのPathアノテーションが同じURIテンプレートを持つ場合,または同じ正規表現に解決されるURIテンプレートを持つ場合,エラーとなります(KDJJ10006-E)。ルートリソースクラスではHTTPステータスコード500のHTTPレスポンスが返されます。サブリソースクラスでは,例外マッピングプロバイダで処理できるjava.lang.RuntimeExceptionがスローされます。
Pathアノテーションがインタフェースや抽象クラスにアノテートされている場合,エラーとなり(KDJJ10006-E),クライアントからの要求は処理されません。HTTPステータスコードには500が返されます。
URIテンプレートは,テンプレートパラメタと呼ばれる埋め込みのパラメタを0個以上含めることができます。テンプレートパラメタは,開始括弧({)で記述し始め,スラッシュ(/)ではない一文字以上の英数字および記号を続けて記述し,最後に閉じ括弧(})を記述します。テンプレートパラメタの実際の値は,PathParamアノテーションでアノテートされたパラメタ,フィールド,またはbeanプロパティにインジェクトすると,取得できます。テンプレートパラメタの記述方法については,標準仕様を確認してください。
テンプレートパラメタの例を次に示します。
package com.someshop; |
この例では,Pathアノテーションに含まれる表現{id}はテンプレートパラメタです。ルートリソースクラスcom.someshop.CustomerResourceを含むWebアプリケーション(WARファイル)のコンテキストルートが"resource"で,Webアプリケーションが"someshop.com"というホストで公開されているとします。その場合,URL"http://someshop.com/resource/customers/333"に対するHTTP GETリクエストは,サブリソースメソッドgetCustomer()にディスパッチされ,テンプレートパラメタidの実際の値はPathParamアノテーションでアノテートされたパラメタidにインジェクトされます。
一方,URL"http://someshop.com/resource/customers/333/444"に対するHTTP GETリクエストは,どのメソッドにもディスパッチされません。HTTPステータスコードには404が返されます。
テンプレートパラメタは,Pathアノテーションの値(URIテンプレート)のどこにでも埋め込むことができます。テンプレートパラメタを複数使用している例を次に示します。
package com.someshop; |
この例では,Pathアノテーションに含まれる表現{firstname}および{lastname}は,ハイフンによって区切られた二つのテンプレートパラメタです。
URL"http://someshop.com/resource/customers/John-Smith"に対するHTTP GETリクエストは,サブリソースメソッドgetCustomer()にディスパッチされ,テンプレートパラメタfirstnameおよびテンプレートパラメタlastnameの実際の値は,それぞれPathParamアノテーションでアノテートされたパラメタfirstnameおよびパラメタlastnameにインジェクトされます。
Pathアノテーションでは,ワイルドカード以外の正規表現を使用できます。テンプレートパラメタでの正規表現の使用例を次に示します。
package com.someshop; |
この例では,Pathアノテーションに含まれる表現{id : ¥¥d+}は,正規表現を使用しているテンプレートパラメタです。ここでは,識別子idと正規表現"¥¥d+"を組み合わせて使用しています。識別子と正規表現は,コロン(:)で区切ります。
正規表現"¥¥d+"は,一桁以上の数字と一致します。URL"http://someshop.com/resource/customers/333"に対するHTTP GETリクエストは,サブリソースメソッドgetCustomer()にディスパッチされます。
正規表現".+"は,どんな文字とでも一致します。URL"http://someshop.com/resource/customers/33/John/Smith"に対するHTTP GETリクエストは,サブリソースメソッドgetCustomerIdAndName()にディスパッチされます。
次に示す場合,エラーが発生します(KDJJ10006-E)。
ルートリソースクラスではHTTPステータスコード500のHTTPレスポンスが返されます。サブリソースクラスでは例外マッピングプロバイダで処理できるjava.lang.RuntimeExceptionがスローされます(KDJJ10006-E)。