配置 JAX-RS 2.0 客户机
对于 Java™ API for XML RESTful Web Services 2.0,可以配置客户机以访问 REST 端点。JAX-RS 2.0 引入了新的标准化客户机 API 以便您可对远程 RESTful Web Service 发出 HTTP 请求。
关于此任务
过程
下一步做什么
创建 JAX-RS 2.0 客户机之后,可以通过在 server.xml 文件中定义 webTarget 元素或者通过在客户机应用程序中程序化配置属性来配置该客户机。
要在 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}
- com.ibm.ws.jaxrs.client.connection.timeout
- 使用以下客户机属性以获取客户机代理支持:
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。
如果要在 JAX-RS 2.0 中使用安全套接字层 (SSL) 功能,那么您需要启用 ssl-1.0 或 appSecurity-2.0 功能部件。对于 LTPA 令牌功能,需要 appSecurity-2.0 功能部件。ClientBuilder cb = ClientBuilder.newBuilder(); Client c = cb.build(); c.property("com.ibm.ws.jaxrs.client.ltpa.handler", "true");
有关如何配置环境以使 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 引用标识。
有关通过从 IHS 密钥文件抽取证书,并将该证书添加至 Liberty JKS 文件来建立信任的更多信息,请参阅 Create a key database file and certificates needed to authenticate the Web server during an SSL handshake。ClientBuilder cb = ClientBuilder.newBuilder(); cb.property("com.ibm.ws.jaxrs.client.ssl.config", "mySSLRefId"); Client c = cb.build();
注: server.xml 中的配置如下所示:<ssl id="mySSLRefId" keyStoreRef="clientKeyStore" trustStoreRef="clientTrustStore" />
配置出站 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 过滤器的更多信息,请参阅SSL 配置的出站过滤器。<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 过滤器,那么 JAX-RS 客户机将使用出站 SSL 缺省值。
在 server.xml 文件中,您要更新的配置为如下所示:
有关 SSL 出站缺省值的更多信息,请参阅配置用于出站通信的 SSL 设置。<sslDefault outboundSSLRef=”mySSLRefId” /> <ssl id="mySSLRefId" keyStoreRef="clientKeyStore" trustStoreRef="clientTrustStore"/> <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" />
- 在 server.xml 文件中启用 transportSecurity-1.0 功能部件:
- 使用 com.ibm.ws.jaxrs.client.disableCNCheck 客户机属性来禁用公共名称检查。
ClientBuilder cb = ClientBuilder.newBuilder(); cb.property("com.ibm.ws.jaxrs.client.disableCNCheck", true);