24.3.1 インジェクション用アノテーション

ここでは,JAX-RSエンジンがサポートするインジェクション用アノテーションについて説明します。

<この項の構成>
(1) 注意事項
(2) javax.ws.rs.HeaderParamアノテーション
(3) javax.ws.rs.CookieParamアノテーション
(4) javax.ws.rs.MatrixParamアノテーション
(5) javax.ws.rs.QueryParamアノテーション
(6) javax.ws.rs.PathParamアノテーション
(7) javax.ws.rs.FormParamアノテーション
(8) javax.ws.rs.core.Contextアノテーション
(9) javax.ws.rs.DefaultValueアノテーション
(10) javax.ws.rs.Encodedアノテーション

(1) 注意事項

(a) 複数のアノテーションを使用する場合

インジェクション用アノテーションは,パラメタ,フィールド,またはbeanプロパティそれぞれにつき一つだけ使用できます。一つのパラメタ,フィールド,またはbeanプロパティにつき複数のアノテーションを同時に指定した場合は,最も右のアノテーションだけが有効になります。最も右のアノテーションがJAX-RS 1.1仕様でない場合は,ほかのすべてのアノテーションが無視されてインジェクションは実行されません。

(b) beanプロパティに使用する場合

インジェクション用アノテーションをbeanプロパティに使用する場合は,setterメソッドに対してメソッドレベルでアノテートしてください。

(c) フィールドに使用する場合

ルートリソースクラスおよび例外マッピングプロバイダでは,コンストラクタおよびbeanプロパティのsetterメソッドから,インジェクション用アノテーションでアノテートされたフィールドを参照または変更しないでください。

コンストラクタ,フィールド,およびbeanプロパティへのインジェクションは,ルートリソースクラスおよび例外マッピングプロバイダがJAX-RSエンジンによってインスタンス化されるときに同時に行われます。このため,コンストラクタおよびbeanプロパティのsetterメソッドから,インジェクション用アノテーションでアノテートされたフィールドを参照した場合,取得される値は不定です。また,インジェクション用アノテーションでアノテートされたフィールドを変更した場合,フィールドへのインジェクションが失敗するか,または成功しても値が不定になります。

(2) javax.ws.rs.HeaderParamアノテーション

javax.ws.rs.HeaderParamアノテーションはHTTPヘッダの値を取得するために使用します。アノテーションの値には,HTTPリクエストに含まれるHTTPヘッダの名称を指定します。

javax.ws.rs.HeaderParamアノテーションを指定できる対象を,次の表に示します。

表24-3  javax.ws.rs.HeaderParamアノテーションを指定できる対象

Webリソースまたはプロバイダコンストラクタのパラメタフィールドbeanプロパティメソッドのパラメタ
ルートリソースクラス
サブリソースクラス×××
例外マッピングプロバイダ×××
(凡例)
○:指定できることを示します。
×:指定できないことを示します。
-:該当するパラメタがないことを示します。

Webリソースまたはプロバイダについては,「17. Webリソースとプロバイダ」の各項目を参照してください。

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

javax.ws.rs.CookieParamアノテーションはHTTP Cookieの値を取得するために使用します。アノテーションの値は,HTTPリクエストに含まれるCookieの名称を指定します。

javax.ws.rs.CookieParamアノテーションを指定できる対象を,次の表に示します。

表24-4  javax.ws.rs.CookieParamアノテーションを指定できる対象

Webリソースまたはプロバイダコンストラクタのパラメタフィールドbeanプロパティメソッドのパラメタ
アプリケーションサブクラス×××
ルートリソースクラス
サブリソースクラス×××
エンティティプロバイダ×××
コンテキストプロバイダ×××
例外マッピングプロバイダ×××
(凡例)
○:指定できることを示します。
×:指定できないことを示します。
-:該当するパラメタがないことを示します。

Webリソースまたはプロバイダについては,「17. Webリソースとプロバイダ」の各項目を参照してください。

(4) javax.ws.rs.MatrixParamアノテーション

javax.ws.rs.MatrixParamアノテーションはURIマトリクスパラメタの値を取得するために使用します。アノテーションの値は,HTTPリクエストに含まれるマトリクスパラメタの名称を指定します。

javax.ws.rs.MatrixParamアノテーションを指定できる対象を,次の表に示します。

表24-5  javax.ws.rs.Matrix parameterアノテーションを指定できる対象

Webリソースまたはプロバイダコンストラクタのパラメタフィールドbeanプロパティメソッドのパラメタ
アプリケーションサブクラス×××
ルートリソースクラス
サブリソースクラス×××
エンティティプロバイダ×××
コンテキストプロバイダ×××
例外マッピングプロバイダ×××
(凡例)
○:指定できることを示します。
×:指定できないことを示します。
-:該当するパラメタがないことを示します。

Webリソースまたはプロバイダについては,「17. Webリソースとプロバイダ」の各項目を参照してください。

(5) javax.ws.rs.QueryParamアノテーション

javax.ws.rs.QueryParamアノテーションはURIクエリパラメタの値を取得するために使用します。アノテーションの値は,HTTPリクエストに含まれるクエリパラメタの名称を指定します。

javax.ws.rs.QueryParamアノテーションを指定できる対象を,次の表に示します。

表24-6  javax.ws.rs.QueryParamを指定できる対象

Webリソースまたはプロバイダコンストラクタのパラメタフィールドbeanプロパティメソッドのパラメタ
アプリケーションサブクラス×××
ルートリソースクラス
サブリソースクラス×××
エンティティプロバイダ×××
コンテキストプロバイダ×××
例外マッピングプロバイダ×××
(凡例)
○:指定できることを示します。
×:指定できないことを示します。
-:該当するパラメタがないことを示します。

Webリソースまたはプロバイダについては,「17. Webリソースとプロバイダ」の各項目を参照してください。

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

javax.ws.rs.PathParamアノテーションはURIのパスの値を取得するために使用します。アノテーションの値には,テンプレートパラメタを指定します。

javax.ws.rs.PathParamアノテーションを指定できる対象を,次の表に示します。

表24-7  javax.ws.rs.PathParamアノテーションを指定できる対象

Webリソースまたはプロバイダコンストラクタのパラメタフィールドbeanプロパティメソッドのパラメタ
アプリケーションサブクラス×××
ルートリソースクラス
サブリソースクラス×××
エンティティプロバイダ×××
コンテキストプロバイダ×××
例外マッピングプロバイダ×××
(凡例)
○:指定できることを示します。
×:指定できないことを示します。
-:該当するパラメタがないことを示します。

Webリソースまたはプロバイダについては,「17. Webリソースとプロバイダ」の各項目を参照してください。

(7) javax.ws.rs.FormParamアノテーション

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サーバ用ユーザプロパティファイル)」を参照してください。

(8) javax.ws.rs.core.Contextアノテーション

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プロパティ
(凡例)
○:指定できることを示します。
×:指定できないことを示します。
注※
エンティティボディおよびクエリパラメタは取得できません。エンティティパラメタを持つリソースメソッドで,ContextアノテーションでインジェクトされたHttpServletRequestインスタンスのgetReader()メソッドを呼び出した場合,例外マッピングプロバイダで処理できるjava.lang.IllegalStateExceptionがスローされます。

(9) javax.ws.rs.DefaultValueアノテーション

javax.ws.rs.DefaultValueアノテーションは,次に示すアノテーションと組み合わせて使用できます。javax.ws.rs.DefaultValueアノテーションを使用すると,それぞれのアノテーションでアノテートされたパラメタにインジェクトする値が,HTTPリクエストにない場合のデフォルト値を指定できます。

例えば,インスタンスに対してクエリもしくはマトリクスパラメタがURIの要求に存在しないとき,または対象のフォームパラメタが要求のエンティティボディに存在しないときは,DefaultValueアノテーションに指定されている初期値が使用されます。

(10) javax.ws.rs.Encodedアノテーション

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デコードされるのを無効化できます。