Menu Close

49.3. クライアント呼び出しの構築

概要

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

invocation.Builder クラス

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();

HTTP ヘッダーの定義

以下のように、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");

HTTP メソッドの呼び出し

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 インスタンスで、適切なエンティティープロバイダー をリクエストされた型に登録する必要があります。エンティティープロバイダーの詳細は 「リクエストとレスポンスの解析」 を参照してください。

post または put での送信メッセージの指定

リクエストにメッセージボディーを含む 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 オブジェクトになります。非同期呼び出しの詳細は、「クライアントでの非同期処理」 を参照してください。