17.1.3 戻り値

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

表17-6 リソースメソッドの戻り値に使用できるJavaの型とMIMEメディアタイプの組み合わせ

項番Javaの型charset※1MIMEメディアタイプ
1byte[]×任意(*/*)
2java.lang.String任意(*/*)
3java.io.InputStream×任意(*/*)
4java.io.Reader任意(*/*)
5java.io.File×任意(*/*)
6javax.activation.DataSource×任意(*/*)
7javax.xml.transform.Source※2×text/xml,
application/xml,
application/*+xml
8javax.xml.bind.JAXBElement<String>※3text/xml,
application/xml,
application/*+xml
9XmlRootElementアノテーションでアノテートされたJAXBクラス※3text/xml,
application/xml,
application/*+xml
10javax.ws.rs.core.MultivaluedMap<String, String>application/x-www-form-urlencoded
11javax.ws.rs.core.StreamingOutput×任意(*/*)
12org.w3c.dom.Document×text/xml,
application/xml,
application/*+xml
13java.util.List<T>※4text/xml,
application/xml,
application/*+xml
14java.awt.image.RenderedImage×image/jpeg
15void任意(*/*)
16javax.ws.rs.core.Response任意(*/*)
17javax.ws.rs.core.GenericEntity<T>※5Tに指定した型と同じMIMEメディアタイプです。
18POJO※6×※7application/json
(凡例)
-:該当しないことを示します。
任意(*/*):すべてのMIMEメディアタイプをサポートしていることを示します。
注※1
Producesアノテーションまたは戻り値にcharsetパラメタが含まれる場合,HTTPレスポンスに変換するときに,その情報がContent-Type HTTPヘッダのcharsetパラメタに反映されるかどうかを示します。
○:反映されます。Producesアノテーションおよび戻り値にcharsetパラメタが含まれない場合はUTF-8が仮定されます。
△:Tに指定した型に依存します。
×:反映されません。
注※2
次に示す実装クラスを使用できます。
・javax.xml.transform.stream.StreamSource
・javax.xml.transform.sax.SAXSource
・javax.xml.transform.dom.DOMSource
注※3
MIMEメディアタイプがapplication/fastinfosetまたはapplication/jsonの場合,エラーにならないで正常終了します。
注※4
TにはXmlRootElementアノテーションでアノテートされたJAXBクラスを指定できます。
注※5
Tにはこの表の項番17以外の型を指定できます。
注※6
JSON POJOマッピングを有効にしてください。JSON POJOマッピングが有効でない場合の動作は,サポートされないJava型がエンティティパラメタに指定された場合の動作と同じです。JSON POJOマッピングを有効にする方法については「18. JSON POJOマッピング」を参照してください。
注※7
Content-Type HTTPヘッダにcharsetパラメタを追加しないでください。

戻り値とHTTPレスポンスの対応を次の表に示します。

表17-7 戻り値とHTTPレスポンスの対応

項番戻り値HTTPレスポンス
HTTPステータスコードエンティティボディ
1void204空のエンティティボディ
2Responsenullではないインスタンス200Responseのエンティティプロパティ
3null204空のエンティティボディ
4Stringnullではないインスタンス200Stringの値
5null204空のエンティティボディ
6void,Response,String以外のサポートしているJavaの型nullではないインスタンス200戻り値のクラスに応じて変換されたエンティティボディ
7null204空のエンティティボディ
(凡例)
-:戻り値の値がないことを示します。

戻り値の型がサポートされないJavaの型の場合,エラーとなり(KDJJ10026-E),HTTPステータスコードに500が設定された,例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。ただし,戻り値の型がjavax.mail.internet.MimeMultipartで,MIMEメディアタイプがmultipart/*のときは,エラーにならないで正常終了します。

HTTPレスポンスのエンティティボディへの変換で例外が発生した場合,エラーとなります。例外の処理については「17.1.8 例外ハンドリング」を参照してください。

戻り値の型が次に示すJavaの型で,HTTPレスポンスのエンティティボディが使用できないMIMEメディアタイプの場合,エラーとなり(KDJJ10026-E),HTTPステータスコードに500が設定された,例外マッピングプロバイダで処理できるjavax.ws.rs.WebApplicationExceptionがスローされます。

  1. javax.xml.bind.JAXBElement<String>
  2. XmlRootElementアノテーションでアノテートされたJAXBクラス
  3. javax.ws.rs.core.MultivaluedMap<String, String>
  4. java.util.List<T>
  5. java.awt.image.RenderedImage

ただし,1.または2.でHTTPリクエストのエンティティボディのMIMEメディアタイプがapplication/fastinfosetまたはapplication/jsonのときは,エラーにならないで正常終了します。

次に示す戻り値の場合,警告メッセージまたはエラーメッセージがログに出力されます(KDJJ20003-WまたはKDJJ10006-E)。KDJJ20003-WとKDJJ10006-Eについては,「13.7.1 Webリソース初期化時の構文チェック(KDJJ20003-WとKDJJ10006-E)」を参照してください。