ここでは,JAX-RSエンジンがサポートするインジェクション用アノテーションについて説明します。
インジェクション用アノテーションは,パラメタ,フィールド,またはbeanプロパティそれぞれにつき一つだけ使用できます。一つのパラメタ,フィールド,またはbeanプロパティにつき複数のアノテーションを同時に指定した場合は,最も右のアノテーションだけが有効になります。最も右のアノテーションがJAX-RS 1.1仕様でない場合は,ほかのすべてのアノテーションが無視されてインジェクションは実行されません。
インジェクション用アノテーションをbeanプロパティに使用する場合は,setterメソッドに対してメソッドレベルでアノテートしてください。
ルートリソースクラスおよび例外マッピングプロバイダでは,コンストラクタおよびbeanプロパティのsetterメソッドから,インジェクション用アノテーションでアノテートされたフィールドを参照または変更しないでください。
コンストラクタ,フィールド,およびbeanプロパティへのインジェクションは,ルートリソースクラスおよび例外マッピングプロバイダがJAX-RSエンジンによってインスタンス化されるときに同時に行われます。このため,コンストラクタおよびbeanプロパティのsetterメソッドから,インジェクション用アノテーションでアノテートされたフィールドを参照した場合,取得される値は不定です。また,インジェクション用アノテーションでアノテートされたフィールドを変更した場合,フィールドへのインジェクションが失敗するか,または成功しても値が不定になります。
javax.ws.rs.HeaderParamアノテーションはHTTPヘッダの値を取得するために使用します。アノテーションの値には,HTTPリクエストに含まれるHTTPヘッダの名称を指定します。
javax.ws.rs.HeaderParamアノテーションを指定できる対象を,次の表に示します。
表24-3 javax.ws.rs.HeaderParamアノテーションを指定できる対象
Webリソースまたはプロバイダ | コンストラクタのパラメタ | フィールド | beanプロパティ | メソッドのパラメタ |
---|---|---|---|---|
ルートリソースクラス | ○ | ○ | ○ | ○ |
サブリソースクラス | × | × | × | ○ |
例外マッピングプロバイダ | × | × | × | - |
Webリソースまたはプロバイダについては,「17. Webリソースとプロバイダ」の各項目を参照してください。
javax.ws.rs.CookieParamアノテーションはHTTP Cookieの値を取得するために使用します。アノテーションの値は,HTTPリクエストに含まれるCookieの名称を指定します。
javax.ws.rs.CookieParamアノテーションを指定できる対象を,次の表に示します。
表24-4 javax.ws.rs.CookieParamアノテーションを指定できる対象
Webリソースまたはプロバイダ | コンストラクタのパラメタ | フィールド | beanプロパティ | メソッドのパラメタ |
---|---|---|---|---|
アプリケーションサブクラス | × | × | × | - |
ルートリソースクラス | ○ | ○ | ○ | ○ |
サブリソースクラス | × | × | × | ○ |
エンティティプロバイダ | × | × | × | - |
コンテキストプロバイダ | × | × | × | - |
例外マッピングプロバイダ | × | × | × | - |
Webリソースまたはプロバイダについては,「17. Webリソースとプロバイダ」の各項目を参照してください。
javax.ws.rs.MatrixParamアノテーションはURIマトリクスパラメタの値を取得するために使用します。アノテーションの値は,HTTPリクエストに含まれるマトリクスパラメタの名称を指定します。
javax.ws.rs.MatrixParamアノテーションを指定できる対象を,次の表に示します。
表24-5 javax.ws.rs.Matrix parameterアノテーションを指定できる対象
Webリソースまたはプロバイダ | コンストラクタのパラメタ | フィールド | beanプロパティ | メソッドのパラメタ |
---|---|---|---|---|
アプリケーションサブクラス | × | × | × | - |
ルートリソースクラス | ○ | ○ | ○ | ○ |
サブリソースクラス | × | × | × | ○ |
エンティティプロバイダ | × | × | × | - |
コンテキストプロバイダ | × | × | × | - |
例外マッピングプロバイダ | × | × | × | - |
Webリソースまたはプロバイダについては,「17. Webリソースとプロバイダ」の各項目を参照してください。
javax.ws.rs.QueryParamアノテーションはURIクエリパラメタの値を取得するために使用します。アノテーションの値は,HTTPリクエストに含まれるクエリパラメタの名称を指定します。
javax.ws.rs.QueryParamアノテーションを指定できる対象を,次の表に示します。
表24-6 javax.ws.rs.QueryParamを指定できる対象
Webリソースまたはプロバイダ | コンストラクタのパラメタ | フィールド | beanプロパティ | メソッドのパラメタ |
---|---|---|---|---|
アプリケーションサブクラス | × | × | × | - |
ルートリソースクラス | ○ | ○ | ○ | ○ |
サブリソースクラス | × | × | × | ○ |
エンティティプロバイダ | × | × | × | - |
コンテキストプロバイダ | × | × | × | - |
例外マッピングプロバイダ | × | × | × | - |
Webリソースまたはプロバイダについては,「17. Webリソースとプロバイダ」の各項目を参照してください。
javax.ws.rs.PathParamアノテーションはURIのパスの値を取得するために使用します。アノテーションの値には,テンプレートパラメタを指定します。
javax.ws.rs.PathParamアノテーションを指定できる対象を,次の表に示します。
表24-7 javax.ws.rs.PathParamアノテーションを指定できる対象
Webリソースまたはプロバイダ | コンストラクタのパラメタ | フィールド | beanプロパティ | メソッドのパラメタ |
---|---|---|---|---|
アプリケーションサブクラス | × | × | × | - |
ルートリソースクラス | ○ | ○ | ○ | ○ |
サブリソースクラス | × | × | × | ○ |
エンティティプロバイダ | × | × | × | - |
コンテキストプロバイダ | × | × | × | - |
例外マッピングプロバイダ | × | × | × | - |
Webリソースまたはプロバイダについては,「17. Webリソースとプロバイダ」の各項目を参照してください。
javax.ws.rs.FormParamアノテーションは,HTTPリクエストのエンティティボディに含まれるフォームパラメタの値を取得するために使用します。アノテーションの値はフォームパラメタの名称を指定します。
javax.ws.rs.FormParamアノテーションを指定できる対象を,次の表に示します。
表24-8 javax.ws.rs.FormParamアノテーションを指定できる対象
Webリソースまたはプロバイダ | コンストラクタのパラメタ | フィールド | beanプロパティ | メソッドのパラメタ |
---|---|---|---|---|
ルートリソースクラス | ○ | ○ | ○ | ○ |
サブリソースクラス | × | × | × | ○ |
例外マッピングプロバイダ | × | × | × | - |
Webリソースまたはプロバイダについては,「17. Webリソースとプロバイダ」の各項目を参照してください。
エンティティボディに含まれるフォームパラメタ数の上限値は,デフォルトでは10,000です。リクエストのパラメタ数が指定した値を超えた場合,エラーとなり(KDJJ10042-E),HTTPステータスコードに413を設定した,例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。必要に応じてJ2EEサーバ用ユーザプロパティファイル(usrconf.properties)のwebserver.connector.limit.max_parameter_countプロパティで変更してください。J2EEサーバ用ユーザプロパティファイルについては,マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「2.4 usrconf.properties(J2EEサーバ用ユーザプロパティファイル)」を参照してください。
javax.ws.rs.Contextアノテーションはコンテキストの値をインジェクトするために使用します。javax.ws.rs.Contextアノテーションを指定できる対象を,次の表に示します。
表24-9 javax.ws.rs.Contextアノテーションを指定できる対象(1)
Webリソースまたはプロバイダ | Context Application型 | Context UriInfo型 | Context HttpHeaders型 | Context Request型 | Context SecurityContext型 | Context Providers型 | |
---|---|---|---|---|---|---|---|
ルートリソースクラス | コンストラクタのパラメタ | × | ○ | ○ | ○ | ○ | ○ |
フィールド | × | ○ | ○ | ○ | ○ | ○ | |
beanプロパティ | × | ○ | ○ | ○ | ○ | ○ | |
メソッドのパラメタ | × | ○ | ○ | ○ | ○ | ○ | |
サブリソースクラス | コンストラクタのパラメタ | × | × | × | × | × | × |
フィールド | × | × | × | × | × | × | |
beanプロパティ | × | × | × | × | × | × | |
メソッドのパラメタ | × | ○ | ○ | ○ | ○ | ○ | |
例外マッピングプロバイダ | コンストラクタのパラメタ | × | × | × | × | × | ○ |
フィールド | × | ○ | ○ | ○ | ○ | ○ | |
beanプロパティ | × | ○ | ○ | ○ | ○ | ○ |
表24-10 javax.ws.rs.Contextアノテーションを指定できる対象(2)
Webリソースまたはプロバイダ | Context HttpServletRequest型 | HttpServletResponse型 | ServletContext型 | ServletConfig型 | |
---|---|---|---|---|---|
ルートリソースクラス | コンストラクタのパラメタ | ○※ | ○ | ○ | ○ |
フィールド | ○※ | ○ | ○ | ○ | |
beanプロパティ | ○※ | ○ | ○ | ○ | |
メソッドのパラメタ | ○※ | ○ | ○ | ○ | |
サブリソースクラス | コンストラクタのパラメタ | × | × | × | × |
フィールド | × | × | × | × | |
beanプロパティ | × | × | × | × | |
メソッドのパラメタ | ○※ | ○ | ○ | ○ | |
例外マッピングプロバイダ | コンストラクタのパラメタ | ○※ | ○ | ○ | ○ |
フィールド | ○※ | ○ | ○ | ○ | |
beanプロパティ | ○※ | ○ | ○ | ○ |
javax.ws.rs.DefaultValueアノテーションは,次に示すアノテーションと組み合わせて使用できます。javax.ws.rs.DefaultValueアノテーションを使用すると,それぞれのアノテーションでアノテートされたパラメタにインジェクトする値が,HTTPリクエストにない場合のデフォルト値を指定できます。
例えば,インスタンスに対してクエリもしくはマトリクスパラメタがURIの要求に存在しないとき,または対象のフォームパラメタが要求のエンティティボディに存在しないときは,DefaultValueアノテーションに指定されている初期値が使用されます。
javax.ws.rs.Encodedアノテーションは,URLエンコードされた値が自動でURLデコードされるのを無効化するために使用します。URLエンコードされた値が自動でURLデコードされるのは,次に示すインジェクション用アノテーションでアノテートされたパラメタ,フィールド,およびbeanプロパティです。
javax.ws.rs.Encodedアノテーションは,次に示す場所で使用できます。
パラメタレベル,フィールドレベル,プロパティレベルでは,前述のインジェクション用アノテーション(javax.ws.rs.MatrixParam,javax.ws.rs.QueryParam,javax.ws.rs.PathParam)と組み合わせて使用してください。
クラスレベルでjavax.ws.rs.Encodedアノテーションを使用した場合は,そのクラスのすべてのパラメタ,フィールド,およびbeanプロパティで,URLエンコードされた値が自動でURLデコードされるのを無効化できます。
コンストラクタレベルでjavax.ws.rs.Encodedアノテーションを使用した場合は,そのコンストラクタのすべてのパラメタで,URLエンコードされた値が自動でURLデコードされるのを無効化できます。
メソッドレベルでjavax.ws.rs.Encodedアノテーションを使用した場合は,そのリソースメソッド,サブリソースメソッド,またはサブリソースロケータのすべてのパラメタで,URLエンコードされた値が自動でURLデコードされるのを無効化できます。