49.2. クライアントターゲットの構築

最初の Client インスタンスの作成後、次のステップはリクエスト URI を構築することです。WebTarget ビルダークラスを使用すると、URI パスやクエリーパラメーターを含む URI のすべての側面を設定できます。

javax.ws.rs.client.WebTarget ビルダークラスは、リクエストの REST URI を構築できるようにする Fluent API の一部を提供します。

WebTarget インスタンスを作成するには、javax.ws.rs.client.Client インスタンス上で target メソッドのいずれかを呼び出します。以下に例を示します。

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

target メソッドを使用して、完全なパスをすべて一度に指定できます。または、基本パスを指定してから、target メソッドと path メソッドの組み合わせを使用して、パスセグメントを 1 つずつ追加することもできます。ベースパスとパスセグメントを組み合わせる利点は、WebTarget ベースパスオブジェクトを、わずかに異なるターゲット上で複数の呼び出しに対して簡単に再使用できることです。以下に例を示します。

// Java
import javax.ws.rs.client.WebTarget;
...
WebTarget base = client.target("http://example.org/bookstore/");
WebTarget headers     = base.path("bookheaders");
// Now make some invocations on the 'headers' target...
...
WebTarget collections = base.path("collections");
// Now make some invocations on the 'collections' target...
...

ターゲットパスの構文も URI テンプレートパラメーターをサポートします。つまり、パスセグメントはテンプレートパラメーター {param} で初期化でき、その後に指定値に解決されます。以下に例を示します。

// Java
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.core.Response;
...
WebTarget base = client.target("http://example.org/bookstore/");
WebTarget books = base.path("books").path("{id}");
...
Response resp = books.resolveTemplate("id", "123").request("application/xml").get();

ここで、resolveTemplate メソッドは、パスセグメント {id} を値 123 に置き換えます。

クエリーパラメーターは URI パスに追加できます。ここでは、URI パスでは、クエリーパラメーターの先頭に 1 つの ? 文字が付けられます。このメカニズムでは、構文 ?name1=value1&name2=value2&…​ を使用して一連の名前/値のペアを設定することができます。

WebTarget インスタンスでは、以下のように queryParam メソッドを使用してクエリーパラメーターを定義できます。

// Java
WebTarget target = client.target("http://example.org/bookstore/")
                         .queryParam("userId","Agamemnon")
                         .queryParam("lang","gr");

マトリックスパラメーターはクエリーパラメーターと若干似ていますが、広くサポートされておらず、異なる構文は使用します。WebTarget インスタンスでマトリックスパラメーターを定義するには、matrixParam(String, Object) メソッドを呼び出します。