Spring,構建 Java™ 平臺和 Enterprise Edition
(Java EE) 應用程序的著名框架,現在在其模型-視圖-控制器(Model-View-Controller ,MVC)層支持具象狀態傳輸 (REST)。RESTful web 服務根據客戶端請求生成多個具象(representations)很重要。在本篇文章中,學習使用HttpMessageConverter
生成多個具象。代碼示例展示如何使用 RestTemplate
和HttpMessageConverter
與服務進行通信。此外,還將學習如何使用
Spring API 和註釋構建 RESTful web 服務,生成常見具象,比如 ATOM Feed、XML 和 JavaScript Object Notation (JSON)。
簡介
隨附文章,“使用 Spring 3 構建 RESTful web 服務”(參見 參考資料),介紹了使用
Spring 構建 RESTful web 服務的方式。還解釋瞭如何使用 ContentNegotiatingViewResolver
生成多個具象,這是
RESTful web 服務的一個重要功能。本文還闡述了使用 HttpMessageConverter
生成多個具象的另一種方式,並且本文中的示例展示瞭如何使用 RestTemplate
和 HttpMessageConverter
與服務進行通信。
Spring MVC 中的 REST 支持
本部分提供了支持 RESTful web 服務的主要 Spring 功能(或註釋)的概述。
-
@Controller
-
使用
@Controller
註釋對將成爲 MVC 中控制器的類進行註釋並處理 HTTP 請求。 -
@RequestMapping
-
使用
@RequestMapping
註釋對函數進行註釋,該函數處理某些 HTTP 方法、URI 或 HTTP 頭。此註釋是 Spring REST 支持的關鍵。可以更改method
參數以處理其他 HTTP 方法。例如:
@RequestMapping(method=RequestMethod.GET, value="/emps", headers="Accept=application/xml, application/json")
-
@PathVariable
-
使用
@PathVariable
註釋可將 URI 中的路徑變量作爲參數插入。例如:
@RequestMapping(method=RequestMethod.GET, value="/emp/{id}") public ModelAndView getEmployee(@PathVariable String id) { … }
-
其他有用的註釋
-
使用
@RequestParam
將 URL 參數插入方法中。使用
@RequestHeader
將某一 HTTP 頭插入方法中。使用
@RequestBody
將 HTTP 請求正文插入方法中。使用
@ResponseBody
將內容或對象作爲 HTTP 響應正文返回。使用
HttpEntity<T>
將它自動插入方法中,如果將它作爲參數提供。使用
ResponseEntity<T>
返回具有自定義狀態或頭的 HTTP 響應。例如:
public @ResponseBody Employee getEmployeeBy(@RequestParam("name") String name, @RequestHeader("Accept") String accept, @RequestBody String body) {…} public ResponseEntity<String> method(HttpEntity<String> entity) {…}
參見 Spring 文檔(參見 參考資料) 獲得可插入方法中的支持註釋或對象的完整列表。
多具象支持
使用不同 MIME 類型表示同一資源是
RESTful web 服務的一個重要方面。通常,可以使用具有不同 "accept" HTTP 頭的同一 URI 提取具有不同表示的資源。還可以使用不同的 URI 或具有不同請求參數的 URI。
“使用 Spring 3 構建
RESTful web 服務”(參見 參考資料)介紹了
ContentNegotiatingViewResolver
,可以挑選不同的視圖解析器處理同一
URI(具有不同的 accept 頭)。因此,ContentNegotiatingViewResolver
可用於生成多個具象。
還有另一種方式可生成多具象 —
將
HttpMessageConverter
和 c@ResponseBody
註釋結合起來使用。使用這種方法無需使用視圖技術。
HttpMessageConverter
HTTP 請求和響應是基於文本的,意味着瀏覽器和服務器通過交換原始文本進行通信。但是,使用
Spring,controller 類中的方法返回純 'String' 類型和域模型(或其他 Java 內建對象)。如何將對象序列化/反序列化爲原始文本?這由
HttpMessageConverter
處理。Spring
具有捆綁實現,可滿足常見需求。表 1 顯示了一些示例。
表 1. HttpMessageConverter 示例
使用...... | 您可以...... |
---|---|
StringHttpMessageConverter | 從請求和響應讀取/編寫字符串。默認情況下,它支持媒體類型 text/* 並使用文本/無格式內容類型編寫。 |
FormHttpMessageConverter | 從請求和響應讀取/編寫表單數據。默認情況下,它讀取媒體類型 application/x-www-form-urlencoded 並將數據寫入 MultiValueMap<String,String>。 |
MarshallingHttpMessageConverter | 使用 Spring 的 marshaller/un-marshaller 讀取/編寫 XML 數據。它轉換媒體類型爲 application/xml 的數據。 |
MappingJacksonHttpMessageConverter |
使用 Jackson 的 ObjectMapper 讀取/編寫
JSON 數據。它轉換媒體類型爲 application/json 的數據。 |
AtomFeedHttpMessageConverter | 使用 ROME 的 Feed API 讀取/編寫 ATOM 源。它轉換媒體類型爲 application/atom+xml 的數據。 |
RssChannelHttpMessageConverter | 使用 ROME 的 feed API 讀取/編寫 RSS 源。它轉換媒體類型爲 application/rss+xml 的數據。 |
構建 RESTful web 服務
在此部分中,學習構建可生成多個具象的簡單
RESTful web 服務。示例應用程序中使用的一些資源在 “使用 Spring 3 構建 RESTful web 服務”(參見 參考資料)中構建。還可以 下載 示例代碼。
首先,您必須配置
HttpMessageConverter
。要生成多個具象,自定義幾個 HttpMessageConverter
實例,以將對象轉換爲不同的媒體類型。此部分包括
JSON、ATOM 和 XML 媒體類型。
JSON
從最簡單的示例開始。JSON 是一個輕量型的數據交換格式,人們可輕鬆地進行讀取和編寫。清單
1 顯示了配置 JSON converter 的代碼。
清單 1. 配置 rest-servlet.xml 中的 HttpMessageConverter
<bean class="org.springframework.web.servlet.mvc.annotation
.AnnotationMethodHandlerAdapter">
<property name="messageConverters">
<list>
<ref bean="jsonConverter" />
<ref bean="marshallingConverter" />
<ref bean="atomConverter" />
</list>
</property>
</bean>
<bean id="jsonConverter"
class="org.springframework.http.converter.json
.MappingJacksonHttpMessageConverter">
<property name="supportedMediaTypes" value="application/json" />
</bean>
在配置中,註冊了 3 個轉換程序。
MappingJacksonHttpMessageConverter
用於將對象轉換爲
JSON,反之亦然。此內置轉換程序使用 Jackson 的 ObjectMapper
將
JSON 映射到 JavaBean,因此您必須將下列 Jackson JAR 文件添加到類路徑。
-
org.codehaus.jackson.jar
-
org.codehaus.jackson.mapper.jar
下一步是編寫一個方法,處理請求
JSON 具象的請求。清單 2 顯示了詳細信息。
清單 2. 處理在 EmployeeController 中定義的 JSON 請求
@RequestMapping(method=RequestMethod.GET, value="/emp/{id}",
headers="Accept=application/json")
public @ResponseBody Employee getEmp(@PathVariable String id) {
Employee e = employeeDS.get(Long.parseLong(id));
return e;
}
@RequestMapping(method=RequestMethod.GET, value="/emps",
headers="Accept=application/json")
public @ResponseBody EmployeeListinggetAllEmp() {
List<Employee> employees = employeeDS.getAll();
EmployeeListinglist = new EmployeeList(employees);
return list;
}
@ResponseBody
註釋用於將返回對象(Employee
或 EmployeeList
)變爲響應的正文內容,將使用 MappingJacksonHttpMessageConverter
將其映射到
JSON。
使用
HttpMessageConverter
和 @ResponseBody
,您可以實現多個具象,而無需包含
Spring 的視圖技術 — 這是使用ContentNegotiatingViewResolver
所不具有的一個優勢。
現在您可以使用 CURL 或 REST
Client Firefox 插件調用請求。記住添加一個 HTTP 頭:
Accept=application/json
。清單
3 以 JSON 格式顯示了所需的響應。
清單 3. getEmp() 和 getAllEmp() 的 JSON 結果
Response for /rest/service/emp/1
{"id":1,"name":"Huang Yi Ming","email":"[email protected]"}
Response for /rest/service/emps
{"count":2,
"employees":[
{"id":1,"name":"Huang Yi Ming","email":"[email protected]"},
{"id":2,"name":"Wu Dong Fei","email":"[email protected]"}
]}
XML
Spring 的內置轉換程序
MarshallingHttpMessageConverter
用於在對象和
XML (OXM) 之間進行映射。本示例使用 JAXB 2 作爲轉換程序的 marshaller/un-marshaller。清單 4 顯示了配置。
清單 4. 配置 MarshallingHttpMessageConverter
<bean id="marshallingConverter"
class="org.springframework.http.converter.xml
.MarshallingHttpMessageConverter">
<constructor-arg ref="jaxbMarshaller" />
<property name="supportedMediaTypes" value="application/xml"/>
</bean>
<bean id="jaxbMarshaller"
class="org.springframework.oxm.jaxb.Jaxb2Marshaller">
<property name="classesToBeBound">
<list>
<value>dw.spring3.rest.bean.Employee</value>
<value>dw.spring3.rest.bean.EmployeeList</value>
</list>
</property>
</bean>
瞭解 JAXB 2 不能很好地支持
java.util.List<T> 到 XML 的映射很重要。常用實踐是爲對象集添加一個包裝類。參見 “使用 Spring 3 構建 RESTful web 服務”(參見 參考資料)或 下載 源代碼,瞭解此
JAXB 註釋類的詳細信息。
在處理請求的控制器中的方法如何?回顧一下 清單
2 中的代碼。發現在此處不需要添加任何代碼一點也不奇怪。您只需要在
Accept
頭中添加另一個支持的媒體類型,如下所示。
headers=”Accept=application/json, application/xml”
轉換程序將對象正確地映射到請求的類型(JSON
或 XML)。清單 5 顯示了請求 application/xml 具象的理想結果。
清單 5. getEmp() 和 getAllEmp() 的 XML 結果
Response for /rest/service/emp/1
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<employee>
<email>[email protected]</email>
<id>1</id>
<name>Huang Yi Ming</name>
</employee>
Response for /rest/service/emps
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<employees>
<count>2</count>
<employee>
<email>[email protected]</email>
<id>1</id>
<name>Huang Yi Ming</name>
</employee>
<employee>
<email>[email protected]</email>
<id>2</id><name>Wu Dong Fei</name>
</employee>
</employees>
ATOM 源
ATOM 源是另一種在 RESTful
web 服務中交換數據的常見格式。Atom 源文檔是 Atom 源(包括有關源及與其相關的所有或部分項的元數據)的具象。其根是
atom:feed
元素。還有一個
ATOM Publish Protocol (APP) 定義交換格式和行爲。(定義 ATOM 和 APP 格式不在本文的討論範圍內。參見 參考資料 瞭解更多信息。)
本示例使用
AtomFeedHttpMessageConverter
轉換
ATOM 源,利用 ROME ATOM API。因此,您必須在類路徑中包含 JAR 文件 sun.syndication.jar。清單 6 顯示了此轉換程序的配置。
清單 6. 配置 AtomFeedHttpMessageConverter
<bean id="atomConverter"
class="org.springframework.http.converter.feed
.AtomFeedHttpMessageConverter">
<property name="supportedMediaTypes" value="application/atom+xml" />
</bean>
清單 7 顯示了處理 ATOM
請求和源生成的代碼。
清單 7. EmployeeController & AtomUtil 類中的 getEmpFeed()
@RequestMapping(method=RequestMethod.GET, value="/emps",
headers="Accept=application/atom+xml")
public @ResponseBody Feed getEmpFeed() {
List<Employee> employees = employeeDS.getAll();
return AtomUtil.employeeFeed(employees, jaxb2Mashaller);
}
public static Feed employeeFeed(
List<Employee> employees, Jaxb2Marshaller marshaller) {
Feed feed = new Feed();
feed.setFeedType("atom_1.0");
feed.setTitle("Employee Atom Feed");
List<Entry> entries = new ArrayList<Entry>();
for(Employee e : employees) {
StreamResult result = new StreamResult(
new ByteArrayOutputStream());
marshaller.marshal(e, result);
String xml = result.getOutputStream().toString();
Entry entry = new Entry();
entry.setId(Long.valueOf(e.getId()).toString());
entry.setTitle(e.getName());
Content content = new Content();
content.setType(Content.XML);
content.setValue(xml);
List<Content> contents = new ArrayList<Content>();
contents.add(content);
entry.setContents(contents);
entries.add(entry);
}
feed.setEntries(entries);
return feed;
}
在上述代碼中,注意:
-
getEmpFeed()
方法將同一 URI 處理爲getAllEmp()
,但具有不同的Accept
頭。 -
使用
employeeFeed()
方法,您可以將Employee
對象解析爲 XML,然後將其添加到源項的<content>
元素。
清單 8 顯示了請求 URI /rest/service/emps
的 application/atom+xml 具象時的輸出。
清單 8. 請求 application/atom+xml 時的 /rest/service/emps
輸出
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title>Employee Atom Feed</title>
<entry>
<title>Huang Yi Ming</title>
<id>1</id>
<content type="xml">
<employee>
<email>[email protected]</email>
<id>1</id>
<name>Huang Yi Ming</name>
</employee>
</content>
</entry>
<entry>
<title>Wu Dong Fei</title>
<id>2</id>
<content type="xml">
<employee>
<email>[email protected]</email>
<id>2</id>
<name>Wu Dong Fei</name>
</employee>
</content>
</entry>
</feed>
實現 POST、PUT 和 DELETE
目前爲止,示例已實現了幾個處理
HTTP
GET
方法的方法。清單 9 顯示了 POST
、PUT
和 DELETE
方法的實現。
清單 9. EmployeeController 中的 POST、PUT 和 DELETE
方法
@RequestMapping(method=RequestMethod.POST, value="/emp")
public @ResponseBody Employee addEmp(@RequestBody Employee e) {
employeeDS.add(e);
return e;
}
@RequestMapping(method=RequestMethod.PUT, value="/emp/{id}")
public @ResponseBody Employee updateEmp(
@RequestBody Employee e, @PathVariable String id) {
employeeDS.update(e);
return e;
}
@RequestMapping(method=RequestMethod.DELETE, value="/emp/{id}")
public @ResponseBody void removeEmp(@PathVariable String id) {
employeeDS.remove(Long.parseLong(id));
}
@RequestBody
註釋在 addEmp()
和 updateEmp()
方法中使用。它接收
HTTP 請求正文並試圖使用註冊的 HttpMessageConverter
將其轉換爲對象類。在下一部分中,您將使用 RestTemplate
與這些服務進行通信。
使用 RestTemplate 與 REST 服務進行通信
“使用 Spring 3 構建
RESTful web 服務”(參見 參考資料)介紹瞭如何使用
CURL 和 REST 客戶端測試 REST 服務。從編程水平上講,Jakarta Commons HttpClient 通常用於完成此測試(但這不在本文的討論範圍中)。您還可以使用名爲
RestTemplate
的
Spring REST 客戶端。從概念上講,它與 Spring 中的其他模板類相似,比如 JdbcTemplate
和 JmsTemplate
。
RestTemplate
還使用 HttpMessageConverter
。您可以將對象類傳入請求並使轉換程序處理映射。
配置 RestTemplate
清單 10 顯示了
RestTemplate
的配置。它還使用之前介紹的
3 個轉換程序。
清單 10. 配置 RestTemplate
<bean id="restTemplate"
class="org.springframework.web.client.RestTemplate">
<property name="messageConverters">
<list>
<ref bean="marshallingConverter" />
<ref bean="atomConverter" />
<ref bean="jsonConverter" />
</list>
</property>
</bean>
本文中的示例僅使用了一些可簡化服務器之間通信的方法。
RestTemplate
支持其他方法,包括:
-
exchange
:使用請求正文執行一些 HTTP 方法並獲得響應。 -
getForObject
:執行 HTTPGET
方法並將響應作爲對象獲得。 -
postForObject
:使用特定請求正文執行 HTTPPOST
方法。 -
put
:使用特定請求正文執行 HTTPPUT
方法。 -
delete
:執行 HTTPDELETE
方法以獲得特定 URI。
代碼示例
下列代碼示例幫助闡述如何使用
RestTemplate
。參見
RestTemplate API(參見 參考資料)獲得使用的
API 的詳細說明。
清單 11 顯示如何將頭添加到請求中,然後調用請求。使用
MarshallingHttpMessageConverter
您可以獲得響應並將其轉換爲類型類。可以使用不同的媒體類型測試其他具象。
清單 11. XML 具象請求
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_XML);
HttpEntity<String> entity = new HttpEntity<String>(headers);
ResponseEntity<EmployeeList> response = restTemplate.exchange(
"http://localhost:8080/rest/service/emps",
HttpMethod.GET, entity, EmployeeList.class);
EmployeeListingemployees = response.getBody();
// handle the employees
清單 12 顯示瞭如何將新員工發佈到服務器。服務器端服務
addEmp()
可接受媒體類型爲
application/xml 和 application/json 的數據。
清單 12. 發佈新員工
Employee newEmp = new Employee(99, "guest", "[email protected]");
HttpEntity<Employee> entity = new HttpEntity<Employee>(newEmp);
ResponseEntity<Employee> response = restTemplate.postForEntity(
"http://localhost:8080/rest/service/emp", entity, Employee.class);
Employee e = response.getBody();
// handle the employee
清單 13 顯示瞭如何 PUT
修改的員工以更新舊員工。它還顯示了可用作請求 URI 佔位符(
{id}
)的功能。
清單 13. PUT 以更新員工
Employee newEmp = new Employee(99, "guest99", "[email protected]");
HttpEntity<Employee> entity = new HttpEntity<Employee>(newEmp);
restTemplate.put(
"http://localhost:8080/rest/service/emp/{id}", entity, "99");
清單 14 顯示瞭如何 DELETE
現有員工。
清單 14. DELETE 現有員工
restTemplate.delete(
"http://localhost:8080/rest/service/emp/{id}", "99");
結束語
在本篇文章中,您學習了 Spring
3 中引入的
HttpMessageConverter
。它提供了對多具象的客戶端和服務器端支持。使用提供的 源代碼,您可以探索本文中的 HttpMessageConverter
實現和使用
“使用 Spring 3 構建 RESTful web 服務” 中的ContentNegotiatingViewResolver
實現之間的差異。
轉:http://www.ibm.com/developerworks/cn/web/wa-restful/#download