使用 Jersey 和 Apache Tomcat 构建 RESTful Web 服务
作者:
IBM
IBM
出处:
http://www.ibm.com/developerworks/cn/web/wa-aj-tomcat/
使用 Jersey 和 Apache Tomcat 构建 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 方法。(参考资料 提供了有关 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(用于 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 的库。
在本文的以下部分,我介绍了所有这些组件,但是更关注核心服务器。
我将从可以集成到 Tomcat 的 “hello world” 应用程序开始。该应用程序将带领您完成设置环境的过程,并涉及 Jersey 和 JAX-RS 的基础知识。
然后,我将介绍更加复杂的应用程序,深入探讨 JAX-RS 的本质和特性,比如多个 MIME 类型表示形式支持、JAXB 支持等。我将从样例中摘取一些代码片段来介绍重要的概念。
要设置开发环境,您需要以下内容(见 参考资料 中的下载):
- 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 归档,包含所有必需的库
首先,为 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 服务的环境,该服务对客户端发出 “Hello”。
要做到这一点,您需要将所有的 REST 请求发送到 Jersey 容器 —— 在应用程序的 web.xml 文件中定义 servlet 调度程序(参见清单 1)。除了声明 Jersey servlet 外,它还定义一个初始化参数,指示包含资源的 Java 包。
清单 1. 在 web.xml 文件中定义 Jersey servlet 调度程度
<servlet> |
现在您将编写一个名为 HelloResource 的资源,它接受 HTTP GET
并响应 “Hello Jersey”。
清单 2. sample.hello.resources 包中的 HelloResource
@Path("/hello") |
该代码中有几个地方需要强调:
- 资源类(Resource Class):注意,资源类是一个简单的 Java 对象 (POJO),可以实现任何接口。这增加了许多好处,比如可重用性和简单。
- 注释(Annotation):在 javax.ws.rs.* 中定义,是 JAX-RS (JSR 311) 规范的一部分。
@Path
:定义资源基 URI。由上下文根和主机名组成,资源标识符类似于 http://localhost:8080/Jersey/rest/hello。@GET:
这意味着以下方法可以响应 HTTPGET
方法。@Produces:
以纯文本方式定义响应内容 MIME 类型。
要测试应用程序,可以打开您的浏览器并输入 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 了解详情。您还可以从本文最后下载完整的代码包(参见 下载)。
@Path("/contacts") |
有几个有趣的地方需要注意。
@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 { |
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 示例进行说明。
通常通过填写表单创建新联系人。也就是说,HTML 表单将 POST 到服务器,服务器创建并维护新创建的联系人。清单 5 演示了该操作的服务器端逻辑。
@POST |
注意该示例的以下部分:
@Consumes:
声明该方法使用 HTML FORM。@FormParam:
注入该方法的 HTML 属性确定的表单输入。@Response.created(uri).build():
构建新的 URI 用于新创建的联系人(/contacts/{id}
)并设置响应代码(201/created
)。您可以使用 http://localhost:8080/Jersey/rest/contacts/<id> 访问新联系人。
我使用 PUT 方法更新现有资源。但是,也可以通过更新实现,或者像清单 6 中的代码片段展示的那样创建一个资源。
@PUT |
我还在本示例中包含了许多不同的概念,重点强调以下概念:
- Consume XML:
putContact()
方法接受 APPLICATION/XML 请求类型,而这种输入 XML 将使用 JAXB 绑定到 Contact 对象。您将在下一节中找到客户端代码。 - 空响应带有不同的状态码:
PUT
请求的响应没有任何内容,但是有不同的状态码。如果数据存储库中存在联系人,我将更新该联系人并返回204/no content
。如果没有新联系人,我将创建一个并返回201/created
。
实现 DELETE
方法非常简单。示例请查看清单 7。
@DELETE |
在上一节中,我介绍了几个表示形式类型。现在我将简要浏览一遍并深入探讨 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> 作为包装器元素。
@XmlRootElement |
XML representation: |
对于使用 JAXB 的更高主题,请查看 参考资料 中的项目主页。
在目前为止的示例中,我开发了一个支持 CRUD 的 RESTful Web 服务。现在我开始解释如何使用 curl 和 Jersey 客户端 API 与该 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 "<contact><id>foo</id> |
一个通过 “foo” 识别的新联系人将添加到联系人存储库。您可以使用 URI /contacts 或 /contacts/foo 验证联系人集合或单个联系人。
Jersey 还提供了一个客户端库,帮助您与服务器通讯并对 RESTful 服务进行单元测试。该库是一个一般实现,可以整合任何 HTTP/HTTPS-based Web 服务。
客户端的核心类是 WebResource
类。您可以使用该类根据根 URI 构建一个请求 URL,然后发送请求并获取响应。清单 10 展示了如何创建 WebResource
实例。注意 WebResource
是一个大对象,因此只创建一次。
Client c = Client.create(); |
第一个 Jersey 客户端示例将发送 GET
请求获取所有联系人并打印响应状态码和响应内容,参见清单 11。
ClientResponse response = r.get(ClientResponse.class); |
清单 12 展示了另一个创建通过 “foo” 识别的新联系人的示例。
Address[] addrs = { |
注意 WebResource
实例的 API。它构建 URI,设置请求头,并在一行代码中调用请求。内容(Contact 对象)将自动绑定到 XML。
清单 13 展示了检索通过 “foo” 识别的联系人(已上一个示例中创建)的最后一个示例然后删除该联系人。
GenericType<JAXBElement<Contact>> generic = new GenericType<JAXBElement<Contact>>() {}; |
注意,当您想获取 JAXB bean 响应时,您需要使用 Java 2 Platform, Standard Edition (J2SE) 中引入的范型特性。
使用 Jersey 客户端练习这些示例。您可以在资源包中找到更多样例代码(见 下载)。还可以参考 Jersey 网站查看更多信息(见 参考资料)。
Jersey 可以使用 Jersey 集成库与其他框架或实用工具库集成。目前,Jersey 可以集成 Spring、Guice,还支持 ATOM 表示形式与 apache-adbera 的集成。在 Jersey 项目主页可以找到 API 和入门指南。
下载
描述 | 名字 | 大小 | 下载方法 |
---|---|---|---|
源代码 | Jersey.Sample.Contact.Src.zip | 10KB | HTTP |
学习
- 在 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。
使用 Jersey 和 Apache Tomcat 构建 RESTful Web 服务的更多相关文章
- 基于jersey和Apache Tomcat构建Restful Web服务(二)
基于jersey和Apache Tomcat构建Restful Web服务(二) 上篇博客介绍了REST以及Jersey并使用其搭建了一个简单的“Hello World”,那么本次呢,再来点有趣的东西 ...
- 基于jersey和Apache Tomcat构建Restful Web服务(一)
基于jersey和Apache Tomcat构建Restful Web服务(一) 现如今,RESTful架构已然成为了最流行的一种互联网软件架构,它结构清晰.符合标准.易于理解.扩展方便,所以得到越来 ...
- 使用 RestEasy 和 Apache Tomcat 构建 RESTful Web 服务
第一次,用这个RestEasy框架,用的时候,总是提示,404的错误,郁闷,呵呵,不过经过努力,终于解决问题,特别留个标记. 关于404的错误,上网找了一大堆,也还不行. 我感觉应该是lib下面架包的 ...
- 用于构建 RESTful Web 服务的多层架构
作者:Bruce Sun, Java 架构师, IBM 出处:http://www.ibm.com/developerworks/cn/web/wa-aj-multitier/ 用于构建 RESTfu ...
- SpringBoot实战(十)之使用Spring Boot Actuator构建RESTful Web服务
一.导入依赖 <?xml version="1.0" encoding="UTF-8"?> <project xmlns="http ...
- Guzzle – 构建 RESTful Web 服务的 PHP HTTP 框架
Guzzle 减轻了发送 HTTP 请求和创建 Web 服务客户端的痛苦.它包含建立一个强大的网络服务客户端的工具,包括:服务描述定义的输入和输出的 API,资源迭代器遍历分页资源,尽可能有效地发送大 ...
- 使用 Spring 3 MVC HttpMessageConverter 功能构建 RESTful web 服务
原文地址:http://www.ibm.com/developerworks/cn/web/wa-restful/ 简介: Spring,构建 Java™ 平台和 Enterprise Edition ...
- Yii2高速构建RESTful Web服务功能简单介绍
Yii2相比Yii1而言,一个重大的改进是内置了功能完备的RESTful支持. 其内置RESTful支持提供了例如以下功能: 使用ActiveRecord的通用接口来高速构建原型: 应答格式协商(缺省 ...
- [译]Spring Boot 构建一个RESTful Web服务
翻译地址:https://spring.io/guides/gs/rest-service/ 构建一个RESTful Web服务 本指南将指导您完成使用spring创建一个“hello world”R ...
随机推荐
- IOS - 绘制文字 drawInRect: withFont: not working
在图形绘制中,我们经常会需要绘制文本,但我在给PDF上绘制Text时,始终绘制不上, 使用过: [str drawInRect:cubeRect withAttributes:attrs]; CGCo ...
- [POJ2104] K – th Number (可持久化线段树 主席树)
题目背景 这是个非常经典的主席树入门题--静态区间第K小 数据已经过加强,请使用主席树.同时请注意常数优化 题目描述 如题,给定N个正整数构成的序列,将对于指定的闭区间查询其区间内的第K小值. 输入输 ...
- redis实现集群加主从复制
a)原理 (1)前提背景:如何解决redis横向扩展的问题----redis集群实现方式 (2)介绍redis 集群 ① Redis 集群是一个提供在多个Redis间节点间共享数据的程序集 ② 优势: ...
- CAD教程--嵌入表格
1.第一步,打开excel复制一下表格 2.第二步,打开CAD,选择编辑->选择性粘贴->autocad图元,左键点击一下图就行了,找找图,放大到适合的比例就行了.
- CF909B Segments
CF909B Segments 题意翻译 题目描述 给你一个整数N.考虑坐标轴上所有可能的部分,在整数点上的端点,坐标在0到N之间,包括它们. 您希望在几个层中绘制这些片段,这样在每个层中这些片段就不 ...
- DynaActionForm(动态ActionForm)的使用
在struts中利用DynaActionForm(动态ActionForm)可以节省代码的编写. 1.在struts-config.xml中配置DynaActionForm:加入这个Form中有三个属 ...
- spring mvc流程理解
1.controller处理的终究就是一个结果,默认是modelandview对象,controller里自己随便调用service或者dao,终究都还是在controller里有返回值. 2. 在 ...
- pythonWeb -- Django开发- Admin
[第一次使用Admin 要创建超级用户账号] 1.\ python manage.py createsuperuser You have 1 unapplied migration(s). Your ...
- Android仿IOS的AssistiveTouch的控件EasyTouch实现
概述: 之前我听到过一则新闻,就是说Ipone中的AssistiveTouch的设计初衷是给残疾人使用的. 而这一功能在亚洲(中国)的使用最为频繁. 虽不知道这新闻的可靠性,但无庸置疑的是它的确给我们 ...
- BEGINNING SHAREPOINT® 2013 DEVELOPMENT 第3章节--SharePoint 2013 开发者工具 用SPD开发SharePoint应用程序
BEGINNING SHAREPOINT® 2013 DEVELOPMENT 第3章节--SharePoint 2013 开发者工具 用SPD开发SharePoint应用程序 非常多开 ...