在Eclipse中使用Jersey和Tomcat构建RESTful WebService及其调用

java 同时被 2 个专栏收录
21 篇文章 0 订阅
7 篇文章 0 订阅

在Eclipse中使用Jersey和Tomcat构建RESTful WebService及其调用

分类: 16_JAVA 9366人阅读 评论(2) 收藏 举报

在Eclipse中使用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库文件的下载地址:http://jersey.java.net/nonav/documentation/latest/chapter_deps.html

需要下载的库文件如下:

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 调度程度

  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

  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 方法(如GETPOSTPUTDELETE)操作源。用程序中的所有内容都是源:工、系人、组织等。在 JAX-RX 中,源通 POJO实现,使用@Path释组成其标识符源可以有子源。在种情况下,父源是源集合,子源是成员资源。

例 Contacts用程序中,您将操作个人系人和系人集合。ContactsResource 是 /contacts URI 成的集合源,ContactResource 是 /contacts/{contactId} URI成的成员资源。下划线 JavaBean 是一个简单的 Contact,使用 id、名称和地址作字段。参 3 和清 4 了解情。

单 3. ContactsResource

  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

  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)并新建一个联系人

  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 请求并创建或更新联系人

  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 确定的联系人

  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

  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:

  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:

  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 对象。

  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客户端,该工具的安装请参考文章http://blog.csdn.net/zztfj/article/details/7588330

获取所有联系人列表,并返回XML格式(默认格式)。



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


 

 

使用 Jersey Client 与 REST 服务通讯

Jersey 还提供了一个客户端库,帮助您与服务器通讯并对 RESTful 服务进行单元测试。该库是一个一般实现,可以整合任何 HTTP/HTTPS-based Web 服务。

客户端的核心类是 WebResource 类。您可以使用该类根据根 URI 构建一个请求 URL,然后发送请求并获取响应。清单 10 展示了如何创建 WebResource 实例。注意 WebResource 是一个大对象,因此只创建一次。


单 10. 创建 WebResource 实例

  1.                   
  2. Client c = Client.create();  
  3. WebResource r=c.resource("http://localhost:8080/Jersey/rest/contacts");  

第一个 Jersey 客户端示例将发送 GET 请求获取所有联系人并打印响应状态码和响应内容,参见清单 11。

单 11. GET 所有联系人并打印响应

  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. 创建一个联系人

  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,设置请求头,并在一行代码中调用请求。内容(Contact 对象)将自动绑定到 XML。

清单 13 展示了检索通过 “foo” 识别的联系人(已上一个示例中创建)的最后一个示例然后删除该联系人。


单 13. 检索 “foo” 联系人并删除

  1. GenericType<JAXBElement<Contact>> generic = new GenericType<JAXBElement<Contact>>() {};  
  2. JAXBElement<Contact> jaxbContact = r  
  3.     .path("foo")  
  4.     .type(MediaType.APPLICATION_XML)  
  5.     .get(generic);  
  6. Contact contact = jaxbContact.getValue();  
  7. System.out.println(contact.getId() + ": " + contact.getName());  
  8.   
  9. ClientResponse response = r.path("foo").delete(ClientResponse.class);  
  10. System.out.println(response.getStatus());    


 

注意,当您想获取 JAXB bean 响应时,您需要使用 Java 2 Platform, Standard Edition (J2SE) 中引入的范型特性。



Jersey jar库文件的下载地址:http://download.csdn.net/detail/zztfj/4334371

本文的源代码下载:http://download.csdn.net/detail/zztfj/4334425

 

 

 

 

 

  • 0
    点赞
  • 0
    评论
  • 0
    收藏
  • 扫一扫,分享海报

©️2022 CSDN 皮肤主题:大白 设计师:CSDN官方博客 返回首页
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

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

余额充值