クライアント API

クライアント API は、Web リソースへのアクセスに使用される Java ベースの API です。この API を使用して実装されたリソースに限定されません。HTTP ベースの通信の既存の確立されたクライアント側実装を活用する再利用可能なクライアント側ソリューションの簡潔で効率的な実装を可能にするために、plain HTTP communication APISE と比較してより高いレベルの抽象化と拡張プロバイダーとの統合を提供します。

クライアント API は、REST アーキテクチャスタイルの主要な制約である Uniform Interface Constraint および関連するデータ要素をクライアント側の Java アーティファクトとしてカプセル化し、複数の拡張ポイントを定義することでプラグ可能なアーキテクチャをサポートします。

クライアント API のブートストラップと構成

API への主なエントリポイントは、Client インスタンスをブートストラップするために使用される ClientBuilder です。configurable は、基盤となる通信インフラストラクチャを管理し、Web リソースにアクセスするためのルートオブジェクトとして機能する重いオブジェクトです。次の例は、Client インスタンスのブートストラップと構成を示しています。

   Client client = ClientBuilder.newClient();

   client.property("MyProperty", "MyValue")
         .register(MyProvider.class)
         .register(MyFeature.class);
 

Web リソースへのアクセス

Web リソースは、メソッド呼び出しがチェーン化され、最終的に HTTP リクエストを送信する Fluent API を使用してアクセスできます。次の例では、"http://example.org/hello" で識別されるリソースの text/plain 表現を取得します。

   Client client = ClientBuilder.newClient();
   Response res = client.target("http://example.org/hello").request("text/plain").get();
 

概念的には、リクエストを送信するために必要な手順は次のとおりです。

1. Client インスタンスを取得する
2. Web リソースを指す WebTarget を作成する
3. build リクエスト
4. レスポンスを直接取得するリクエストを送信するか、後で送信するために準備された Invocation を取得します

上記のように、個々の Web リソースは、リソースターゲットとして表されるクライアント API にあります。各 WebTarget インスタンスは、具体的な URI にバインドされています。"http://example.org/messages/123"、または URI テンプレート（例: "http://example.org/messages/{id}"。このようにして、単一のターゲットが特定のリソースを指すか、後で具体的なリソースを導出できるリソースのより大きなグループ（たとえば、共通の構成を共有する）を表すことができます。

   // Parent target for all messages
   WebTarget messages = client.target("http://example.org/messages/{id}");

   // New target for http://example.org/messages/123
   WebTarget msg123 = messages.resolveTemplate("id", 123);

   // New target for http://example.org/messages/456
   WebTarget msg456 = messages.resolveTemplate("id", 456);
 

一般的な呼び出し

Invocation は、準備され、実行の準備ができているリクエストです。呼び出しは、作成者と提出者の間の関心事の分離を可能にする汎用インターフェースを提供します。特に、サブミッターは呼び出しがどのように準備されたかを知る必要はなく、同期で実行するか非同期で実行するかを知るだけです。

   Invocation inv1 = client.target("http://example.org/atm/balance")
       .queryParam("card", "111122223333").queryParam("pin", "9876")
       .request("text/plain").buildGet();
   Invocation inv2 = client.target("http://example.org/atm/withdrawal")
       .queryParam("card", "111122223333").queryParam("pin", "9876")
       .request().buildPost(text("50.0")));

   Collection invs = Arrays.asList(inv1, inv2);
   // Executed by the submitter
   Collection ress = Collections.transform(invs, new F() {
      public Response apply(Invocation inv) {return inv.invoke(); }
   });