菜鸟学Struts2——零配置(Convention )

　　又是周末，继续Struts2的学习，之前学习了，Struts的原理，Actions以及Results，今天对对Struts的Convention Plugin进行学习，如下图：

Struts Convention支持零配置进行开发，也就是约定约定优于配置的方式。

（1）环境准备

使用Convention Plugin进行开发，需要引入struts2-convention-plugin，完整的pom.xml依赖如下：

 <dependency>
     <groupId>org.apache.struts</groupId>
     <artifactId>struts2-core</artifactId>
     <version>2.3.31</version>
 </dependency>
 <dependency>
     <groupId>org.apache.struts</groupId>
     <artifactId>struts2-convention-plugin</artifactId>
     <version>2.3.31</version>
 </dependency>

（2）Action约定

convention有自己定义的struts-plugin.xml如下：

 <?xml version="1.0" encoding="UTF-8" ?>
 <!DOCTYPE struts PUBLIC
     "-//Apache Software Foundation//DTD Struts Configuration 2.3//EN"
     "http://struts.apache.org/dtds/struts-2.3.dtd">

 <struts order="20">
   <bean type="com.opensymphony.xwork2.UnknownHandler" name="convention" class="org.apache.struts2.convention.ConventionUnknownHandler"/>

   <bean type="org.apache.struts2.convention.ActionConfigBuilder" name="convention" class="org.apache.struts2.convention.PackageBasedActionConfigBuilder"/>
   <bean type="org.apache.struts2.convention.ActionNameBuilder" name="convention" class="org.apache.struts2.convention.SEOActionNameBuilder"/>
   <bean type="org.apache.struts2.convention.ResultMapBuilder" name="convention" class="org.apache.struts2.convention.DefaultResultMapBuilder"/>
   <bean type="org.apache.struts2.convention.InterceptorMapBuilder" name="convention" class="org.apache.struts2.convention.DefaultInterceptorMapBuilder"/>
   <bean type="org.apache.struts2.convention.ConventionsService" name="convention" class="org.apache.struts2.convention.ConventionsServiceImpl"/>

   <bean type="com.opensymphony.xwork2.config.PackageProvider" name="convention.packageProvider" class="org.apache.struts2.convention.ClasspathPackageProvider"/>
   <bean type="com.opensymphony.xwork2.config.PackageProvider" name="convention.containerProvider" class="org.apache.struts2.convention.ClasspathConfigurationProvider"/>

   <constant name="struts.convention.actionConfigBuilder" value="convention"/>
   <constant name="struts.convention.actionNameBuilder" value="convention"/>
   <constant name="struts.convention.resultMapBuilder" value="convention"/>
   <constant name="struts.convention.interceptorMapBuilder" value="convention"/>
   <constant name="struts.convention.conventionsService" value="convention"/>

   <constant name="struts.convention.result.path" value="/WEB-INF/content/"/>
   <constant name="struts.convention.result.flatLayout" value="true"/>
   <constant name="struts.convention.action.suffix" value="Action"/>
   <constant name="struts.convention.action.disableScanning" value="false"/>
   <constant name="struts.convention.action.mapAllMatches" value="false"/>
   <constant name="struts.convention.action.checkImplementsAction" value="true"/>
   <constant name="struts.convention.default.parent.package" value="convention-default"/>
   <constant name="struts.convention.action.name.lowercase" value="true"/>
   <constant name="struts.convention.action.name.separator" value="-"/>
   <constant name="struts.convention.package.locators" value="action,actions,struts,struts2"/>
   <constant name="struts.convention.package.locators.disable" value="false"/>
   <constant name="struts.convention.package.locators.basePackage" value=""/>
   <constant name="struts.convention.exclude.packages" value="org.apache.struts.*,org.apache.struts2.*,org.springframework.web.struts.*,org.springframework.web.struts2.*,org.hibernate.*"/>
   <constant name="struts.convention.relative.result.types" value="dispatcher,velocity,freemarker"/>
   <constant name="struts.convention.redirect.to.slash" value="true"/>
   <constant name="struts.convention.action.alwaysMapExecute" value="true"/>
   <constant name="struts.mapper.alwaysSelectFullNamespace" value="true"/>
   <!-- <constant name="struts.convention.action.includeJars"  /> -->
   <constant name="struts.convention.action.fileProtocols" value="jar" />

   <constant name="struts.convention.classes.reload" value="false" />

   <constant name="struts.convention.exclude.parentClassLoader" value="true" />

   <package name="convention-default" extends="struts-default">
   </package>
 </struts>

struts-plugin.xml是会被struts加载的，struts默认回加载"struts-default.xml,struts-plugin.xml,struts.xml";这些XML。这里需要关注的是上面的24行-36行。

Convention默认扫描的包含struts, struts2, action 或 actions的包，在这些包中实现了com.opensymphony.xwork2.Action或者是名字以Action结尾（上面struts-plugin.xml第26行的配置）的类型会被当作Action处理。下面这些类都会被当作Action处理：

 com.example.actions.MainAction
 com.example.actions.products.Display (implements com.opensymphony.xwork2.Action)
 com.example.struts.company.details.ShowCompanyDetailsAction

而struts, struts2, action 或 actions下面的子包会被当作命名空间（namespace）

 com.example.actions.MainAction -> /
 com.example.actions.products.Display -> /products
 com.example.struts.company.details.ShowCompanyDetailsAction -> /company/details

Action类的驼峰命名规则将被“-”分隔（上面struts-plugin.xml第32行配置）如下：

 com.example.actions.MainAction -> /main
 com.example.actions.products.Display -> /products/display
 com.example.struts.company.details.ShowCompanyDetailsAction -> /company/details/show-company-details

下面是一个Action约定的例子（创建3个Action分别对应上面3种规则）：

 package yaolin.core.action;
 /**
  * /out.action
  * @author yaolin
  */
 public class OutAction { // 对应第一种规则
     public String execute() {
         return "success";
     }
 }

 package yaolin.core.action.ns;
 /**
  * ns子包名作为命名空间
  * /ns/in.action
  * @author yaolin
  */
 public class InAction { // 对应第二种规则

     public String execute() {
         return "input";
     }

     // /ns/in!play.action
     public String play() {
         return "play";
     }
 }

 package yaolin.core.action.ns;
 /**
  * ns子包名作为命名空间
  * /ns/nil-oay.action
  * @author yaolin
  */
 public class NilOayAction { // 对应第三种规则

     public String execute() {
         return "input";
     }
 }

创建struts.xml 开启“！”方法匹配（这里非必要，用于匹配play方法）

 <!DOCTYPE struts PUBLIC
     "-//Apache Software Foundation//DTD Struts Configuration 2.3//EN"
     "http://struts.apache.org/dtds/struts-2.3.dtd">
 <struts>
     <constant name="struts.enable.DynamicMethodInvocation" value="true" />
 </struts>

创建对应result的jsp页面（上面struts-plugin.xml第24行指定了jsp文件的根路径问“/WEB-INF/content”）

（2）Result约定

Result约定是在action名字之后加上“-result”，即如果InAction方法返回的是"input"，那么jsp的名称为"in-input"（“in-input.jsp”），如果方法放回的是“success”则既可以匹配“in.jsp”也可以匹配“in-success.jsp”，如下表：

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/hello	error	/WEB-INF/content/test/test2/hello-error.html	Dispatcher

详见Struts源码，如下：

 org.apache.struts2.convention.ConventionUnknownHandler#handleUnknownResult
 public Result handleUnknownResult(ActionContext actionContext, String actionName,ActionConfig actionConfig, String resultCode) throws XWorkException {

     PackageConfig pkg = configuration.getPackageConfig(actionConfig.getPackageName());
     String ns = pkg.getNamespace();
     String pathPrefix = determinePath(actionConfig, ns);

     Result result = scanResultsByExtension(ns, actionName, pathPrefix, resultCode, actionContext);

     if (result == null) {
         // Try /idx/action/index.jsp
         Map<String, ResultTypeConfig> resultsByExtension = conventionsService.getResultTypesByExtension(pkg);
         for (String ext : resultsByExtension.keySet()) {
             if (LOG.isTraceEnabled()) {
                 String fqan = ns + "/" + actionName;
                 LOG.trace("Checking for [#0/index.#1]", fqan, ext);
             }
             String path = string(pathPrefix, actionName, "/index", nameSeparator, resultCode, ".", ext);
             result = findResult(path, resultCode, ext, actionContext, resultsByExtension);
             if (result != null) {
                 break;
             }
             path = string(pathPrefix, actionName, "/index.", ext);
             result = findResult(path, resultCode, ext, actionContext, resultsByExtension);
             if (result != null) {
                 break;
             }
         }
     }

     if (result == null && resultCode != null) {
         //try to find an action to chain to. If the source action is "foo" and
         //the result is "bar", we will try to find an action called "foo-bar"
         //in the same package
         String chainedTo = actionName + nameSeparator + resultCode;
         ActionConfig chainedToConfig = pkg.getActionConfigs().get(chainedTo);
         if (chainedToConfig != null) {
             if (LOG.isTraceEnabled()) {
                 LOG.trace("Action [#0] used as chain result for [#1] and result [#2]", chainedTo, actionName, resultCode);
             }
             ResultTypeConfig chainResultType = pkg.getAllResultTypeConfigs().get("chain");
             result = buildResult(chainedTo, resultCode, chainResultType, actionContext);
         }
     }
     return result;
 }

（3）chain约定

如果Action的方法中返回的result中没有对应的物理视图且这个result跟这个Action类中的某个方法名一致，那么Struts，会自动转化成chain类型，规则是当前action+"-"+result（这里的"-"是上面struts-plugin.xml第32行配置）。

从上面org.apache.struts2.convention.ConventionUnknownHandler#handleUnknownResult的源码中可以看出如果result没有匹配到且“index”和默认拓展etx都没有匹配到result，那么struts会进行chain处理，如果原action是“foo”、result是“bar“，则chain为”foo-bar“，注意这里action是"action",不是Action中的方法("！"后面的)，看一下下面的例子：

 package yaolin.core.action.ns;

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

 /**
  * ns子包名作为命名空间
  * /ns/nil-oay.action
  * @author yaolin
  */
 public class NilOayAction {

     public String foo() {
         return "bar";
     }

     // chain to
     @Action("nil-oay-bar")
     public String bar() {
         return "foo-bar";
     }
 }

这里foo是NilOayAction的一个方法（非execute），则访问规则为/ns/nil-oay!foo.action，但是没有为其指定"nil-oay-bar.jsp"物理视图，而NilOayAction类中有跟result一样名字的bar函数。那么Struts会将其转化为Chain，上一个action名称，即"nil-oay"（这里不是foo，foo是方法名，不是action），再加入result，即"bar"，组成"nil-oay-bar"，这样会访问上面的bar()方法，bar()方法@Action("nil-oay-bar")，这时返回result="foo-bar"，对应的物理视图为"/WEB-INF/content/nil-oay-bar-foo-bar.jsp"，如果找不到，则会直接找"/WEB-INF/content/foo-bar.jsp"。

（4）注解

(a)Action 注解：

Annotation	Description
Actions Annotation	Group of @Action annotations, maps multiple URLs to the same action
Action Annotation	Defines the URL of an action
InterceptorRefs Annotation	Gropup of @InterceptorRef annotations
InterceptorRef Annotation	Interceptor, or interceptor stack to be applied to at action
Results Annotation	Group of @Result annotations
Result Annotation	Defines a result for an action
Namespace Annotation	Set the path of the action URL (used to overwrite the default)
ResultPath Annotation	Set where the results are located (used to overwrite the default)
ParentPackage Annotation	Set the parent package of the actions (used to overwrite the default)
ExceptionMappings	Group of @ExceptionMapping annotations
ExceptionMapping	Defines an exception mapping

(b)Workflow  注解

Annotation	Description
InputConfig Annotation	Defines what method to execute, or result to be returned if there are validation errors

(c) Interceptor 注解

Annotation	Description
After Annotation	Marks a action method that needs to be executed after the result.
Before Annotation	Marks a action method that needs to be executed before the main action method.
BeforeResult Annotation	Marks a action method that needs to be executed before the result.

(d) Validation 注解

Annotation	Description
ConversionErrorFieldValidator Annotation	Checks if there are any conversion errors for a field.
DateRangeFieldValidator Annotation	Checks that a date field has a value within a specified range.
DoubleRangeFieldValidator Annotation	Checks that a double field has a value within a specified range.
EmailValidator Annotation	Checks that a field is a valid e-mail address.
ExpressionValidator Annotation	Validates an expression.
FieldExpressionValidator Annotation	Uses an OGNL expression to perform its validator.
IntRangeFieldValidator Annotation	Checks that a numeric field has a value within a specified range.
RegexFieldValidator Annotation	Validates a regular expression for a field.
RequiredFieldValidator Annotation	Checks that a field is non-null.
RequiredStringValidator Annotation	Checks that a String field is not empty.
StringLengthFieldValidator Annotation	Checks that a String field is of the right length.
UrlValidator Annotation	Checks that a field is a valid URL.
Validation Annotation	Marker annotation for validation at Type level.
Validations Annotation	Used to group validation annotations.
VisitorFieldValidator Annotation	Invokes the validation for a property's object type.
CustomValidator Annotation	Use this annotation for your custom validator types.

（e）Type Convention 注解

Annotation	Description
Conversion Annotation	Marker annotation for type conversions at Type level.
CreateIfNull Annotation	For Collection and Map types: Create the types within the Collection or Map, if null.
Element Annotation	For Generic types: Specify the element type for Collection types and Map values.
Key Annotation	For Generic types: Specify the key type for Map keys.
KeyProperty Annotation	For Generic types: Specify the key property name value.
TypeConversion Annotation	Used for class and application wide conversion rules.

接下来将用注解进行开发。

未完，待续。