Java RESTful Web Service实战（第2版） 1.3 解读JAX-RS标准

<b>1.3　解读jax-rs标准</b>

jax-rs是java领域的rest式的web服务的标准规范，是使用java完成rest服务的基本约定。

<b>1.3.1　jax-rs2标准</b>

java领域中的web service是指实现soap协议的jax-ws。直到java ee 6（发布于2008年9月）通过jcp（java

community process）组织定义的jsr311（http://www.jcp.org/en/jsr/detail?id=311），才将rest在java领域标准化。

jsr311名为the java api for

restful web service，即jax-rs，其参考实现是glassfish项目中的jersey1.0。此后，jsr311进行了一次升级（2009年9月），即jax-rs1.1。jax-rs诞生后，时隔5年（2013年5月）发布的java ee7包含了jsr339，将jax-rs升级到jax-rs2（http://www.jcp.org/en/jsr/detail?id=339）。jax-rs2.0在前面版本的基础上增加了很多实用性的功能，比如对rest客户端api的定义，异步rest等，对rest的支持更加完善和强大。

jax-rs的版本对应的参考实现jersey项目版本信息参见表1-1。

表1-1　jax-rs标准和jersey版本信息

jsr标准  jsr名称  标准发布时间         jsr实现

jsr311       jax-rs

1.0        2008年9月8日    jersey1.x

1.1        2009年9月17日  jersey1.x

jsr339       jax-rs

2.0        2013年5月22日  jersey2.x

<b>1.3.2　jax-rs2的目标</b>

jax-rs2标准（即jsr339）中定义了目标、非目标和元素等内容。jsr339标准中的这部分内容通常被以实现业务功能为目的的开发人员所忽视，在此和读者分享的一个开发经验是：要掌握一项技术，先要掌握它背后标准的定义。首先我们来看看jax-rs2的目标。

1）基于pojo：jax-rs2的api提供一组注解（annotation）和相关的接口、类，并定义了pojo（plain ordinary java object）对象的生命周期和作用域。规定使用pojo来公布web资源。

2）以http为中心：jax-rs2采用http协议，并提供清晰的http和统一资源定位（uri）元素来映射相关的api类和注解。jax-rs2的api不但支持通用的http使用模式，还对webdav和atom等扩展协议提供灵活的支持。

3）格式独立性：jax-rs2对传输数据（http

entity）的类型/格式的支持非常宽泛，允许在标准风格之上使用额外的数据类型。

4）容器独立性：jax-rs2的应用可以部署在各种servlet容器中，比如tomcat/jetty，也可以部署在支持jax-ws的容器中，比如glassfish。

5）内置于java ee：jax-rs2是java ee规范的一部分，它定义了在一个java ee容器内的web资源类的内部，如何使用java ee的功能和组件。

阅读指南

webdav（web-based

distributed authoring and versioning，基于web的分布式创作和版本控制）是ietf组织的rfc2518协议。webdav基于并扩展了http

1.1，在http标准方法以外添加了以下内容。

mkcol：创建集合。

propfind/proppatch：针对资源和集合检索和设置属性。

copy/move：管理命名空间上下文中的集合和资源。

lock/unlock：改写保护，支持文件的版本控制。

针对在rest风格的web服务中是否应该使用webdav，业内的声音并不一致，持反对意见的主要观点是webdav带来了非统一的接口，这违背了rest的初衷。本书的示例将不采用webdav，但文字部分将讲述如何支持webdav。atom类型传输格式将在2.3节讲述。

<b>1.3.3　非jax-rs2的目标</b>

那么哪些不是jax-rs2的目标呢？

1）对j2se 6.0之前版本的支持：jax-rs2中大量使用了注解（annotation），需要j2se 6.0以及更新的版本，因此不提供对j2se 6.0以下版本的支持。

2）对服务的描述、注册和探测：jax-rs2没有定义也无须支持任何服务的描述（description）、服务的注册（registration）和服务的探测（discovery）。

3）http协议栈：jax-rs2没有定义新的http协议栈。承载jax-rs2应用的容器提供对http协议的支持。

4）数据类型/格式类：jax-rs2没有定义处理实体内容的类，它将这一类型的类交由使用jax-rs2的应用中的类去实现。

<b>1.3.4　解读jax-rs元素</b>

最后，我们来看看jax-rs2中定义了哪些元素。

1）资源类：使用jax-rs注解来实现相关web资源的java类。如果用mvc的三层结构来解读，那么资源类位于最前端，用于接收请求和返回响应。通常，但不是约定，我们使用resource作为包名，三层的包定义形如：resource-service-dao。

2）根资源类：使用@path注解，提供资源类树的根资源及其子资源的访问。资源类分为根资源类和子资源类，由于jersey默认提供wadl（参见1.6节），每个应用公布的全部资源接口可以通过wadl页面查阅。

3）请求方法标识符：使用运行期注解@httpmethod，用来标识处理资源的http请求方法。该方法将使用资源类的相应方法处理，标准的方法包括delete、get、head、options、post、put，详见2.1节。

4）资源方法：资源类中定义的方法使用了请求方法标识符，用来处理相关资源的请求。就是上面提到的资源类的相应方法。

5）子资源标识符：资源类中定义的方法，用来定位相关资源的子资源。

6）子资源方法：资源类中定义的方法，用来处理相关资源的子资源的请求。

7）provider：一种jax-rs扩展接口的实现类，扩展了jax-rs运行期的能力。第4章详述了各种provider及其实现。

8）filter：一种用于过滤请求和响应的provider，详见3.3节。

9）entity interceptor：一种用于处理拦截消息读写的provider，详见3.5节。

10）invocation：一种用于配置发布http请求的客户端api对象，详见5.1.3节。

11）webtarget：一种使用uri标识的invocation容器对象，详见5.1.2节。

12）link：一种携带元数据的uri，包括媒体类型、关系和标题等，详见2.4节。