使用Jersey和Apache和Tomcat搭建Web服务 – Apache

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 方法。（参考资料提供了有关RESTful Web 服务的更多介绍和设计考虑事项）

表 1. 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 包。

清单 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://trustauth.cn: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