17.1.2　エンティティパラメタ

@POST
public String getRequestParameters(@MatrixParam("matrix") String matrix,
    String entity) {
  return "Matrix is:" + matrix + "\mEntity Body is: " + entity;
}

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

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

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

項番	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がスローされます。

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

エンティティパラメタの型がPOJOの場合は，次の注意事項があります。

• JSON POJOマッピングが有効になっていない場合，エラーとなり（KDJJ10024-E），HTTPステータスコードに415を設定した，例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。JSON POJOマッピングを有効にする方法については「18.　JSON POJOマッピング」を参照してください。

ページの先頭へ