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
オブジェクトになります。非同期呼び出しの詳細は、「クライアントの非同期処理」 を参照してください。