2.2. JAX-RS Client

JAX-RS 2.0 引入了一个新的客户端 API，用于发送 HTTP 请求到远程 RESTful Web 服务。这是一个流畅的请求构建 API，包含 3 个主要类：

客户端 接口是 Web 目标实例的构建器。WebTarget 代表用于构建子资源 Web 目标或调用请求的不同 URL 或 URL 模板。

可以通过两种方式创建客户端：标准方式，或使用 ResteasyClientBuilder 类。使用 ResteasyClientBuilder 类的优点是它提供了一些额外的帮助程序方法来配置您的客户端。

ResteasyClientBuilder 类提供这些帮助程序方法，但该类特定于 JBoss EAP API。如果要将应用程序迁移到新服务器，您必须重新构建应用程序。ResteasyClientBuilder 类依赖于 RESTEasy，并且类不可移植。

创建客户端的标准方式同时遵循 JAX-RS 和 Java EE API 规范，它在 JAX-RS 实施中可移植。

使用标准方法创建客户端

以下示例显示了创建客户端的标准方法之一：

Client client = ClientBuilder.newClient();

另外，您可以使用另一种标准方法来创建客户端，如下例所示：

Client client = ClientBuilder.newBuilder().build();
WebTarget target = client.target("http://foo.com/resource");
Response response = target.request().get();
String value = response.readEntity(String.class);
response.close();  // You should close connections!

使用 ResteasyClientBuilder 类创建客户端

以下示例演示了使用 ResteasyClientBuilder 类来创建客户端：

ResteasyClient client = new ResteasyClientBuilder().build();
ResteasyWebTarget target = client.target("http://foo.com/resource");

使用 JAX-RS 2.1 时，您可以向 ClientBuilder 类添加两个超时方法。超时方法是符合规格的方法，您可以使用它们，而不使用 RESTEasy 方法。

以下 ClientBuilder 规格兼容方法替换了一些已弃用的 RESTEasy 方法：

以下示例显示了 connectTimeout 和 readTimeout 方法 的指定值：

import javx.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Client;

Client client = ClientBuilder.newBuilder()
	       .connectTimeout(100, TimeUnit.SECONDS)
	       .readTimeout(2, TimeUnit.SECONDS)
	       .build();

请注意 ，readTimeout 适用于现有连接上已执行的请求。

RESTEasy 自动加载一组默认提供程序，其中包含 META-INF/services/javax.ws.rs.ext.Providers 文件中列出的所有类。另外，您可以通过方法调用 Client.configuration（） 提供的配置对象手动注册其他提供程序、过滤器和拦截器。通过配置，您可以设置可能需要的配置属性。

每个 Web 目标 都有一个配置实例，它继承了与父实例注册的组件和属性。这可让您为每个目标资源设置特定的配置选项，例如用户名和密码。

使用 RESTEasy 客户端类

您必须将 RESTEasy 客户端的以下依赖项添加到 Maven pom.xml 文件中：

<dependency>
	<groupId>org.jboss.resteasy</groupId>
	<artifactId>resteasy-client</artifactId>
	<version>VERSION_IN_EAP</version>
 </dependency>

有关使用 RESTEasy 客户端类 的工作示例，请参见 JBoss EAP 附带的 jaxrs-client 和 resteasy-jaxrs-client 快速入门。

客户端过滤器

客户端具有两种过滤器：

// execute request filters
for (ClientRequestFilter filter : requestFilters) {
	filter.filter(requestContext);
	if (isAborted(requestContext)) {
    return requestContext.getAbortedResponseObject();
  }
}

// send request over the wire
response = sendRequest(request);

// execute response filters
for (ClientResponseFilter filter : responseFilters) {
	filter.filter(requestContext, responseContext);
}

将客户端过滤器注册到客户端请求

以下示例演示了如何将客户端过滤器注册到客户端请求：

client = ClientBuilder.newClient();
WebTarget base = client.target(generateURL("/") + "get");
base.register(ClientExceptionsCustomClientResponseFilter.class).request("text/plain").get();

客户端缓存

RESTEasy 能够设置客户端缓存。此缓存查找随服务器响应发回的 cache-control 标头。如果 cache-control 标头指定允许客户端缓存响应，RESTEasy 会将它缓存在本地内存中。

ResteasyWebTarget target = client.target(generateBaseUrl());
target.register(BrowserCacheFeature.class);

块编码支持

RESTEasy 为客户端 API 提供指定请求应在区块传输模式中发送的功能。可以通过两种方式指定区块传输模式，如下所示：