第49章 JAX-RS 2.0 クライアント API

JAX-RS 2.0 は JAX-RS クライアントの Fluent API を定義します。これにより、HTTP リクエストを段階的に構築し、適切な HTTP 動詞 (GET、POST、PUT、または DELETE) を使用してリクエストを呼び出すことができます。

アプリケーションで JAX-RS 2.0 クライアント API を使用するには、以下の Maven 依存関係をプロジェクトの pom.xml ファイルに追加する必要があります。

<dependency>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-rt-rs-client</artifactId>
  <version>3.3.6.fuse-790049-redhat-00001</version>
</dependency>

非同期呼び出し機能 (「クライアントでの非同期処理」 を参照) を使用する場合は、以下の Maven 依存関係も必要です。

<dependency>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-rt-transports-http-hc</artifactId>
  <version>3.3.6.fuse-790049-redhat-00001</version>
</dependency>

JAX-RS 2.0 クライアントインターフェースおよびクラスは以下の Java パッケージにあります。

javax.ws.rs.client

JAX-RS 2.0 Java クライアントを開発する場合、通常はコアパッケージからクラスにアクセスする必要があります。

javax.ws.rs.core

次のコードフラグメントは、JAX-RS 2.0 クライアント API を使用して http://example.org/bookstore JAX-RS サービスで呼び出しを行い、GET HTTP メソッドで呼び出す簡単な例を示しています。

// Java
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Client;
import javax.ws.rs.core.Response;
...
Client client = ClientBuilder.newClient();
Response res = client.target("http://example.org/bookstore/books/123")
    .request("application/xml").get();

JAX-RS 2.0 クライアント API は Fluent API (ドメイン固有言語として呼ばれることもある) として設計されています。Fluent API では、Java メソッドのチェーンは単一のステートメントで呼び出され、Javaメソッドが単純な言語のコマンドのように見えます。JAX-RS 2.0 では、Fluent API は REST リクエストをビルドし、呼び出すために使用されます。

JAX-RS 2.0 クライアント API を使用すると、以下のようにクライアント呼び出しがビルドされ、一連のステップで呼び出されます。

最初のステップでは、javax.ws.rs.client.Client オブジェクトを作成し、クライアントをブートストラップします。この Client インスタンスは比較的重いオブジェクトで、JAX-RS クライアント (場合によってはインターセプターや追加の CXF 機能を含む) をサポートするために必要なテクノロジーのスタックを表します。理想的には、新しいオブジェクトを作成する代わりに、利用可能な場合はクライアントオブジェクトを再使用する必要があります。

新しい Client オブジェクトを作成するには、以下のように ClientBuilder クラスで静的メソッドを呼び出します。

// Java
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Client;
...
Client client = ClientBuilder.newClient();
...

ターゲットを設定することで、REST 呼び出しに使用される URI を効果的に定義します。次の例は、path(String) メソッドを使用して、ベース URI base を定義し、ベース URI にパスセグメントを追加する方法を示しています。

// Java
import javax.ws.rs.client.WebTarget;
...
WebTarget base = client.target("http://example.org/bookstore/");
WebTarget books = base.path("books").path("{id}");
...

これは実際には 2 つのステップを 1 つにまとめたものです。まず、HTTPリクエスト (ヘッダー、受け入れられたメディアタイプなど) を構築し、次に、関連する HTTP メソッドを呼び出します (必要に応じて、リクエストメッセージボディーを提供します)。

たとえば、application/xml メディア型を受け入れるリクエストを作成および呼び出すには、以下を実行します。

// Java
import javax.ws.rs.core.Response;
...
Response resp = books.resolveTemplate("id", "123").request("application/xml").get();

最後に、前のステップで取得したレスポンス resp を解析する必要があります。通常、レスポンスは javax.ws.rs.core.Response オブジェクトの形式で返されます。これは、HTTP ヘッダーと、他の HTTP メタデータおよび HTTP メッセージボディー (ある場合) ををカプセル化します。

String 形式で返された HTTP メッセージにアクセスする場合、以下のように String.class 引数を指定して readEntity メソッドを呼び出して、簡単にアクセスできます。

// Java
...
String msg = resp.readEntity(String.class);

String.class を readEntity の引数として指定すると、レスポンスのメッセージボディーに String として常にアクセスできます。メッセージボディーのより一般的な変換については、変換を実行するエンティティプロバイダーを提供できます。詳細は 「リクエストとレスポンスの解析」 を参照してください。