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