构建 Apache Wink REST 服务（1）简介

look_w

本文讨论 Apache Wink 1.0 框架的架构，解释一个示例 Apache Wink RESTful 服务的设计、实现和部署。本文还帮助您了解 REST 范型的基本知识，解释新的 JAX-RS 1.0 标准，从而帮助 Java 开发人员使用注释实现 RESTful Web 服务。       
常用缩写词

• API：应用程序编程接口（Application programming interface）
• CSV：逗号分隔值（Comma-separated values）
• HTML：超文本标记语言（Hypertext Markup Language）
• HTTP：超文本传输协议（Hypertext Transfer Protocol）
• JSON：JavaScript™ Object Notation
• OOP：面向对象编程（Object-oriented programming）
• REST：具象状态传输（Representational State Transfer）
• RSS：真正简单的聚合（Really Simple Syndication）
• URI：统一资源标识符（Uniform Resource Identifier）
• WAR：Web archive
• WSDL：Web 服务描述语言（Web Services Description Language）
• XML：可扩展标记语言（Extensible Markup Language）

REST 概述首先简要介绍一下 REST。REST 代表 Representational State Transfer，它是 World Wide Web 所依赖的一套架构原则。Roy Fielding 在他的博士论文 “Architectural Styles and the Design of Network-based Software Architectures” 中首次提出了这个概念。在他的论文中，Fielding 明确指出 REST 和 World Wide Web 的五个架构原则：               

• 可寻址性（Addressability）。REST 中的所有东西都基于资源 的概念。资源与 OOP 中的对象或其他名词不同，它是一种抽象，必须可以通过 URI 寻址或访问。
• 接口一致性（Interface uniformity）。与 SOAP 或其他标准不同，REST 要求用来操纵资源的方法或动词不是任意的。这意味着 RESTful 服务的开发人员只能使用 HTTP 支持的方法，比如 GET、PUT、POST、DELETE 等等。因此不需要使用 WSDL 等服务描述语言。
• 无状态（Statelessness）。为了增强可伸缩性，服务器端不存储客户机的状态信息。这使服务器不与特定的客户机相绑定，负载平衡变得简单多了。这还让服务器更容易监视、更可靠。
• 具象（Representational）。客户机总是与资源的某种具象交互，绝不会直接与资源本身交互。同一资源还可以有多个具象。理论上说，持有资源的具象的任何客户机应该有操纵底层资源的足够信息。
• 连通性（Connectedness）。任何基于 REST 的系统都应该预见到客户机需要访问相关的资源，应该在返回的资源具象中包含这些资源。例如，可以以超链接的形式包含特定 RESTful 服务的操作序列中的相关步骤，让客户机可以根据需要访问它们。

JAX-RSWeb 上的 REST以下站点当前正在使用 REST：

• Atom Publishing Protocol。Atom 是 REST 协议最正规的实现之一，广泛用于博客发布领域。
• Sun 的 Cloud API。这是 Sun 的 RESTful API，用于管理和创建计算、连网和存储元素等云资源。
• Digg 的 API。Digg 是一个流行的社交网站，它使用 RESTful API 让用户和合作伙伴能够以编程方式与站点和数据交互。
• Netflix API。Netflix 是一个 DVD 出租网站，它使用 RESTful API 提供对影片目录的细粒度访问，以及以编程方式调整用户队列和获取影片推荐。
• Flickr API。Flickr 是一个照片上传网站，用户可以使用它提供的 RESTful API 上传、更换和搜索照片和像册。

为什么需要另一个 Java 标准？定义 JAX-RS 这个新规范是为了简化基于 REST 的 Java 开发。它主要关注使用 Java 注释和普通旧式 Java 对象 (POJO) 实现 RESTful 服务。尽管总是可以使用 servlet 实现 RESTful 服务，但是以这种方式实现业务逻辑需要太多 HTTP GET 请求。               
JAX-RS 隐藏所有 HTTP 并把 servlet 绑定到 Java 类中的各个方法。注释还可以动态地提取 HTTP 请求中的信息，以及把应用程序生成的异常映射到 HTTP 响应码。由于这些原因，JAX-RS 是一种实现 RESTful Java Web 服务的有效方法。               
Apache Wink 和 REST我已经介绍了 REST 和 JAX-RS，现在开始讨论 Apache Wink。Apache Wink 1.0 是一个从头设计的完全兼容的 JAX-RS 1.0 规范实现。它很容易使用和应用于生产环境，它提供的特性可以增强核心 JAX-RS 规范。               
Apache Wink 运行时架构是 JAX-RS 1.0 规范的简单实现。Apache Wink 部署在 Java Platform, Enterprise Edition (Java EE) 环境中，由以下三个组件组成：               

• Apache Wink RestServlet。RestServlet 在 Web 应用程序的 Java EE web.xml 描述符文件中配置。这个 servlet 作为所有 HTTP Web 服务请求的主入口点，它把请求和响应对象实例分派给请求处理器进行进一步处理。
• 请求处理器。RequestProcessor 是核心 Apache Wink 引擎，它由 Apache Wink RestServlet 初始化。请求处理器使用请求 URI 寻找、匹配和调用相应的资源类和方法。在请求处理期间发生的任何异常都会导致 RequestProcessor 调用 Error Handler Chain 以处理异常。
• 资源。在 REST 中，代表 Web 服务的任何组件或对象都被称为资源。资源允许通过它的许多具象之一获取和操纵数据。实现资源的 POJO 被称为资源类。资源类进一步实现资源方法，资源方法实际处理底层业务逻辑。

整个请求周期被称为 Apache Wink 逻辑流，见 。               
图 1. Apache Wink 逻辑流Apache Wink 不但帮助实现 RESTful Web 服务，而且提供一个强大的客户机库，可以使用它轻松地消费 RESTful 服务。最后，Apache Wink 附带一组内置的提供者，它们帮助开发人员支持多种行业标准的数据格式：XML、Atom、RSS、JSON、CSV 和 HTML。               
RESTful 设计现在该实践一下了。为了保持趣味性，我们要在 Apache Wink 1.0 上设计、实现和部署一个不太简单的 RESTful 服务。这个服务是 PayPal Payflow 支付网关服务的 RESTful 包装器，它可以通过 Internet 进行信用卡处理。但是，对于这个示例，我们只关注它的交易查询功能。只要提供一个属于经过身份验证的用户的惟一 ID，这个功能可以查询任何交易的状态。               
资源/URI 设计 首先定义服务的接口模型并给它分配 URI，这使服务成为 REST 中的资源。因为这个服务的功能是提供交易状态，可以公开  所示的 URI。               
清单 1. 交易服务的 URI 模式

1 2	/transactions /transactions{id}

/transactions URI 表示系统中的所有交易。使用 /transactions{id} 查询某一交易的状态。{id} 代表对应于交易模型的交易 ID 的惟一字母数字值。另外，使用  中的模式验证用户的身份，其中的 UNAME、VNAME、PNAME 和 PWD 是在注册时分配给商人的 Payflow 网关登录凭证的组成部分。               
清单 2. 在查询字符串中包含用户凭证的 URI 模式

1	/transactions{id}?user=UNAME&vendor=VNAME&partner=PNAME&pwd=PWD