Menu Close

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

概要

JAX-RS 2.0 は、REST 呼び出しまたは HTTP クライアント呼び出しを実行できるフル機能のクライアント API を定義します。これには、Fluent API (リクエストの構築を簡素化)、メッセージを解析するためのフレームワーク (エンティティープロバイダーと呼ばれるプラグインのタイプに基づく)、クライアント側での非同期呼び出しのサポートが含まれます。

49.1. JAX-RS 2.0 クライアント API の概要

概要

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

注記

Blueprint XML または Spring XML で JAX-RS クライアントを定義することもできます (jaxrs:client 要素を使用)。この方法の詳細は、「JAX-RS クライアントエンドポイントの設定」 を参照してください。

依存関係

アプリケーションで 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>

クライアント API パッケージ

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

Fluent API

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

REST 呼び出しを行う手順

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

  1. クライアントをブートストラップします。
  2. ターゲットを設定します。
  3. 呼び出しをビルドし、実行します。
  4. レスポンスを解析します。

クライアントのブートストラップ

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