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節。