4 RESTful Webサービス・クライアントの開発

この章では、Java API for RESTful Web Services (JAX-RS)を使用して、Representational State Transfer (REST)アーキテクチャ・スタイルに従ったWebLogic Webサービス・クライアントを開発する方法について説明します。

この章の内容は以下のとおりです。

• RESTful Webサービス・クライアントの開発について

• クライアント・インスタンスの作成および構成

• Webリソース・インスタンスの作成

• リソースへのリクエストの送信

• リソースからのレスポンスの受信

RESTful Webサービス・クライアントの開発について

Jersey JAX-RS RIにより、RESTful Webサービス・クライアントを開発するためのクライアントAPIが提供されます。クライアントAPIにアクセスするには、com.sun.jersey.api.client.Clientクラスのインスタンスを作成してから、そのインスタンスを使用してWebリソースへのアクセスおよびHTTPリクエストの送信を行います。

注意: 標準のクライアントAPIはJSR-311 JAX-RS 2.0仕様の一部としてサポートされる予定です。

以下の項で、RESTful Webサービス・クライアントの開発の詳細について説明します。

• RESTful Webサービス・クライアントを開発するタスクの概要

• RESTful Webサービス・クライアントの例

RESTful Webサービス・クライアントを開発するタスクの概要

次の表に、RESTful Webサービス・クライアントを開発するのに必要なタスクのサブセットの概要を示します。高度なタスクの詳細は、「高度なRESTful Webサービス・クライアント・タスク」を参照してください。

表4-1 RESTful Webサービス・クライアントを開発するタスクの概要

タスク	詳細についての参照先
com.sun.jersey.api.client.Clientクラスのインスタンスを作成します。	クライアント・インスタンスの作成および構成
Webリソースのインスタンスを作成します。	Webリソース・インスタンスの作成
リソースへリクエストを送信します。たとえば、リソース情報をGET、PUT、POSTおよびDELETEするHTTPリクエストです。	リソースへのリクエストの送信
リソースからレスポンスを受信します。	リソースからのレスポンスの受信

RESTful Webサービス・クライアントの例

次に、例2-1「簡単なRESTful Webサービス」で定義されたRESTful Webサービスを呼び出すのに使用できる簡単なRESTful Webサービス・クライアントの例を示します。この例では:

• ClientインスタンスがクライアントAPIにアクセスするために作成されます。詳細は、「クライアント・インスタンスの作成と構成」を参照してください。

• WebResourceインスタンスがWebリソースにアクセスするために作成されます。詳細は、「Webリソース・インスタンスの作成」を参照してください。

• getリクエストがリソースに送信されます。詳細は、 「リソースへのリクエストの送信」を参照してください。

• レスポンスは文字列値で返されます。レスポンスの受信についての詳細は、「リソースからのレスポンスの受信」を参照してください。

追加の例を「RESTful Webサービスの詳細」に示します。

例4-1 簡単なRESTful Webサービス・クライアントの例

package samples.helloworld.client;
 
import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.WebResource;
 
public class helloWorldClient {
    public helloWorldClient() {
        super();
    }
 
    public static void main(String[] args) {
        Client c = Client.create();
        WebResource resource = c.resource("http://localhost:7101/RESTfulService-Project1-context-root/jersey/helloWorld");
        String response = resource.get(String.class);
    }
}

クライアント・インスタンスの作成および構成

Jersey JAX-RS RIクライアントAPIにアクセスするには、com.sun.jersey.api.client.Clientクラスのインスタンスを作成します。詳細は、http://jersey.java.net/nonav/apidocs/1.9/jersey/com/sun/jersey/api/client/Client.htmlを参照してください。

オプションで、クライアント・インスタンスの作成時に、表4-2で定義したように、com.sun.jersey.api.client.Client.ClientConfigを定義し、その情報をcreateメソッドに渡すことで、クライアント構成プロパティを渡すことができます。詳細は、http://jersey.java.net/nonav/apidocs/1.9/jersey/com/sun/jersey/api/client/ClientConfig.htmlを参照してください。

表4-2 RESTful Webサービス・クライアント構成プロパティ

プロパティ	説明
PROPERTY_BUFFER_RESPONSE_ENTITY_ON_EXCEPTION	クライアントがレスポンス・エンティティをバッファリングする必要があるかどうかと、ある場合にはUniformInterfaceExceptionがスローされるとリソースを閉じるかどうかを指定するブール値です。このプロパティのデフォルトはtrueです。
PROPERTY_CHUNKED_ENCODING_SIZE	チャンク化されたエンコードのサイズを指定する整数値です。0以下の値はデフォルトのチャンク・サイズが使用されることを示します。設定されない場合、チャンクは使用されません。
PROPERTY_CONNECT_TIMEOUT	接続タイムアウト間隔をミリ秒単位で指定する整数値です。このプロパティが0または設定されない場合、間隔は無限です。
PROPERTY_FOLLOW_REDIRECTS	3xxレスポンスで宣言されたURIに自動的にリダイレクトされるかどうかを指定するブール値です。このプロパティのデフォルトはtrueです。
PROPERTY_READ_TIMEOUT	読取りタイムアウト間隔をミリ秒単位で指定する整数値です。このプロパティが0または設定されない場合、間隔は無限です。

例4-2にクライアント・インスタンスの作成方法の例を示します。

例4-2 クライアント・インスタンスの作成

import com.sun.jersey.api.client.Client;
...
    public static void main(String[] args) {
        Client c = Client.create();
...

例4-3に、クライアント・インスタンスを作成し、構成プロパティをcreateに渡す方法の例を示します。

例4-3 クライアント・インスタンスの作成および構成

import com.sun.jersey.api.client.*
...
    public static void main(String[] args) {
        ClientConfig cc = new DefaultClientConfig();
        cc.getProperties().put(ClientConfig.PROPERTY_FOLLOW_REDIRECTS, true);
        Client c = Client.create(cc);
...

また、getPropertiesメソッドから戻されたマップにプロパティを設定するか、または特定のsetterメソッドを呼び出すことで、クライアントの作成後にクライアント・インスタンスを構成することもできます。

例4-4に、クライアントを作成した後で構成する方法の例を示します。この例では:

• PROPERTY_FOLLOW_REDIRECTSはgetPropertiesメソッドから戻されたマップにプロパティを設定することにより構成されます。

• PROPERTY_CONNECT_TIMEOUTはsetterメソッドを使用して構成されます。

例4-4 クライアント・インスタンスの作成後の構成

import com.sun.jersey.api.client.*
...
    public static void main(String[] args) {
        Client c = Client.create();
        c.getProperties().put(ClientConfig.PROPERTY_FOLLOW_REDIRECTS, true);
        c.setConnectTimeout(3000);
...

Webリソース・インスタンスの作成

RESTful Webサービスにリクエストを送信する前に、URIで指定したリソースにアクセスするための、com.sun.jersey.api.client.WebResourceまたはcom.sun.jersey.api.client.AsyncWebResourceのインスタンスを作成する必要があります。WebResourceまたはAsyncWebResourceインスタンスはクライアント・インスタンスに対して定義された構成を継承します。詳細は、以下を参照してください。

• WebResource: http://jersey.java.net/nonav/apidocs/1.9/jersey/com/sun/jersey/api/client/WebResource.html

• AsyncWebResource: http://jersey.java.net/nonav/apidocs/1.9/jersey/com/sun/jersey/api/client/AsyncWebResource.html

注意: クライアント・インスタンスはコストの高いリソースなので、複数のWebリソースを作成する場合、可能ならば1つのクライアント・インスタンスを再利用することを推奨します。

例4-5に、http://example.com/helloworldにホストされたWebリソースへのインスタンスを作成する方法の例を示します。

例4-5 Webリソース・インスタンスの作成

import com.sun.jersey.api.client.*
...
    public static void main(String[] args) {\
...
        Client c = Client.create();
        WebResource resource = c.resource("http://example.com/helloWorld");
...

例4-5に、http://example.com/helloworldにホストされたWebリソースへのインスタンスを作成する方法の例を示します。

例4-6 非同期Webリソース・インスタンスの作成

import com.sun.jersey.api.client.*;
...
    public static void main(String[] args) {\
...
        Client c = Client.create();
         AsyncWebResource asyncResource = c.resource("http://example.com/helloWorld");
...

リソースへのリクエストの送信

次の項で説明するように、WebResourceまたはAsyncWebResourceインスタンスを使用して、関連するWebリソースへのリクエストを構築します。

• リクエストの構築方法

• HTTPリクエストの送信方法

• Acceptヘッダーの構成方法

• 問合せパラメータを渡す方法

リクエストの構築方法

Webリソースへのリクエストは、com.sun.jersey.api.client.RequestBuilderインタフェースで定義したように、ビルダー・パターンを使用して構造化されます。RequestBuilderインタフェースはcom.sun.jersey.api.client.WebResource、com.sun.jersey.api.client.AsyncWebResourceおよびその他のリソース・クラスにより実装されます。

表4-3で定義されたメソッドを使用してリクエストを構築することができ、HTTPリクエスト・メソッドが続きます(「HTTPリクエストの送信方法」を参照)。リクエストの構築方法の例を次の項で示します。

RequestBuilderとそのメソッドの詳細は、http://jersey.java.net/nonav/apidocs/1.9/jersey/com/sun/jersey/api/client/RequestBuilder.htmlを参照してください。

表4-3 リクエストの構築

メソッド	説明
accept()	有効なメディア・タイプを定義します。「Acceptヘッダーの構成方法」を参照してください。
acceptLanguage()	acceptLanguageメソッドを使用して有効な言語を定義します。
cookie()	設定するcookieを追加します
entity()	リクエスト・エンティティを構成します。「リクエスト・エンティティの構成方法」を参照してください。
header()	HTTPヘッダーおよび値を追加します。「Acceptヘッダーの構成方法」を参照してください。
type()	メディア・タイプを構成します。「リクエスト・エンティティの構成方法」を参照してください。

HTTPリクエストの送信方法

表4-4に、HTTPリクエストを送信するのに使用できるWebResourceおよびAsyncWebResourceの各メソッドを示します。

AsyncWebResourceの場合、java.util.concurrent.Future<V>オブジェクトが返されます。このオブジェクトは後で、実行を妨げずに計算結果へアクセスする際に使用できます。Future<V>の詳細は、http://docs.oracle.com/javase/6/docs/api/index.html?java/util/concurrent/Future.htmlを参照してください。

表4-4 HTTPリクエストを送信するためのWebResourceメソッド

メソッド	説明
get()	リソースの表現を取得するためにHTTP GETメソッドを呼び出します。
post()	指定したリソースの表現を作成または更新するためにHTTP POSTメソッドを呼び出します。
put()	リソースの表現を更新するためにHTTP PUTメソッドを呼び出します。
delete()	リソースの表現を削除するためにHTTP DELETEメソッドを呼び出します。

レスポンスにエンティティ(または表現)が含まれる場合、インスタンスのJavaタイプはHTTPメソッド内で宣言される必要があります。

例4-7に、HTTP GETリクエストの送信方法の例を示します。この例では、レスポンス・エンティティはStringのインスタンスであることが要求されます。レスポンス・エンティティはStringインスタンスにデシリアライズされます。

例4-7 HTTP GETリクエストの送信

import com.sun.jersey.api.client.WebResource;
...
    public static void main(String[] args) {
...
         WebResource resource = c.resource("http://example.com/helloWorld");
         String response = resource.get(String.class);
...

例4-8に、HTTP PUTリクエストの送信とエンティティfoo:barのWebリソースへの配置方法を示します。この例では、レスポンス・エンティティはcom.sun.jersey.api.client.ClientResponseのインスタンスであることが要求されます。

例4-8 HTTP PUTリクエストの送信

import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.ClientResponse;
...
    public static void main(String[] args) {
...
         WebResource resource = c.resource("http://example.com/helloWorld");
         ClientResponse response = resource.put(ClientResponse.class, "foo:bar");
...

汎用型を使用してHTTPリクエストを送信する場合、実行時に型のイレイジャを回避するために、汎用型を保持するcom.sun.jersey.api.client.GenericTypeオブジェクトを作成する必要があります。詳細は、http://jersey.java.net/nonav/apidocs/1.9/jersey/com/sun/jersey/api/client/GenericType.htmlを参照してください。

例4-9に、汎用型を保持するGenericTypeを使用する、汎用型を使用したHTTPリクエストの送信方法の例を示します。

例4-9 汎用型を使用したHTTP GETリクエストの送信

import com.sun.jersey.api.client.WebResource;
...
    public static void main(String[] args) {
...
        WebResource resource = c.resource("http://example.com/helloWorld");
        List<String> list = resource.get(new GenericType<List<String>>() {});
...

問合せパラメータを渡す方法

javax.ws.rs.core.MultivaluedMapを定義し、WebリソースでqueryParamsメソッドを使用して、HTTPリクエストの一部としてマップを渡すことで、GETリクエスト内の問合せパラメータを渡すことができます。

MultivaluedMapについての詳細は、http://docs.oracle.com/javaee/6/api/javax/ws/rs/core/MultivaluedMap.htmlを参照してください。

例4-10に、GETリクエスト内のパラメータをhttp://example.com/helloworldにホストされたWebリソースに渡し、次のリクエストURIの結果となる例を示します: http://example.com/base?param1=val1&param2=val2

例4-10 問合せパラメータを渡す

import com.sun.jersey.api.client.WebResource;
import javax.ws.rs.core.MultivaluedMap;
import javax.ws.rs.core.MultivaluedMapImpl;
...
    public static void main(String[] args) {
...
        WebResource resource = c.resource("http://example.com/helloWorld");
        MultivaluedMap queryParams = new MultivaluedMapImpl();
        queryParams.add("param1", "val1");
        queryParams.add("param2", "val2");
        String response = resource.queryParams(queryParams).get(String.class);
...

Acceptヘッダーの構成方法

Webリソースでacceptメソッドを使用して、リクエストのAcceptヘッダーを構成します。

例4-11に、http://example.com/helloworldにホストされたWebリソースへのGETリクエストに、有効なMIMEメディア・タイプとしてtext/plainを指定する方法の例を示します。

例4-11 Acceptヘッダーの構成

import com.sun.jersey.api.client.WebResource;
...
    public static void main(String[] args) {
...
        WebResource resource = c.resource("http://example.com/helloWorld");
        String response = resource.accept("text/plain").get(String.class);
...

カスタム・ヘッダーの追加方法

Webリソースでheaderメソッドを使用して、カスタム・ヘッダーをリクエストに追加します。

例4-12に、値BARを含むカスタム・ヘッダーFOOを、http://example.com/helloworldにホストされたWebリソースへのGETリクエストに追加する方法の例を示します。

例4-12 カスタム・ヘッダーの追加

import com.sun.jersey.api.client.WebResource;
...
    public static void main(String[] args) {
...
        WebResource resource = c.resource("http://example.com/helloWorld");
        String response = resource.header("FOO", "BAR").get(String.class);
...

リクエスト・エンティティの構成方法

Webリソースでentityメソッドを使用して、リクエスト・エンティティとタイプを構成します。または、Webリソースでtypeメソッドのみを使用してリクエスト・エンティティのタイプを構成することもできます。

例4-13に、リクエスト・エンティティおよびタイプの構成方法の例を示します。

例4-13 リクエスト・エンティティの構成

import com.sun.jersey.api.client.WebResource;
...
    public static void main(String[] args) {
...
        WebResource resource = c.resource("http://example.com/helloWorld");
        String response = resource.entity(request, MediaType.TEXT_PLAIN_TYPE).get(String.class);
...

例4-14に、リクエスト・エンティティのメディア・タイプのみを構成する方法の例を示します。

例4-14 リクエスト・エンティティのメディア・タイプのみの構成

import com.sun.jersey.api.client.WebResource;
...
    public static void main(String[] args) {
...
        WebResource resource = c.resource("http://example.com/helloWorld");
        String response = resource.type(MediaType.TEXT_PLAIN_TYPE).get(String.class);
...

リソースからのレスポンスの受信

「HTTPリクエストの送信方法」で説明したように、HTTPメソッドの呼出し時に、レスポンスにエンティティのJavaタイプ(または表現)を定義します。

レスポンス・メタデータが必要な場合、Javaタイプcom.sun.jersey.api.client.ClientResponseをレスポンス・タイプとして宣言します。ClientResponseタイプを使用すると、ステータス、ヘッダーおよびエンティティ情報にアクセスできます。

次の項で、ClientResponseを使用してアクセスできるレスポンス・メタデータについて説明します。ClientResponseについての詳細は、http://jersey.java.net/nonav/apidocs/1.9/jersey/com/sun/jersey/api/client/ClientResponse.htmlを参照してください。

• リクエストのステータスへのアクセス方法

• レスポンス・エンティティの取得方法

リクエストのステータスへのアクセス方法

ClientResponseオブジェクトでgetStatusメソッドを使用して、クライアント・レスポンスのステータスにアクセスします。有効なステータス・コードのリストは、http://jersey.java.net/nonav/apidocs/1.9/jersey/com/sun/jersey/api/client/ClientResponse.Status.htmlを参照してください。

例4-11に、レスポンスのステータス・コードにアクセスする方法の例を示します。

例4-15 リクエストのステータスへのアクセス

import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.ClientResponse;
...
    public static void main(String[] args) {
...
        WebResource resource = c.resource("http://example.com/helloWorld");
        ClientResponse response = resource.get(ClientResponse.class);
        int status = response.getStatus();
...

レスポンス・エンティティの取得方法

ClientResponseオブジェクトでgetEntityメソッドを使用して、レスポンス・エンティティを取得します。

例4-11に、レスポンス・エンティティを取得する方法の例を示します。

例4-16 レスポンス・エンティティの取得

import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.ClientResponse;
...
    public static void main(String[] args) {
...
        WebResource resource = c.resource("http://example.com/helloWorld");
        ClientResponse response = resource.get(ClientResponse.class);
        String entity = response.getEntity(String.class);
...

高度なRESTful Webサービス・クライアント・タスク

以下に示すものを含む、高度なRESTful Webサービス・クライアント・タスクの詳細は、『Jersey 1.9 User Guide』(http://jersey.java.net/nonav/documentation/1.9/user-guide.html)を参照してください。

• 表現タイプの追加

• フィルタの使用

• HTTP URLConnectionを使用したセキュリティの有効化