本文由IBMDW的Yi Ming Huang, Dong Fei Wu, Qing Guo等三位IBM軟件工程師聯(lián)合撰寫(xiě)，原文標(biāo)題為《使用 Jersey 和 Apache Tomcat 構(gòu)建 RESTful Web 服務(wù)》。

RESTful Web 服務(wù)簡(jiǎn)介

REST 在 2000 年由 Roy Fielding 在博士論文中提出，他是 HTTP 規(guī)范 1.0 和 1.1 版的首席作者之一。

REST 中最重要的概念是資源（resources），使用全球 ID（通常使用 URI）標(biāo)識(shí)。客戶端應(yīng)用程序使用 HTTP 方法（GET/ POST/ PUT/ DELETE）操作資源或資源集。RESTful Web 服務(wù)是使用 HTTP 和 REST 原理實(shí)現(xiàn)的 Web 服務(wù)。通常，RESTful Web 服務(wù)應(yīng)該定義以下方面：

• Web 服務(wù)的基/根 URI，比如 http://host/<appcontext>/resources。
• 支持 MIME 類(lèi)型的響應(yīng)數(shù)據(jù)，包括 JSON/XML/ATOM 等等。
• 服務(wù)支持的操作集合（例如 POST、GET、PUT 或 DELETE）。

表 1 演示了典型 RESTful Web 服務(wù)中使用的資源 URI 和 HTTP 方法。

表 1. RESTful Web 服務(wù)示例

JSR 311 (JAX-RS) 和 Jersey

JSR 311 或 JAX-RS（用于 RESTful Web Services 的 Java API）的提議開(kāi)始于 2007 年，1.0 版本到 2008 年 10 月定稿。目前，JSR 311 版本 1.1 還處于草案階段。該 JSR 的目的是提供一組 API 以簡(jiǎn)化 REST 樣式的 Web 服務(wù)的開(kāi)發(fā)。

在 JAX-RS 規(guī)范之前，已經(jīng)有 Restlet 和 RestEasy 之類(lèi)的框架，可以幫助您實(shí)現(xiàn) RESTful Web 服務(wù)，但是它們不夠直觀。Jersey 是 JAX-RS 的參考實(shí)現(xiàn)，它包含三個(gè)主要部分。

• 核心服務(wù)器（Core Server）：通過(guò)提供 JSR 311 中標(biāo)準(zhǔn)化的注釋和 API 標(biāo)準(zhǔn)化，您可以用直觀的方式開(kāi)發(fā) RESTful Web 服務(wù)。
• 核心客戶端（Core Client）：Jersey 客戶端 API 幫助您與 REST 服務(wù)輕松通信。
• 集成（Integration）：Jersey 還提供可以輕松集成 Spring、Guice、Apache Abdera 的庫(kù)。

在本文的以下部分，我介紹了所有這些組件，但是更關(guān)注核心服務(wù)器。

構(gòu)建 RESTful Web 服務(wù)

我將從可以集成到 Tomcat 的 “hello world” 應(yīng)用程序開(kāi)始。該應(yīng)用程序?qū)ьI(lǐng)您完成設(shè)置環(huán)境的過(guò)程，并涉及 Jersey 和 JAX-RS 的基礎(chǔ)知識(shí)。

然后，我將介紹更加復(fù)雜的應(yīng)用程序，深入探討 JAX-RS 的本質(zhì)和特性，比如多個(gè) MIME 類(lèi)型表示形式支持、JAXB 支持等。我將從樣例中摘取一些代碼片段來(lái)介紹重要的概念。

Hello World：第一個(gè) Jersey Web 項(xiàng)目

要設(shè)置開(kāi)發(fā)環(huán)境，您需要以下內(nèi)容：

• IDE：Eclipse IDE for JEE (v3.4+) 或 IBM Rational Application Developer 7.5
• Java SE5 或更高版本
• Web 容器：Apache Tomcat 6.0（Jetty 和其他也可以）
• Jersey 庫(kù)：Jersey 1.0.3 歸檔，包含所有必需的庫(kù)

設(shè)置 Jersey 的環(huán)境

首先，為 Eclipse 上的 Tomcat 6.0 創(chuàng)建服務(wù)器運(yùn)行時(shí)。這是用于 RESTful Web 應(yīng)用程序的 Web 容器。然后創(chuàng)建一個(gè)名為 “Jersey” 應(yīng)用程序，并將目標(biāo)運(yùn)行時(shí)指定為 Tomcat 6.0。

最后，從 Jersey 開(kāi)發(fā)包中將以下庫(kù)復(fù)制到 WEB-INF 下的庫(kù)目錄：

• 核心服務(wù)器：jersey-core.jar，jersey-server.jar，jsr311-api.jar，asm.jar
• 核心客戶端：（用于測(cè)試）jersey-client.jar
• JAXB 支持：（在高級(jí)樣例中使用）jaxb-impl.jar，jaxb-api.jar，activation.jar，stax-api.jar，wstx-asl.jar
• JSON 支持：（在高級(jí)樣例中使用）jersey-json.jar

開(kāi)發(fā) REST 服務(wù)

現(xiàn)在，您已經(jīng)設(shè)置好了開(kāi)發(fā)第一個(gè) REST 服務(wù)的環(huán)境，該服務(wù)對(duì)客戶端發(fā)出 “Hello”。

要做到這一點(diǎn)，您需要將所有的 REST 請(qǐng)求發(fā)送到 Jersey 容器 —— 在應(yīng)用程序的 web.xml 文件中定義 servlet 調(diào)度程序（參見(jiàn)清單 1）。除了聲明 Jersey servlet 外，它還定義一個(gè)初始化參數(shù)，指示包含資源的 Java 包。

清單 1. 在 web.xml 文件中定義 Jersey servlet 調(diào)度程度

				
<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>            

現(xiàn)在您將編寫(xiě)一個(gè)名為 HelloResource 的資源，它接受 HTTP GET 并響應(yīng) “Hello Jersey”。

清單 2. sample.hello.resources 包中的 HelloResource

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

該代碼中有幾個(gè)地方需要強(qiáng)調(diào)：

• 資源類(lèi)（Resource Class）：注意，資源類(lèi)是一個(gè)簡(jiǎn)單的 Java 對(duì)象 (POJO)，可以實(shí)現(xiàn)任何接口。這增加了許多好處，比如可重用性和簡(jiǎn)單。
• 注釋?zhuān)ˋnnotation）：在 javax.ws.rs.* 中定義，是 JAX-RS (JSR 311) 規(guī)范的一部分。
• @Path：定義資源基 URI。由上下文根和主機(jī)名組成，資源標(biāo)識(shí)符類(lèi)似于 http://localhost:8080/Jersey/rest/hello。
• @GET：這意味著以下方法可以響應(yīng) HTTP GET 方法。
• @Produces：以純文本方式定義響應(yīng)內(nèi)容 MIME 類(lèi)型。

測(cè)試 Hello 應(yīng)用程序

要測(cè)試應(yīng)用程序，可以打開(kāi)您的瀏覽器并輸入 URL http://<host>:<port>/<appctx>/rest/hello。您將看到響應(yīng) “Hello Jersey”。這非常簡(jiǎn)單，使用注釋處理請(qǐng)求、響應(yīng)和方法。

以下部分將涉及 JAX-RS 規(guī)范的必要部分，使用 Contacts 示例應(yīng)用程序中的代碼片段進(jìn)行介紹。您可以在源代碼包中找到這個(gè)高級(jí)樣例的所有代碼。

資源

資源是組成 RESTful Web 服務(wù)的關(guān)鍵部分。您可以使用 HTTP 方法（如 GET、POST、PUT 和 DELETE）操作資源。應(yīng)用程序中的所有內(nèi)容都是資源：?jiǎn)T工、聯(lián)系人、組織等。在 JAX-RX 中，資源通過(guò) POJO 實(shí)現(xiàn)，使用 @Path 注釋組成其標(biāo)識(shí)符。資源可以有子資源。在這種情況下，父資源是資源集合，子資源是成員資源。

在樣例 Contacts 應(yīng)用程序中，您將操作個(gè)人聯(lián)系人和聯(lián)系人集合。ContactsResource 是 /contacts URI 組成的集合資源，ContactResource 是 /contacts/{contactId} URI 組成的成員資源。下劃線 JavaBean 是一個(gè)簡(jiǎn)單的 Contact 類(lèi)，使用 id、名稱(chēng)和地址作為成員字段。參見(jiàn)清單 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<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);
	}
}            

有幾個(gè)有趣的地方需要注意。

• @Context： 使用該注釋注入上下文對(duì)象，比如 Request、Response、UriInfo、ServletContext 等。
• @Path("{contact}")：這是 @Path 注釋?zhuān)c根路徑 “/contacts” 結(jié)合形成子資源的 URI。
• @PathParam("contact")：該注釋將參數(shù)注入方法參數(shù)的路徑，在本例中就是聯(lián)系人 id。其他可用的注釋有 @FormParam、@QueryParam 等。
• @Produces：響應(yīng)支持多個(gè) MIME 類(lèi)型。在本例和上一個(gè)示例中，APPLICATION/XML 將是默認(rèn)的 MIME 類(lèi)型。

您也許還注意到了，GET 方法返回定制 Java 對(duì)象而不是 String（純文本），正如上一個(gè) Hello World 示例所示。 JAX-RS 規(guī)范要求實(shí)現(xiàn)支持多個(gè)表示形式類(lèi)型，比如 InputStream、byte[]、JAXB 元素、JAXB 元素集合等等，以及將其序列化為 XML、JSON 或純文本作為響應(yīng)的能力。下文我將提供更多有關(guān)表示形式技術(shù)的信息，尤其是 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 的代碼簡(jiǎn)單明了。注意以下內(nèi)容：

• Representation Type Contact：Contact 是一個(gè)簡(jiǎn)單的 JavaBean，由 @XmlRootElement 注釋?zhuān)@使它可以表示為 XML 或 JSON。
• ContactStore：這是基于 HashMap 的內(nèi)存數(shù)據(jù)存儲(chǔ)庫(kù)，其實(shí)現(xiàn)對(duì)于本文不重要。

方法

HTTP 方法映射到資源的 CRUD（創(chuàng)建、讀取、更新和刪除） 操作。盡管您可以做一些小修改，比如讓 PUT 方法變成創(chuàng)建或更新，但基本的模式如下：

• HTTP GET：獲取/列出/檢索單個(gè)資源或資源集合。
• HTTP POST：新建資源。
• HTTP PUT：更新現(xiàn)有資源或資源集合。
• HTTP DELETE：刪除資源或資源集合。

因?yàn)槲乙呀?jīng)介紹過(guò) GET 方法，我將從 POST 開(kāi)始說(shuō)明。就像其他方法一樣，我仍然使用 Contact 示例進(jìn)行說(shuō)明。

POST

通常通過(guò)填寫(xiě)表單創(chuàng)建新聯(lián)系人。也就是說(shuō)，HTML 表單將 POST 到服務(wù)器，服務(wù)器創(chuàng)建并維護(hù)新創(chuàng)建的聯(lián)系人。清單 5 演示了該操作的服務(wù)器端邏輯。

清單 5. 接受表單提交（POST）并新建一個(gè)聯(lián)系人

				
@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()： 構(gòu)建新的 URI 用于新創(chuàng)建的聯(lián)系人（/contacts/{id}）并設(shè)置響應(yīng)代碼（201/created）。您可以使用 http://localhost:8080/Jersey/rest/contacts/<id> 訪問(wèn)新聯(lián)系人。

PUT

我使用 PUT 方法更新現(xiàn)有資源。但是，也可以通過(guò)更新實(shí)現(xiàn)，或者像清單 6 中的代碼片段展示的那樣創(chuàng)建一個(gè)資源。

清單 6. 接受 PUT 請(qǐng)求并創(chuàng)建或更新聯(lián)系人

				
@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;
}            

我還在本示例中包含了許多不同的概念，重點(diǎn)強(qiáng)調(diào)以下概念：

• Consume XML：putContact() 方法接受 APPLICATION/XML 請(qǐng)求類(lèi)型，而這種輸入 XML 將使用 JAXB 綁定到 Contact 對(duì)象。您將在下一節(jié)中找到客戶端代碼。
• 空響應(yīng)帶有不同的狀態(tài)碼：PUT 請(qǐng)求的響應(yīng)沒(méi)有任何內(nèi)容，但是有不同的狀態(tài)碼。如果數(shù)據(jù)存儲(chǔ)庫(kù)中存在聯(lián)系人，我將更新該聯(lián)系人并返回 204/no content。如果沒(méi)有新聯(lián)系人，我將創(chuàng)建一個(gè)并返回 201/created。

DELETE

實(shí)現(xiàn) DELETE 方法非常簡(jiǎn)單。示例請(qǐng)查看清單 7。

清單 7. 刪除其 ID 確定的聯(lián)系人

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

表示形式

在上一節(jié)中，我介紹了幾個(gè)表示形式類(lèi)型?，F(xiàn)在我將簡(jiǎn)要瀏覽一遍并深入探討 JAXB 表示形式。其他受支持的表示形式有 byte[]、InputStream、File 等。

• String：純文本。
• Response：一般 HTTP 響應(yīng)，包含帶有不同響應(yīng)代碼的定制內(nèi)容。
• Void：帶有 204/no content 狀態(tài)碼的空響應(yīng)。
• Resource Class：將流程委托給該資源類(lèi)。
• POJO：使用 @XmlRootElement 注釋的 JavaBean，這讓它成為一個(gè) JAXB bean，可以綁定到 XML。
• POJO 集合：JAXB bean 集合。

JAX-RS 支持使用 JAXB (Java API for XML Binding) 將 JavaBean 綁定到 XML 或 JSON，反之亦然。JavaBean 必須使用 @XmlRootElement 注釋。清單 8 使用 Contact bean 作為示例。沒(méi)有明確 @XmlElement 注釋的字段將包含一個(gè)名稱(chēng)與之相同的 XML 元素。清單 9 顯示了用于一個(gè) Contact bean 的序列化 XML 和 JSON 表示形式。聯(lián)系人集合的表示形式與此相同，默認(rèn)使用 <Contacts> 作為包裝器元素。

清單 8. Contact bean

				
@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
}               

清單 9. 一個(gè) Contact 的表示形式

				
				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"}]}
         

與 REST 服務(wù)通訊的客戶端

在目前為止的示例中，我開(kāi)發(fā)了一個(gè)支持 CRUD 的 RESTful Web 服務(wù)?，F(xiàn)在我開(kāi)始解釋如何使用 curl 和 Jersey 客戶端 API 與該 REST 服務(wù)通訊。這樣一來(lái)，我可以測(cè)試服務(wù)器端代碼，并介紹更多有關(guān)客戶端技術(shù)的信息。

使用 curl 與 REST 服務(wù)通訊

Curl 是一個(gè)流行的命令行工具，可以向使用 HTTP 和 HTTPS 協(xié)議的服務(wù)器發(fā)送請(qǐng)求。這是一個(gè)與 RESTful Web 服務(wù)通訊的好工具，因?yàn)樗梢酝ㄟ^(guò)任何 HTTP 方法發(fā)送內(nèi)容。Curl 已經(jīng)在 Linux 和 Mac 中自帶了，并且有一個(gè)實(shí)用工具，可以在 Windows 平臺(tái)上進(jìn)行安裝。

現(xiàn)在，我們初始化獲取所有聯(lián)系人的第一個(gè) curl 命令。您可以參考 清單 3 獲取服務(wù)器端代碼。

curl http://localhost:8080/Jersey/rest/contacts

響應(yīng)將使用 XML 并包含所有聯(lián)系人。

注意，getContacts() 方法還生成一個(gè) application/json MIME 類(lèi)型響應(yīng)。您還可以請(qǐng)求該類(lèi)型的內(nèi)容。

curl –HAccept:application/json http://localhost:8080/Jersey/rest/contacts

響應(yīng)將是一個(gè)包含所有聯(lián)系人的 JSON 字符串。

現(xiàn)在，我將 PUT 一個(gè)新的聯(lián)系人。注意，清單 6 中的 putContact() 方法接受 XML 并使用 JAXB 將 XML 綁定到 Contact 對(duì)象。

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

一個(gè)通過(guò) “foo” 識(shí)別的新聯(lián)系人將添加到聯(lián)系人存儲(chǔ)庫(kù)。您可以使用 URI /contacts 或 /contacts/foo 驗(yàn)證聯(lián)系人集合或單個(gè)聯(lián)系人。

使用 Jersey Client 與 REST 服務(wù)通訊

Jersey 還提供了一個(gè)客戶端庫(kù)，幫助您與服務(wù)器通訊并對(duì) RESTful 服務(wù)進(jìn)行單元測(cè)試。該庫(kù)是一個(gè)一般實(shí)現(xiàn)，可以整合任何 HTTP/HTTPS-based Web 服務(wù)。

客戶端的核心類(lèi)是 WebResource 類(lèi)。您可以使用該類(lèi)根據(jù)根 URI 構(gòu)建一個(gè)請(qǐng)求 URL，然后發(fā)送請(qǐng)求并獲取響應(yīng)。清單 10 展示了如何創(chuàng)建 WebResource 實(shí)例。注意 WebResource 是一個(gè)大對(duì)象，因此只創(chuàng)建一次。

清單 10. 創(chuàng)建 WebResource 實(shí)例

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

第一個(gè) Jersey 客戶端示例將發(fā)送 GET 請(qǐng)求獲取所有聯(lián)系人并打印響應(yīng)狀態(tài)碼和響應(yīng)內(nèi)容，參見(jiàn)清單 11。

清單 11. GET 所有聯(lián)系人并打印響應(yīng)

				
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 展示了另一個(gè)創(chuàng)建通過(guò) “foo” 識(shí)別的新聯(lián)系人的示例。

清單 12. 創(chuàng)建一個(gè)聯(lián)系人

				
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 實(shí)例的 API。它構(gòu)建 URI，設(shè)置請(qǐng)求頭，并在一行代碼中調(diào)用請(qǐng)求。內(nèi)容（Contact 對(duì)象）將自動(dòng)綁定到 XML。

清單 13 展示了檢索通過(guò) “foo” 識(shí)別的聯(lián)系人（已上一個(gè)示例中創(chuàng)建）的最后一個(gè)示例然后刪除該聯(lián)系人。

清單 13. 檢索 “foo” 聯(lián)系人并刪除

				
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());            

注意，當(dāng)您想獲取 JAXB bean 響應(yīng)時(shí)，您需要使用 Java 2 Platform, Standard Edition (J2SE) 中引入的范型特性。

使用 Jersey 客戶端練習(xí)這些示例。您可以在資源包中找到更多樣例代碼。還可以參考 Jersey 網(wǎng)站查看更多信息。

結(jié)束語(yǔ)

Jersey 可以使用 Jersey 集成庫(kù)與其他框架或?qū)嵱霉ぞ邘?kù)集成。目前，Jersey 可以集成 Spring、Guice，還支持 ATOM 表示形式與 apache-adbera 的集成。在 Jersey 項(xiàng)目主頁(yè)可以找到 API 和入門(mén)指南。