Struts2的REST插件

注意：本插件僅適用於Struts 2.1.1或更高的版本。

特性
用法
2.1 定製ContentTypeHandlers
2.2 關於struts.xml

示例
配置
安裝
資源

此REST插件簡化了人們和電腦客戶端對REST風格資源的訪問。其目標是100%實現和Ruby on Rails REST URL風格相兼容的，並且可以免除使用XML作爲資源的開發模式。它基於Convention Plugin來支持對action和result的自動配置。

此Rest風格的action映射強制兼容Ruby-On-Rails的風格映射。如果方法未被指定（通過“！”或者“method:”前綴），那麼將基於ReST風格的約定（通過檢查URL和HTTP方法）進行猜測。這裏特別說明的是，此插件和codebehind plugin一起也可以正常工作，因此，不再需要使用基於XML的配置文件。

此映射支持如下參數：

struts.mapper.idParameterName - 如果設置，則它的值將被作爲保存id的參數名，然後id將被從action名稱中移除。不管是否指定了相關方法，此映射都會試圖從url中移除標識符並將它作爲一個參數保存。
struts.mapper.indexMethodName - 在沒有id參數的情況下，通過GET請求調用的方法名。默認爲index。
struts.mapper.getMethodName - 在具有id參數的情況下，通過GET請求調用的方法名。默認爲show。
struts.mapper.postMethodName - 在沒有id參數的情況下，通過POST請求調用的方法名。默認爲create。
struts.mapper.putMethodName - 在具有id參數的情況下，通過PUT請求調用的方法名。默認爲update。
struts.mapper.deleteMethodName - 在具有id參數的情況下，通過DELETE請求調用的方法名。默認爲destory。
struts.mapper.editMethodName - 在具有id參數且指定了“edit”視圖的情況下，通過GET請求調用的方法名。默認爲edit。
struts.mapper.newMethodName - 在沒有id參數且指定了“new”視圖的情況下，通過GET請求調用的方法名。默認爲editNew。


下列URL將調用Action的相關方法如下：

GET: /movies => method="index"
GET: /movies/Thrillers => method="show", id="Thrillers"
GET: /movies/Thrillers;edit => method="edit", id="Thrillers"
GET: /movies/Thrillers/edit => method="edit", id="Thrillers"
GET: /movies/new => method="editNew"
POST: /movies => method="create"
PUT: /movies/Thrillers => method="update", id="Thrillers"
DELETE: /movies/Thrillers => method="destroy", id="Thrillers"
爲了模擬HTTP方法的PUT和DELETE請求，因爲HTML並不支持，我們將使用一個叫做“_method”的HTTP參數。

或者，使用下表的表示方式：

HTTP method URI Class.method parameters
GET /movie Movie.index
POST /movie Movie.create
PUT /movie/Thrillers Movie.update id="Thrillers"
DELETE /movie/Thrillers Movie.destroy id="Thrillers"
GET /movie/Thrillers Movie.show id="Thrillers"
GET /movie/Thrillers/edit Movie.edit id="Thrillers"
GET /movie/new Movie.editNew

除了作爲一個REST風格的URL映射器以外，此插件還對於multiple content types、通過URL擴展名的可切換性提供了內建的支持。這樣，一個單一的資源就能夠被作爲一個multiple content types暴露出去，而不需要其他額外的工作。

例如，通過暴露一個“orders”資源，客戶端可以立即通過如下方式進行訪問：

http://my.company.com/myapp/orders/1
http://my.company.com/myapp/orders/1.xml
http://my.company.com/myapp/orders/1.xhtml
http://my.company.com/myapp/orders/1.json

此REST插件自動處理序列號和反序列化以及相應的格式化。

一、特性
完全實現 Ruby on Rails 的REST風格URL
支持免XML開發，不需要註解
內建序列號和反序列化支持，以支持XML和JSON
自動錯誤處理
針對HTTP響應的類型安全設置
自動有條件的GET支持

二、用法
在配置的包（package）中創建以“Controller”結尾的Java對象。這裏的“Controller”後綴用於區別REST action和普通的Struts2 action。儘管這完全是可選的，以及它們的功能完全相同。現在，加入方法即可處理各種請求。舉例說明，下面的資源action將支持使用GET和PUT請求訪問/orders/34資源：

package org.apache.struts2.rest.example;

public class OrdersController implements ModelDriven {

private OrderManager orderManager;
private String id;
private Order model;

// Handles /orders/{id} GET requests
public HttpHeaders show() {
model = orderManager.findOrder(id);
return new DefaultHttpHeaders("show")
.withETag(model.getUniqueStamp())
.lastModified(model.getLastModified());
}

// Handles /orders/{id} PUT requests
public String update() {
orderManager.updateOrder(model);
return "update";
}

// getters and setters
}

在這個例子中，使用了ModelDriven 接口，來確保只有模型——這裏的Order對象，被返回給客戶端。否則，OrdersController 對象將被整個序列化。

你也許在想爲什麼show()方法返回了一個HttpHeaders 對象，而update()方法返回了預期的結果代碼字符串。REST插件添加了對action方法的支持，對於那些通過響應有更多控制的action，返回HttpHeaders 對象是一種方式。在本例中，我們想要確保響應包括ETag 頭和一個最近修改日期，以便信息可以被客戶端正確的緩存。HttpHeaders 對象是一個方便的方式，可以在保證在類型安全的情況下控制響應。

而且，請注意，我們沒有在上述任何一個方法中，返回通常的“success”結果碼。這允許我們使用Codebehind Plugin插件的特性，當訪問擴展名爲.xhtml的資源時，以更加直觀的方式來選擇結果模板去處理。在本例中，我們可以通過爲相應的方法創建/orders-show.jsp 和/orders-update.jsp頁面，來提供一個定製化的XHTML 資源視圖。

2.1 定製ContentTypeHandlers
如果你需要處理不被默認處理器支持的擴展名時，你可以創建你自己的ContentTypeHandler 實現，並在struts.xml中進行定義即可。

<bean name="yaml" type="org.apache.struts2.rest.handler.ContentTypeHandler" class="com.mycompany.MyYamlContentHandler" />
如果內建的內容類型處理器無法滿足你的需要，那麼你可以提供另一個處理器，覆蓋對任何擴展名的默認處理方式，並使用它自己的別名進行聲明，例如：

<bean name="myXml" type="org.apache.struts2.rest.handler.ContentTypeHandler" class="com.mycompany.MyXmlContentHandler" />

然後，只需要告知REST插件使用你自己的處理器，去覆蓋特定擴展的處理器即可。在struts.properties文件中，可以做如下配置：

struts.rest.handlerOverride.xml=myXml

2.2 關於struts.xml
配置Struts以使用REST action映射器：

<constant name="struts.mapper.class" value="rest" />
因爲REST插件使用Convention plugin，需要在Struts.xml中進行相關設置：

<constant name="struts.convention.action.suffix" value="Controller"/>
<constant name="struts.convention.action.mapAllMatches" value="true"/>
<constant name="struts.convention.default.parent.package" value="rest-default"/>
對於上述例子而言，package設置如下：

<constant name="struts.convention.package.locators" value="example"/>


三、示例
此插件是隨struts2-rest-showcase 應用程序一起發佈的，用以演示一個簡單的REST web應用程序。

該示例和不同於一般，控制器將被映射到一個關聯的HTTP（PUT,DELETE）方法。

看下圖可以讓你更容易的理解REST的工作方式：


四、配置
配置可以定製，具體可以查看開發指南文檔。要獲得更多的配置項信息，可以查看Convention Plugin的文檔。

設置 描述 默認 可能值
struts.rest.handlerOverride.EXTENSION 處理EXTENSION 值的ContentTypeHandler 實現的別名 N/A 任何聲明瞭的ContentTypeHandler實現的別名
struts.rest.defaultExtension 當沒有在request中顯示指定的時候默認使用擴展類型 xml 任意擴展名
struts.rest.validationFailureStatusCode 校驗失敗後返回的HTTP狀態碼 400 任意HTTP的數字狀態碼

五、安裝
複製插件的jar包到應用程序的/WEB-INF/lib 即可。此插件依賴於Convention Plugin，因此，如果沒有類似於Maven2那樣的支持傳遞依賴的構建系統的話，你可能也需要加入Convention Plugin的jar包。

六、資源
http://www.b-simple.de/documents - 精短的RESTful Rails 教程(PDF格式, 有多種語言)
RESTful Web Services - 來自 O'Reilly 的一本書
Go Light with Apache Struts 2 and REST - Don Brown 在 ApacheCon US 2008 年會上的幻燈片簡報


本文來自CSDN博客，轉載請標明出處：http://blog.csdn.net/abigfrog/archive/2009/11/10/4793039.aspx