48.3. アプリケーションの応答の微調整

RESTful サービスでは、リソースメソッドがプレーンな Java コンストラクトを返す場合に、コンシューマーへ返される応答をより正確に制御する必要があります。JAX-RS Response クラスを使用すると、リソースメソッドがコンシューマーに送信される戻り値をある程度制御し、応答に HTTP メッセージヘッダーとクッキーを指定できます。

Response オブジェクトは、コンシューマーに返されるエンティティーを表すオブジェクトをラップします。Response オブジェクトは ResponseBuilder クラスをファクトリーとして使用してインスタンス化されます。

ResponseBuilder クラスには、応答のメタデータを操作するために使用されるメソッドも多数あります。たとえば、ResonseBuilder クラスには、HTTP ヘッダーとキャッシュ制御ディレクティブを設定するメソッドが含まれます。

Response クラスには保護されたコンストラクターがあるため、直接インスタンス化することはできません。これらは、Response クラスによって囲まれた ResponseBuilder クラスを使用して作成されます。ResponseBuilder クラスは、そこから作成された応答にカプセル化されるすべての情報のホルダーです。ResponseBuilder クラスには、メッセージに HTTP ヘッダープロパティーを設定するすべてのメソッドもあります。

Response クラスは、適切な応答コードの設定とエンティティーのラップを容易にするメソッドを提供します。一般的な応答ステータスコードごとにメソッドがあります。エンティティー本体または必要なメタデータを含むステータスに対応するメソッドには、関連する応答ビルダーに、情報を直接設定できるバージョンが含まれています。

ResponseBuilder クラスの build() メソッドは、メソッドが呼び出される際に応答ビルダーに保存されている情報が含まれる応答オブジェクトを返します。応答オブジェクトが返されると、応答ビルダーはクリーンな状態に戻ります。

応答ビルダーを取得する方法は 2 つあります。

Response クラスの詳細は、Response クラスの Javadoc を参照してください。

ResponseBuilder クラスの詳細は、ResponseBuilder クラスの Javadoc を参照してください。

Apache CXF ResponseBuilderIml クラスの詳細は、ResponseBuilderImpl Javadoc を参照してください。

Response クラスは、RESTful サービスが必要とするより一般的な応答を処理するためのショートカットメソッドを提供します。これらのメソッドは、提供された値またはデフォルト値のいずれかを使用して適切なヘッダーの設定を処理します。また、必要に応じてエンティティーボディーの設定を処理します。

要求が正常に処理されると、アプリケーションが応答を送信して、要求が完了したことを確認する必要があります。この応答にはエンティティーが含まれる可能性があります。

応答を正常に完了した場合の最も一般的な応答は OK です。OK 応答には通常、リクエストに対応するエンティティーが含まれます。Response クラスには、応答のステータスを 200 に設定し、指定されたエンティティーを囲まれた応答ビルダーに追加するオーバーロードされた ok() メソッドがあります。ok() メソッドには 5 つのバージョンがあります。最も一般的に使用されるバリアントは以下のとおりです。

200 応答での応答の作成 は、OK ステータスで応答を作成する例を示しています。

import javax.ws.rs.core.Response;
import demo.jaxrs.server.Customer;
...

Customer customer = new Customer("Jane", 12);

return Response.ok(customer).build();

要求元がエンティティーボディーを期待しない場合は、200 OK のステータスではなく 204 No Content ステータスを送信する方が適切な場合があります。Response.noContent() メソッドにより、適切な応答オブジェクトが作成されます。

204 ステータスでの応答の作成 は、204 ステータスで応答を作成する例を示しています。

import javax.ws.rs.core.Response;

return Response.noContent().build();

Response クラスは、3 つのリダイレクト応答ステータスを処理するメソッドを提供します。

304 ステータスでの応答の作成 は、304 ステータスで応答を作成する例を示しています。

import javax.ws.rs.core.Response;

return Response.notModified().build();

Response クラスは、2 つの基本的な処理エラーに対する応答を作成するメソッドを提供します。

500 ステータスでの応答の作成 は、500 ステータスで応答を作成する例を示しています。

import javax.ws.rs.core.Response;

return Response.serverError().build();

Response クラスメソッドは、一般的なケースの応答を作成するためのショートカットを提供します。キャッシュ制御ディレクティブの指定、カスタム HTTP ヘッダーの追加、または Response クラスで処理されていないステータスの送信など、より複雑なケースに対応する必要がある場合は、build() メソッドを使用してレスポンスオブジェクトを生成する前に、ResponseBuilder クラスメソッドを使用してレスポンスを入力する必要があります。

「応答ビルダーの取得」 で説明されているように、Apache CXF ResponseBuilderImpl クラスを使用して直接操作できるレスポンスビルダーインスタンスを作成できます。

カスタムヘッダーは、ResponseBuilder クラスの header() メソッドを使用してレスポンスに追加されます。header() メソッドは、2 つのパラメーターを取ります。

header() メソッドを繰り返し呼び出すと、メッセージに複数のヘッダーを設定することができます。

応答へのヘッダーの追加 は、応答にヘッダーを追加するコードを示します。

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

ResponseBuilderImpl builder = new ResponseBuilderImpl();
builder.header("username", "joe");
Response r = builder.build();

カスタムヘッダーは、ResponseBuilder クラスの cookie() メソッドを使用してレスポンスに追加されます。cookie() メソッドは 1 つ以上のクッキーを取ります。各クッキーは javax.ws.rs.core.NewCookie オブジェクトに保存されます。最も簡単に使用できる NewCookie クラスのコンストラクターは、2 つのパラメーターを取ります。

cookie() メソッドを繰り返し呼び出して、複数のクッキーを設定できます。

応答へのクッキーの追加 は、クッキーを応答に追加するコードを示します。

import javax.ws.rs.core.Response;
import javax.ws.rs.core.NewCookie;

NewCookie cookie = new NewCookie("username", "joe");

Response r = Response.ok().cookie(cookie).build();

Response クラスのヘルパーメソッドでサポートされないステータスを返す場合は、ResponseBuilder クラスの status() メソッドを使用してレスポンスのステータスコードを設定することができます。status() メソッドには 2 つのバリアントがあります。1 つは、レスポンスコードを指定する int を取ります。もう 1 つは Response.Status オブジェクトを取り、応答コードを指定します。

Response.Status クラスは、Response クラスで囲まれた列挙型です。定義されたほとんどの HTTP 応答コードに、エントリーがあります。

応答へのヘッダーの追加 に、応答ステータスを 404 Not Found に設定するコードを示します。

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

ResponseBuilderImpl builder = new ResponseBuilderImpl();
builder.status(404);
Response r = builder.build();

ResponseBuilder クラスの cacheControl() メソッドを使用すると、レスポンスにキャッシュ制御ヘッダーを設定することができます。cacheControl() メソッドは、応答のキャッシュ制御ディレクティブを指定する javax.ws.rs.CacheControl オブジェクトを取ります。

CacheControl クラスには、HTTP 仕様でサポートされるすべてのキャッシュ制御ディレクティブに対応するメソッドがあります。ディレクティブが簡単な on または off の値である場合、setter メソッドは boolean の値を取ります。ディレクティブは max-age ディレクティブなどの数値が必要であるため、setter は int の値を取ります。

応答へのヘッダーの追加 は、no-store キャッシュ制御ディレクティブを設定するコードを表しています。

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

CacheControl cache = new CacheControl();
cache.setNoCache(true);

ResponseBuilderImpl builder = new ResponseBuilderImpl();
builder.cacheControl(cache);
Response r = builder.build();