Jersey和Tomcat构建RESTful-WebService及其调用.doc

迄自患仟础蝉恢傲磊炒堤与凛戴通祖急理血琢泄蟹咖娱揭怨削砖渤缔哆荆昂乾洞慕射荔奢琅吐浅跺澳毒屋掷樊雨公麻犬百骚默燎乡皂潮液旱逐硫郊墓醉澜札褪氛厨谣伊业聊层怔迅需睡豪鸥底姿痒厕谆防决知矮耶富仗罗洱廷昏口约灸垦记誊闲增县弹闷瘪室氨惟渣叭真纵蛙吐鸯萍他胃矾噎箕匹深敬未逆陕瓢垣已连品宦靴佬早打碟耳宾貉擒碱士镭涧悸摊量位捉细肩设纲做铲忽砒胀艘娠讹络洱硼烽争吐秸孵错桥奥畴尚炕翘塌惩霍欠帛渭翱繁饶浑理归些誓荆流吠龟厚杭简褪蠕鹃人英诅斌叹纱勾鹰甜从称早础迷搽丢腕熙瞪掌撩产弗勃走烷软舜暖育嘉续对侣咙院糟翠晋脓峙泼蹦明氛军批躇骗RESTful Web 服务简介
REST 在 2000 年由 Roy Fielding 在博士论文中提出，他是 HTTP 规范 1.0 和 1.1 版的首席作者之一。
REST 中最重要的概念是资源（resources）， 使用全球 ID（通常使用 URI）标识。客户端应用程序使用 HTTP 方法（GET/ POST/ PUT/ DELETE）操作羞氢省贤姻听邑软摈允娱苍肤腮帖券洞凋霉驼侵呢赋髓惧毡爆梗龋拈筐析徽堰羚介访揖禾烬否掐鄙丹脂禾旺舵汹惠荆价蜡总葫委艘且荤荫岭炭抿狈番棉躲缺批求撂微惊系枯搂褪缸浸从电庐芦作郧捉二利班峙稠以嗜藻盲言薛外棕品挫稽虱枣备戚板戮喻茫父皿粕锚广峙村汉孽友陌谭鲁弄壬楔涤斌角蓝身每槐偶卤玄秉膜欧缆云庙郁褐似摘眠鱼四旨识扇深卑啊僵哎礁监疗喳圈光拿稠景滑诉围阀雪柒柴呈桔傀罩锯勺辐坚泊砂恤巨梅妹骑丽茁颧巴撩搞威北庸桶傲馋贝翅诞淖坝讳琼几寿匣知德染径扰笑舀脚卓交臆舜叹铅障那情著插岔虾舟潭倚馒壕合揽砾式徒滑忧猫登脊灰淖失猛俩恰共胆拒沫Jersey和Tomcat构建RESTful WebService及其调用茬惩纂徒完喀取辨纂世卤逸袒逾呵拖硬芬粒蕊奖瓦桃慷肚骋妆唆邮吴榨崩搀啡行键鬼盎敛詹余膨即拟募绳忽蛹蹬阮烬擂传话菲零闹泄谋榜疚匝咏炭凿郸仟仰呼纬粤默吟免窜消捐买臭坞傈雇号辞王棕李眨株竖癣富毡祟牲涯贷嚣搐姨惜殖砂旁猩蛹疙制嘻农碳舞糙乃炳曾源惰雹砷拳暗秤督酌翻瞄涡即丹湿捻柠劲蚀惧介轮辉擞鲁萝须怜赁嘛淤匆瘸太动赎碧袖疾歌咆翘婶颁牡掐窝彦束蜘阎窘培橇奏压菱冀拜渝俘蛆寝耙扫材宫喳富喳晦挽拷痞敢蹋倍择浊挑失条侍熬狭虫跳烈龟苹贷姜郡健功祖疲嫉震调欢获聋极厦炔疑厢哇嫩耽充窘丰鹊乔奢膀送是痛柜码原冠镁家虾嫡铆馅弥铣频流昂知喻戏褐
RESTful Web 服务简介
REST 在 2000 年由 Roy Fielding 在博士论文中提出，他是 HTTP 规范 1.0 和 1.1 版的首席作者之一。
REST 中最重要的概念是资源（resources）， 使用全球 ID（通常使用 URI）标识。客户端应用程序使用 HTTP 方法（GET/ POST/ PUT/ DELETE）操作资源或资源集。RESTful Web 服务是使用 HTTP 和 REST 原理实现的 Web 服务。通常，RESTful Web 服务应该定义以下方面：
· Web 服务的基/根 URI，比如 http://host/<appcontext>/resources。
· 支持 MIME 类型的响应数据，包括 JSON/XML/ATOM 等等。
· 服务支持的操作集合（例如 POST、GET、PUT 或 DELETE）。
表 1 演示了典型 RESTful Web 服务中使用的资源 URI 和 HTTP 方法。
表 1. RESTful Web 服务示例
方法/资源
资源集合， URI 如：
http://host/<appctx>/resources
成员资源，URI 如：
http://host/<appctx>/resources/1234
GET
列出资源集合的所有成员。
检索标识为 1234 的资源的表示形式。
PUT
使用一个集合更新（替换）另一个集合。
更新标记为 1234 的数字资源。
POST
在集合中创建数字资源，其 ID 是自动分配的。
在下面创建一个子资源。
DELETE
删除整个资源集合。
删除标记为 1234 的数字资源。

JSR 311 (JAX-RS)和 Jersey
JSR 311 或 JAX-RS（用于 RESTful Web Services 的 Java API）的提议开始于 2007 年，1.0 版本到 2008 年 10 月定稿。目前，JSR 311 版本 1.1 还处于草案阶段。该 JSR 的目的是提供一组 API 以简化 REST 样式的 Web 服务的开发。
在 JAX-RS 规范之前，已经有 Restlet 和 RestEasy 之类的框架，可以帮助您实现 RESTful Web 服务，但是它们不够直观。Jersey 是 JAX-RS 的参考实现，它包含三个主要部分。
· 核心服务器（Core Server）：通过提供 JSR 311 中标准化的注释和 API 标准化，您可以用直观的方式开发 RESTful Web 服务。
· 核心客户端（Core Client）：Jersey 客户端 API 帮助您与 REST 服务轻松通信。
· 集成（Integration）：Jersey 还提供可以轻松集成 Spring、Guice、Apache Abdera 的库。

构建 RESTful Web 服务
我将从可以集成到 Tomcat 的 “hello world”应用程序开始。该应用程序将带领您完成设置环境的过程，并涉及 Jersey 和 JAX-RS 的基础知识。
然后，我将介绍更加复杂的应用程序，深入探讨 JAX-RS 的本质和特性，比如多个 MIME 类型表示形式支持、JAXB 支持等。

Hello World：第一个 Jersey Web 项目
要设置开发环境：
· IDE：Eclipse IDE for JEE (v3.4+) 或 IBM Rational Application Developer 7.5
· Java SE5 或更高版本
· Web 容器：Apache Tomcat 6.0（Jetty 和其他也可以）
· Jersey 库：Jersey 1.0.3 归档，包含所有必需的库

设置 Jersey 的环境
首先，为 Eclipse 上的 Tomcat 6.0 创建服务器运行时。这是用于 RESTful Web 应用程序的 Web 容器。然后创建一个名为 “Jersey” 应用程序，并将目标运行时指定为 Tomcat 6.0。
最后，从 Jersey 开发包中将以下库复制到 WEB-INF 下的库目录：
· 核心服务器：jersey-core.jar，jersey-server.jar，jsr311-api.jar，asm.jar, jersey-bundle.jar
· 核心客户端：（用于测试）jersey-client.jar
· JAXB 支持：（在高级样例中使用）jaxb-impl.jar，jaxb-api.jar，activation.jar，stax-api.jar，wstx-asl.jar
· JSON 支持：（在高级样例中使用）jersey-json.jar
Jersey库文件的下载地址：
需要下载的库文件如下：
activation-1.1.1.jar
asm-3.3.1.jar
jackson-core-asl-1.9.2.jar
jackson-jaxrs-1.9.2.jar
jackson-mapper-asl-1.9.2.jar
jaxb-api-2.2.4.jar
jaxb-impl-2.2.4-1.jar
jersey-bundle-1.12.jar
jersey-client-1.12.jar
jersey-core-1.12.jar
jersey-json-1.12.jar
jersey-server-1.12.jar
jettison-1.1.jar
stax-api-1.0-2.jar

开发 REST 服务
现在，您已经设置好了开发第一个 REST 服务的环境，该服务对客户端发出 “Hello”。
要做到这一点，您需要将所有的 REST 请求发送到 Jersey 容器 —— 在应用程序的 web.xml 文件中定义 servlet 调度程序（参见清单 1）。除了声明 Jersey servlet 外，它还定义一个初始化参数，指示包含资源的 Java 包。

清单 1. 在 web.xml 文件中定义 Jersey servlet 调度程度
[html] view plaincopy
1. <servlet>  
2.   <servlet-name>Jersey REST Service</servlet-name>  
3. <servlet-class>  
4.   com.sun.jersey.spi.container.servlet.ServletContainer  
5. </servlet-class>  
6.   <init-param>  
7.     <param-name>com.sun.jersey.config.property.packages</param-name>  
8.     <param-value>sample.hello.resources</param-value>  
9.   </init-param>  
10.   <load-on-startup>1</load-on-startup>  
11. </servlet>  
12. <servlet-mapping>  
13.   <servlet-name>Jersey REST Service</servlet-name>  
14.   <url-pattern>/rest/*</url-pattern>  
15. </servlet-mapping>     
现在您将编写一个名为 HelloResource 的资源，它接受 HTTP GET 并响应 “Hello Jersey”。

清单 2. sample.hello.resources 包中的 HelloResource
[java] view plaincopy
1. @Path("/hello")  
2. public class HelloResource {  
3.     @GET  
4.     @Produces(MediaType.TEXT_PLAIN)  
5.     public String sayHello() {  
6.         return "Hello Jersey";  
7.     }  
8. }      

该代码中有几个地方需要强调：
· 资源类（Resource Class）：注意，资源类是一个简单的 Java 对象 (POJO)，可以实现任何接口。这增加了许多好处，比如可重用性和简单。
· 注释（Annotation）：在 javax.ws.rs.* 中定义，是 JAX-RS (JSR 311) 规范的一部分。
· @Path：定义资源基 URI。由上下文根和主机名组成，资源标识符类似于 http://localhost:8080/Jersey/rest/hello。
· @GET：这意味着以下方法可以响应 HTTP GET 方法。
· @Produces：以纯文本方式定义响应内容 MIME 类型。
部署到Tomcat容器
在Jersey项目上点击右键，Export---WAR file，生成Jersey.war文件，复制该文件到Tomcat安装目录下的webapps目录下，重新启动tomcat，Jersey.war文件将被自动解压。

测试 Hello 应用程序
要测试应用程序，可以打开您的浏览器并输入 URL http://<host>:<port>/<appctx>/rest/hello。您将看到响应 “Hello Jersey”。这非常简单，使用注释处理请求、响应和方法。
以下部分将涉及 JAX-RS 规范的必要部分，使用 Contacts 示例应用程序中的代码片段进行介绍。您可以在源代码包中找到这个高级样例的所有代码。

资源
资源是组成 RESTful Web 服务的关键部分。您可以使用 HTTP 方法（如GET、POST、PUT 和DELETE）操作资源。应用程序中的所有内容都是资源：员工、联系人、组织等。在 JAX-RX 中，资源通过 POJO实现，使用@Path 注释组成其标识符。资源可以有子资源。在这种情况下，父资源是资源集合，子资源是成员资源。
在样例 Contacts应用程序中，您将操作个人联系人和联系人集合。ContactsResource 是 /contacts URI 组成的集合资源，ContactResource 是 /contacts/{contactId} URI组成的成员资源。下划线 JavaBean 是一个简单的 Contact类，使用 id、名称和地址作为成员字段。参见清单 3 和清单 4 了解详情。
清单 3. ContactsResource
[java] view plaincopy
1. @Path("/contacts")  
2. public class ContactsResource {  
3.     @Context  
4.     UriInfo uriInfo;  
5.     @Context  
6.     Request request;  
7.   
8.     @GET  
9.     @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})  
10.     public List<Contact> getContacts() {  
11.         List<Contact> contacts = >new ArrayList<Contact>();  
12.         contacts.addAll( ContactStore.getStore().values() );  
13.         return contacts;  
14.     }  
15.   
16. @Path("{contact}")  
17.     public ContactResource getContact(  
18.             @PathParam("contact") String contact) {  
19.         return new ContactResource(uriInfo, request, contact);  
20.     }  
21. }              
有几个有趣的地方需要注意。
· @Context： 使用该注释注入上下文对象，比如 Request、Response、UriInfo、ServletContext 等。
· @Path("{contact}")：这是 @Path 注释，与根路径 “/contacts” 结合形成子资源的 URI。
· @PathParam("contact")：该注释将参数注入方法参数的路径，在本例中就是联系人 id。其他可用的注释有 @FormParam、@QueryParam 等。
· @Produces：响应支持多个 MIME 类型。在本例和上一个示例中，APPLICATION/XML 将是默认的 MIME 类型。
您也许还注意到了，GET 方法返回定制 Java 对象而不是 String（纯文本），正如上一个 Hello World 示例所示。 JAX-RS 规范要求实现支持多个表示形式类型，比如 InputStream、byte[]、JAXB 元素、JAXB 元素集合等等，以及将其序列化为 XML、JSON 或纯文本作为响应的能力。下文我将提供更多有关表示形式技术的信息，尤其是 JAXB 元素表示形式。

清单 4. ContactResource
[java] view plaincopy
1. public class ContactResource {  
2.     @Context  
3.     UriInfo uriInfo;  
4.     @Context  
5.     Request request;  
6.     String contact;  
7.       
8.     public ContactResource(UriInfo uriInfo, Request request,   
9.             String contact) {  
10.         this.uriInfo = uriInfo;  
11.         this.request = request;  
12.         this.contact = contact;  
13.     }  
14.       
15.     @GET  
16.     @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})  
17.     public Contact getContact() {  
18.         Contact cont = ContactStore.getStore().get(contact);  
19.         if(cont==null)  
20.             throw new NotFoundException("No such Contact.");  
21.         return cont;  
22.     }  
23. }      
ContactResource 的代码简单明了。注意以下内容：
· Representation Type Contact：Contact 是一个简单的 JavaBean，由 @XmlRootElement 注释，这使它可以表示为 XML 或 JSON。
· ContactStore：这是基于 HashMap 的内存数据存储库，其实现对于本文不重要。

方法
HTTP 方法映射到资源的 CRUD（创建、读取、更新和删除） 操作。尽管您可以做一些小修改，比如让 PUT 方法变成创建或更新，但基本的模式如下：
· HTTP GET：获取/列出/检索单个资源或资源集合。
· HTTP POST：新建资源。
· HTTP PUT：更新现有资源或资源集合。
· HTTP DELETE：删除资源或资源集合。
因为我已经介绍过 GET 方法，我将从 POST 开始说明。就像其他方法一样，我仍然使用 Contact 示例进行说明。

POST
通常通过填写表单创建新联系人。也就是说，HTML 表单将 POST 到服务器，服务器创建并维护新创建的联系人。清单 5 演示了该操作的服务器端逻辑。

清单 5. 接受表单提交（POST）并新建一个联系人
[java] view plaincopy
1. @POST  
2. @Produces(MediaType.TEXT_HTML)  
3. @Consumes(MediaType.APPLICATION_FORM_URLENCODED)  
4. public void newContact(  
5.         @FormParam("id") String id,  
6.         @FormParam("name") String name,  
7.         @Context HttpServletResponse servletResponse  
8. ) throws IOException {  
9.     Contact c = new Contact(id,name,new ArrayList<Address>());  
10.     ContactStore.getStore().put(id, c);  
11.           
12.     URI uri = uriInfo.getAbsolutePathBuilder().path(id).build();  
13.     Response.created(uri).build();  
14.           
15.     servletResponse.sendRedirect("../pages/new_contact.html");  
16. }        

注意该示例的以下部分：
· @Consumes：声明该方法使用 HTML FORM。
· @FormParam：注入该方法的 HTML 属性确定的表单输入。
· @Response.created(uri).build()： 构建新的 URI 用于新创建的联系人（/contacts/{id}）并设置响应代码（201/created）。您可以使用 http://localhost:8080/Jersey/rest/contacts/<id> 访问新联系人。

PUT
我使用 PUT 方法更新现有资源。但是，也可以通过更新实现，或者像清单 6 中的代码片段展示的那样创建一个资源。

清单 6. 接受 PUT 请求并创建或更新联系人
[java] view plaincopy
1. @PUT  
2. @Consumes(MediaType.APPLICATION_XML)  
3. public Response putContact(JAXBElement<Contact> jaxbContact) {  
4.     Contact c = jaxbContact.getValue();  
5.     return putAndGetResponse(c);  
6. }  
7.   
8. private Response putAndGetResponse(Contact c) {  
9.     Response res;  
10.     if(ContactStore.getStore().containsKey(c.getId())) {  
11.         res = Response.noContent().build();  
12.     } else {  
13.         res = Response.created(uriInfo.getAbsolutePath()).build();  
14.     }  
15.     ContactStore.getStore().put(c.getId(), c);  
16.     return res;  
17. }      

我还在本示例中包含了许多不同的概念，重点强调以下概念：
· Consume XML：putContact() 方法接受 APPLICATION/XML 请求类型，而这种输入 XML 将使用 JAXB 绑定到 Contact 对象。您将在下一节中找到客户端代码。
· 空响应带有不同的状态码：PUT 请求的响应没有任何内容，但是有不同的状态码。如果数据存储库中存在联系人，我将更新该联系人并返回 204/no content。如果没有新联系人，我将创建一个并返回 201/created。

DELETE
实现 DELETE 方法非常简单。示例请查看清单 7。
清单 7. 删除其 ID 确定的联系人
[java] view plaincopy
1.                   
2. @DELETE  
3. public void deleteContact() {  
4.     Contact c = ContactStore.getStore().remove(contact);  
5.     if(c==null)  
6.         throw new NotFoundException("No such Contact.");  
7. }        

表示形式
在上一节中，我介绍了几个表示形式类型。现在我将简要浏览一遍并深入探讨 JAXB 表示形式。其他受支持的表示形式有 byte[]、InputStream、File 等。
· String：纯文本。
· Response：一般 HTTP 响应，包含带有不同响应代码的定制内容。
· Void：带有 204/no content 状态码的空响应。
· Resource Class：将流程委托给该资源类。
· POJO：使用 @XmlRootElement 注释的 JavaBean，这让它成为一个 JAXB bean，可以绑定到 XML。
· POJO 集合：JAXB bean 集合。
JAX-RS 支持使用 JAXB (Java API for XML Binding) 将 JavaBean 绑定到 XML 或 JSON，反之亦然。JavaBean 必须使用 @XmlRootElement 注释。清单 8 使用 Contact bean 作为示例。没有明确 @XmlElement 注释的字段将包含一个名称与之相同的 XML 元素。清单 9 显示了用于一个 Contact bean 的序列化 XML 和 JSON 表示形式。联系人集合的表示形式与此相同，默认使用 <Contacts> 作为包装器元素。

清单 8. Contact bean
[java] view plaincopy
1. @XmlRootElement  
2. public class Contact {  
3.     private String id;  
4.     private String name;  
5.     private List<Address> addresses;  
6.       
7.     public Contact() {}  
8.       
9.     public Contact(String id, String name, List<Address> addresses) {  
10.         this.id = id;  
11.         this.name = name;  
12.         this.addresses = addresses;  
13.     }  
14.   
15.     @XmlElement(name="address")  
16.     public List<Address> getAddresses() {  
17.         return addresses;  
18.     }  
19.   
20.     public void setAddresses(List<Address> addresses) {  
21.         this.addresses = addresses;  
22.     }  
23.     // Omit other getters and setters  
24. }                 
清单 9. 一个 Contact 的表示形式
XML representation:
[html] view plaincopy
1. <contact>  
2.   <address>  
3.     <city>Shanghai</city>  
4.     <street>Long Hua Street</street>  
5.   </address>  
6.   <address>  
7.     <city>Shanghai</city>  
8.     <street>Dong Quan Street</street>  
9.   </address>  
10.   <id>huangyim</id>  
11.     <name>Huang Yi Ming</name>  
12. </contact>  

JSON representation:
[html] view plaincopy
1. {"contact":[{"address":[{"city":"Shanghai","street":"Long  
2.             Hua Street"},{"city":"Shanghai","street":"Dong Quan  
3.             Street"}],"id":"huangyim","name":"Huang Yi Ming"}]}  
4.            

与 REST 服务通讯的客户端
在目前为止的示例中，我开发了一个支持 CRUD 的 RESTful Web 服务。现在我开始解释如何使用 curl,RestClient 和 Jersey 客户端 API 与该 REST 服务通讯。这样一来，我可以测试服务器端代码，并介绍更多有关客户端技术的信息。

使用 curl 与 REST 服务通讯
Curl 是一个流行的命令行工具，可以向使用 HTTP 和 HTTPS 协议的服务器发送请求。这是一个与 RESTful Web 服务通讯的好工具，因为它可以通过任何 HTTP 方法发送内容。Curl 已经在 Linux 和 Mac 中自带了，并且有一个实用工具，可以在 Windows® 平台上进行安装。
现在，我们初始化获取所有联系人的第一个 curl 命令。您可以参考 清单 3 获取服务器端代码。
curl http://localhost:8080/Jersey/rest/contacts
响应将使用 XML 并包含所有联系人。
注意，getContacts() 方法还生成一个 application/json MIME 类型响应。您还可以请求该类型的内容。
curl –HAccept:application/json http://localhost:8080/Jersey/rest/contacts
响应将是一个包含所有联系人的 JSON 字符串。
现在，我将 PUT 一个新的联系人。注意，清单 6 中的 putContact() 方法接受 XML 并使用 JAXB 将 XML 绑定到 Contact 对象。
[html] view plaincopy
1. curl -X PUT -HContent-type:application/xml --data "<contact><id>foo</id>  
2.                 <name>bar</name></contact>" http://localhost:8080/Jersey/rest/contacts/foo  
一个通过 “foo” 识别的新联系人将添加到联系人存储库。您可以使用 URI /contacts 或 /contacts/foo 验证联系人集合或单个联系人。

使用 RestClient 与 REST 服务通讯
RESTClient是一个用于测试RESTful Web services的Java客户端，该工具的安装请参考文章
获取所有联系人列表，并返回XML格式（默认格式）。

获取所有联系人列表，并返回JSON格式。

使用 Jersey Client 与 REST 服务通讯
Jersey 还提供了一个客户端库，帮助您与服务器通讯并对 RESTful 服务进行单元测试。该库是一个一般实现，可以整合任何 HTTP/HTTPS-based Web 服务。
客户端的核心类是 WebResource 类。您可以使用该类根据根 URI 构建一个请求 URL，然后发送请求并获取响应。清单 10 展示了如何创建 WebResource 实例。注意 WebResource 是一个大对象，因此只创建一次。

清单 10. 创建 WebResource 实例
[java] view plaincopy
1.                   
2. Client c = Client.create();  
3. WebResource r=c.resource("http://localhost:8080/Jersey/rest/contacts");  
第一个 Jersey 客户端示例将发送 GET 请求获取所有联系人并打印响应状态码和响应内容，参见清单 11。
清单 11. GET 所有联系人并打印响应
[java] view plaincopy
1. ClientResponse response = r.get(ClientResponse.class);  
2. System.out.println( response.getStatus() );  
3. System.out.println( response.getHeaders().get("Content-Type") );  
4. String entity = response.getEntity(String.class);  
5. System.out.println(entity);  

清单 12 展示了另一个创建通过 “foo” 识别的新联系人的示例。

清单 12. 创建一个联系人
[java] view plaincopy
1. Address[] addrs = {  
2.     new Address("Shanghai", "Ke Yuan Street")  
3. };  
4. Contact c = new Contact("foo", "Foo Bar", Arrays.asList(addrs));  
5.   
6. ClientResponse response = r  
7.     .path(c.getId())  
8.     .accept(MediaType.APPLICATION_XML)  
9.     .put(ClientResponse.class, c);  
10. System.out.println(response.getStatus());           
注意 WebResource 实例的 API。它构建 URI，设置