RESTful Web 服务和 Apache Wink，第 1 部分: 构建 Apache Wink REST 服务

最新推荐文章于 2021-02-19 04:30:59 发布
最新推荐文章于 2021-02-19 04:30:59 发布
阅读量1k 收藏 1
点赞数 1

本文讨论 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-RS

Web 上的 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。

图 1. Apache Wink 逻辑流
显示逻辑流的图。数据在请求处理器、Apache Wink 运行时、Apache Wink REST servlet、HTTP 客户机以及资源和应用程序代码之间流动

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 中的资源。因为这个服务的功能是提供交易状态，可以公开 清单 1 所示的 URI。

清单 1. 交易服务的 URI 模式
/transactions
/transactions{id}

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

清单 2. 在查询字符串中包含用户凭证的 URI 模式
/transactions{id}?user=UNAME&vendor=VNAME&partner=PNAME&pwd=PWD

回页首

数据设计

每个 RESTful 接口必须决定支持它的客户机使用哪种具象。Apache Wink 1.0 可以支持 XML、JSON、HTML 和 Atom 等，这个示例使用 JSON，因为这是一种流行的格式，而且 Ajax 应用程序很容易使用 JavaScript 代码。清单 3 是一个采用 JSON 格式的交易状态示例。

清单 3. JSON 字符串形式的交易状态响应
{
 "RESULT":19,"PNREF":"V19A2A1A7CC5",
 "RESPMSG":"Original transaction ID not found: V19A2A192BE9",
 "AUTHCODE":null,"CVV2MATCH":null,"AVSADDR":null,
 "AVSZIP":null,"IAVS":null,"CARDSECURE":null
}

回页首

HTTP 方法设计

最后，必须决定使用哪些 HTTP 方法操作资源及其功能。一定要坚持这些 HTTP 方法的正规用法，不要偏离规范。例如，GET 应该是安全的只读幂等（idempotent）调用，它不应该以任何方式更改资源的状态。违反这条原则会增加复杂性，给客户机带来混乱。在这个示例中，因为希望对单一交易的状态执行只读查询，显然应该使用 GET 方法，使用的 URI 模式见 清单 4。

清单 4. 交易服务示例 URI 模式
/transactions{id}

每个 GET 调用返回一个 JSON 格式的字符串，这是查询的交易的状态数据，见 清单 5。

清单 5. 包含交易 ID 的 GET 请求
GET /transactions/V19A2A192BE9 HTTP/1.1

但是，这种查询交易状态的模型有一个问题：服务无法验证查询交易的用户是否确实是交易的所有者。为了解决这个问题，允许客户机在 URI 中作为查询参数传递登录凭证，见 清单 6。

清单 6. 在查询字符串中包含安全凭证的 GET 请求
GET /transactions/V19A2A192BE9?user=winktest&vendor=winktest
    &partner=PayPal&pwd=wink123
HTTP/1.1

回页首

Apache Wink 服务实现

Apache Wink 服务实现为 POJO（即普通的 Java 类），它使用 JAX-RS 注释把 HTTP 请求映射到 Java 方法。在默认情况下，服务可以是单实例的，也可以为每个请求创建服务实例。在这个示例中，通过创建 TransactionResource 类实现 Apache Wink RESTful 服务。它解析状态查询请求，验证用户凭证，调用 Payflow 网关服务，然后以 JSON 对象的形式返回交易的状态。清单 7 给出 TransactionResource 类的代码片段。

清单 7. Apache Wink 服务 Java 类片段
package org.openengine.wink.example.payflow;
	import ...;
	
	@Path("/transactions")
	public class TransactionResource {   
	
	@GET
	@Path("{pnref}")
	@Produces(MediaType.APPLICATION_JSON)
	public JSONObject doInquiry(@PathParam("pnref") String pnref,  
				@QueryParam("user") String userName, 
				@QueryParam("vendor") String vendorName, 
				@QueryParam("partner") String partnerName,
				@QueryParam("pwd") String password) {
		try {
			return getTxnStatus(pnref, 
		userName, vendorName, 
		partnerName, password);
	
		} catch (JSONException e) {
		throw new WebApplicationException
		(Response.Status.INTERNAL_SERVER_ERROR);
		}
	} 
	....

@javax.ws.rs.Path 注释指出这个类是 JAX-RS 服务。所有 JAX-RS 服务都需要这个注释。@Path 注释的值 /transactions 指出交易服务的 URI 的相对路径。

@GET 注释指出这个方法本身映射到的 HTTP 动词。方法级 @Path 注释的值相对于主 URI 指定子根。方法级 @Path 和 @PathParam 中的{pnref} 表示交易的惟一 ID。例如，如果 URI 是 /transactions/V19A2A192BE9，V19A2A192BE9 字符串会被注入 getTxnStatus 方法的{pnref} 参数中。

@javax.ws.rs.QueryParam 注释与 @PathParam 相似，但是它把各个 URI 查询参数注入 Java 参数中，见 清单 8。

清单 8. 包含查询参数的 URI
/transactions/V19A2A192BE9?user=winktest&vendor=winktest&partner=PayPal&pwd=wink123

回页首

Apache Wink 服务配置

Apache Wink 应用程序通常打包为 WAR 文件，部署在 Apache Tomcat 等 servlet 容器中。与其他 Web 应用程序一样，Apache Wink 服务也需要一个 web.xml 文件。清单 9 给出示例 Apache Wink 服务的 web.xml 文件的内容。

清单 9. web.xml Web 配置文件
<web-app>
	<display-name>Wink demo</display-name>
	<description>Demonstration of SDK features</description>

	<!-- Wink SDK servlet configuration. 
		This servlet handles HTTP requests
		of SDK web service on application server.-->
				
	<servlet>
		<servlet-name>restSdkService</servlet-name>
		<servlet-class>
			org.apache.wink.server.internal.servlet.RestServlet
		</servlet-class>
		<init-param>
			<param-name>applicationConfigLocation</param-name>
			<param-value>/WEB-INF/application</param-value>
		</init-param>
	</servlet>

	<servlet-mapping>
		<servlet-name>restSdkService</servlet-name>
		<url-pattern>/rest/*</url-pattern>
	</servlet-mapping>
</web-app>

可以看到 web.xml 文件中定义了 Apache Wink RestServlet 和它的 url-pattern。还有 RestServlet 的初始化参数，它指向 /WEB-INF/application 目录中的一个文件。这个文件包含 JAX-RS 应该部署的所有类和对象的列表。您不需要这个配置文件，可以让应用程序类以编程方式列出服务实现的资源，但是这个示例使用应用程序配置文件的方式，见 清单 10。

清单 10. 应用程序配置文件
org.openengine.wink.example.payflow.TransactionResource

回页首

运行 Apache Wink 服务

要想运行这个服务，首先必须在 Tomcat 上构建和部署应用程序。执行以下步骤：

  1. 从 下载 部分下载 PayFlow 示例项目。
  2. 把 PayFlow 项目的内容解压到 C 驱动器上的一个文件夹。C:\PayFlow 目录应该像 图 2 这样。
    图 2. PayFlow 示例项目的目录结构
    窗口显示 dist、lib 和 source 目录以及 build.xml 文件
  3. 把 JAVA_HOME 和 ANT_HOME 变量设置为自己的 Java 和 Apache Ant 安装目录。
  4. 在系统变量 PATH 中添加 JAVA_HOME/bin 和 ANT_HOME/bin。
  5. 从 C:\PayFlow 目录运行 Ant，从而对 PayFlow 项目执行 Ant 构建。

    这个步骤应该会构建 PayFlow 项目并创建文件 PayFlow.war，见 图 3。

    图 3. Ant 脚本构建的输出
    命令提示显示 Ant 脚本构建代码。显示成功地构建了 payflow.war 文件
  6. 把 PayFlow.war 文件复制到 TOMCAT 主目录下的 webapps 目录中，见 图 4。
    图 4. 在 Tomcat 服务器上部署 PayFlow 项目
    窗口显示 webapps 目录下的 docs、examples、host-manager 和 root 子目录以及 payflow.war 文件
  7. 通过运行 TOMCAT_HOME\bin 文件夹中的 startup.bat 文件启动 Tomcat Web 服务器。
  8. 启动您喜欢的浏览器，访问 URI http://localhost:8080/PayFlow/rest/transactions/V19A2A192BE9?user=winktest&vendor=winktest&partner=PayPal&pwd=wink123>（假设 Tomcat Web 服务器配置为监听端口 8080）。

    浏览器应该会提示您保存文件 V19A2A192BE9，其中包含 JSON 格式的交易状态，见 图 5。

    图 5. 浏览器保存文件窗口，保存包含交易状态的 JSON 文件
    窗口显示保存 application/json 文件，选择了 save file 单选按钮

回页首

结束语

本文简要介绍了 REST 架构和 JAX-RS Java 标准（这个标准用于简化 RESTful 服务实现）的基本知识。然后讨论了新的 Apache Wink 1.0 框架，这是一个完全兼容的容易使用的 JAX-RS 1.0 规范实现。介绍了 Apache Wink 的底层架构，然后设计和实现了一个新的示例 Apache Wink Web 服务，讨论了部署和运行它所需的步骤。关于 REST、JAX-RS 和 Apache Wink 1.0 框架的更多信息，请参见本文的 参考资料 部分。

回页首

下载

描述 名字 大小
Apache Wink 服务实现 PayFlow.zip 2.51MB

参考资料

学习

acmant
关注
REST架构之Apache Wink介绍
永无止境，上下求索
06-24 1万+
REST(Representational State Transfer)  based Web Service是相对于传统的Web Service(SOAP+WSDL+UDDI)而提出的。传统的Web Service可以很好的解决异构系统之间的通信问题，但是需要首先定义好XML格式的合同(WSDL)，client和server都必须严格遵守协议，不容易升级以及集群伸缩。REST Web Serv
Apache Wink 创建RESTfull
06-15 5205
本文将介绍 Apache Wink，一种用于构造 Representational State Transfer (REST)ful Web 服务的框架。Apache Wink 是一个 Apache Incubator 项目。它的目标是通过提供使用 Java™ 注释在类的内部定义服务的能力，提供一种简单的编写 RESTful Web 服务的方法。  　　REST　　
apache wink rest学习（配置、编码、调用）
iteye_4668的博客
04-10 799
        最近接触新的项目，项目中远程接口用的是rest wink，以前项目对于这种需求基本都是webservice去实现的，今天特意对rest wink进行了理论研究和实际编码工作，所以记录记录下来以便后面查阅。理论部分看到一篇好文章，这里就直接引用下好了，文章地址：https://www.oschina.net/question/5189_8593 REST 代表 Represen...
REST架构之Apache Wink
weixin_30394981的博客
11-30 143
Apache Wink是一个使用简单，稳定的Java框架，用于创建RESTful web services应用程序。Wink包括了一个服务器端模块和一个客户端模块，用于帮助开发者快速高效的开发RESTful Web services应用。 首先，需要在web.xml里面配置一下，把REST的访问都安排给Wink来处理。代码如下： <servlet> <ser...
Apache Wink和REST
cuyi7076的博客
06-26 455
本文是由三部分组成的系列文章的第三篇，将Apache Wink与其他各种免费和开源的JAX-RS实现（例如Project Jersey，JBoss RESTEasy和Restlet Framework）进行了比较。 它提供了每个实现框架的高级概述，同时根据一组通用属性突出显示了差异。 最后，本文通过分析和审查不同的JAX-RS实现，帮助您选择合适的框架。 常用缩略语 API：应用程...
Apache Wink 和 REST1
02-20
RESTful Web 服务和 Apache Wink
apache wink集成spring 开发rest服务
03-23
Apache Wink是一个开源框架，主要用于构建RESTful Web服务。它基于Java EE标准，提供了一组API和工具，帮助开发者快速创建、部署和管理RESTful应用程序。Spring框架则是Java领域广泛使用的依赖注入（DI）和面向切面...
Apache Wink 和 REST
02-20
RESTful Web 服务和 Apache Wink
apache-wink-1.3.0-src.tar.gz
07-18
Apache Wink是一个开源的Java框架，主要用于构建RESTful Web服务。这个"apache-wink-1.3.0-src.tar.gz"文件是Apache Wink 1.3.0版本的源代码压缩包，提供了完整的源码，供开发者进行深入研究、定制和扩展。以下是...
使用ApacheWink和Ajax构建富JavaWeb应用程序
03-01
本文将介绍ApacheWink，一种用于构造RepresentationalStateTransfer(REST)fulWeb服务的框架。ApacheWink是一个ApacheIncubator项目。它的目标是通过提供使用Java?注释在类的内部定义服务的能力，提供一种简单的编写RESTfulWeb服务的方法。本文将介绍ApacheWink，演示如何安装它，并附带一个简单的管理任务列表的RESTfulWeb服务。本文的示例基于ApacheWink发行版携带的Bookmarks示例。尽管如此，本文中的示例使用了不同的消息格式，可以使用AsynchronousJavaScript+XML(Ajax
apache wink client
haohaodigua的专栏
11-27 1574
http://apache-wink-users.3471013.n2.nabble.com/how-can-i-hold-the-session-from-the-wink-RestClient-td7035956.html   http://lj.platformatyourservice.com/lj80/Category:REST_API    // create the re
java wink_Apache Wink 创建RESTfull
weixin_31925685的博客
02-19 182
本文将介绍 Apache Wink，一种用于构造 Representational State Transfer (REST)ful Web服务的框架。Apache Wink 是一个 Apache Incubator 项目。它的目标是通过提供使用 Java™注释在类的内部定义服务的能力，提供一种简单的编写 RESTful Web 服务的方法。REST与 SOAP 不同，RESTful Web 服务...
Apache 顶级项目 Wink 将由于不活跃而终止
weixin_34293911的博客
06-02 209
近日，Apache 发布了一封终止 Apache Wink 项目相关事项的邮件，宣布Apache 顶级项目 Wink 将由于不活跃而终止，具体内容如下： Announcing that the Apache Wink committers have voted to retire the project due to inactivity. Wink w...
提供一个wink restclient用get访问restapi的例子（java语言）
dobingT001的博客
05-05 1125
public void getMethod() { JSONObject result; String url = "https://api.bmob.cn/1/classes/xxx"; // 详细的类库请使用Apache wink，地址：http://wink.apache.org  RestClient restClient = new RestClient(getClien
使用Apache CXF开发RESTful服务
最佳 Java 编程
05-16 402
介绍 如您所知，有两种开发Web服务的方法 简单对象访问协议（SOAP） 代表性状态转移（REST） 在继续学习如何使用Apache CXF创建基于REST的Web服务之前，我们将了解什么是REST。 REST不是一项技术，当然也不是某种标准。 这只是一种架构风格，它限制了如何以某种方式编写Web服务。 此样式由某个Roy Fielding（您猜对了，是的，他是HTTP的架构...
Apache-cxf搭建Restful风格WebServcie
程序猿劝退师的博客
09-13 725
目录 1.Restful风格介绍 1.1传统的请求 1.2基于restful风格的请求： 1.3注意事项 1.4风格约定: 2.常用的restful框架 3.Apache-cxf框架 3.1项目架构图 3.2pom.xml 3.3服务端接口 3.4发布服务 3.5客户端 1.Restful风格介绍 表现层状态转换（REST，英文：Representational Sta...
Apache Wink REST开发中的高级主题
cuyi7076的博客
06-26 186
本文探讨了与Apache Wink 1.0版开发相关的高级主题，包括使用附加注释，将Wink服务与流行的Spring框架集成以及使用Apache Wink Client框架实现自定义RESTful客户端。 常用缩略语 API：应用程序编程接口 CSV：逗号分隔值 HTTP：超文本传输​​协议 JSON： JavaScript对象表示法 MIME：多用途Interne...
如何使用wink框架_带有Apache Wink的RESTful Web服务，第1部分，构建Apache Wink REST服务
cuyi7076的博客
06-26 195
存档日期：2019年4月22日 | 上次更新时间：2010年2月9日 | 首次发布：2010年1月19日 本文是由三部分组成的系列文章的第一篇，探索Apache Wink 1.0的基础，Apache Wink 1.0是用于实现和使用基于REST的Web服务的新Java™框架。 此内容不再被更新或维护。 全文以PDF格式“按原样”提供。 随着技术的飞速发展，某些内容，步骤或插图可能已更改...
Apache Wink开发者指南：构建RESTful Web服务
开始使用Apache Wink的步骤包括安装、配置环境，以及创建第一个REST服务。开发者可以快速上手，通过简单的注解来定义资源和处理方法。 4. **JAX-RS概念** JAX-RS是Java中定义RESTful服务的标准。Apache Wink实现...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值