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

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

WebApplicationException 例外を作成する最も簡単な方法は、引数のないコンストラクターを使用するか、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「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.");