50.2. WebApplicationException 例外を使用したレポート

JAX-RS API には WebApplicationException ランタイム例外が導入され、リソースメソッドが RESTful クライアントが消費するのに適した例外を簡単に作成できるようになりました。WebApplicationException 例外には、リクエスト元に返されるエンティティーボディーを定義する Response オブジェクトを含めることができます。また、エンティティーボディーが指定されていない場合に、クライアントに HTTP ステータスコードを指定するメカニズムも提供します。

WebApplicationException 例外を作成する最も簡単な方法として、no の引数コンストラクターまたは WebApplicationException 例外で元の例外をラップするコンストラクターのいずれかを使用します。どちらのコンストラクターも、空の応答で WebApplicationException を作成します。

これらのコンストラクターのいずれかによって作成された例外が出力されると、ランタイムはエンティティーボディーが空でステータスコードが 500 Server Error のレスポンスを返します。

500 以外のエラーコードを返す場合は、ステータスを指定できるようにする 4 つの WebApplicationException コンストラクターのいずれかを使用できます。例50.1「ステータスコードでの WebApplicationException の作成」 に示されているこれらのコンストラクターの 2 つを整数として返します。

例50.2「ステータスコードでの WebApplicationException の作成」 に記載されている他の 2 つは、レスポンスステータスを Response.Status のインスタンスとしてし取ります。

これらのコンストラクターのいずれかによって作成された例外が出力されると、ランタイムはエンティティーボディーが空で指定したステータスコードがレスポンスを返します。

例外とともにメッセージを送信する場合は、Response オブジェクトを取る WebApplicationException コンストラクターのいずれかを使用することができます。ランタイムは、Response オブジェクトを使用してクライアントに送信される応答を作成します。応答に保存されているエンティティーはメッセージのエンティティーボディーに、応答のステータスフィールドはメッセージの HTTP ステータスにマップされます。

例50.3「例外を含めたメッセージの送信」 は、例外の理由を含むテキストメッセージをクライアントに返すコードを示しています。HTTP メッセージのステータスは 409 Conflict に設定されます。

import javax.ws.rs.core.Response;
import javax.ws.rs.WebApplicationException;
import org.apache.cxf.jaxrs.impl.ResponseBuilderImpl;

...
ResponseBuilderImpl builder = new ResponseBuilderImpl();
builder.status(Response.Status.CONFLICT);
builder.entity("The requested resource is conflicted.");
Response response = builder.build();
throw WebApplicationException(response);

WebApplicationException 例外を拡張できます。これにより、カスタム例外を作成して、一部のボイラープレートコードを削除できるようになります。

例50.4「Extending WebApplicationException」 では、例50.3「例外を含めたメッセージの送信」 にコードと同様の応答を作成する新しい例外を紹介しています。

public class ConflicteddException extends WebApplicationException
{
  public ConflictedException(String message)
  {
    ResponseBuilderImpl builder = new ResponseBuilderImpl();
    builder.status(Response.Status.CONFLICT);
    builder.entity(message);
    super(builder.build());
     }
}

...
throw ConflictedException("The requested resource is conflicted.");