第 49 章 JAX-RS 2.0 Client API

摘要

JAX-RS 2.0 定义了一个功能齐全的客户端 API,可用于进行 REST 调用或任何 HTTP 客户端调用。这包括一个流畅的 API(以简化构建请求)、用于解析消息的框架(基于称为 实体提供商 的插件),以及对客户端上异步调用的支持。

49.1. JAX-RS 2.0 客户端 API 简介

概述

JAX-RS 2.0 定义了用于 JAX-RS 客户端的流畅 API,它可让您构建 HTTP 请求逐步构建,然后使用适当的 HTTP 动词(GET、POST、PUT 或 DELETE)调用请求。

注意

也可以在 Blueprint XML 或 Spring XML 中定义 JAX-RS 客户端(使用 jaxrs:client 元素)。有关这个方法的详情,请参考 第 18.2 节 “配置 JAX-RS 客户端端点”

依赖项

要在应用中使用 JAX-RS 2.0 客户端 API,您必须将以下 Maven 依赖项添加到项目的 pom.xml 文件中:

<dependency>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-rt-rs-client</artifactId>
  <version>3.3.6.fuse-7_11_0-00038-redhat-00001</version>
</dependency>

如果您计划使用异步调用功能(请参阅 第 49.6 节 “客户端上的异步处理”),您还需要以下 Maven 依赖项:

<dependency>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-rt-transports-http-hc</artifactId>
  <version>3.3.6.fuse-7_11_0-00038-redhat-00001</version>
</dependency>

客户端 API 软件包

JAX-RS 2.0 客户端接口和类位于以下 Java 软件包中:

javax.ws.rs.client

在开发 JAX-RS 2.0 Java 客户端时,您通常需要访问核心软件包中的类:

javax.ws.rs.core

简单客户端请求的示例

以下代码片段演示了一个简单的示例,其中 JAX-RS 2.0 客户端 API 用于对 http://example.org/bookstore JAX-RS 服务进行调用,并通过 GET HTTP 方法调用:

// Java
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Client;
import javax.ws.rs.core.Response;
...
Client client = ClientBuilder.newClient();
Response res = client.target("http://example.org/bookstore/books/123")
    .request("application/xml").get();

Fluent API

JAX-RS 2.0 客户端 API 设计为一个 流畅的 API (有时称为域特定语言)。在流畅的 API 中,以单一声明调用一个 Java 方法链,因此 Java 方法从简单语言类似命令。在 JAX-RS 2.0 中,流畅的 API 用于构建和调用 REST 请求。

进行 REST 调用的步骤

使用 JAX-RS 2.0 客户端 API,在一系列步骤中构建并调用客户端调用,如下所示:

  1. 引导客户端。
  2. 配置目标。
  3. 构建并发出调用。
  4. 解析响应。

引导客户端

第一步是通过创建 javax.ws.rs.client.Client 对象来引导客户端。此 客户端 实例是一个相对重量型对象,它代表支持 JAX-RS 客户端(包括拦截器和其他 CXF 功能)所需的技术堆栈。理想情况下,您应在可以时重新使用客户端对象,而不是创建新对象。

要创建新的 Client 对象,请在 ClientBuilder 类上调用静态方法,如下所示:

// Java
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Client;
...
Client client = ClientBuilder.newClient();
...

配置目标

通过配置目标,您可以有效地定义用于 REST 调用的 URI。以下示例演示了如何使用 path(String) 方法定义基本 URI 基础 URI,然后向基本 URI 添加额外路径片段:

// Java
import javax.ws.rs.client.WebTarget;
...
WebTarget base = client.target("http://example.org/bookstore/");
WebTarget books = base.path("books").path("{id}");
...

构建并调用

这实际上分为两个步骤:首先,您先构建 HTTP 请求(包括标头、接受媒体类型等);然后,您可以调用相关的 HTTP 方法(可选提供请求消息正文(如果需要)。

例如,要创建并调用接受 application/xml 介质类型的请求:

// Java
import javax.ws.rs.core.Response;
...
Response resp = books.resolveTemplate("id", "123").request("application/xml").get();

解析响应

最后,您需要解析上一步中获得的重新启动。通常,以 javax.ws.rs.core.Response 对象的形式返回响应,它封装了 HTTP 标头和其他 HTTP 元数据,以及 HTTP 邮件正文(若有)。

如果要以 String 格式访问返回的 HTTP 消息,您可以使用 String.class 参数调用 readEntity 方法,如下所示:

// Java
...
String msg = resp.readEntity(String.class);

您可以始终将响应的消息正文作为 String 进行访问,方法是将 String.class 指定为 readEntity 的参数。有关更常规转换或转换邮件正文,您可以提供 一个实体供应商 来执行转换。如需了解更多详细信息,请参阅 第 49.4 节 “解析请求和响应”