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//resources。
支持 MIME 类型的响应 数据,包括 JSON/XML/ATOM 等等。
服务支持的操作集合(例如 POST、 GET、PUT 或 DELETE)。
表 1 演示了典型 RESTful Web 服务中使用的 资源 URI 和 HTTP 方法。
表 1. RESTful Web 服务示例
方法/资源 资源集合, URI 如: http://host//resources 成员资源,URI 如: http://host//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- 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 包。
清单 1. 在 web.xml 文件中定义 Jersey servlet 调度程度
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”。
清单 2. sample.hello.resources 包中的 HelloResource
@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 了解详情。您还可以从本文最后下载完整的 代码包(参见 下载)。
清单 3. ContactsResource
@Path ("/contacts")public class ContactsResource { @Context UriInfo uriInfo; @Context Request 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 元素表示形式。
清单 4. ContactResource
public class ContactResource { @Context UriInfo uriInfo; @Context Request 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 演示了该 操作的服务器端逻辑。
清单 5. 接受表单提交(POST)并新建一个联系 人
@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 中的代码片段展示的那样创建一个资源。
清单 6. 接受 PUT 请求并创建或更新联系人
@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。
清单 7. 删除其 ID 确定的联系人
@DELETE public 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 表示形式。联系人集合的表示形式与此相同,默认使用 作为包装器元素。
清单 8. Contact bean
@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 }
清单 9. 一个 Contact 的表示形式
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"}]}XML representation: Shanghai Long Hua Street
与 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 是一个大对象,因此只创建一次。
清单 10. 创建 WebResource 实例
Client c = Client.create();WebResource r=c.resource ("http://localhost:8080/Jersey/rest/contacts");
第一个 Jersey 客户端示例将发送 GET 请求获取所有联系人并打印响应状态码和响应内 容,参见清单 11。
清单 11. GET 所有联系人并打印响应
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” 识别的新联系人的示例。
清单 12. 创建一个联 系人
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” 识别的联系人(已上一个示例中创建)的最后一个示例然后 删除该联系人。
清单 13. 检索 “foo” 联系人并删除
GenericType<JAXBElement> generic = new GenericType<JAXBElement>() {};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 可以集成 Spring、Guice,还支持 ATOM 表示形式与 apache-adbera 的集成。在 Jersey 项目主页可以找到 API 和入门指南。
本文配套源码
你怎么样对待别人被人就怎么样对待你。