17.1.2 エンティティパラメタ
リソースメソッドのパラメタのうち,アノテーションでアノテートされていないパラメタをエンティティパラメタと呼びます。エンティティパラメタの値は,HTTPエンティティボディです。
リソースメソッドでエンティティパラメタを使用する例を次に示します。
@POST public String getRequestParameters(@MatrixParam("matrix") String matrix, String entity) { return "Matrix is:" + matrix + "\mEntity Body is: " + entity; }
この例では,リソースメソッドgetRequestParameters()は,MatrixParamアノテーションでアノテートされたパラメタmatrixと,アノテートされていないパラメタ(エンティティパラメタ)entityを持っています。エンティティボディの内容が"Entity Content"であるHTTPリクエストを受信した場合,エンティティパラメタentityの値は"Entity Content"になります。
(1) エンティティパラメタに使用できるJavaの型とMIMEメディアタイプの組み合わせ
エンティティパラメタに使用できるJavaの型とMIMEメディアタイプの組み合わせを次の表に示します。なお,POJOにJAXB仕様のアノテーションは使用しないでください。使用した場合,説明とは異なる動作になるおそれがあります。
項番 |
Javaの型 |
charset※1 |
MIMEメディアタイプ |
---|---|---|---|
1 |
byte[] |
× |
任意(*/*) |
2 |
java.lang.String |
○ |
任意(*/*) |
3 |
java.io.InputStream |
× |
任意(*/*) |
4 |
java.io.Reader |
○ |
任意(*/*) |
5 |
java.io.File※2 |
○ |
任意(*/*) |
6 |
javax.activation.DataSource |
○ |
任意(*/*) |
7 |
javax.xml.transform.Source※3 |
× |
text/xml, application/xml, application/*+xml |
8 |
javax.xml.bind.JAXBElement<String>※4 |
× |
text/xml, application/xml, application/*+xml |
9 |
XmlRootElementアノテーションおよび/またはXmlTypeアノテーションでアノテートされたJAXBクラス※4 |
× |
text/xml, application/xml, application/*+xml |
10 |
javax.ws.rs.core.MultivaluedMap<String,String> |
○ |
application/x-www-form-urlencoded |
11 |
org.w3c.dom.Document |
× |
text/xml, application/xml, application/*+xml |
12 |
java.util.List<T>※5 |
× |
text/xml, application/xml, application/*+xml |
13 |
java.awt.image.RenderedImage |
× |
application/octet-stream, image/jpeg |
14 |
com.cosminexus.jersey.core.provider.EntityHolder<T>※6 |
△ |
Tに指定した型と同じMIMEメディアタイプです。 |
15 |
POJO※7 |
○ |
application/json |
(2) エンティティパラメタに関する注意事項
エンティティパラメタに関するそのほかの注意事項は次のとおりです。
- エンティティパラメタへの変換で例外が発生した場合の動作について
-
エンティティパラメタへの変換で例外が発生した場合,エラーとなります。例外の処理については「17.1.8 例外ハンドリング」を参照してください。
- エンティティパラメタの型がサポートされないJavaの型の場合,またはHTTPリクエストのエンティティボディが使用できないMIMEメディアタイプの場合の動作について
-
次に示すJavaの型のエンティティパラメタでは,HTTPリクエストのエンティティボディが使用できないMIMEメディアタイプの場合,エラーとなり(KDJJ10024-E),HTTPステータスコードに415が設定された,例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。
-
javax.xml.bind.JAXBElement<String>
-
XmlRootElementアノテーションおよび/またはXmlTypeアノテーションでアノテートされたJAXBクラス
-
javax.ws.rs.core.MultivaluedMap<String,String>
-
java.util.List<T>
-
POJO
ただし,1.または2.でHTTPリクエストのエンティティボディのMIMEメディアタイプがapplication/fastinfosetまたはapplication/jsonのときは,エラーにならないで正常終了します。
java.awt.image.RenderedImageのエンティティパラメタでは,HTTPリクエストのエンティティボディのMIMEメディアタイプがimage/*の場合,例外マッピングプロバイダで処理できるjava.io.IOExceptionがスローされます。
-
com.cosminexus.jersey.core.provider.EntityHolder<T>のエンティティパラメタでは,HTTPリクエストにエンティティボディがある場合,次に示すどちらかのときにエラーとなり(KDJJ10003-E),HTTPステータスコードに500が設定された,例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。
・Tがサポートされない型(表の項番1および項番14)のとき
・Tがサポートされる型(表の項番2から項番13まで)だが,HTTPリクエストのエンティティボディが使用できないMIMEメディアタイプのとき
-
エンティティパラメタの型がサポートされないJavaの型を使用した場合,エラーとなり(KDJJ10024-E),HTTPステータスコードに次の値が設定された,例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。
400:エンティティパラメタの型がjava.lang.Objectで,HTTPリクエストのエンティティボディのMIMEメディアタイプがapplication/xml,text/xml,またはapplication/*+xmlのとき
415:エンティティパラメタの型がjava.lang.Object以外の場合,またはエンティティパラメタの型がjava.lang.Objectで,HTTPリクエストのエンティティボディのMIMEメディアタイプがapplication/xml,text/xml,application/*+xmlのどれでもない場合
ただし,エンティティパラメタの型がjavax.mail.internet.MimeMultipartで,HTTPリクエストのエンティティボディのMIMEメディアタイプがmultipart/*のときは,エラーにならないで正常終了します。
-
- リソースメソッドで使用できるエンティティパラメタの数について
-
リソースメソッドで使用できるエンティティパラメタは一つだけです。リソースメソッドが複数のエンティティパラメタを持つ場合,警告メッセージがログに出力されます(KDJJ20012-W)。HTTPリクエストのエンティティボディは最初のエンティティパラメタだけにインジェクトされ,二つ目以降のエンティティパラメタの状態は保証されません。
- GET要求メソッド識別子を持つリソースメソッドについて
-
GET要求メソッド識別子を持つリソースメソッドがエンティティパラメタを持つ場合,警告メッセージまたはエラーメッセージがログに出力されます(KDJJ20003-WまたはKDJJ10006-E)。KDJJ20003-WおよびKDJJ10006-Eについては,「13.7.1 Webリソース初期化時の構文チェック(KDJJ20003-WとKDJJ10006-E)」を参照してください。
- 注意
-
EncodedアノテーションおよびDefaultValueアノテーションがエンティティパラメタにアノテートされている場合,無視されます。
- エンティティパラメタの型パラメタが解決できない場合のメッセージの出力について
-
エンティティパラメタの型パラメタが解決できない場合は,警告メッセージまたはエラーメッセージがログに出力されます(KDJJ10006-EまたはKDJJ20003-W)。KDJJ20003-WとKDJJ10006-Eについては,「13.7.1 Webリソース初期化時の構文チェック(KDJJ20003-WとKDJJ10006-E)」を参照してください。
- エンティティパラメタに特定の型が指定された場合の注意
-
エンティティパラメタの型がjavax.ws.rs.core.MultivaluedMap<String,String>,またはcom.cosminexus.jersey.core.provider.EntityHolder<javax.ws.rs.core.MultivaluedMap<String,String>>の場合,次の注意事項があります。
-
エンティティボディがJAX-RS機能のサーブレットやサーブレットフィルタ以外からすでにアクセスされている場合,警告メッセージがログに出力されます(KDJJ20007-W)。
このとき,エンティティパラメタの状態は不定です。エンティティボディに含まれるフォームパラメタは,FormParamアノテーションでアノテートされたパラメタから参照してください。
-
エンティティボディに含まれるフォームパラメタ数の上限値は,デフォルトでは10,000です。
リクエストのパラメタ数が指定した値を超えた場合,エラーとなり(KDJJ10042-E),HTTPステータスコードに413を設定した,例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。必要に応じてJ2EEサーバ用ユーザプロパティファイル(usrconf.properties)のwebserver.connector.limit.max_parameter_countプロパティで変更してください。
J2EEサーバ用ユーザプロパティファイルについては,マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「2.2.3 usrconf.properties(J2EEサーバ用ユーザプロパティファイル)」を参照してください。
エンティティパラメタの型がPOJOの場合は,次の注意事項があります。
-
JSON POJOマッピングが有効になっていない場合,エラーとなり(KDJJ10024-E),HTTPステータスコードに415を設定した,例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。JSON POJOマッピングを有効にする方法については「18. JSON POJOマッピング」を参照してください。
-