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メディアタイプの組み合わせ
(2) エンティティパラメタに関する注意事項

(1) エンティティパラメタに使用できるJavaの型とMIMEメディアタイプの組み合わせ

エンティティパラメタに使用できるJavaの型とMIMEメディアタイプの組み合わせを次の表に示します。なお,POJOにJAXB仕様のアノテーションは使用しないでください。使用した場合,説明とは異なる動作になるおそれがあります。

表17-5 エンティティパラメタに使用できるJavaの型とMIMEメディアタイプの組み合わせ

項番Javaの型charset※1MIMEメディアタイプ
1byte[]×任意(*/*)
2java.lang.String任意(*/*)
3java.io.InputStream×任意(*/*)
4java.io.Reader任意(*/*)
5java.io.File※2任意(*/*)
6javax.activation.DataSource任意(*/*)
7javax.xml.transform.Source※3×text/xml,
application/xml,
application/*+xml
8javax.xml.bind.JAXBElement<String>※4×text/xml,
application/xml,
application/*+xml
9XmlRootElementアノテーションおよび/またはXmlTypeアノテーションでアノテートされたJAXBクラス※4×text/xml,
application/xml,
application/*+xml
10javax.ws.rs.core.MultivaluedMap<String,String>application/x-www-form-urlencoded
11org.w3c.dom.Document×text/xml,
application/xml,
application/*+xml
12java.util.List<T>※5×text/xml,
application/xml,
application/*+xml
13java.awt.image.RenderedImage×application/octet-stream,
image/jpeg
14com.cosminexus.jersey.core.provider.EntityHolder<T>※6Tに指定した型と同じMIMEメディアタイプです。
15POJO※7application/json
(凡例)
任意(*/*):すべてのMIMEメディアタイプをサポートしていることを示します。
注※1
Content-Type HTTPヘッダにcharsetパラメタが含まれる場合,エンティティパラメタにインジェクトされるときにその情報が考慮されるかどうかを示します。
○:考慮されます。Content-Type HTTPヘッダにcharsetパラメタが含まれない場合は,UTF-8が仮定されます。
△:Tに指定した型に依存します。
×:考慮されません。
なお,Consumesアノテーションの値にcharsetパラメタが含まれていても無視されます。
注※2
JAX-RSエンジンは,J2EEサーバの環境にtempディレクトリを作成し,一時ファイルを保存します。J2EEサーバの環境はcjsetupコマンドを使用して構築します。cjsetupコマンドについては,マニュアル「アプリケーションサーバ リファレンス コマンド編」の「cjsetup(J2EEサーバのセットアップとアンセットアップ)」を参照してください。
注※3
次に示す実装クラスを使用できます。
・javax.xml.transform.stream.StreamSource
・javax.xml.transform.sax.SAXSource
・javax.xml.transform.dom.DOMSource
注※4
MIMEメディアタイプがapplication/fastinfosetまたはapplication/jsonの場合,エラーにならないで正常終了します。
注※5
TにはXmlRootElementアノテーションおよび/またはXmlTypeアノテーションでアノテートされたJAXBクラスを指定できます。
注※6
Tにはこの表の項番2から項番13,および項番15の型を指定できます。
注※7
JSON POJOマッピングを有効にしてください。JSON POJOマッピングが有効でない場合の動作は,サポートされないJava型がエンティティパラメタに指定された場合の動作と同じです。JSON POJOマッピングを有効にする方法については「18. JSON POJOマッピング」を参照してください。

(2) エンティティパラメタに関する注意事項

エンティティパラメタに関するそのほかの注意事項は次のとおりです。

エンティティパラメタへの変換で例外が発生した場合の動作について
エンティティパラメタへの変換で例外が発生した場合,エラーとなります。例外の処理については「17.1.8 例外ハンドリング」を参照してください。
エンティティパラメタの型がサポートされないJavaの型の場合,またはHTTPリクエストのエンティティボディが使用できないMIMEメディアタイプの場合の動作について
次に示すJavaの型のエンティティパラメタでは,HTTPリクエストのエンティティボディが使用できないMIMEメディアタイプの場合,エラーとなり(KDJJ10024-E),HTTPステータスコードに415が設定された,例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。
  1. javax.xml.bind.JAXBElement<String>
  2. XmlRootElementアノテーションおよび/またはXmlTypeアノテーションでアノテートされたJAXBクラス
  3. javax.ws.rs.core.MultivaluedMap<String,String>
  4. java.util.List<T>
  5. 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.4 usrconf.properties(J2EEサーバ用ユーザプロパティファイル)」を参照してください。
エンティティパラメタの型がPOJOの場合は,次の注意事項があります。
  • JSON POJOマッピングが有効になっていない場合,エラーとなり(KDJJ10024-E),HTTPステータスコードに415を設定した,例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。JSON POJOマッピングを有効にする方法については「18. JSON POJOマッピング」を参照してください。