5.1. Uniform Interface Constraint 统一接口约束

统一接口约束边界 RESTful Web 服务的体系结构,以便客户端,如浏览器,可以使用相同的接口与任何服务通信。这是一个非常强大的概念在软件工程中,使基于网络的搜索引擎和服务混搭式应用成为可能。它导致属性如:

1.简单,架构更容易理解和维护,

2.可演化性或松散耦合、客户和服务可以随时间推移而发展也许是新的、意想不到的方式,同时保持向后兼容性。

需要进一步的约束:

1.每一个由 URI 标识的资源;

2.通过 HTTP 客户端交互与资源使用一组固定的 HTTP 请求和响应方法;

3.可以返回定义一个或多个媒体类型的资源;

4.内容可以链接到更多的资源。

上述过程重复一遍,应该是熟悉的人都使用一个浏览器填写 HTML 表单和链接。基于同样的过程适用于非浏览器客户端。

许多现有的基于 java 的客户端 API,比如 Apache HTTP 客户端API或HttpUrlConnection JDK 太专注于提供的“客户端-服务器”约束的交往请求和响应,而不是由URI标识,使用一组固定的HTTP方法的资源。

JAX-RS资源的客户端 API 是一个Java类的实例 WebTarget。封装了一个URI。固定的 HTTP 方法可以调用基于 WebTarget。表示是Java类型，它的实例，可以包含链接，可以创建新实例 WebTarget。

5.2. Ease of use and reusing JAX-RS artifacts 易于使用和可重用的 JAX-RS 工件

因为 JAX-RS 组件被表示为一个带注释的 Java 类型,它很容易配置,传递和注入的方式在其他客户端api不是很直观的或可能。Jerse y客户端 API重用 JAX-RS 和 Jersey 实现的许多方面如:

1.使用 UriBuilder 和 UriTemplate 更安全的构建 URI;

2.内置支持 Java 类型的表示如 byte[], String, Number, Boolean, Character, InputStream, java.io.Reader, File, DataSource, JAXB beans 以及额外 Jersey 特性的 JSON 和 Multi Part 的支持。

3.使用流利的构建式 API 模式,让它更容易构建请求。

一些 api ,比如 Apache HTTP 客户端或 HttpURLConnection 可能相当难以使用和/或需要太多的代码做一些相对简单的,尤其是当客户需要了解不同的载荷表示。这就是为什么 Jersey 实现 JAX-RS Client API 支持包装 HttpUrlConnection 和 Apache HTTP 客户端。因此可以获得既定的 JAX-RS 实现的好处和特点而变得易于使用的好处 JAX-RS 客户端 API 的简单的设计。与低层的HTTP客户端库,例如,发送一个POST请求与一群类型的 HTML 表单参数和接收响应反序列化到JAXB bean却并非易事。用新的 JAX-RS 客户端 API 支持泽这个任务非常简单:

Example 5.1. POST request with form parameters 将form参数以POST形式请求

  1. Client client = ClientBuilder.newClient();
  2. WebTarget target = client.target("http://localhost:9998").path("resource");
  4. Form form = new Form();
  5. form.param("x", "foo");
  6. form.param("y", "bar");
  8. MyJAXBBean bean =
  9. target.request(MediaType.APPLICATION_JSON_TYPE)
  10.     .post(Entity.entity(form,MediaType.APPLICATION_FORM_URLENCODED_TYPE),
  11.         MyJAXBBean.class);

在5.1的例子中首先创建一个新的 WebTarget 实例使用一个新的客户端实例,接着创建一个表单实例有两个参数形式。一旦准备好了,表单实例发布到目标资源。首先,在请求中指定可接受的媒体类型(…)方法。然后在post(…)方法,调用一个静态方法在 JAX-RS 实体是由构造请求实体实例和附加适当的内容媒体类型的形式被发送的实体。post(…)方法的第二个参数指定响应实体的Java类型,应该从方法返回一个成功的响应。在这种情况下请求JAXB bean的一个实例返回成功。Jersey客户端API负责选择适当的MessageBodyWriter < T >序列化表单的实例,调用POST请求和响应消息有效负载的生产和反序列化到JAXB bean的一个实例使用一个适当的MessageBodyReader < T >。

如果上面的代码必须使用 HttpUrlConnection 编写,开发人员必须编写自定义代码序列化表单数据发送 POST 请求和响应输入流反序列化成 JAXB bean。另外,写更多的代码必须使它容易重用相同的逻辑通信时资源“http://localhost:8080/resource”,是由 JAX-RS 代表WebTarget实例在我们的例子中。