Struts2ConventionPlugin中文文档15505.pdf
15页
Struts2 Convention Plugin 中文文档 Introduction 从 struts2.1 版本开始，Convention Plugin作为替换替换Codebehind Plugin来实现Struts2 的零配置 • 包命名习惯来指定Action 位置 • 命名习惯制定结果（支持JSP,FreeMarker等）路径 • 类名到URL 的约定转换 • 包名到命名空间（namespace）的约定转换 • 遵循SEO 规范的链接地址（即：使用my-action 来替代 MyAction） • 基于注解的Action 名 • 基于注解的拦截机（Interceptor） • 基于注解的命名空间（Nameespace） • 基于注解的XWork 包 • 默认action 以及默认的结果（比如：/products 将会尝试寻找com.example.actions.Products 或 com.example.actions.products.Index进行处理） 无需配置Convention 即可使用Convention，Convention 的某些约束习惯可以通过配置属性来控制，您也可以在类中覆写其中的方法 来达到扩展目地。
安装 使用Convention插件，你需要将其JAR文件放到你应用的WEB-INF/lib目录中，你也可以在你Macen 项目的POM 文件中添加下面包依 赖 1.
本例中，我们将演示根据访问URL 来访问固定 的Action，默认情况下，Convention 会默认所有的结果页面都存储在WEB-INF/content 下，你也可以在struts 的 properties 文件中设定struts.convention.result.path的值到一个新的路径路径最后“/”是不必要 的，Convention 会自动进行处理以下是本例的JSP 文件 WEB-INF/content/hello-world.jsp 1. 2.
3. Hello world! 4. 5. 启动Tomcat 或其他你所使用的JEE 容器，在浏览器访问http://localhost:8080/hello-world ， 你可看到以下信息： Hello world! 这表明，Convention 已经能正常运行，并找到了结果即使在没有action 存在情况下，convention 也会根据URL 规则来找到结果页 面 Code behind hello world 我们继续扩展本例并添加代码实现类。为了实现本功能，首先需要Convention能正确找到我们的Action 类，默认情况下，Convention 会找到com.opensymphony.xwork2.Action 的实现类，或制定包中以Action 结尾的类 action Convention 使用以下方法来搜索类路径，首先，Convention 会从根package 中寻找包名含有struts, struts2, action or actions 的任意packages下一部，Convention 从前一步找到的package 以及其子package 中寻找 com.opensymphony.xwork2.Action 的实现以及以Action 结尾的类，下面为Convention 寻找的类 1. com.example.actions.MainAction 2. com.example.actions.products.Display (implements com.opensymphony.xwork2.Action) 3. pany.details.ShowCompanyDetailsAction 4. com.example.actions.MainAction 5. com.example.actions.products.Display (implements com.opensymphony.xwork2.Action) 6. pany.details.ShowCompanyDetailsAction 每一个被Convention 找到action 都会对应一个明确的URL地址，URL以 package的名字以及Action 类名为基础。
首先Convention 从根package 以及类所在的package 名来确定对应的URL 中的路径（namespace），以下就是根据 package 确定的URL namespace 1. com.example.actions.MainAction -> / 2. com.example.actions.products.Display -> /products 3. pany.details.ShowCompanyDetailsAction -> /company/details 接下来Convention 需要确定URL 的具体资源部分第一步取消类名中的Action，并以”-”来分割类名的其他部分，且将每个分部的首字 母转为小写如下所示 1. com.example.actions.MainAction -> /main 2. com.example.actions.products.Display -> /products/display 3. pany.details.ShowCompanyDetailsAction -> /company/details/show-company-details 你也可以通过配置struts.convention.exclude.packages 来告诉Convention忽略某些包，也可以设置struts.convention.package.locators 用来更改Convention 默认的根packages，最后你还可以设置 struts.convention.action.packages. 来让Convention 只搜索特定package 下的Action 以下就是action 类的实现代码： 1. package com.example.actions; 2. 3. import com.opensymphony.xwork2.ActionSupport; 4. 5. public class HelloWorld extends ActionSupport { 6. private String message; 7. 8. public String getMessage() { 9. return message; 10. } 11. 12. public String execute() { 13. message = "Hello World!"; 14. return SUCCESS; 15. } 16.} 编译以上代码，并将其class 放到 WEB-INF/classes 中，Convention 将会将 /hello-world 映射到这个Action. 部署上面的类以后，我们在JSP 文件中添加打印message 的语句，具体代码如下： 1. 2.
3. The message is ${message} 4. 5. 启动应用服务器，在浏览器访问 http://localhost:8080/hello-world 地址，我们看到如下结果界面： The message is Hello World! Results and result codes Struts 启动后，Convention 将预设好应用中的所有的action，默认情况下，配置将包含在你应用中能找到的所有JSP 文件。同时您也可在Action 代码中设置与习惯不同的结果页面通常Action 方法返回一个字符串，通过返回的字符串找到结果页面，而使用 Convention 允许你在action 代码中指定和返回字符串不同的结果页面 编译下面的例子我们希望在action 中返回zero 而不是success， 第一步，我们更新action 类，返回zero 1. package com.example.actions; 2. 3. import com.opensymphony.xwork2.ActionSupport; 4. 5. public class HelloWorld extends ActionSupport { 6. private String message; 7. 8. public String getMessage() { 9. return message; 10. } 11. 12. public String execute() { 13. if (System.currentTimeMillis() % 2 == 0) { 14. message = "It's 0"; 15. return "zero"; 16. } 17. 18. message = "It's 1"; 19. return SUCCESS; 20. } 21.} 接下来，我们添加一个新的JSP 页面 WEB-INF/content/hello-world-zero.jsp 。
需要注意的是，文件名的第一部分和action 名是对应的，后面的部分和action返回的字符串对应这就是convention 确定具体使用那个页 面来渲染结果下面是修改后的JSP 代码： 1. 2.
3. The error message is ${message} 4. 5. 现在，你可以编辑你的程序，重启应用，刷新页面，根据当前时间不通，会看到不通的渲染结果页面 结果页面的类型会自动匹配文件，支持的渲染页面的格式为：jsp.ftl,vm,html,htm. 下面是actiong 和结果模版的映射关系： URL Result File that could match Result Type /hello success /WEB-INF/content/hello.jsp Dispatcher /hello success /WEB-INF/content/hello-success.htm Dispatcher /hello success /WEB-INF/content/hello.ftl FreeMarker /hello-world input /WEB-INF/content/hello-world-input.vm Velocity /test1/test2/error /WEB-INF/content/test/test2/hello-Dispatch hello error.html er Action 链 如果在一个action 结果中调用另外一个action ，他们俩将被链接到一起，如果在第一个action 代码中未定义result，如下代码： 1. package com.example.actions; 2. 3. import com.opensymphony.xwork2.Action; 4. import com.opensymphony.xwork2.ActionSupport; 5. 6. public class HelloAction extends ActionSupport { 7. @Action("foo") 8. public String foo() { 9. return "bar"; 10. } 11. 12. @Action("foo-bar") 13. public String bar() { 14. return SUCCESS; 15. } 16.} “foo”action执行时候，由于找不到结果，convention 尝试在同一个包下寻找action 名为“foo-bar”的action。 如果找到这样的action， convention 将会调用并返回相关联的result XWork packages 为了避免冲突，可将action 放在一个自定义XWORK 的 package 下package 命名由action 所在的Java 包 ,action 对应的 URL 中 namespace 部分以及action的 parent XWork package三个部分组成parent XWork package 值在属性 struts.convention.default.parent.package 中指定（默认为conventionDefault），package 的属性值须继承于 strutsDefault 因此，Convention 插件中XWORK packages 采用如下命名规则： 1.
此外，你还可以修改action 配置文件中定 义的父XWORK 的包信息 Action annotation Convention 插件可以使用Action 注解语句来修改action 返回的URL 地址本注解同时也允许包含在Actions 语句中，用来使一个action 对应于多个 URL在 action 方法中使用本注解语句，可以参考以下代码： 1. package com.example.actions; 2. 3. import com.opensymphony.xwork2.ActionSupport; 4. import org.apache.struts2.convention.annotation.Action; 5. 6. public class HelloWorld extends ActionSupport { 7. @Action("/different/url") 8. public String execute() { 9. return SUCCESS; 10. } 11.} 现在我们action 类中将使用 /different/url 来替代默认的 /hello-world,如果未指定@Result（参考下节），result 的路径将会使用action 的 namespace，上面的例子中将会返回 一下路径 "/WEB-INF/content/different/url.jsp" 。
Action类中的单个方法可以使用Actions 注解来映射多个地址 1. package com.example.actions; 2. 3. import com.opensymphony.xwork2.ActionSupport; 4. import org.apache.struts2.convention.annotation.Action; 5. import org.apache.struts2.convention.annotation.Actions; 6. 7. public class HelloWorld extends ActionSupport { 8. @Actions({ 9. @Action("/different/url"), 10. @Action("/another/url") 11. }) 12. public String execute() { 13. return SUCCESS; 14. } 15.} 另外的 Action 或 Actions 的使用方法是，在单个action 类中定义多个action方法，每个方法对应一个不同的地址。
下面是多个action 方法的范例： 1. package com.example.actions; 2. 3. import com.opensymphony.xwork2.ActionSupport; 4. import org.apache.struts2.convention.annotation.Action; 5. import org.apache.struts2.convention.annotation.Actions; 6. 7. public class HelloWorld extends ActionSupport { 8. @Action("/different/url") 9. public String execute() { 10. return SUCCESS; 11. } 12. 13. @Action("url") 14. public String doSomething() { 15. return SUCCESS; 16. } 17.} 前面的例子中，第二个URL 地址是不推荐的，上面url 将使用java 包名作为namespace，而不会直接使用Action 注解的地址。
Interceptor 和 interceptor stacks 同样可以使用interceptorRefs 注解来指定下例演示了在action 中同时添加"validation"和 "defaultStack"拦截器 1. package com.example.actions; 2. 3. import com.opensymphony.xwork2.ActionSupport; 4. import org.apache.struts2.convention.annotation.Action; 5. import org.apache.struts2.convention.annotation.Actions; 6. 7. public class HelloWorld extends ActionSupport { 8. @Action(interceptorRefs={@InterceptorRef("validation"), @InterceptorRef("defaultStack")}) 9. public String execute() { 10. return SUCCESS; 11. } 12. 13. @Action("url") 14. public String doSomething() { 15. return SUCCESS; 16. } 17.} 可以通过params 属性来将参数传递给结果。
属性的值是一个偶数个元素的String 的数组，由形如{"key0", "value0, "key1", "value1" ... "keyN", "valueN"}所组成，举个例子： 1. package com.example.actions; 2. 3. import com.opensymphony.xwork2.ActionSupport; 4. import org.apache.struts2.convention.annotation.Action; 5. import org.apache.struts2.convention.annotation.Actions; 6. 7. public class HelloWorld extends ActionSupport { 8. @Action(interceptorRefs=@InterceptorRef(value="validation",params={"programmatic", "false", "declarative", "true})) 9. public String execute() { 10. return SUCCESS; 11. } 12. 13. @Action("url") 14. public String doSomething() { 15. return SUCCESS; 16. } 17.} 如果未指定interceptors，将会使用默认的。
InterceptorRef annotation Interceptors 可以在方法级进行指定，使用Action 注解或在类上使用InterceptorRefs 注解Class 级别的拦截会被应用到类包含的所有action 上可以参考下面例子： 1. package com.example.actions; 2. 3. import com.opensymphony.xwork2.ActionSupport; 4. import org.apache.struts2.convention.annotation.Action; 5. import org.apache.struts2.convention.annotation.Actions; 6. 7. @InterceptorRefs({ 8. @InterceptorRef("interceptor-1"), 9. @InterceptorRef("defaultStack") 10.}) 11.public class HelloWorld extends ActionSupport { 12. @Action(value="action1", interceptorRefs=@InterceptorRef("validation")) 13. public String execute() { 14. return SUCCESS; 15. } 16. 17. @Action(value="action2") 18. public String doSomething() { 19. return SUCCESS; 20. } 21.} 下面的拦截机将会应用到“action1”中："interceptor-1","defaultStack"中的所有拦截机, "validation" "defaultStack"中的所有拦截机也会对”action2”生效 Result annotation Convention 允许action 类为每个action 定义不同的results，results 分为两类，全局的（global）和本地的（local），全局 results 可以被action 类中所有的action 分享，这种results 在 action 类上使用注解进行声明。
本地results 只能在 action 方法上进行声明下面是两种results 注解的例子： 1. package com.example.actions; 2. 3. import com.opensymphony.xwork2.ActionSupport; 4. import org.apache.struts2.convention.annotation.Action; 5. import org.apache.struts2.convention.annotation.Actions; 6. import org.apache.struts2.convention.annotation.Result; 7. import org.apache.struts2.convention.annotation.Results; 8. 9. @Results({ 10. @Result(name="failure", location="fail.jsp") 11.}) 12.public class HelloWorld extends ActionSupport { 13. @Action(value="/different/url", 14. results={@Result(name="success", location="http://struts.apache.org", type="redirect")} 15. ) 16. public String execute() { 17. return SUCCESS; 18. } 19. 20. @Action("/another/url") 21. public String doSomething() { 22. return SUCCESS; 23. } 24.} 参数同样可以在results 中通过params 属性进行传递，和上面一样，由形如{"key0", "value0, "key1", "value1" ... "keyN", "valueN"}所组成。
可参考下例： 1. package com.example.actions; 2. 3. import com.opensymphony.xwork2.ActionSupport; 4. import org.apache.struts2.convention.annotation.Action; 5. import org.apache.struts2.convention.annotation.Actions; 6. import org.apache.struts2.convention.annotation.Result; 7. import org.apache.struts2.convention.annotation.Results; 8. 9. public class HelloWorld extends ActionSupport { 10. @Action(value="/different/url", 11. results={@Result(name="success", type="httpheader", params={"status", "500", "errorMessage", "Internal Error"})} 12. ) 13. public String execute() { 14. return SUCCESS; 15. } 16. 17. @Action("/another/url") 18. public String doSomething() { 19. return SUCCESS; 20. } 21.} Namespace annotation namespace 注解允许action 使用指定的路径替代默认的以package 包名作为路径。
本注解可以在action 类或Java 包中的package-info.java 类中进行设置设置在action类中的namespace注解，对本action类中所有的action都有 效，这是不完全合乎规范的action URL 处理地址设置在package-info.java 中的namespace 注解，将会改变本java 包下所有的action 的默认 namespace下面是此注解的例子： 1. package com.example.actions; 2. 3. import com.opensymphony.xwork2.ActionSupport; 4. import org.apache.struts2.convention.annotation.Action; 5. import org.apache.struts2.convention.annotation.Namespace; 6. 7. @Namespace("/custom") 8. public class HelloWorld extends ActionSupport { 9. @Action("/different/url") 10. public String execute() { 11. return SUCCESS; 12. } 13. 14. @Action("url") 15. public String doSomething() { 16. return SUCCESS; 17. } 18.} 在上例中的action 会对2 个不同的地址响应：/different/url 和 /custom/url 下面是一个在package-info.java中使用namespace 注解的例子： 1. @org.apache.struts2.convention.annotation.Namespace("/custom") 2. package com.example.actions; 这会改变com.example.actions包下所有action 的默认namespace 。
请注意一点，本注解不会应用到子一级的包中 ResultPath annotation ResultPath 注解用来更改默认的results 存储路径，注解可以放到action 的类中，也可以放到package-info.java 文件夹中参考下例： 1. package com.example.actions; 2. 3. import com.opensymphony.xwork2.ActionSupport; 4. import org.apache.struts2.convention.annotation.Action; 5. import org.apache.struts2.convention.annotation.ResultPath; 6. 7. @ResultPath("/WEB-INF/jsps") 8. public class HelloWorld extends ActionSupport { 9. public String execute() { 10. return SUCCESS; 11. } 12.} 上面的result 将以 WEB-INF/jsps 替换默认的 WEB-INF/content ParentPackage annotation ParentPackage 注解用来定义具体action 类的父XWork 包或java 包，下面例子演示了在action 类上使用本注解： 1. package com.example.actions; 2. 3. import com.opensymphony.xwork2.ActionSupport; 4. import org.apache.struts2.convention.annotation.Action; 5. import org.apache.struts2.convention.annotation.ParentPackage; 6. 7. @ParentPackage("customXWorkPackage") 8. public class HelloWorld extends ActionSupport { 9. public String execute() { 10. return SUCCESS; 11. } 12.} ExceptionMapping Annotation ExceptionMapping 注解用来影射action 抛出的异常。
可以参考exception mapping documentation 获得详细信息注解用类级别，在这种情况下，注解会应用到类里面的所有action 1. @ExceptionMappings({ 2. @ExceptionMapping(exception = "java.lang.NullPointerException", result = "success", params = {"param1", "val1"}) 3. }) 4. public class ExceptionsActionLevelAction { 5. 6. public String execute() throws Exception { 7. return null; 8. } 9. } 可以在ExceptionMapping 注解中使用params 属性来传递具体值给结果渲染页ExceptionMapping 注解同样可以在action 级别进行设置： 1. public class ExceptionsMethodLevelAction { 2. @Action(value = "exception1", exceptionMappings = { 3. @ExceptionMapping(exception = "java.lang.NullPointerException", result = "success", params = {"param1", "val1"}) 4. }) 5. public String run1() throws Exception { 6. return null; 7. } 8. } Actions in jar files 默认情况下，Convention 插件不会从jar 文件中寻找action。
如果想实现这一功能，jar 文件必须被 struts.convention.action.includeJars 所定义的正则 匹配到在例子中 myjar1.jar 和 myjar2.jar 将被插件检测到： 1.
