Convention 插件（2）—— Annotation

1. 与包和命名空间相关的注解

1.1 @Namespace

• 使用指定的路径替代默认的以 package 包名作为路径的 Action 访问路径。
• 此注解只有一个属性 value，用来指定 Action 的命名空间。
• 此注解可以在 Action 类上或在 Java 包中的 package-info.java 文件中的包申明语句上进行配置。当两处同时进行配置时，Action 类中的配置会覆盖 package-info.java 中的配置。
  
  • 配置在 Action 类中的 namespace 注解，对本 Action 类中所有的 action 方法都有效
  • 配置在 package-info.java 中的 namespace 注解，对本 java 包下所有的 action 类中的 action 方法都有效

举例：

@Namespace("/demo_action") // 当只有一个属性且为 value 时，可省略属性名直接指定属性值
public class DemoAction extends ActionSupport {
    ...
}

// package-info.java
@Namespace("/demo_pacakge")
package app.web.action

import org.apache.struts2.convention.annotation.Namespace;

1.2 @Namespaces

用于组合多个 @Namespace，同样可以修饰 Action 类或 Java 的包的 package-info.java，说明该 Action 类或 Java 包中的所有 action 方法都有多个命名空间，可以通过指定的多个不同的命名空间访问。

举例：

@Namespaces({@Namespace("/demo_action_1"), @Namespace("/demo_action_2")})
public class DemoAction extends ActionSupport {
    ...
}

1.3 @ParentPackage

用于指定被修饰的 Action 所在包的父包，默认继承 struts-default 包，通常无须显示指定，效果同 xml 中的 package 元素的 extends 属性，同样可以修饰 Action 类或 Java 的包的 package-info.java

举例：

@Namespace("/demo")
@ParentPackage("struts-default")
public class DemoAction extends ActionSupport {
    ...
}

2. 与 Action 相关的注解

2.1 @Action

配置在 action 方法上，用来指定该 Action 相关的参数，主要有以下属性：

• value：指定 action 方法的访问名，即逻辑 Action
• params：传入 action 方法的参数，接收一个 String[]，形式为：{“key”, “value”, “key2”, “value2”}
• results：指定 action 的返回结果，接收一个 Result[]，具体元素说明详见 @Result
• interceptorRefs：为 action 配置拦截器，接收一个 InterceptorRef[]，具体元素说明详见 @InterceptorRef
• exceptionMappings：映射 action 中抛出的异常，接收一个 ExceptionMapping[]，具体元素说明详见 @ExceptionMapping
• className：指定 action 的 className，默认为当前注解所在类，通常无须指定

此注解也可以配置在类上，此时调用该 Action 相当于访问该 Action 类中的 excute() 方法。

举例：

@Action(value = "login", className = "app.web.action.DemoAction", exceptionMappings = {
            @ExceptionMapping(exception = "java.lang.NullPointerException", result = "error") }, interceptorRefs = {
                    @InterceptorRef(value = "defaultStack", params = { "key1", "value1", "key2",
                            "value2" }) }, params = { "key3", "value3", "key4", "value4" }, results = {
                                    @Result(name = "success", location = "/success.jsp"),
                                    @Result(name = "error", location = "/error.jsp") })
public String login() throws Exception {
    // ...
    return SUCCESS;
}

2.2 @Actions

用于组织多个 @Action ，它只需指定一个value属性值，该属性接收一个 Action[]，同样可以配置在 action 方法上或 Action 类上，说明该 action 方法或 Action 类中的 excute() 方法对应多个逻辑 Action。

举例：

@Actions(value = { @Action("login"), @Action("index") })
public String login() throws Exception {
    // ...
    return SUCCESS;
}

3. 与 Result 相关的注解

Convention 中总共有三个与返回类型相关的注解：@Result，@Results，@ResultPath。在 Action 类上使用注解 @Results 组织 @Result 表示全局（global） result，对整个 Action 类的所有 action 方法有效；在 action 方法的 @Action 注解中使用 @Result 表示本地（local） result，只对当前 action 方法有效。

3.1 @Result

用于指定 Action 的返回结果，作为 @Action 注解中 results 属性的值。主要有如下相关属性：

• name：指定 Action 返回的结果名，即返回结果的逻辑名，与 action 方法中的 return 的字符串值相对应，如：success，error， input 等
• location：指定 Action 结果名对应的具体返回地址，即返回结果的物理地址，可以是 jsp，action 或者其他的表现层技术（FreeMarker，Velocity 等）
• type：指定跳转到具体物理地址的方式，如：dispatcher（默认），redirect，chain，redirectAction，stream 等
• params：传递给 result 的参数，接收一个 String[]，形式为：{“key”, “value”, “key2”, “value2”}

举例：

// 此 action 执行完成后跳转到另一个 action 方法，路径为 /index/welcome.action
@Action(value = "login", results = {
        @Result(name = "success", location = "welcome.action", type = "chain", params = { "namespace",
                "/index" }) }) // namespace 指明目标 action 的命名空间，如起始 action 在同一命名空间下可省略
public String login() throws Exception {
    // ...
    return SUCCESS;
}

注意：
虽然 @Result 注解定义中是可以在 class 上使用的，但经测试：在 Action 类上使用此注解并未生效，需要使用下面的 @Results 注解包裹才能生效！

3.2 @Results

用于组织多个@Result，配置在 Action 类上，进行全局的 result 设置。它只需指定一个 value 属性值，该属性接收一个 Result[]。

举例：

@Results(value = { @Result(name = "success", location = "/success.jsp"),
        @Result(name = "error", location = "/error.jsp") })
public class DemoAction extends ActionSupport {
    // ...
}

3.3 @ResultPath

用来修改 @Result 中指定的 location 的默认存储路径，对于 JSP 而言，Convention 插件的默认存储路径为 WEB-INF/content，可通过常量 struts.convention.result.path 进行全局修改。此注解可以配置在 Action 类上，对该 Action 类中的所有 action 方法生效，也可以配置在 package-info.java 文件中，对该 package 中的所有 action 方法生效。

此注解主要有如下两个属性：

• value：指定从哪个目录下搜索物理视图资源
• property：指定 key，使用此 key 的值从struts.property 文件寻找对应的 value 作为搜索物理视图资源的根目录，struts.property 文件必须存在于 classpath 下

通常情况下，此注解并不常用，对于默认存储路径的修改也可在 @Result 的 location 属性中直接指明：

• location 中的 JSP 文件没有以 “/” 开头，如 ” jsp/index.jsp”，在没有修改任何配置的情况下，系统会去 WEB-INF/content/jsp/ 目录下寻找 index.jsp 文件
• location 中的 JSP 文件以 “/” 开头，如 “/demo/index.jsp”，在没有修改任何配置的情况下，系统会去 /demo 目录下寻找 index.jsp 文件，”/” 代表当前 Web 项目的根目录

举例：

// 此类下的 action 返回的物理视图都会去 Web 工程的根目录下查找
@ResultPath(value = "/")
public class DemoAction extends ActionSupport {
    //...
}

4. 与 Interceptor 相关的注解

用于为指定 action 引用拦截器或拦截器栈

4.1 @InterceptorRef

此注解可以作为 @Action 属性 interceptorRefs 的值，也可以配置在 Action 类上，对整个 Action 类中的所有 action 方法生效。主要有如下属性：

• value：指定引用哪个拦截器或拦截器栈
• params：为引用的拦截器或拦截器栈中的拦截器指定参数值，接收一个 String[]，形式为：{“key”, “value”, “key2”, “value2”}

举例：

// 以文件上传为例，引入 Struts2 中的默认拦截器栈，为其中的 fileUpload 拦截器指定参数
@Action(value = "FileUpload", params = { "savePath", "/WEB-INF/uploadfile" }, results = {
        @Result(location = "/success.jsp") }, interceptorRefs = { @InterceptorRef(value = "defaultStack", params = {
                "fileUpload.maximumSize", "1024*1024", "fileUpload.allowedTypes", "text/plain,image/jpg",
                "fileUpload.allowedExtensions", "txt,jpg" }) })
public String fileUpload() throws Exception {
    // ...
}

4.2 @InterceptorRefs

用于组织多个 @InterceptorRef，它只需指定一个 value 属性值，该属性接收一个 InterceptorRef[]。此注解配置在 Action 类上，对整个 Action 类中的所有 action 方法生效。

举例：

@InterceptorRefs(value = { @InterceptorRef("MyInterceptor"), @InterceptorRef("defaultStack") })
public class DemoAction extends ActionSupport {
    // ...
}

4.3 @DefaultInterceptorRef

为指定 Action 设置默认的拦截器或拦截器栈，只需指定一个 value 属性值。此注解只能配置在 package-info.java 文件中。

举例：

@DefaultInterceptorRef("defaultStack")
package app.web.action;

import org.apache.struts2.convention.annotation.*;

5. 与 Exception 相关的注解

与 Exception 相关的注解主要有两个：@ExceptionMapping 和 @ExceptionMappings。在 Action 类上使用 @ExceptionMappings 组织 @ExceptionMapping 表示全局（global） ExceptionMappings，对整个 Action 类中的所有 action 方法生效；在 action 方法的 @Action 注解中使用 @ExceptionMapping，表示本地（local） ExceptionMapping，仅对当前 action 方法生效。

5.1 @ExceptionMapping

用于定义异常类和物理视图之间的对应关系，作为 @Action 注解中 exceptionMappings 属性的值，主要有如下属性：

• exception：指定 action 方法中抛出的哪些异常需要跳转到对应的物理视图
• result：指定异常对应的物理视图名
• params：添加需要传递给 result 对应物理视图的参数信息

此处不再举例，参考 @Action 的例子

5.2 @ExceptionMappings

用于组织多个 @ExceptionMapping，它只需指定一个 value 属性值，该属性接收一个ExceptionMapping[]。此注解配置在 Action 类上，对整个 Action 类中的所有 action 方法生效。

举例：

@ExceptionMappings(value = { @ExceptionMapping(exception = "java.lang.NullPointerException", result = "success") })
public class DemoAction extends ActionSupport {
    // ...
}

6. 其他注解

由于下面注解不属于 Convention 插件，与主题不符，所以只作简单罗列，具体配置下次再单独发文详解。

6.1 与校验相关的注解

6.1.1 @Validations

用于组织其他具体的注解校验器，不同的属性配置不同的注解校验器，属性名基本为注解校验器名去掉 Validation 后缀，可以配置在 Action 类上或者 action 方法上。

常见的注解校验器如下：

• @RequiredFieldValidator 必填校验器
• @StringLengthFieldValidator 字符串长度校验器
• @UrlValidator 网址校验器
• @DateRangeFieldValidator 日期校验器
• @IntRangeFieldValidator 整数校验器
• @EmailValidator 邮箱校验器
• @ExpressionValidator 表达式校验器
• @FieldExpressionValidator 字段表达式校验器
• @ConversionErrorFieldValidator 转换校验器
• @RegexFieldValidator 正则表达式校验器

6.1.2 @SkipValidation

配置在 action 方法上，指定该 action 方法不需要校验，此注解无任何属性。