JAX-RS 2.0 クライアントの構成

Java™ API for XML RESTful Web Services 2.0 の場合、クライアントが REST エンドポイントにアクセスするように構成できます。JAX-RS 2.0 では標準化された新しい Client API が導入され、リモート RESTful Web サービスに HTTP 要求を行うことができるようになりました。

このタスクについて

Client API を使用して Web リソースにアクセスするには、Client のインスタンスが必要です。ClientBuildernewClient または build を呼び出すことによって、Client のデフォルト・インスタンスを取得できます。クライアントを作成すると、サーバー・レベルで、またはクライアント・アプリケーション内で、そのクライアントを構成できます。

手順

  1. server.xml ファイルで jaxrsClient-2.0 または jaxrs-2.0 フィーチャーを使用可能にします。
    <featureManager>
        <feature>jaxrs-2.0</feature>// If you only need the JAX-RS 2.0 client feature, you can enable jaxrsClient-2.0 instead of  jaxrs-2.0 
    </featureManager>
  2. JAX-RS 2.0 クライアントを作成し、要求をサーバーに送信します。
    javax.ws.rs.client.ClientBuilder cb = ClientBuilder.newBuilder();
    
    javax.ws.rs.client.Client c = cb.build();
    String res = null;
    
    try {
    	res = c.target("<Resource_URL>")
                 .path("<PATH>")
                 .request()
                 .get(String.class);
    	} catch (Exception e) {
          	res = "[Error]:" + e.toString();
          } finally {
                c.close();        
          }   
    非同期 JAX-RS 2.0 クライアントについて詳しくは、非同期処理を参照してください。

次のタスク

JAX-RS 2.0 クライアントを作成すると、server.xml ファイル内で webTarget エレメントを定義するか、クライアント・アプリケーション内のプロパティーをプログラマチックに構成するか、いずれかの方法でそのクライアントを構成できます。

[17.0.0.2 and later]webTarget XML エレメントで server.xml ファイル内のプロパティーを構成するには、次のようにします。

<webTarget URI="value" property="value" property="value".../>
webTarget オブジェクトがインスタンス化され、その URI がこのエレメント内の URI 値と一致するとき、プロパティーが webTarget オブジェクトに適用されます。webTarget エレメントを定義する際、以下の構成情報を考慮してください。
  • URI は http://foo のように完全な形にすることも、末尾に * を使用して http://foo* のようにすることもできます。末尾に * を使用する場合、プロパティーは http://foo で始まる URI を持つすべての webTarget オブジェクトに適用されます。
  • server.xml ファイル内の複数の webTarget エレメントがその URI に一致する場合、完全一致が最初に適用され、次にワイルドカードによる一致が、URI によるソート順で適用されます。
  • プロパティー名の突き合わせでは大/小文字の区別はありません。
  • 指定された任意の JAX-RS プロパティー名およびプロパティー値が使用できます。構成プロパティーの短縮名を調べるには、webTarget JAX-RS クライアント・プロパティーを参照してください。

JAX-RS 2.0 アプリケーション内のプロパティーをプログラマチックに構成するには、次のようにします。

  • com.ibm.ws.jaxrs.client.connection.timeout クライアント・プロパティーと com.ibm.ws.jaxrs.client.receive.timeout クライアント・プロパティーを使用して、タイムアウト値を設定します。
    • com.ibm.ws.jaxrs.client.connection.timeout
      javax.ws.rs.client.ClientBuilder cb = ClientBuilder.newBuilder();
              cb.property("com.ibm.ws.jaxrs.client.connection.timeout", "1000"); 
              Client c = cb.build();
    • com.ibm.ws.jaxrs.client.receive.timeout
      javax.ws.rs.client.ClientBuilder cb = ClientBuilder.newBuilder();
              cb.property("com.ibm.ws.jaxrs.client.receive.timeout", "1000"); 
              Client c = cb.build();
    ヒント: タイムアウト・プロパティーの値はミリ秒単位であり、タイプは long または int です。値のタイプが無効な場合、次のメッセージが表示されます。
    CWWKW0700E: The timeout value {0} that you specified in the property com.ibm.ws.jaxrs.client.receive.timeout on the JAX-RS Client side is invalid. The value is set to default 30000. {3}
  • クライアント・プロキシー・サポートに関する次のクライアント・プロパティーを使用します。
    ClientBuilder cb = ClientBuilder.newBuilder();
    cb.property("com.ibm.ws.jaxrs.client.proxy.host", "hostname");
    cb.property("com.ibm.ws.jaxrs.client.proxy.port", "8888";);
    cb.property("com.ibm.ws.jaxrs.client.proxy.type", "HTTP");
    
    Client c = cb.build();  
    • com.ibm.ws.jaxrs.client.proxy.host
    • com.ibm.ws.jaxrs.client.proxy.port
      ヒント: プロキシー・サーバー・ポート値のタイプは int でなければなりません。デフォルト値は 80 です。値のタイプが無効な場合、次のメッセージが表示されます。
      CWWKW0701E: The proxy server port value {0} that you specified in the property com.ibm.ws.jaxrs.client.proxy.port on the JAX-RS Client side is invalid. The value is set to default 80. {3}
    • com.ibm.ws.jaxrs.client.proxy.type
      ヒント: プロキシー・サーバー・タイプの値は HTTP または SOCKS でなければなりません。デフォルト値は HTTP です。プロキシー・サーバーのタイプが無効な場合、次のメッセージが表示されます。
      CWWKW0702E: The proxy server type value {0} that you specified in the property com.ibm.ws.jaxrs.client.proxy.type on the JAX-RS Client side is invalid. The value is set to default HTTP. {3}
  • com.ibm.ws.jaxrs.client.ltpa.handler クライアント・プロパティーを使用して、SSO Cookie を設定し、値を true に設定します。
    ClientBuilder cb = ClientBuilder.newBuilder();
            Client c = cb.build();
            c.property("com.ibm.ws.jaxrs.client.ltpa.handler", "true");
    JAX-RS 2.0 で Secure Sockets Layer (SSL) 機能を使用する場合、ssl-1.0 フィーチャーまたは appSecurity-2.0 フィーチャーを有効にする必要があります。LTPA トークン機能には、appSecurity-2.0 フィーチャーが必要です。

    IHS を介した SSL を使用して JAX-RS 2.0 クライアントが実行されるように環境を構成する方法について詳しくは、IBM® HTTP Server の SSL サポートの構成を参照してください。

    注: ssl-1.0 フィーチャーは、appSecurity-2.0 フィーチャーのサブフィーチャーです。jaxrsClient-2.0 フィーチャーと ssl-1.0 フィーチャーを有効にすると、appSecurity-2.0 フィーチャーが自動的に有効になります。
  • com.ibm.ws.jaxrs.client.ssl.config クライアント・プロパティーを使用して、server.xml の SSL 参照 ID を設定します。
    ClientBuilder cb = ClientBuilder.newBuilder();
            cb.property("com.ibm.ws.jaxrs.client.ssl.config", "mySSLRefId"); 
            Client c = cb.build();
    IHS の鍵ファイルから証明書を抽出し、それを Liberty の JKS ファイルに追加することにより信頼を確立することについて詳しくは、『Create a key database file and certificates needed to authenticate the Web server during an SSL handshake』を参照してください。
    注: server.xml 内の構成は次のようになります。
    <ssl id="mySSLRefId" keyStoreRef="clientKeyStore" trustStoreRef="clientTrustStore" />
  • [17.0.0.3 and later]com.ibm.ws.jaxrs.client.ssl.config クライアント・プロパティーをプログラマチックに設定する代わりに、使用するアウトバウンド SSL を識別する際に JAX-RS 2.0 クライアントが SSL 構成に依存できるように、アウトバウンド SSL を構成します。

    アウトバウンド SSL を構成するには、アウトバウンド SSL フィルターとアウトバウンド SSL デフォルトの両方を構成するか、もしくはその 2 つのオプションのうち 1 つを構成することができます。いずれのオプションの組み合わせを実装する場合でも、transportSecurity-1.0 フィーチャーを使用可能にする必要があります。

    • server.xml ファイルで transportSecurity-1.0 フィーチャーを使用可能にします。
      <featureManager>
          <feature>transportSecurity-1.0</feature>
      </featureManager>
    • 宛先ホストの SSL 構成、または宛先ホストと宛先ポートの両方の SSL 構成を指定するように、アウトバウンド SSL フィルターを構成します。
      更新する server.xml ファイル内の構成は次のとおりです。
      <ssl id="mySSLRefId" keyStoreRef="clientKeyStore"
      trustStoreRef="clientTrustStore">
         <outboundConnection host=”myhost.atdomain.com” port=”9443” />       
         <outboundConnection host=”theotherhost.atdomain.com” port=”8020” 
      /> 
      </ssl>
      <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" >
         <outboundConnection host=”defaulthost.domain.com” />      
      </ssl>
      アウトバウンド SSL フィルターについて詳しくは、SSL 構成のアウトバウンド・フィルターを参照してください。
    • アウトバウンド SSL デフォルトを構成します。

      アウトバウンド接続と突き合わせる SSL フィルターが存在しない場合、JAX-RS クライアントはアウトバウンド SSL デフォルトを使用します。

      更新する server.xml ファイル内の構成は次のとおりです。
      <sslDefault outboundSSLRef=”mySSLRefId” /> 
      
      <ssl id="mySSLRefId" keyStoreRef="clientKeyStore" 
      trustStoreRef="clientTrustStore"/>      
      
      <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" />
      SSL アウトバウンド・デフォルトについて詳しくは、アウトバウンド通信の SSL 設定の構成を参照してください。
  • com.ibm.ws.jaxrs.client.disableCNCheck クライアント・プロパティーを使用して、 共通名のチェックを無効にします。
    ClientBuilder cb = ClientBuilder.newBuilder();
    cb.property("com.ibm.ws.jaxrs.client.disableCNCheck", true);

トピックのタイプを示すアイコン タスク・トピック

ファイル名: twlp_jaxrs2.0_clientconfig.html