49.3. クライアント呼び出しのビルド

WebTarget ビルダークラスを使用してターゲット URI を構築した後、次の手順では HTTP ヘッダーやクッキーなどの他のものを設定します。これは、Invocation.Builder クラスを使用します。呼び出しの構築における最後のステップは、適切な HTTP 動詞 (GET、POST、PUT、または DELETE) を呼び出して、必要に応じてメッセージボディーを指定します。

javax.ws.rs.client.Invocation.Builder ビルダークラスは、Fluent API の一部を提供し、HTTP メッセージの内容を構築し、HTTP メソッドを呼び出すことができます。

Invocation.Builder インスタンスを作成するには、javax.ws.rs.client.WebTarget インスタンス上で request メソッドのいずれかを呼び出します。以下に例を示します。

// Java
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.client.Invocation.Builder;
...
WebTarget books = client.target("http://example.org/bookstore/books/123");
Invocation.Builder invbuilder = books.request();

以下のように、header メソッドを使用してリクエストメッセージに HTTP ヘッダーを追加できます。

Invocation.Builder invheader = invbuilder.header("From", "fionn@example.org");

以下のように、cookie メソッドを使用してクッキーをリクエストメッセージに追加できます。

Invocation.Builder invcookie = invbuilder.cookie("myrestclient", "123xyz");

以下のように、プロパティーメソッドを使用して、このリクエストのコンテキストでプロパティーを設定できます。

Invocation.Builder invproperty = invbuilder.property("Name", "Value");

以下のように、受け入れられるメディアタイプ、言語、またはエンコードを定義できます。

Invocation.Builder invmedia = invbuilder.accept("application/xml")
                                        .acceptLanguage("en-US")
                                        .acceptEncoding("gzip");

REST 呼び出しを構築するプロセスは、HTTP 呼び出しを実行する HTTP メソッドを呼び出して終了します。以下のメソッド (javax.ws.rs.client.SyncInvoker ベースクラスから継承) を呼び出すことができます。

get
post
delete
put
head
trace
options

呼び出す特定の HTTP 動詞がこのリストにない場合は、汎用 method メソッドを使用して HTTP メソッドを呼び出すことができます。

すべての HTTP 呼び出しメソッドには、型なしのバリアントと型付きバリアント (追加の引数を取る) が用意されています。デフォルトの get() メソッド (引数を取らない) を使用してリクエストを呼び出すと、javax.ws.rs.core.Response オブジェクトがその呼び出しから返されます。以下に例を示します。

Response res = client.target("http://example.org/bookstore/books/123")
                     .request("application/xml").get();

ただし、get(Class<T>) メソッドを使用して、レスポンスを特定の型として返すように要求することもできます。たとえば、リクエストを呼び出して、BookInfo オブジェクトとしてレスポンスを返すように要求するには、次のようにします。

BookInfo res = client.target("http://example.org/bookstore/books/123")
                     .request("application/xml").get(BookInfo.class);

ただし、これを機能させるには、application/xml レスポンス形式をマッピングできる Client インスタンスで、適切なエンティティープロバイダー をリクエストされた型に登録する必要があります。エンティティープロバイダーの詳細は、「要求と応答の解析」 を参照してください。

HTTP メソッド (POST または PUT など) の要求にメッセージボディーが含まれる場合に、そのメッセージボディーをメソッドの最初の引数として指定する必要があります。メッセージボディーは javax.ws.rs.client.Entity オブジェクトとして指定する必要があります。ここで、Entity はメッセージの内容とそれに関連するメディア型をカプセル化します。たとえば、メッセージの内容が String 型として提供される POST メソッドを呼び出すには、以下のようにします。

import javax.ws.rs.client.Entity;
...
Response res = client.target("http://example.org/bookstore/registerbook")
                     .request("application/xml")
                     .put(Entity.entity("Red Hat Install Guide", "text/plain"));

必要に応じて、Entity.entity() コンストラクターメソッドが、登録済みエンティティープロバイダーを使用して、提供されたメッセージインスタンスを自動的に指定のメディア型にマップします。メッセージボディーは、常に単純な String 型として指定できます。

すぐに HTTP リクエストを呼び出す代わりに (get() メソッドを呼び出すなど)、後で呼び出すことのできる javax.ws.rs.client.Invocation オブジェクトを作成するオプションがあります。Invocation オブジェクトは、HTTP メソッドを含む、保留中の呼び出しの詳細を すべて カプセル化します。

以下のメソッドは、Invocation オブジェクトの構築に使用できます。

buildGet
buildPost
buildDelete
buildPut
build

たとえば、GET Invocation オブジェクトを作成し、後で呼び出すには、以下のようなコードを使用することができます。

import javax.ws.rs.client.Invocation;
import javax.ws.rs.core.Response;
...
Invocation getBookInfo = client.target("http://example.org/bookstore/books/123")
                     .request("application/xml").buildGet();
...
// Later on, in some other part of the application:
Response = getBookInfo.invoke();

JAX-RS 2.0 クライアント API は、クライアント側での非同期呼び出しをサポートします。非同期呼び出しを行うには、request() の後のメソッドのチェーンで async() メソッドを呼び出します。以下に例を示します。

Future<Response> res = client.target("http://example.org/bookstore/books/123")
                     .request("application/xml")
                     .async()
                     .get();

非同期呼び出しを行うと、戻り値は java.util.concurrent.Future オブジェクトになります。非同期呼び出しの詳細は、「クライアントの非同期処理」 を参照してください。