Java RESTful Web Service实战[按需印刷]

2.1.3　扩展服务 28
2.1.4　测试和运行服务 31
2.2　第一个Servlet 容器服务 32
2.2.1　创建和分析Web 服务 32
2.2.2　Jetty 插件与REST 服务 35
2.2.3　运行在Servlet 容器 38
2.2.4　运行在Java EE 容器 39
2.3　REST 服务类型 40
2.4　REST 应用描述 45
2.4.1　应用的描述 46
2.4.2　资源的描述 46
2.4.3　WADL 的配置 47
2.5　第一个完整的REST 服务 48
2.5.1　定义资源 48
2.5.2　集成Spring 51
2.5.3　集成JPA 53
2.5.4　集成jQuery 55
2.5.5　请求处理流程分析 57
2.6　REST 调试工具 64
2.6.1　命令行调试工具cURL 64
2.6.2　基于浏览器的图形化调试插件 66
2.7　本章小结 69
第3 章　REST API 设计 70
3.1　REST 统一接口 70
3.1.1　GET 方法 71
3.1.2　PUT 方法 73
3.1.3　DELETE 方法 75
3.1.4　POST 方法 76
3.1.5　WebDAV 扩展方法 77
3.2　REST 资源定位 79
3.2.1　资源地址设计 79
3.2.2　@QueryParam 注解 81
3.2.3　@PathParam 注解 83
3.2.4　@FormParam 注解 86
3.2.5　@BeanParam 注解 88
3.2.6　@CookieParam 注解 88
3.2.7　@Context 注解 89
3.3　REST 传输格式 90
3.3.1　基本类型 90
3.3.2　文件类型 90
3.3.3　InputStream 类型 91
3.3.4　Reader 类型 92
3.3.5　XML 类型 93
3.3.6　JSON 类型 96
3.4　REST 连通性 112
3.4.1　过渡型链接 113
3.4.2　结构型链接 114
3.5　REST 响应处理 114
3.5.1　返回类型 115
3.5.2　处理异常 117
3.6　REST 内容协商 119
3.6.1 @Produces 注解 119
3.6.2 @Consumes 注解 121
3.7　本章小结 122
第4 章　REST 请求处理 123
4.1　REST 和AOP 123
4.2　Providers 详解 124
4.2.1　实体Providers 124
4.2.2　上下文Providers 129
4.3　REST 请求流程 130
4.4　REST 过滤器 132
4.4.1　ClientRequestFilter 132
4.4.2　ContainerRequestFilter 133
4.4.3　ContainerResponseFilter 134
4.4.4　ClientResponseFilter 135
4.4.5　访问日志 136
4.5　REST 拦截器 138
4.6　绑定机制 140
4.7　优先级 144
4.8　本章小结 145
第5 章　REST 客户端 146
5.1　客户端接口 146
5.1.1　Client 接口 147
5.1.2　WebTarget 接口 148
5.1.3　Invocation 接口 148
5.2　资源释放 149
5.3　连接器 150
5.4　封装Client 153
5.5　本章小结 154
第二篇　全面掌握——JAX-RS 2.0 进阶
第6 章　REST 安全 156
6.1　身份认证 157
6.1.1　基本认证 157
6.1.2　摘要认证 158
6.1.3　表单认证 158
6.1.4　证书认证 159
6.2　资源授权 160
6.2.1　容器管理权限 160
6.2.2　应用管理权限 163
6.3　认证与授权实现 163
6.3.1　基本认证与JDBCRealm 164
6.3.2　摘要认证与UserDatabase-Realm 170
6.3.3　表单认证与DataSource-Realm 173
6.3.4　表单认证与JAASRealm 177
6.3.5　证书认证与UserDatabase-Realm 180
6.4　JAX-RS 2.0 实现 184
6.5　其他安全考虑 187
6.6　本章小结 188
第7 章　REST 测试 189
7.1　Jersey 测试框架 189
7.2　单元测试 192
7.2.1　集成Spring 的单元测试 192
7.2.2　异步测试 194
7.3　集成测试 194
7.4　日志增强 195
7.5　本章小结 195
第8 章　REST 推送与异步通信 196
8.1　服务器—浏览器通信 196
8.1.1　Polling 技术 197
8.1.2　Comet 技术 197
8.1.3　SSE 技术 199
8.1.4　WebSocket 技术 199
8.2　SSE 详述 200
8.2.1　Java 并发 200
8.2.2　SSE 流程 202
8.2.3　SSE 实现 204
8.3　异步通信 209
8.4　JAX-RS 2.0 实现异步通信 211
8.4.1　服务端实现 211
8.4.2　客户端实现和测试 213
8.5　本章小结 215
第9 章　Jersey 1.x 迁移 216
9.1　变更Maven 依赖定义 216
9.2　客户端迁移 217
9.2.1　Client 接口迁移 217
9.2.2　WebTarget 接口迁移 218
9.2.3　QueryParam 219
9.3　服务器端迁移 219
9.4　本章小结 220
第10 章　JAX-RS 调优 221
10.1　使用缓存优化负载 221
10.1.1　缓存协商 221
10.1.2　条件GET 223
10.1.3　REST 缓存实践 224
10.1.4　ab 测试 226
10.2　使用版本号优化服务 226
10.2.1　何时使用版本号 227
10.2.2　如何使用版本号 227
10.3　使用参数配置优化服务 229
10.3.1　通用配置 229
10.3.2　服务器端配置 230
10.3.3　客户端配置 231
10.4　Java 虚拟机调优 232
10.4.1　虚拟机概述 232
10.4.2　内存溢出与内存泄漏 235
10.5　本章小结 236
第三篇　实践分享——JAX-RS 2.0 综合
第11 章　统一自动化测试平台 238
11.1　ATUP 的定义 238
11.1.1　需求仓库 239
11.1.2　需求分析 241
11.1.3　迭代规划 242
11.2　ATUP 的设计 244
11.2.1　开发和部署环境 244
11.2.2　模块定义和拓扑 247
11.2.3　持续集成流程 248
11.3　ATUP 的实现 250
11.3.1　Sprint1 核心功能 250
11.3.2　Sprint2 模块功能 281
11.3.3　Iteration1 的演示和回顾 288
11.3.4　Sprint3 持续交付 291
11.3.5　交付和总结 293
11.4　本章小结 293
附录　Web 简史 294
参考资料 297
后记 298

.　　第2 章讲述了使用Jersey 2.x 开发一个基于JAX-RS 2.0 标准的应用的基本知识以及如何使用Jersey 来集成Spring 和JPA 以快速开发一个REST 式的Web 服务。本章包含10 个示例项目。
　　第3 章深入阐述了如何使用Jersey 设计和实现REST 式的Web 服务的API。本章包含5 个示例项目。
　　第4 章深入阐述了Jersey 的Providers 对REST 请求的处理。
　　第5 章讲述了Jersey 的客户端开发的基本实践和常用配置。
　　第二篇共5 章（第6 ～10 章），讲述写好REST 程序的必要知识点。完成第二篇的阅读和实践，读者可以全面了解如何写好一个完整的REST 式的Web 服务。
　　第6 章全面讲述了如何实现一个安全的REST 式的Web 服务。
　　第7 章讲述了Jersey 的测试框架及其使用。
　　第8 章讲述了Jersey 对HTML5 的SSE 的支持和异步请求处理。
　　第9 章讲述了Jersey 1.x 迁移到Jersey 2.x 的要素和经验分享。
　　第10 章分享了REST 式的Web 服务的性能调优的经验。
　　第三篇包含1 章（第11 章），分享了5 年外企工作中，我对自动化测试和敏捷的体会。完成本部分内容的阅读和实践，读者可以更宏观地审视REST 的应用场景，起到抛砖引玉的作用。
　　第11 章讲述一个完整的REST 项目的全过程。
　　全文由三个小版组成：“阅读指南”、“小白讲堂”（为某些在知识点上比较“小白”的同学介绍概念性的知识）和“宅人坑事”（技术宅最自豪和最担惊受怕的就是“踩坑”），旨在和读者分享基础知识和心得体会，只为交流，切勿对号入座。
　　第一篇推荐研发工程师和REST 小白完整阅读，这部分包含了了解和使用JAX-RS 2.0 完成学习和工作的必要章节。对于有基础的技术人员，可以作为实践的参考有选择地阅读。
　　第二篇推荐致力于提高自己的技术人员完整阅读，这部分包含了JAX-RS 2.0 的高级功能。永不满足和持续学习的精神，会让你在关键时刻成为“关键先生”。架构师和项目经理在考虑安全、性能等问题时，可以参考相关章节。
　　第三篇推荐渴望实战指导的技术人员阅读和跟随实践。同时，该篇结合了笔者参与敏捷实践的体会，以scrum 的方式进行开发管理。因此，敏捷实践者和相关的部门经理可以参考。
　　产品经理可以阅读与REST 特性相关的章节，这样可帮你在设计应用方面有所提高。
　　源代码
　　章节 源代码地址
　　第1 章～第10 章 https://github.com/feuyeux/jax-rs2-guide
　　第11 章 https://github.com/feuyeux/jax-rs2-atup
　　勘误和交流
　　作为开发者，非常欢迎读者能与我一起交流JAX-RS 2.0 相关的技术。我的邮箱是：feuyeux@gmail.com，新浪微博是：六爷1_1。
　　本书的勘误统计在https://github.com/feuyeux/jax-rs2-guide/wiki 中，欢迎读者批评指正。
　　致谢
　　感谢我的夫人Caroline。写作期间，没有时间陪你共度周末，甚至没有精力陪你共度以2 开头的最后一个生日，也没有营造任何浪漫的气氛。我们的女儿从蹒跚学步到会唱儿歌，我没有更多的时间陪伴你们，而你一如既往地支持我，在此我对你表示深深的感谢。
　　感谢华章公司的杨福川。我最难忘的是最初谈到要出本书时与君一拍即合的快意，这为我此后动笔增添了无穷的动力和信心。同时，阁下给予我的信任和鼓励也极大地推动了本书的顺利完成。在此后一年多的交往中，我深深感受到了业内对杨福川专业水准的评价和他敬业的态度。
　　感谢华章公司编辑高婧雅专业和耐心的审阅和指正。我曾一度被这位可敬的东北妹子的严谨和勤奋打击，心生愧对华章精品精神的挫败感。但随着婧雅的不断鼓励和支持，我一遍遍改进着稿件，自信心得到了恢复，同时，内心得到了安慰，我没有偏离初心和那份原动力。非常感谢华章公司和婧雅。
　　感谢RedHat 公司姜宁师兄的技术校对，感谢阿里巴巴公司许晓斌的敏捷校对。
　　最后，我要感谢Technicolor 敏捷团队中的每一位成员，正是与各位度过的每一天，才让我有资本和信心与广大读者分享在REST 式的开发中的经验和教训，并在本书中介绍自动化
　　测试和敏捷实践的相关知识。
　　

.　　1.1.1一种架构风格
　　REST 是一种架构风格。在REST 架构风格中，对象被抽象为一种资源（resource），资源的命名使用概念清晰的名词来定义。表述性状态是对资源数据在某个瞬间状态的快照，资源的某个瞬时状态被定义为一种表述（representation），这种描述性的状态包括资源数据的内容、表述格式（比如XML、JSON、Atom）等信息，一种资源可以对应多种表述。REST 的资源是可寻址的，通过HTTP 协议（RFC 2616 ）定义的通用动词方法（比如GET、PUT、DELETE、POST），并使用URI 协议（RFC 3305 ）来唯一标识某个资源公布出来的接口。请求一个资源的过程可以理解为，访问一个具有指定性和描述性的URI，经由HTTP，将资源的表述从服务器转移到客户端，或者相反方向。
　　REST 不是一种技术（technology），也不是一个标准（standard）或协议（protocol），它使用既有标准：HTTP+URI+XML
　　，来实现其要求的架构风格。因此，与之对应的不是SOAP，而是像RPC 这样的架构风格。
　　1.1.2基本实现形式
　　HTTP+URI+XML 是REST 的基本实现形式，但不是唯一的实现形式。REST 从推出时就使用已有的HTTP 协议、URI 协议来描述，而对如何使用一种编程语言来实现，并没有进行任何描述和规定，甚至对于REST 应该包含哪些传输类型或者数据格式也没有描述，但通常的实现至少包含XML 格式。具体而言，HTTP 协议和URI 用于统一接口和定位资源，文本、二进制流、XML 和JSON 等格式用来作为资源的表述。正如采用已有技术XMLHttpRequest+JavaScript+XML（XML 后来几乎被JSON 替代）实现AJAX 一样，使用HTTP+URI+XML 实现REST 的好处是让开发者持有这些已知的技术来开发REST，入门门槛较低，关注点更容易放到REST 的核心概念和业务逻辑上。
　　这里要提示读者的是，以HTTP+URI+XML 实现的应用并不一定是REST 式的，但对于AJAX，这个逆命题（以XMLHttpRequest+JavaScript+XML 实现的应用一定是AJAX 应用）是成立的。因为AJAX 是一种“技术流派”，而REST 是一种架构风格。学习和使用REST 的关键是掌握这种思想，而不是具体的实现形式。
　　XML 似乎成为了数据格式的借指，不仅代表XML 本身。
　　1.2解读REST 服务
　　英文RESTful 对应的中文是REST 式的。RESTful 的应用或者Web 服务是常见的两种
　　REST 式的项目部署、存在的方式。本节将介绍RESTful Web Services 并对比和传统Web
　　Services 的不同。
　　1. REST 式的Web 服务
　　RESTful Web Services（REST 式的Web 服务）是一种遵守REST 式风格的Web 服务。
　　REST 式的Web 服务是一种ROA（Resource-Oriented Architecture，面向资源的架构）的应用。
　　其主要特点是方法信息存在于HTTP 的方法中（比如GET、PUT），作用域存在于URI 中。
　　例如，在一个获取设备资源列表的GET 请求中，方法信息是GET，作用域信息是URI 中包
　　含的对设备资源的过滤、分页和排序等条件。
　　2. 对比RPC 风格
　　相比Web 服务领域广为流行的RPC（Remote Procedure Call ，远程过程调用）风格，
　　REST 风格更轻量和快速。从方法信息角度看，REST 采用标准的HTTP 方法，而RPC 请求
　　都是HTTP 协议的POST 方法，其方法信息包含在SOAP 协议包或HTTP 协议包中，方法名
　　称不具有通用性。从作用域角度看，REST 采用URI 显式定义作用域，而RPC 的这一信息同
　　样包含于协议包中，不能直观呈现。
　　RPC 风格的开发关注于服务器-客户端之间的方法调用，而不关注基于哪个网络层的
　　哪种协议。也就是说，RPC 是面向方法调用过程的，相比而言，REST 是面向资源状态的。
　　RPC 风格的两个代表是XML-RPC 和大Web 服务。
　　（1）XML-RPC
　　XML-RPC 是一种使用XML 格式封装方法调用，并使用HTTP 协议作为传送机制的
　　RPC 风格的实现。XML-RPC 的请求方法都是HTTP 协议的POST 方法，请求和响应的数据
　　格式均为XML。
　　XML-RPC 的数据格式和使用XML 作为资源的表述的REST 外观上很相似，但数据的内容则大相径庭。REST 式的XML 信息的主体是对一个资源状态的表述，无须包含方法信息，因为其请求的HTTP 方法就已经决定了这一点。XML-RPC 的请求数据结构额外包含方法调用信息和参数信息。
　　对于响应信息的内容，两者也截然不同，REST 式的通常会包含响应实体信息以及HTTP 状态码和可选的异常信息，而XML-RPC 的返回信息仅仅是对方法调用的响应信息。
　　XML-RPC 是一种遗留技术，已经被SOAP 取代。在Java 领域，JAX-RPC 标准已经被
　　JAX-WS 取代。XML-RPC 的应用依然存在，著名的测试用例管理系统TestLink 的对外接口
　　就是使用PHP 开发的XML-RPC。
　　（2）大Web 服务大Web 服务（Big Web Services ）是Leonard Richardson 和Sam Ruby 在其所著的《RESTful
　　Web Services 》一书中，对基于SOAP+ WSDL+UDDI+WS-标准栈等技术实现RPC 风格的大型Web 服务的统称。事实上，“大Web 服务”这一说法也被Java EE 7 的布道者在多次演讲中使用。在Java 领域，对应的标准主要是JAX-WS 2.0/2.1/2.2（JSR 224）。相较REST 式的Web 服务，大Web 服务功能更强大、设计更复杂。大Web 服务同样是跨平台、跨语言的，对复杂的数据类型的支持也非常好。大Web 服务是基于RPC 风格的重量级的设计，因此方法和作用域无法通过直观断定，需要定义在消息中，而且方法名不是统一和通用的。同时，大Web 服务走HTTP 协议时，请求都是基于POST 方法的。
　　对比RPC 风格的Web 服务，REST 式的Web 服务形式更简单、设计更轻量、实现更快捷。REST 无须引入SOAP 消息传输层，无须注册服务，也没有客户端stub 的概念等。但是，REST 风格的Web 服务并没有像大Web 服务那样提供诸如安全策略等全面的标准规范。
　　大Web 服务和REST 式的Web 服务各有其优势，并不是一种代换关系。在实际开发中，两者共存于一个项目中也是一种解决方案。
　　3. 对比MVC 风格
　　MVC 风格的出现将模型、视图、控制解耦，其亮点是从前到后的一致性，其结构简洁、逻辑清晰，易于扩展和增强。MVC 在Java 领域的普遍实现方式是在Web 前端使用标签库来对应服务端的模型类实例和控制类实例，标签库和服务端依赖库可以是松散的耦合——比如Spring 生态系统，也可以是全栈式的统一体系，比如JSF 体系。但无论如何实现，在Web 前端的开发过程中，必须时刻考虑页面标签和服务端的映射关系，包括模型类的匹配和转换，数据结构，控制类输入和输出的参数类型和数量等。
　　因此，MVC 风格偏重于解决服务器端的逻辑分层，客户端是逻辑分层的延伸。MVC 的标签库，虽然其形态已经和HTML 页面融合，但本质上还是Java 编写的装饰模式的类实例，对应的是服务器端使用Java 编写的模型类或者控制器类，因此MVC 很难实现跨语言解耦。而REST 风格偏重于统一接口，因此具体实现就可以跨平台和跨语言。正如附录中Web 简史中所述，REST 推动了Web 开发的新时代，使用纯HTML 作为客户端，没有服务器端和客户端的耦合。显而易见，使用纯HTML 开发的REST 客户端和使用Java 开发的REST 服务器端并不存在语言上的耦合。
　　MVC 和REST 式并不是互斥的，像Spring 的MVC 模块已经支持REST 式的开发。Jersey 作为JAX-RS 标准的实现，也实现了MVC 的功能，可参考相关模块：jersey-mvc、jersey-mvc-freemarker 和jersey-mvc-jsp。需要说明的是，本书致力于讲述JAX-RS，对Jersey 实现中的JAX-RS 之外的功能只做必要的讲述。由于MVC 和REST 之间有更多的并行存在性，因此本书余文没有将MVC 放入讲述之列。
　　1.3解读JAX-RS
　　JAX-RS 是Java 领域的REST 式的Web 服务的标准规范。如果我们只学习工具的使用而
　　不知标准是怎样定义的，那么可能不会理解其本质。因此，我们首先来学习和掌握JAX-RS 规范，这是使用Java 完成REST 式的Web 服务的基础和前提。
　　1. JAX-RS2 标准
　　Java 领域中的Web Services 是指实现SOAP 协议的JAX-WS。直到Java EE 6 （发布于
　　2008 年9 月）通过JCP（Java Community Process ）组织定义的JSR 311（http://www.jcp.org/
　　en/jsr/detail?id=311），才将REST 在Java 领域标准化。JSR 311 名为The Java API for RESTful
　　Web Services ，即JAX-RS，其参考实现是GlassFish 项目中的Jersey 1.0。此后，JSR 311 进
　　行了一次升级（2009 年9 月），即JAX-RS 1.1 。JAX-RS 诞生后，时隔5 年（2013 年5 月）
　　发布的Java EE 7 包含了JSR 339 ，将JAX-RS 升级到JAX-RS 2.0（http://www.jcp.org/en/jsr/
　　detail?id=339）。JAX-RS 2.0 在前面版本的基础上增加了很多实用性的功能，比如对REST 客
　　户端API 的定义、异步REST 等，对REST 的支持更加完善。
　　JAX-RS 的版本对应的参考实现的Jersey 项目版本信息参见表1-1。
　　表1-1JAX-RS 标准和Jersey 版本信息
　　JAX-RS 标准 JAX-RS 名称 标准发布时间 JAX-RS 实现
　　311 JAX-RS 1.0 2008 年9 月8 日 Jersey 1.x
　　311 JAX-RS 1.1 2009 年9 月17 日
　　339 JAX-RS 2.0 2013 年5 月22 日 Jersey 2.x
　　2. JAX-RS 2.0 的目标
　　JAX-RS 2.0 标准（即JSR 339）中定义了目标、非目标和元素等内容。JSR 339 标准中的这部分内容通常被以实现业务功能为目的的开发人员所忽视，在此和读者分享的一个开发经验是，要掌握一项技术，要先掌握它背后标准的定义。我们首先来看看JAX-RS 2.0 的目标。
　　1）基于POJO ：JAX-RS 2.0 的API 提供一组注解（annotation）和相关的接口、类，并定义了POJO（Plain Ordinary Java Objects ）对象的生命周期和作用域。规定使用POJO 来公布Web 资源。
　　2）以HTTP 为中心：JAX-RS 2.0 采用HTTP 协议，并提供清晰的HTTP 和统一资源定位（URI）元素来映射相关的API 类和注解。JAX-RS 2.0 的API 不但支持通用的HTTP 使用模式，还对WebDAV 和Atom 等扩展协议提供灵活的支持。
　　3）格式独立性：JAX-RS 2.0 对传输数据（HTTP Entity ）的类型/ 格式的支持非常宽泛，允许在标准风格之上使用额外的数据类型。
　　4）容器独立性：JAX-RS 2.0 的应用可以部署在各种Servlet 容器中，比如Tomcat/Jetty，也可以部署在支持JAX-WS 的容器中，比如GlassFish。
　　5）内置于Java EE ：JAX-RS 2.0 是Java EE 规范的一部分，它定义了在一个Java EE 容器内的Web 资源类的内部，如何使用Java EE 的功能和组件。
　　小白讲堂
　　WebDAV（Web-based Distributed Authoring and Versioning ，基于Web 的分布式创作和版本控制）是IETF 组织的RFC 2518 协议。WebDAV 基于并扩展了HTTP 1.1 ，在HTTP 标准方法以外添加了：
　　Mkcol：创建集合；
　　PropFind/PropPatch：针对资源和集合检索和设置属性；
　　Copy/Move：管理命名空间上下文中的集合和资源；
　　Lock/Unlock：改写保护，支持文件的版本控制。
　　针对在REST 风格的Web 服务中是否应该使用WebDAV ，业内的声音并不一致，持反对意见的人的主要观点是WebDAV 带来了非统一的接口，这违背了REST 的初衷。本书的示例将不采用WebDAV ，但文字部分将讲述如何支持WebDAV 。Atom 类型传输格式将在3.3 节讲述。
　　3. 非JAX-RS 2.0 的目标
　　那么哪些不是JAX-RS 2.0 的目标呢？1）对J2SE 6.0 之前版本的支持：JAX-RS 2.0 中大量使用了注解（annotation），需要J2SE 6.0 以及更新的版本，因此不提供对J2SE 6.0 以下版本的支持。2）对服务的描述、注册和探测：JAX-RS 2.0 没有定义也无须支持任何服务的描述（description）、服务的注册（registration）和服务的探测（discovery）。3）HTTP 协议栈：JAX-RS 2.0 没有定义新的HTTP 协议栈。承载JAX-RS 2.0 应用的容器提供对HTTP 的支持。4）数据类型/ 格式类：JAX-RS 2.0 没有定义处理实体内容的类，它将这一类型的类交由使用JAX-RS 2.0 的应用中的类去实现。
　　4. 解读JAX-RS 元素
　　最后，我们来看看JAX-RS 2.0 中定义了哪些元素。
　　1）资源类：使用JAX-RS 注解来实现相关Web 资源的Java 类。如果用MVC 的三层
　　结构来解读，那么资源类位于最前端，用于接收请求和返回响应。通常但不是约定使用
　　resource 作为包名，三层的包定义形如：resource-service-dao。
　　2）根资源类：使用@Path 注解，提供资源类树的根资源及其子资源的访问。资源类分
　　为根资源类和子资源类。由于Jersey 默认提供WADL （参见2.4 节），因此每个应用公布的全
　　部资源接口可以通过WADL 页面查阅。
　　3）请求方法标识符：使用运行期注解@HttpMethod，用来标识处理资源的HTTP 请
　　求方法。该方法将被资源类的相应方法处理，标准的方法包括DELETE、GET、HEAD、
　　OPTIONS、POST、PUT，详见3.1 节。
　　4）资源方法：资源类中定义的方法，使用了请求方法标识符，用来处理相关资源的请
　　求。就是上面提到的资源类的相应方法。5）子资源标识符：资源类中定义的方法，用来定位相关资源的子资源。6）子资源方法：资源类中定义的方法，用来处理相关资源的子资源的请求。7）Providers：一种JAX-RS 扩展接口的实现类，扩展了JAX-RS 运行期的能力。第4 章
　　详述了各种Providers 及其实现。8）Filter：一种用于过滤请求和响应的Provider，详见4.4 节。9）Entity Interceptor：一种用于处理拦截消息读写的Provider。10）Invocation：一种用于配置发布HTTP 请求的客户端API 对象，详见5.1.3 节。11）WebTarget ：一种使用URI 标识的Invocation 容器对象，详见5.1 节。12）Link：一种携带元数据的URI，包括媒体类型、关系和标题等，详见3.4 节。
　　1.4Jersey 项目概要
　　Jersey 是JAX-RS 标准的参考实现，是Java 领域中开发REST 式的Web 服务的“正统”工具。这样讲述的目的是避免读者混淆REST 领域诸多工具的地位，并无偏好推荐之意。本节将带领读者走进Jersey 的世界。
　　Jersey 项目是GlassFish 项目的一个子项目，专门用来实现JAX-RS（JSR 311 和JSR 339）标准，并提供了扩展特性。
　　1. 获得Jersey
　　Jersey 项目的网址是https://jersey.java.net ，这是Jersey 的官方网站。该网站同时提供了JAX-RS 和JAX-RS 2.0 两个并行版本，分别是Jersey 1.1 （截至本书发稿，最新版本是Jersey
　　1.18）和Jersey 2.0（截至本书发稿，最新版本是Jersey 2.9）。读者可以通过单击“latest Jersey User Guide”获取和阅读最新版本的用户手册，这是官方发布的第一手的参考资料。
　　Jersey 项目的下载地址https://jersey.java.net/download.html，Jersey 项目使用Maven 管理项目，该页面至上而下分别是：
　　JAX-RS 标准列表链接。
　　Jersey 最新参考实现的jar 包下载。
　　Jersey 最新参考实现的示例代码下载。创建基于Maven 管理的JAX-RS 容器Jersey 应用。创建基于Maven 管理的Servlet 容器Jersey 应用。
　　JAX-RS 1.1 的参考实现包下载。
　　2. Jersey 源代码
　　Jersey 2 使用GitHub 管理源代码，GitHub 的客户端非常简洁。单击首页下方的“Source Control”进入https://jersey.java.net/scm.html 页面，该页面提供了如何使用GIT 来克隆Jersey 的源代码的介绍。Jersey 源代码的托管地址是https://github.com/jersey/jersey（见图1-1）。
　　如图1-1 所示，Jersey 项目的源代码是使用Maven 构建的多模块项目。每个目录代表一个模块，比如core-server 目录就是Jersey 的Server 模块。bom 目录是个特殊的目录，是Maven 的元数据目录，用于多模块Maven 项目的组织和定义。通过浏览该页面可以观察到Jersey 框架的模块，本章随后会介绍Jersey 的各个模块。第2 章将对基于Maven 管理的Jersey 应用做详细的讲述和演示。
　　图1-1Jersey 源代码仓库
　　小白讲堂
　　Maven（http://maven.apache.org/ ）是Apache 开源组织的项目，该项目用于构建和组织Java 的项目。读者如果对Maven 不熟悉，推荐阅读许晓斌（Juven Xu ）所著的《Maven 实战》（机械工业出版社出版）。
　　如果读者对命令行不熟悉或者没有兴趣，可以使用GUI 工具来完成源代码的管理。对于托管在GitHub 的项目，可以使用GitHub 官方提供的客户端来管理源代码，Windows 版本下载地址：http://windows.github.com，Mac 版本下载地址：http://mac.github.com。这款工具的使用非常简单，如图1-2 所示，左侧树包括本地仓库和GitHub 远程仓库两个结点。右侧是仓库列表，示意图中包括本书的示例项目jax-rs2-guide、第11 章示例项目jax-rs2-atup 和Jersey
　　4. Jersey 项目管理
　　Jersey 使用JIRA 作为项目管理平台，地址是https://java.net/jira/browse/JERSEY。JIRA 和StackOver.ow不同的是，这个平台是Jersey 团队日常开发的管理平台，也就是说，这是Jersey 官方的缺陷管理平台，用于上报缺陷和改进意见，而不是社区性质的交流平台。我们可以从中了解到Jersey 项目的进展情况。Jersey 是一个非常活跃的项目，不仅可以从GitHub 的源代码的提交活动中看到该项目频繁的更新，在JIRA 中，也可以看到该项目推进的速度。
　　宅人坑事
　　这里为喜欢开源社区活动的读者举个例子。我在撰写本书的开始，Jersey 2.0 并不支持与Spring 的集成，因为Jersey 的IoC 容器由GlassFish 的另一个子项目HK2 来支持。随后，我在JIRA 上发现一个Jersey 2.x 支持与Spring 集成的任务被创建了（https://java.net/jira/ browse/JERSEY-1957），此后我经常观察其进展状态，最终看到了这个功能在Jersey 2.2 中以扩展包的形式发布了。因此，当使用Jersey 时，如果遇到Jersey 本身的问题，可以跟踪Jersey 的JIRA 平台来查看Bug 的修复状态，包括将在哪个版本修复，有什么样的临时解决办法（workaround）。同时，跟踪JIRA 也可以了解新版本的发布情况，包括新增哪些功能，升级给哪一部分带来性能、安全的提升等。换句话说，JIRA 展示了Jersey 项目的缺陷修复和新功能发版的计划（roadmap）。
　　5. Jersey 许可
　　开发者使用开源软件的前提是了解它的许可证版本，否则可能会带来侵权问题。相信在正规的公司，大家都有被开发管理部门的人“恐吓”的经历。开发者需感谢开发管理部门所做的工作，他们为公司规避了商业侵权的风险，因为引用的源代码如果出自“传染性”许可，该项目是不能用于闭源的商业用途的。
　　Jersey 的许可证说明地址是：https://jersey.java.net/license.html 。从中我们可以了解到Jersey 使用的是双许可证：CDDL（Common Development and Distribution License，开源通用开发和分发许可证）1.1 和GPLv2（类路径例外）许可证。双重许可是依照两套（或更多套）不同的条款和条件分发相同软件的做法。在为软件授予双重许可时，接收人可以选择他们希望依照哪种条款获得软件。使用双重许可的两个常见动机是遵循商业模式和保持许可证兼容性。GPLv2.0 许可证为无法依照CDDL 许可证使用Jersey 的供应商提供了一个额外选项。Jersey 许可证使整套产品和包保持一致（GlassFish 项目同样依照CDDL 和GPLv2（类路径例外）授予双重许可）。
　　6. Jersey 的模块
　　Jersey 框架是由核心模块、容器模块、连接器模块、Media 模块、扩展模块、测试框架模块和GlassFish Bundle 模块7 个大的模块组成。这不是一成不变的，随着Jersey 的不断发展和完善，会有新的模块加入进来。推荐读者浏览官方文档，最新版本的地址为：https://
　　jersey.java.net/documentation/latest/modules-and-dependencies.html ，从而获得最新的信息。
　　小白讲堂
　　类路径例外是由自由软件基金会的GNU/ 类路径项目制定的。它允许用户将依照任何许可证提供的应用程序链接到依照GPLv2 许可的软件中包含的库，而该应用程序不受GPL 要求公开其本身的限制。为什么需要使用类路径例外？因为作为“基于[GPL] 程序的作品”的一部分提供的所有代码还应获得 GPL 许可。因此，需要指定 GPL 许可证例外情况，以便明确将链接到GPL 实现的任何应用程序从该许可要求中排除。类路径例外实现了这一目的。
　　（1）核心模块
　　Jersey 核心模块由通用包、服务器实现和客户端实现3 个子模块组成，是使用Jersey 必需的依赖，见表1-2。
　　表1-2Jersey 核心模块列表
　　模块名称 模块说明 源代码相对目录
　　jersey-client Jersey 核心客户端实现 core-client
　　jersey-common Jersey 通用包 core-common
　　jersey-server Jersey 核心服务器实现 core-server
　　（2）容器模块
　　Jersey 提供了3 种对应于外部容器的HTTP 容器，分别是Grizzly 2 、JDK-HTTP 和SIMPLE-HTTP，Grizzly 2 同时提供了Servlet 容器。对于Servlet 的实现，Jersey 提供了对Servlet 2.x 和Servlet 3.x 两个版本的实现。它们对应的包名见表1-3，详情可参考第2 章。
　　表1-3Jersey 容器模块列表
　　模块名称 模块说明 源代码相对目录
　　jersey-container-grizzly2-http Grizzly 2 版HTTP 容器 containers/grizzly2-http
　　jersey-container-grizzly2-servlet Grizzly 2 版Servlet 容器 containers/ grizzly2-servlet
　　jersey-container-jdk-http JDK 版HTTP 容器 containers/ jdk-http
　　jersey-container-servlet Jersey 核心Servlet 3.x 实现 containers/ jersey-servlet
　　jersey-container-servlet-core Jersey 核心Servlet 2.x 实现 containers/ jersey-servlet-core
　　jersey-container-simple-http 简单版HTTP 容器 containers/simple-http
　　（3）连接器模块
　　Jersey 客户端底层依赖连接器实现网络通信，如果标准的客户端模块无法实现功能需求，可以考虑引入Grizzly 连接器或者Apache 连接器，见表1-4，详情可参考第5 章。
　　表1-4Jersey 连接器模块列表
　　模块名称 模块说明 源代码相对目录
　　jersey-grizzly-connector Jersey 客户端Grizzly 连接器 connectors/grizzly-connector
　　jersey-apache-connector Jersey 客户端Apache 连接器 connectors/apache-connector
　　（4）Media 模块
　　Jersey Media 模块是支持Jersey 处理传输数据媒体类型的模块。该模块提供了4 种处理JSON 的方式，分别是Jackson、Jettison、MOXy 和JSON-P。另外，Multipart 包用于对Form 表单的支持，SSE 用于对Server Sent Events 支持，见表1-5，详情可参考第3 章。
　　（5）扩展模块
　　Jersey 生态环境中包含了许多JAX-RS 2.0 标准之外的功能，比如MVC、Bean 验证等辅助REST 实现的模块，还有像Spring 支持包这样的对第三方框架支持的模块见表1-6。
　　表1-5Jersey Media 模块列表
　　模块名称 模块说明 源代码相对目录
　　jersey-media-json-jackson Jersey JSON Jackson 包 media/json-jackson
　　jersey-media-json-jettison Jersey JSON Jettison 包 media/json-jettison
　　jersey-media-json-processing Jersey JSON-P（JSR 353）包 media/json-processing
　　jersey-media-moxy Jersey JSON EclipseLink MOXy 包 media/moxy
　　jersey-media-multipart Jersey Multipart 支持包 media/multipart
　　jersey-media-sse Jersey Server Sent Events 支持包 media/sse
　　表1-6Jersey 扩展模块列表
　　模块名称 模块说明 源代码相对目录
　　jersey-bean-validation Bean Validation（JSR-349）支持包 ext/bean-validation
　　jersey-mvc MVC 支持包 ext/mvc
　　jersey-mvc-freemarker Freemarker 模板支持包 ext/mvc-freemarker
　　jersey-mvc-jsp JSP 模板支持包 ext/mvc-jsp
　　jersey-proxy-client 高层客户端代理支持包 ext/proxy-client
　　jersey-servlet-portability 兼容Jersey 1.x 和Jersey 2.x 的Servlet 容器支持包 ext/servlet-portability
　　jersey-wadl-doclet Javadoc 支持包 ext/wadl-doclet
　　jersey-spring3 Spring 3 支持包 ext/spring3
　　（6）测试框架模块
　　Jersey 提供了非常易用且功能强大的测试框架，见表1-7。测试框架提供了测试过程中完整的服务器端和客户端功能，通过测试框架，开发者可以减少很多模板代码的编写。详情可参考7.1 节。
　　表1-7Jersey 测试框架模块列表
　　模块名称 模块说明 源代码相对目录
　　jersey-test-framework-core Jersey 核心测试框架 test-framework /core
　　jersey-test-framework-provider-bundle 测试框架Bundle 支持包 test-framework/providers/bundle
　　jersey-test-framework-provider-default-client 测试框架客户端包 test-framework/providers/default-client
　　jersey-test-framework-provider-external 测试框架扩展容器 test-framework/providers/external
　　jersey-test-framework-provider-grizzly2 测试框架Grizzly 2 容器 test-framework/providers/grizzly2
　　（续）
　　模块名称 模块说明 源代码相对目录
　　jersey-test-framework-provider-inmemory 测试框架内存容器 test-framework/providers/inmemory
　　jersey-test-framework-provider-jdk-http 测试框架JDK 版HTTP 容器 test-framework/providers/jdk-http
　　jersey-test-framework-provider-simple 测试框架简单版HTTP 容器 test-framework/providers/simple
　　（7）GlassFish Bundle 模块GlassFish Bundle 模块是Jersey 提供的用于以Bundle 方式支持GlassFish 服务器的模块，包括CDI 和EJB 集成的扩展包，见表1-8。
　　表1-8GlassFish Bundle 模块列表
　　模块名称 模块说明 源代码相对目录
　　jersey-gf-cdi Jersey 集成GlassFish 的CDI 包 containers\glass.sh\jersey-gf-cdi
　　jersey-gf-ejb Jersey 集成 GlassFish 的EJB 包 containers\glass.sh\jersey-gf-ejb
　　宅人坑事
　　Jersey 在2.6 版本做了一次包重构，清除了对Guava 和ASM 的自然依赖。如果读者的项目需要做Jersey 版本迁移，需要注意这一点。新的包名为：jersey.repackaged.com.google. common 和 jersey.repackaged.objectweb.asm 。
　　7. GlassFish 项目
　　GlassFish 项目地址为https://glass.sh.java.net。GlassFish 比较著名的是Java EE 服务器项目Oracle GlassFish Server ，该项目还同时包含Java EE 中包含的一系列标准规范的参考实现，这些参考实现集成于GlassFish Server，为其Java EE 容器提供支持。其中对JAX-RS 2.0 的实现项目是Jersey。
　　为什么要在JAX-RS 2.0 的介绍中提及GlassFish 项目集呢？因为Jersey 处于GlassFish 生态环境中，GlassFish 又是Java EE 生态环境的实现描述。举个例子，当你需要在REST 项目中访问数据库时，也许出于首选基于标准的实现的考虑，你会选择使用JPA 。而JPA 的参考实现EclipseLink 就是GlassFish 项目集的成员。这就像在你观赏深海的一条鱼的时候，势必有兴趣了解它会以哪些生物为生，又为哪些生物提供了生存保障。通过了解GlassFish 项目，可以更好地完成REST 式的Web 服务。尤其，当你用户用NetBeans 作为开发工具时，GlassFish 服务器和GlassFish 项目集是你生产中的“日用消费品”。
　　这里所列的项目是除Jersey 以外其他的GlassFish 项目，排列顺序并不严谨，大体上以其与Jersey 的紧密关系降序排列。（1）HK2 HK2 项目地址为http://hk2.java.net。HK2 是轻量级DI 架构，实现IoC 和DI 的内核，是Jersey 实现容器内管理Bean 的基础，见表1-9。（2）Grizzly Grizzly 的项目地址为https://grizzly.java.net 。Grizzly 是一个异步I/O 的、高效而健壮的
　　服务器，可以用作HTTP 服务器、Servlet 容器，支持AJP、Comet、WebSocket ，以及相对于RESTFul 的另一种Web Service 实现JAX-WS，见表1-10。
　　如何使用和配置Grizzly 依赖于用户的需求，也就是说，用户的项目不必加载Grizzly 提供的全部jar 包。表1-11 列出了Grizzly 项目的各个模块信息，可以参考该表定义用户的项目对Grizzly 的依赖。
　　表1-9HK2 项目情况简表
　　表1-10Grizzly 项目情况简表
　　项目名称 中文直译 JSR 编号 JSR 名称 当前版本
　　Grizzly 灰熊 JSR-356 Java API for WebSocket 2.3.3
　　表1-11 Grizzly 模块列表
　　模块名称 描述
　　grizzly-framework Grizzly 核心包
　　grizzly-http-server HTTP 服务器包
　　grizzly-http-servlet Servlet 容器包
　　grizzly-portunif Port Uni.cation 包，支持 多种协议和端口的协同工作
　　grizzly-comet
　　grizzly-WebSockets WebSockets 包，支持Web Socket 协议（RFC 6455）
　　Comet 包，支持Comet 方式的BS 访问。典型的场景是长轮询
　　，可以和HTML5 协同工作
　　AJP 包，支持AJP 协议。AJP 是一种使Web 服务器和应用服务器通信的协议，典型的应用是Apache 和Tomcat 的通信
　　支持JAX-WS 标准的HTTP 服务器包
　　grizzly-http-ajp
　　grizzly-http-server-jaxws