ルートリソースクラスは,リソースメソッド,サブリソースメソッド,またはサブリソースロケータのどれかを一つ以上持ち,クラスレベルでPathアノテーションでアノテートされたJavaのpublicのクラスです。
リソースメソッドとサブリソースロケータを持つルートリソースクラスの例を次に示します。
package com.sample.resources; |
com.sample.resources.Resource2はルートリソースクラスです。クラスレベルでPathアノテーションでアノテートされていることに注意してください。このルートリソースクラスは,二つのサブリソースロケータsubResourceLocator1()とsubResourceLocator2()およびHTTP GETリクエストを処理するリソースメソッドgetValue()を持ちます。サブリソースロケータがPathアノテーションでアノテートされ,リソースメソッドが要求メソッド識別子でアノテートされていることに注意してください。二つのクラスSubResource1とSubResource2はサブリソースクラスです。詳細は,次の項目を参照してください。
サブリソースメソッドを持つルートリソースクラスの例を次に示します。
package com.sample.resources; |
com.sample.resources.Resource3はルートリソースクラスです。このルートリソースクラスは,二つのサブリソースメソッドsubResourceMethod1()とsubResourceMethod2()を持ちます。サブリソースメソッドは,Pathアノテーションと要求メソッドの両方でアノテートされます。
PathアノテーションのURLにアスタリスク(*)を指定されている場合は,リソースメソッドだけを呼び出すことができます。サブリソースメソッド,およびサブリソースロケータを呼び出した場合は,例外マッピングプロバイダで処理できるjava.lang.StringIndexOutOfBoundsExceptionがスローされます。
JAX-RSエンジンは,Webリソースに対する要求ごとにルートリソースクラスをインスタンス化します。ルートリソースクラスのライフサイクルは次のとおりです。
ルートリソースクラスは,publicデフォルトコンストラクタ(明示的に宣言されないコンストラクタ)も含めて,少なくとも一つ以上のpublicコンストラクタを持つ必要があります。
パラメタを持つpublicコンストラクタの例を次に示します。
package com.sample.resources; |
この例では,ルートリソースクラスcom.sample.resources.Resource1は,QueryParamアノテーションでアノテートされたパラメタqueryを持つpublicコンストラクタResource1()によってインスタンス化されます。
パラメタqueryを自動でURLデコードされるのを無効化するためにEncodedアノテーションが使用されています。また,クライアントから送信された要求にパラメタqueryにインジェクトする値がない場合のデフォルト値を指定するためにDefaultValueアノテーションが組み合わされて使用されています。
パラメタを持たないpublicコンストラクタの例を次に示します。
package com.sample.resources; |
この例では,ルートリソースクラスcom.sample.resources.Resource2は,パラメタを持たないpublicコンストラクタResource2()によってインスタンス化されます。
パラメタを持つpublicコンストラクタが一つ以上宣言されている例を次に示します。
package com.sample.resources; |
この例では,ルートリソースクラスcom.sample.resources.Resource3は,それぞれMatrixParamアノテーションおよびQueryParamアノテーションでアノテートされたパラメタmatrix1およびパラメタquery1を持つ,2番目のpublicコンストラクタによってインスタンス化されます。
パラメタmatrix1とパラメタquery1を自動でURLデコードされるのを無効化するために,Encodedアノテーションがコンストラクタのレベルで使用されています。
デフォルトコンストラクタの例を次に示します。
package com.sample.resources; |
この例では,ルートリソースクラスcom.sample.resources.Resource4は,暗黙的に宣言されているデフォルトコンストラクタResource4()によってインスタンス化されます。
デフォルトコンストラクタでjava.io.IOExceptionが発生した場合,エラーとなり(KDJJ10039-E),ルートリソースクラスはインスタンス化されません。HTTPステータスコードには500が返されます。
publicコンストラクタが一つも宣言されていない場合,エラーとなり(KDJJ10006-E),ルートリソースクラスはインスタンス化されません。HTTPステータスコードには500が返されます。
なお,次に示すコンストラクタはpublicコンストラクタではありません。
コンストラクタのパラメタで使用できるインジェクション用アノテーションと,オプションのアノテーションの組み合わせを次の表に示します。
表17-2 コンストラクタのパラメタで使用できるアノテーション
項番 | インジェクション用アノテーション | オプションのアノテーション | |
---|---|---|---|
Encoded | DefaultValue | ||
1 | MatrixParam | ○ | ○ |
2 | QueryParam | ○ | ○ |
3 | PathParam | ○ | × |
4 | CookieParam | × | ○ |
5 | HeaderParam | × | ○ |
6 | FormParam | × | ○ |
7 | Context | × | × |
オプションのEncodedアノテーションを使用すると,インジェクション対象のコンストラクタのパラメタが自動でURLデコードされるのを無効化できます。
オプションのDefaultValueアノテーションを使用すると,インジェクション対象のコンストラクタのパラメタにインジェクトする値がない場合に仮定されるデフォルト値を指定できます。
ルートリソースクラスがパラメタを持つpublicコンストラクタを一つ以上持つ場合,JAX-RSエンジンは,最もパラメタ数が多いコンストラクタを使用してルートリソースクラスをインスタンス化します。最もパラメタ数が多いコンストラクタを二つ以上持つ場合,最初に定義されているコンストラクタを使用してルートリソースクラスをインスタンス化します。このとき,警告メッセージがログに出力されます(KDJJ20010-W)。
次のどちらかの場合,HTTPリクエストは処理されません。HTTPステータスコードには500が返されます。なお,ログを確認するときは,JAX-RS機能のログファイルではなくJ2EEサーバのログファイルを確認してください。
ルートリソースクラスのフィールドおよびbeanプロパティで使用できるインジェクション用アノテーションと,オプションのアノテーションの組み合わせを次の表に示します。JAX-RSエンジンは,ルートリソースクラスをインスタンス化する際に,アノテーションに基づいてアノテートされたフィールドおよびbeanプロパティに値をインジェクトします。なお,Beanプロパティは,読み取り専用プロパティでなくても構いません。
表17-3 フィールドおよびbeanプロパティで使用できるアノテーション
項番 | インジェクション用アノテーション | オプションのアノテーション | |
---|---|---|---|
Encoded | DefaultValue | ||
1 | MatrixParam | ○ | ○ |
2 | QueryParam | ○ | ○ |
3 | PathParam | ○ | × |
4 | CookieParam | × | ○ |
5 | HeaderParam | × | ○ |
6 | FormParam | × | ○ |
7 | Context | × | × |
オプションのEncodedアノテーションを使用すると,インジェクション対象のフィールドまたはbeanプロパティが自動でURLデコードされるのを無効化できます。
オプションのDefaultValueアノテーションを使用すると,インジェクション対象のフィールドまたはbeanプロパティにインジェクトする値がない場合に仮定されるデフォルト値を指定できます。
ルートリソースクラスのフィールドでDefaultValueアノテーションを使用する例を次に示します。
private @DefaultValue("value1") @QueryParam("id") String id; |
この例では,クエリパラメタidがURLに指定されていない場合,フィールドidは"value1"になります。
ルートリソースクラスのbeanプロパティでDefaultValueアノテーションを使用する例を次に示します。
private String property1; |
この例では,クエリパラメタprop1がURIに指定されていない場合,beanプロパティproperty1の値は"10"になります。
ルートリソースクラスのフィールドでEncodedアノテーションを使用する例を次に示します。
private @Encoded @QueryParam("id") String id; |
この例では,フィールドidの値は,自動でURLデコードされません。
ルートリソースクラスのbeanプロパティでEncodedアノテーションを使用する例を次に示します。
private String property1; |
この例では,beanプロパティproperty1の値は,自動でURLデコードされません。
ルートリソースクラスのフィールド,またはbeanプロパティのうち,インジェクション用アノテーションとDefaultValueアノテーションが使用されているパラメタで,JAX-RSエンジンがインジェクトするときにランタイム例外が発生した場合,HTTPリクエストは処理されません。HTTPステータスコードには500が返されます。なお,ログを確認するときは,JAX-RS機能のログファイルではなくJ2EEサーバのログファイルを確認してください。
リソースメソッドは,JAX-RS仕様で定義された要求メソッド識別子のどれかでアノテートされた,ルートリソースクラスのメソッドです。ルートリソースクラスは,一つ以上のリソースメソッドを持つことができます。
JAX-RS仕様で定義された要求メソッド識別子を次に示します。
一つのリソースメソッドに対し,二つ以上の要求メソッド識別子を使用している場合,エラーとなり(KDJJ10006-E),ルートリソースクラスはインスタンス化されません。HTTPステータスコードには500が返されます。
二つ以上のリソースメソッドに対し,同じ要求メソッド識別子を使用している場合,エラーとなり(KDJJ10006-E),ルートリソースクラスはインスタンス化されません。HTTPステータスコードには500が返されます。
HTTPリクエストに対し,ディスパッチするリソースメソッドが一つもない場合,HTTPステータスコードに405が設定された,例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。
リソースメソッドで要求メソッド識別子を使用している例を次に示します。
@GET |
この例では,echo()メソッドがGET要求メソッド識別子でアノテートされています。また,echo()メソッドは,Content-Typeが"text/plain"であるHTTPレスポンスを返すために,"text/plain"を値に持つProducesアノテーションでアノテートされています。なお,パラメタidは,クエリパラメタidを受け取るQueryParamアノテーションでアノテートされ,さらにクエリパラメタが自動でURLデコードされるのを無効化するためにEncodedアノテーションでアノテートされています。
リソースメソッドは,要求メソッド識別子が適用されたpublicメソッドである必要があります。次に示すメソッドは,要求メソッド識別子でアノテートされていてもリソースメソッドではありません。
要求メソッド識別子を上記のメソッドのどれかに適用した場合,警告メッセージまたはエラーメッセージがログに出力されます(KDJJ20003-WまたはKDJJ10006-E)。KDJJ20003-WおよびKDJJ10006-Eについては,「13.7.1 Webリソース初期化時の構文チェック(KDJJ20003-WとKDJJ10006-E)」を参照してください。
リソースメソッドのパラメタで使用できるインジェクション用アノテーションと,オプションのアノテーションの組み合わせを次の表に示します。
表17-4 リソースメソッドのパラメタで使用できるアノテーション
項番 | インジェクション用アノテーション | オプションのアノテーション | |
---|---|---|---|
Encoded | DefaultValue | ||
1 | MatrixParam | ○ | ○ |
2 | QueryParam | ○ | ○ |
3 | PathParam | ○ | × |
4 | CookieParam | × | ○ |
5 | HeaderParam | × | ○ |
6 | FormParam | × | ○ |
7 | Context | × | × |
オプションのEncodedアノテーションを使用すると,インジェクション対象のリソースメソッドのパラメタが自動でURLデコードされるのを無効化できます。
オプションのDefaultValueアノテーションを使用すると,インジェクション対象のリソースメソッドのパラメタにアノテートされるアノテーションのデフォルト値を指定できます。
リソースメソッドのパラメタでアノテーションを使用する例を次に示します。
@GET |
この例では,リソースメソッドecho()は,QueryParamアノテーションでアノテートされたパラメタidおよびMatrixParamアノテーションでアノテートされたパラメタmatrix1を含みます。パラメタidは,自動でURLデコードされるのを無効化し,デフォルト値を指定するために,さらにEncodedアノテーションおよびDefaultValueアノテーションでアノテートされています。matrixパラメタは,さらに自動でURLデコードされるのを無効化するためにEncodedアノテーションでアノテートされています。
ルートリソースクラスのリソースメソッド,またはサブリソースメソッドのパラメタのうち,インジェクション用アノテーションとDefaultValueアノテーションが使用されているパラメタで,JAX-RSエンジンがインジェクトするときにランタイム例外が発生した場合,エラーとなり(KDJJ10009-E,KDJJ10006-E),HTTPリクエストは処理されません。HTTPステータスコードには500が返されます。
エンティティパラメタの説明については,「17.1.2 エンティティパラメタ」を参照してください。
戻り値の説明については,「17.1.3 戻り値」を参照してください。
Pathアノテーションでアノテートされたリソースメソッドを,特に,サブリソースメソッドと呼びます。サブリソースメソッドとリソースメソッドの違いは,Pathアノテーションを使用しているかどうかだけです。
サブリソースメソッドの例を次に示します。
package com.sample.resources; |
この例では,doSomething()メソッドがサブリソースメソッドです。ルートリソースクラスcom.sample.resources.Resource1を含むWebアプリケーション(WARファイル)のコンテキストルートが,"example"で,Webアプリケーションが"sample.com"というホストで公開されているとします。その場合,URL"http://sample.com/example/root/sub1"に対するHTTP POST要求は,サブリソースメソッドdoSomething()にディスパッチされます。
一方,URL"http://sample.com/example/root"に対するHTTP POST要求は,リソースメソッドdoOthers()にディスパッチされます。
要求メソッド識別子が適用されていない,Pathアノテーションだけでアノテートされたルートリソースクラスのメソッドをサブリソースロケータと呼びます。
サブリソースロケータは,HTTPリクエストに対する残りの処理を行うサブリソースクラスを返します。サブリソースクラスについては,「17.1.7 サブリソースクラス」を参照してください。
ルートリソースクラスのサブリソースロケータの例を次に示します。
package com.sample.resources; |
対応するサブリソースクラスの例を次に示します。
//サブリソースクラス |
この例では,ルートリソースクラスcom.sample.resources.Resourceは,HTTPリクエストを直接処理しません。サブリソースロケータgetRequestHandlerが返すサブリソースクラスは,com.sample.resources.SubResourceが処理します。
リソースクラスcom.sample.resources.Resourceを含むWebアプリケーション(WARファイル)のコンテキストルートが"example"で,Webアプリケーションが"sample.com"というホストで公開されているとします。その場合,URL"http://sample.com/example/root/sub1?query1=10"に対するHTTP GETリクエストは,ルートリソースクラスcom.sample.resources.ResourceのメソッドgetRequestHandler()にディスパッチされます。
HTTP GETリクエストに対する残りの処理は,サブリソースクラスcom.sample.resources.SubResourceのリソースメソッドgetRequestParameter()によって処理されます。
サブリソースロケータのパラメタとしてエンティティパラメタを使用した場合,エラーとなり(KDJJ10006-E),クライアントからのHTTPリクエストは処理されません。HTTPステータスコードには500が返されます。
サブリソースロケータがpublicでない場合の動作は,リソースメソッドと同じです。
サブリソースロケータの戻り値の型がvoidの場合,エラーとなり(KDJJ10006-E),クライアントからのHTTPリクエストは処理されません。HTTPステータスコードには500が返されます。
サブリソースロケータのパラメタのうち,インジェクション用アノテーションとDefaultValueアノテーションが使用されているパラメタで,JAX-RSエンジンがインジェクトするときにランタイム例外が発生した場合,HTTPリクエストは処理されません。HTTPステータスコードには500が返されます。なお,ログを確認するときは,JAX-RS機能のログファイルではなくJ2EEサーバのログファイルを確認してください。