日期:2014-05-16  浏览次数:20419 次

Struts-json-plugin使用手册(翻译自官方文档)

为了在网上找到struts-json-plugin-xx.jar的源码,可真是费了九牛二虎之力,最后也还是没能如愿以偿,最后只得在Apache-SVN上一页一页的翻看源码来完成上一篇文章,真是悲惨...不过凡事不总是那么绝对——我想这也是生活的魅力所在,居然让我不经意间发现了Apache官网上的一篇关于struts-json-plugin的使用说明文档,非常的详细,非常的全面,不仅有配置说明,还有一个范例工程,赶紧将其拿出来与大家分享。

?

JSON 插件提供了一个 "json" 结果类型来把 action 序列化成 JSON. 这一序列化的过程是递归的, 意即整个对象图,从 action 类开始 (未包括基类) 将会被序列化 (可以用 "root" 属性来指定自己的根对象). 如果使用了 json 拦截器, action 将可通过请求中的 JSON 内容组装出来, 该拦截器遵循以下几条规则:

  1. "content-type" 必须为 "application/json"
  2. JSON 内容必须是格式良好的, 参考 json.org 中的语法.
  3. Action 里必须有欲获取值的属性的相应 public 的 "setter" 方法.
  4. 所支持的类型有: 原始类型 (int,long...String), Date, List, Map, 原始类型数组, 其他的类 (将会支持更多), 和其他类型的数组.
  5. JSON 中的任何将要被填入到 list 或 map 中的对象会是 Map 类型(属性映射到值), 任何整数都是 Long 类型, 任何小数会是 Double 类型, 任何数组会是 List 类型.

给定下面的 JSON 字符串:

?

{
   "doubleValue": 10.10,
   "nestedBean": {
      "name": "Mr Bean"
   },
   "list": ["A", 10, 20.20, {
      "firstName": "El Zorro"
   }],
   "array": [10, 20] 
}

?

action 中必须有一个 "setDoubleValue" 方法, 参数为 "float" 或者 "double"(拦截器将会把值转换为相应的类型). 还必须有一个 "setNestedBean" 方法,它的参数类型可以为任何类类型, 其中含有参数为 "String" 的 "setName" 方法. 还必须有一个参数为 "List" 的 "setList" 方法, 这个 List 中将会包含: "A" (String), 10 (Long), 20.20 (Double), Map ("firstName" -> "El Zorro"). "setArray" 方法可以是 "List", 或任何数字类型数组作参数的.
序列化你的对象成 javascript 的 JSON, 参考 json2

安装

本插件可通过把插件 jar 包到你的应用的 /WEB-INF/lib 目录来完成安装. 没有别的文件需要拷贝或被创建.

使用 maven 的话, 加入下列到你的 pom 中:

?

?

<dependencies>
   ...
   <dependency>
       <groupId>org.apache.struts</groupId>
       <artifactId>struts2-json-plugin</artifactId>
       <version>STRUTS_VERSION</version>
   </dependency>
   ...
</dependencies>

?

定制化序列化和反序列化

使用 JSON 注解来达到定制序列化和反序列化过程. 可用的 JSON 注解如下:

?

?

名称 描述 默认值 序列化 反序列化
name 定制字段名 empty yes no
serialize 标识为可被序列化 true yes no
deserialize 标识为可被反序列化 true no yes
format 用于格式化或解析 Date 字段的格式 "yyyy-MM-dd'T'HH:mm:ss" yes yes

?

?

排除属性

?

逗号分隔的正则表达式列表可传递给 JSON Result 和 Interceptor(拦截器), 被任何 一个正则表达式匹配的属性将会在序列化过程时忽略掉:

?

<!-- Result fragment -->
<result type="json">
  <param name="excludeProperties">
    login.password,
    studentList.*\.sin
  </param>
</result>

<!-- Interceptor fragment -->
<interceptor-ref name="json">
  <param name="enableSMD">true</param>
  <param name="excludeProperties">
    login.password,
    studentList.*\.sin
  </param>
</interceptor-ref>

?

包含属性

逗号分隔的正则表达式列表可被传递给 JSON Result, 用于限制哪些属性可用于序列化. 只有当能够匹配任何一个正则表达式的属性才会包含在序列化输出中.

注:
排除属性表达式优先于包含属性的表达式. 那就是说, 如果包含和排除表达式应用于同一个结果, 包含表达式对于被排除表达式匹配到的属性是不起作用的.

?

?

<!-- Result fragment -->
<result type="json">
  <param name="includeProperties">
    ^entries\[\d+\]\.clientNumber,
    ^entries\[\d+\]\.scheduleNumber,
    ^entries\[\d+\]\.createUserId
  </param>
</result>

?

?

根对象?

使用 "root" 属性(OGNL 表达式) 指定被用于序列化的根对象.

?

<result type="json"&