配置 JAX-RS 2.0 客户机

对于 Java™ API for XML RESTful Web Services 2.0,可以配置客户机以访问 REST 端点。JAX-RS 2.0 引入了新的标准化客户机 API 以便您可对远程 RESTful Web Service 发出 HTTP 请求。

关于此任务

要使用客户机 API 访问 Web 资源,需要客户机实例。缺省客户机实例可通过对 ClientBuilder 调用 newClientbuild 获取。创建客户机之后,您可以在服务器级别或者在客户机应用程序中配置该客户机。

过程

  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]要在 server.xml 文件中对 webTarget XML 元素配置属性:

<webTarget URI="value" property="value" property="value".../>
webTarget 对象已实例化,并且其 URI 与此元素中的 URI 值相匹配时,会将属性应用于 webTarget 对象。当您定义 webTarget 元素时,请考虑以下配置信息:
  • URI 可以精确匹配,例如,http://foo,或者以结尾 * 结束,例如,http://foo*。当您使用结尾 * 时,会将属性应用于其 URI 以 http://foo 开头的任何 webTarget 对象。
  • 如果 server.xml 文件中的多个 webTarget 元素与该 URI 相匹配,那么首先会应用精确匹配,然后应用通配符匹配,按 URI 的排序顺序进行。
  • 属性名称匹配项不区分大小写。
  • 可以使用所提供的任何 JAX-RS 属性名称和值。要查找缩短的配置属性名称,请参阅 webTarget JAX-RS Client Properties

要程序化配置 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();
    提示: 超时属性的值为毫秒,类型必须为长整型或整型。如果值类型无效,那么将显示以下消息:
    CWWKW0700E: 您在 JAX-RS 客户端上的属性 com.ibm.ws.jaxrs.client.receive.timeout 中指定的超时值 {0} 无效。此值设置为缺省值 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
      提示: 代理服务器端口值的类型必须为整型。缺省值为 80。如果值类型无效,那么将显示以下消息:
      CWWKW0701E: 您在 JAX-RS 客户端上的属性 com.ibm.ws.jaxrs.client.proxy.port 中指定的代理服务器端口值 {0} 无效。此值设置为缺省值 80。{3}
    • com.ibm.ws.jaxrs.client.proxy.type
      提示: 代理服务器类型值必须为 HTTP 或 SOCKS。缺省值为 HTTP。如果代理服务器类型无效,那么将显示以下消息:
      CWWKW0702E: 您在 JAX-RS 客户端上的属性 com.ibm.ws.jaxrs.client.proxy.type 中指定的代理服务器类型值 {0} 无效。此值设置为缺省值 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 中使用安全套接字层 (SSL) 功能,那么您需要启用 ssl-1.0 或 appSecurity-2.0 功能部件。对于 LTPA 令牌功能,需要 appSecurity-2.0 功能部件。

    有关如何配置环境以使 JAX-RS 2.0 客户机通过基于 IHS 的 SSL 运行的更多信息,请参阅 Configuring IBM® HTTP server SSL support

    注: 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 引用标识。
    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]配置出站 SSL,以便 JAX-RS 2.0 客户机可以依赖 SSL 配置来标识要使用的出站 SSL,而不用程序化设置 com.ibm.ws.jaxrs.client.ssl.config 客户机属性。

    要配置出站 SSL,您可以既配置出站 SSL 过滤器,也配置出站 SSL 缺省值,或者您可以配置这两个选项中的一个选项。无论您实现这两个选项的哪种组合,都必须启用 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