芈月传 太后是谁:使用 Jersey 和 Apache Tomcat 构建 RESTful Web 服务

回页首

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-client.jar
• JAXB 支持：（在高级样例中使用）jaxb-impl.jar，jaxb-api.jar，activation.jar，stax-api.jar，wstx-asl.jar
• JSON 支持：（在高级样例中使用）jersey-json.jar

开发 REST 服务

现在，您已经设置好了开发第一个 REST 服务的环境，该服务对客户端发出 “Hello”。

要做到这一点，您需要将所有的 REST 请求发送到 Jersey 容器 —— 在应用程序的 web.xml 文件中定义 servlet 调度程序（参见清单 1）。除了声明 Jersey servlet 外，它还定义一个初始化参数，指示包含资源的 Java 包。

  Jersey REST Service  com.sun.jersey.spi.container.servlet.ServletContainer      com.sun.jersey.config.property.packages    sample.hello.resources    1  Jersey REST Service  /rest/*            

现在您将编写一个名为 HelloResource 的资源，它接受 HTTP GET 并响应 “Hello Jersey”。

@Path("/hello")public class HelloResource {@GET@Produces(MediaType.TEXT_PLAIN)public String sayHello() {return "Hello Jersey";}}            

该代码中有几个地方需要强调：

• 资源类（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 类型。

测试 Hello 应用程序

要测试应用程序，可以打开您的浏览器并输入 URL http://://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 了解详情。您还可以从本文最后下载完整的代码包（参见 下载）。

@Path("/contacts")public class ContactsResource {@ContextUriInfo uriInfo;@ContextRequest request;@GET@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})public List getContacts() {List contacts = >new ArrayList();contacts.addAll( ContactStore.getStore().values() );return contacts;}@Path("{contact}")public ContactResource getContact(@PathParam("contact") String contact) {return new ContactResource(uriInfo, request, contact);}}            

有几个有趣的地方需要注意。

• @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 元素表示形式。

public class ContactResource {@ContextUriInfo uriInfo;@ContextRequest request;String contact;public ContactResource(UriInfo uriInfo, Request request, String contact) {this.uriInfo = uriInfo;this.request = request;this.contact = contact;}@GET@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})public Contact getContact() {Contact cont = ContactStore.getStore().get(contact);if(cont==null)throw new NotFoundException("No such Contact.");return cont;}}            

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 演示了该操作的服务器端逻辑。

@POST@Produces(MediaType.TEXT_HTML)@Consumes(MediaType.APPLICATION_FORM_URLENCODED)public void newContact(@FormParam("id") String id,@FormParam("name") String name,@Context HttpServletResponse servletResponse) throws IOException {Contact c = new Contact(id,name,new ArrayList
());ContactStore.getStore().put(id, c);URI uri = uriInfo.getAbsolutePathBuilder().path(id).build();Response.created(uri).build();servletResponse.sendRedirect("../pages/new_contact.html");}            

注意该示例的以下部分：

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

PUT

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

@PUT@Consumes(MediaType.APPLICATION_XML)public Response putContact(JAXBElement jaxbContact) {Contact c = jaxbContact.getValue();return putAndGetResponse(c);}private Response putAndGetResponse(Contact c) {Response res;if(ContactStore.getStore().containsKey(c.getId())) {res = Response.noContent().build();} else {res = Response.created(uriInfo.getAbsolutePath()).build();}ContactStore.getStore().put(c.getId(), c);return res;}            

我还在本示例中包含了许多不同的概念，重点强调以下概念：

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

DELETE

实现 DELETE 方法非常简单。示例请查看清单 7。

@DELETEpublic void deleteContact() {Contact c = ContactStore.getStore().remove(contact);if(c==null)throw new NotFoundException("No such Contact.");}            

表示形式

在上一节中，我介绍了几个表示形式类型。现在我将简要浏览一遍并深入探讨 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 表示形式。联系人集合的表示形式与此相同，默认使用 作为包装器元素。

@XmlRootElementpublic class Contact {private String id;private String name;private List
 addresses;public Contact() {}public Contact(String id, String name, List
 addresses) {this.id = id;this.name = name;this.addresses = addresses;}@XmlElement(name="address")public List
 getAddresses() {return addresses;}public void setAddresses(List
 addresses) {this.addresses = addresses;}// Omit other getters and setters}               

XML representation:  
    Shanghai    Long Hua Street  
  
    Shanghai    Dong Quan Street  
  huangyim    Huang Yi MingJSON representation:{"contact":[{"address":[{"city":"Shanghai","street":"Long            Hua Street"},{"city":"Shanghai","street":"Dong Quan            Street"}],"id":"huangyim","name":"Huang Yi Ming"}]}         

对于使用 JAXB 的更高主题，请查看 参考资料 中的项目主页。

回页首

与 REST 服务通讯的客户端

在目前为止的示例中，我开发了一个支持 CRUD 的 RESTful Web 服务。现在我开始解释如何使用 curl 和 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 对象。

curl -X PUT -HContent-type:application/xml --data "foo                bar" http://localhost:8080/Jersey/rest/contacts/foo

一个通过 “foo” 识别的新联系人将添加到联系人存储库。您可以使用 URI /contacts 或 /contacts/foo 验证联系人集合或单个联系人。

使用 Jersey Client 与 REST 服务通讯

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

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

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

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

ClientResponse response = r.get(ClientResponse.class);System.out.println( response.getStatus() );System.out.println( response.getHeaders().get("Content-Type") );String entity = response.getEntity(String.class);System.out.println(entity);                

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

Address[] addrs = {new Address("Shanghai", "Ke Yuan Street")};Contact c = new Contact("foo", "Foo Bar", Arrays.asList(addrs));ClientResponse response = r.path(c.getId()).accept(MediaType.APPLICATION_XML).put(ClientResponse.class, c);System.out.println(response.getStatus());            

注意 WebResource 实例的 API。它构建 URI，设置请求头，并在一行代码中调用请求。内容（Contact 对象）将自动绑定到 XML。

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

GenericType> generic = new GenericType>() {};JAXBElement jaxbContact = r.path("foo").type(MediaType.APPLICATION_XML).get(generic);Contact contact = jaxbContact.getValue();System.out.println(contact.getId() + ": " + contact.getName());ClientResponse response = r.path("foo").delete(ClientResponse.class);System.out.println(response.getStatus());            

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

使用 Jersey 客户端练习这些示例。您可以在资源包中找到更多样例代码（见 下载）。还可以参考 Jersey 网站查看更多信息（见 参考资料）。

回页首

结束语

Jersey 可以使用 Jersey 集成库与其他框架或实用工具库集成。目前，Jersey 可以集成 Spring、Guice，还支持 ATOM 表示形式与 apache-adbera 的集成。在 Jersey 项目主页可以找到 API 和入门指南。

回页首

下载

关于下载方法的信息

参考资料

学习

• 在 Wikipedia 上查找有关 REST 的介绍和其他相关链接。
  
  
• 查看 Rational Application Developer 试用版。
  
  
• 阅读有关 Jersey client API 的内容以获取更多信息。
  
  
• 可以从 Java Community Process 获取更多有关 JAX-RS (JSR 311) 的信息。
  
  
• JAXB Reference Implementation Project 提供了更多有关 JAXB 的信息。
  
  
• developerWorks 技术活动和网络广播：随时关注 developerWorks 技术活动和网络广播。
  
  
• developerWorks Web development 专区：通过专门关于 Web 技术的文章和教程，扩展您在网站开发方面的技能。
  
  

获得产品和技术

• 从 项目网站 下载 Eclipse。
  
  
• 从 公司网站 获取 Java SE 5.0。
  
  
• 从 项目网站 下载 Apache Tomcat。
  
  
• 可以在 Jersey 项目主页 上查找下载、样例代码归档、用户指南和 JAX-RS API 文档。
  
  
• 获取 curl for Windows。
  
  

作者简介

Yi Ming Huang 是在 China Development Lab 从事 Lotus ActiveInsight 的软件工程师。他擅长与 Portlet/Widget 相关的 Web 开发并对 REST、OSGi 和 Spring 技术感兴趣。

Dong Fei Wu 是 IBM 中国软件开发试验室 IBM WebSphere Dashboard Framework 开发团队的一名软件工程师。他负责设计和开发 WebSphere Dashboard Framework 的基本版本。

Qing Guo 是 IBM WebSphere Dashboard Framework 的开发主管。他在 J2EE 领域有丰富的经验。

为本文评分

平均分 (16个评分)

1 星1 星
2 星2 星
3 星3 星
4 星4 星
5 星5 星

评论

添加评论:

请 登录 或 注册 后发表评论。

注意：评论中不支持 HTML 语法

快来添加第一条评论

回页首

内容

• RESTful Web 服务简介
• JSR 311 (JAX-RS) 和 Jersey
• 构建 RESTful Web 服务
• 资源
• 方法
• 与 REST 服务通讯的客户端
• 结束语
• 下载
• 参考资料
• 作者简介
• 建议

标签

热门文章标签 | 
我的文章标签跳转到标签列表

热门标签

• 3 (3)  
• accessibility (7)  
• ajax (152)  
• apache (10)  
• api (8)  
• aws (4)  
• canvas (4)  
• codeigniter (4)  
• comet (17)  
• css (7)  
• css_(cascading... (6)  
• css3 (5)  
• data_mining (7)  
• dhtml_(dynam... (51)  
• dojo (20)  
• ecmascript (5)  
• firefox (3)  
• flex (14)  
• flex学习 (4)  
• gwt (3)  
• hadoop (5)  
• html (5)  
• html5 (8)  
• http (3)  
• ibm_software_d... (4)  
• java (9)  
• java_技术 (58)  
• javascript (174)  
• jetty (4)  
• jquery (7)  
• json (16)  
• jsp_(javaserv... (10)  
• php (6)  
• php_(hypertex... (10)  
• rest (7)  
• restful (5)  
• soa_(service-o... (5)  
• spring (6)  
• struts (6)  
• web (41)  
• web_authoring (9)  
• web_服务 (24)  
• web_应用 (5)  
• web开发 (8)  
• xhtml_(extens... (18)  
• xml (110)  
• 安全 (11)  
• 编码 (5)  
• 部分: (5)  
• 多媒体 (8)  
• 访问 (26)  
• 访问控制 (6)  
• 基于 (4)  
• 集成 (7)  
• 集成架构 (11)  
• 技巧 (96)  
• 解析器 (4)  
• 可用性 (9)  
• 框架 (6)  
• 内容管理 (5)  
• 企业架构 (4)  
• 社区 (8)  
• 使用 (9)  
• 数据库和数据管理 (8)  
• 数字媒体 (5)  
• 体系架构 (34)  
• 推荐引擎 (14)  
• 系统管理 (11)  
• 协作 (10)  
• 信息架构 (6)  
• 性能 (16)  
• 验证 (5)  
• 业务建模 (4)  
• 应用和信息整合 (14)  
• 应用集成 (81)  
• 应用架构 (37)  
• 应用开发 (21)  
• 用户界面 (103)  
• 优化 (4)  
• 组件 (18)  

热门标签结束

我的标签

我的标签结束

更多更少

• 3 (3)  
• accessibility (7)  
• ajax (152)  
• apache (10)  
• api (8)  
• aws (4)  
• canvas (4)  
• codeigniter (4)  
• comet (17)  
• css (7)  
• css_(cascading... (6)  
• css3 (5)  
• data_mining (7)  
• dhtml_(dynam... (51)  
• dojo (20)  
• ecmascript (5)  
• firefox (3)  
• flex (14)  
• flex学习 (4)  
• gwt (3)  
• hadoop (5)  
• html (5)  
• html5 (8)  
• http (3)  
• ibm_software_d... (4)  
• java (9)  
• java_技术 (58)  
• javascript (174)  
• jetty (4)  
• jquery (7)  
• json (16)  
• jsp_(javaserv... (10)  
• php (6)  
• php_(hypertex... (10)  
• rest (7)  
• restful (5)  
• soa_(service-o... (5)  
• spring (6)  
• struts (6)  
• web (41)  
• web_authoring (9)  
• web_服务 (24)  
• web_应用 (5)  
• web开发 (8)  
• xhtml_(extens... (18)  
• xml (110)  
• 安全 (11)  
• 编码 (5)  
• 部分: (5)  
• 多媒体 (8)  
• 访问 (26)  
• 访问控制 (6)  
• 基于 (4)  
• 集成 (7)  
• 集成架构 (11)  
• 技巧 (96)  
• 解析器 (4)  
• 可用性 (9)  
• 框架 (6)  
• 内容管理 (5)  
• 企业架构 (4)  
• 社区 (8)  
• 使用 (9)  
• 数据库和数据管理 (8)  
• 数字媒体 (5)  
• 体系架构 (34)  
• 推荐引擎 (14)  
• 系统管理 (11)  
• 协作 (10)  
• 信息架构 (6)  
• 性能 (16)  
• 验证 (5)  
• 业务建模 (4)  
• 应用和信息整合 (14)  
• 应用集成 (81)  
• 应用架构 (37)  
• 应用开发 (21)  
• 用户界面 (103)  
• 优化 (4)  
• 组件 (18)  

查看方式云 | 列表

• 打印此页面

• 分享此页面
• 关注 developerWorks

技术主题

• AIX and UNIX
• IBM i
• Information
  Management
• Lotus
• Rational
• WebSphere

• Cloud computing

• Java technology
• Linux
• Open source
• SOA and web services
• Web development
• XML