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 方法不需要校验,此注解无任何属性。