在Eclipse中使用Jersey和Tomcat构建RESTful WebService及其调用
在Eclipse中使用Jersey和Tomcat构建RESTful WebService及其调用html
REST 在 2000 年由 Roy Fielding 在博士论文中提出，他是 HTTP 规范 1.0 和 1.1 版的首席做者之一。web
REST 中最重要的概念是资源（resources），使用全球 ID（一般使用 URI）标识。客户端应用程序使用 HTTP 方法（GET/ POST/ PUT/ DELETE）操做资源或资源集。RESTful Web 服务是使用 HTTP 和 REST 原理实现的 Web 服务。一般，RESTful Web 服务应该定义如下方面：json
Web 服务的基/根 URI，好比 http://host/<appcontext>/resources。api
支持 MIME 类型的响应数据，包括 JSON/XML/ATOM 等等。浏览器
服务支持的操做集合（例如 POST、GET、PUT 或 DELETE）。tomcat
表 1 演示了典型 RESTful Web 服务中使用的资源 URI 和 HTTP 方法。服务器
方法/资源框架 |
资源集合， URI 如： |
成员资源，URI 如： |
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-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 服务的环境，该服务对客户端发出 “Hello”。
要作到这一点，您须要将全部的 REST 请求发送到 Jersey 容器 —— 在应用程序的 web.xml 文件中定义 servlet 调度程序（参见清单 1）。除了声明 Jersey servlet 外，它还定义一个初始化参数，指示包含资源的 Java 包。
清单 1. 在 web.xml 文件中定义 Jersey servlet 调度程度
<servlet> <servlet-name>Jersey REST Service</servlet-name> <servlet-class> com.sun.jersey.spi.container.servlet.ServletContainer </servlet-class> <init-param> <param-name>com.sun.jersey.config.property.packages</param-name> <param-value>sample.hello.resources</param-value> </init-param> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>Jersey REST Service</servlet-name> <url-pattern>/rest/*</url-pattern> </servlet-mapping>
如今您将编写一个名为 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 类型。
部署到Tomcat容器
在Jersey项目上点击右键，Export---WAR file，生成Jersey.war文件，复制该文件到Tomcat安装目录下的webapps目录下，从新启动tomcat，Jersey.war文件将被自动解压。
要测试应用程序，能够打开您的浏览器并输入 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")
public class ContactsResource {
@Context
UriInfo uriInfo;
@Context
Request request;
@GET
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public List<Contact> getContacts() {
List<Contact> contacts = >new ArrayList<Contact>();
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 {
@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 示例进行说明。
一般经过填写表单建立新联系人。也就是说，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<Address>());
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/<id> 访问新联系人。
PUT
我使用 PUT 方法更新现有资源。可是，也能够经过更新实现，或者像清单 6 中的代码片断展现的那样建立一个资源。
@PUT
@Consumes(MediaType.APPLICATION_XML)
public Response putContact(JAXBElement<Contact> 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。
@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 表示形式。联系人集合的表示形式与此相同，默认使用 <Contacts> 做为包装器元素。
@XmlRootElement
public class Contact {
private String id;
private String name;
private List<Address> addresses;
public Contact() {}
public Contact(String id, String name, List<Address> addresses) {
this.id = id;
this.name = name;
this.addresses = addresses;
}
@XmlElement(name="address")
public List<Address> getAddresses() {
return addresses;
}
public void setAddresses(List<Address> addresses) {
this.addresses = addresses;
}
// Omit other getters and setters
}
XML representation:
<contact> <address> <city>Shanghai</city> <street>Long Hua Street</street> </address> <address> <city>Shanghai</city> <street>Dong Quan Street</street> </address> <id>huangyim</id> <name>Huang Yi Ming</name> </contact>
JSON representation:
{"contact":[{"address":[{"city":"Shanghai","street":"Long
Hua Street"},{"city":"Shanghai","street":"Dong Quan
Street"}],"id":"huangyim","name":"Huang Yi Ming"}]}
在目前为止的示例中，我开发了一个支持 CRUD 的 RESTful Web 服务。如今我开始解释如何使用 curl,RestClient 和 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 对象。
[html] view plaincopy
curl -X PUT -HContent-type:application/xml --data "<contact><id>foo</id>
<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 还提供了一个客户端库，帮助您与服务器通信并对 RESTful 服务进行单元测试。该库是一个通常实现，能够整合任何 HTTP/HTTPS-based Web 服务。
客户端的核心类是 WebResource 类。您可使用该类根据根 URI 构建一个请求 URL，而后发送请求并获取响应。清单 10 展现了如何建立 WebResource 实例。注意 WebResource 是一个大对象，所以只建立一次。
[java] view plaincopy
Client c = Client.create();
WebResource r=c.resource("http://localhost:8080/Jersey/rest/contacts");
第一个 Jersey 客户端示例将发送 GET 请求获取全部联系人并打印响应状态码和响应内容，参见清单 11。
[java] view plaincopy
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” 识别的新联系人的示例。
[java] view plaincopy
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” 识别的联系人（已上一个示例中建立）的最后一个示例而后删除该联系人。
[java] view plaincopy
GenericType<JAXBElement<Contact>> generic = new GenericType<JAXBElement<Contact>>() {};
JAXBElement<Contact> 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 jar库文件的下载地址：http://download.csdn.net/detail/zztfj/4334371
- 1. 使用Jersey来创建RESTful WebService
- 2. 使用 Jersey 和 Apache Tomcat 构建 RESTful Web 服务
- 3. Jersey Restful Application with tomcat
- 4. 用Jersey构建RESTful服务1--HelloWorld
- 5. Node.js 调用 restful webservice
- 6. 利用Tomcat发布基于Maven所构建的Jersey RESTful Web Service
- 7. 基于jersey和Apache Tomcat构建Restful Web服务（一）
- 8. Jersey框架SOA构建Restful服务
- 9. 基于jersey和Apache Tomcat构建Restful Web服务（二）
- 10. 用Jersey构建RESTful服务5--Jersey+MySQL5.6+Hibernate4.3
- 更多相关文章...
- • 在Spring中使用Redis - Redis教程
- • 在Java程序中使用Redis - Redis教程
- • TiDB 在摩拜单车在线数据业务的应用和实践
- • 适用于PHP初学者的学习线路和建议
-
每一个你不满意的现在，都有一个你没有努力的曾经。
- 1. 使用Jersey来创建RESTful WebService
- 2. 使用 Jersey 和 Apache Tomcat 构建 RESTful Web 服务
- 3. Jersey Restful Application with tomcat
- 4. 用Jersey构建RESTful服务1--HelloWorld
- 5. Node.js 调用 restful webservice
- 6. 利用Tomcat发布基于Maven所构建的Jersey RESTful Web Service
- 7. 基于jersey和Apache Tomcat构建Restful Web服务（一）
- 8. Jersey框架SOA构建Restful服务
- 9. 基于jersey和Apache Tomcat构建Restful Web服务（二）
- 10. 用Jersey构建RESTful服务5--Jersey+MySQL5.6+Hibernate4.3