Commons-Validator

Commons-Validator

Commons-Validator （一）

    Commons-Validator 包用来把验证规则程序提取出来，以供重复使用。这个包可以使用在 Struts 中，也可以独立的应用在任何其它的应用中。用户可以通过 Java 类的方式自定义验证方法，也可以在配置文件中通过正则表达式配置验证方法。它不但支持服务器端的验证，客户端的验证也支持，具体需要使用 tag 把相应的 js 方法写入相应的页面中。

一、综述：
     整个 Validator 框架可以有若干个 FormSet ，而每个 FormSet 又可以有若干个 Form ，每个 Form 中可以有若干个 Field 。 FormSet 的 process(...) 方法，逐个调用其中的 Form 的 process(...) 方法，而 Form 的 process(...) 方法又是逐个调用 Field 的 process(...) 方法。 Validator 类作为验证的起始点，调用与其一一对应的 Form 的 validate(...) 方法，而 Form 的 validate(...) 方法又是逐个调用其中 Field 的 validate(...) 方法实现的。

二、配置文件说明：

<form-validation>
   <global>
      <constant>
        <constant-name> 验证方法的标志名 </constant-name>
        <constant-value> 正则表达式 </constant-value>
      </constant>
      <validator name=" 这个验证方法的标志名，供下面的 depends 调用 "
                 classname=" 这个验证方法在哪个类中，为类全名 "
                 method=" 验证方法的名称 "
                 methodParams=" 这个验证方法需要的参数类型，依次以逗号格开，为类全名 "
                 depends=" 基于什么验证之上，可以为多个值，以逗号格开，值为方法的标志名 "
                 jsFunction="js 的方法全名，格式为文件路径 . 方法名。文件路径以点隔开，
                             如果不填，默认为 org.apache.commons.validator.javascript.xxxx"
                 msg=" 对应于 properties 文件中的一条，作为不通过验证时返回的信息 "/>
   </global>
   <formset language=" 语言 " country=" 城市 " variant=" 方言？ ">
      <constant>
        <constant-name> 验证方法的标志名 </constant-name>
        <constant-value> 正则表达式 </constant-value>
      </constant>
      <form name="bean 对象名称 ">
         <field property="bean 中的属性名 "  depends=" 需要什么样的验证，可以为多个值，以逗号格开，值为方法的标志名 ">
           <arg name = " 变量名 " key = "properties 文件的 key ，或者来自 Var 的 name" resource = " 是 / 否来自资源文件 "/>
           <var>
             <var-name> 变量名 </var-name>
             <var-value> 变量值 </var-value>
           </var>
         </field>
      </form>
   </formset>  
</form-validation>


Commons-Validator （二）

     在 Validator 的配置文件中，一共有如下几个基本元素。

一、 org.apache.commons.validator.Var
     它的作用是为配置文件 (validator.xml) 中的其它标签提供可取用的变量，为 Field 提供执行验证所需要的其它参数值，比如最大长度。这个类有如下属性： name ，变量的名称； value ，变量的值； jsType ，当要自动生成 js 的时候， js 的类型。

二、 org.apache.commons.validator.Arg
     它的作用是替换信息中的某一部分，或者为验证方法提供必需的参数值。这个类有如下属性： bundle ，资源文件名，用来存放所需要的信息。 key ，表示 Arg 的 key 或者 value 。 name ，表示 Arg 的名称。 position ，这个 Arg 中的值用来替换信息中的哪一部分，需要替换的部分以 {n} 标志。 resource ： key 所指定的信息是否来自外部的资源文件，默认为 true ；如果为 true ，则代表 key 为 buddle 属性所指定的资源文件中的 key 。

三、 org.apache.commons.validator.Msg
     它的作用是在验证不通过时，应该返回什么的信息。这个类有如下属性： bundle ，资源文件名，用来存放所需要的信息。 key ，表示 Msg 的 key 或者 value 。 name ，表示 Msg 的名称。 resource ： key 所指定的信息是否来自外部的资源文件，默认为 true ；如果为 true ，则代表 key 为 buddle 属性所指定的资源文件中的 key 。

四、 org.apache.commons.validator.FormSet
     这个类管理通过一个 Map 所有要检验的 Form 对象， key 为 Form 的 name ；同时通过一个 Map 管理在 <formset/> 中定义的 Constant ， key 为 <constant-name> 。同时其内部有 language ， country ， variant 这几个属性，用来实现国际化。一个配置文件可以有多个 FormSet ，这些 FormSet 的区别是要求不同的本地化。

五、 org.apache.commons.validator.Form
     这个类有如下属性： name ，这个 form 的名称。 lFields ，一个保存所有 Field 的 List 。 hFields ，一个保存所有 Field 的 FastHashMap ，这个 FastHashMap 的 key 值是对应 Field 的 key 属性 ( 对应配置文件中的 property) 。这个类通过 validate(...) 方法用来对这个 Form 中的所有位置低于 page 的 Field 进行验证。它实际是在一个循环中逐个调用每个 field 的 validate(...) 方法，然后把结果保存在一个 ValidatorResults 对象中。

六、 org.apache.commons.validator.Field
     这个类有如下属性： depends ，依赖于什么验证规则。 dependencyList 保存了以逗号为分隔符把 depends 分割生成的 list 。 page ，如果是多步提交的话当前是第几步，值等于或小于表单中 page 性质的值， JavaBean 才会得到处理； args ，是一个数组；这个数组的元素为 HashMap ，每个 HashMap 在数组的位置就是其中的 Arg 中的 position 属性的值； HashMap 中的 key 值为 Arg 的 name ，如果这个 name 为 null 则为默认的值： DEFAULT_ARG(org.apache.commons.validator.Field.DEFAULT) ， value 为 Arg 对象。 hVars ，是一个 FastHashMap ，用来管理所有的 Var 对象， key 为 Var 的 name ，值为 Var 对象。 getIndexedListProperty 表明这个 property 为 JavaBean 中的一个数组元素的 index 。

1 、 process(Map globalConstants, Map constants)
     这个方法用来执行配置文件中变量的替换。它的两个参数分别为在 <global/> 和 <formset/> 中定义的 constant 。在这个 Map 中， key 为 <constant/> 标签中的 constant-name ， value 为 <constant-value> 。在配置文件中，可以实现如下的变量使用方式： Form 的 property 属性， Var 中的 value 属性， Arg 中的 key 属性， Msg 的 key 属性，他们均可以通过 {constant-name} 的方式，引用在 <global/> 或者 <formset/> 标签中定义的 constant 。 Arg 中的 key 属性，可以通过 {Var:var-name} 的方式引用在 <var/> 中定义的 Var 。

    FormSet 中的 process(...) 方法依次调用其中的 Form 的 process(...) 方法，而 Form 的 process(...) 方法又依次调用其中的 Field 的 process(...) 方法。

2 、 validate(Map params, Map actions)
     执行验证，其中 actions 保存了所有的 ValidatorAction 对象。它首先会从 params 取出 key 为 Validator.BEAN_PARAM(java.lang.Object) 的值作为要验证的 JavaBean 。然后通过 generateKey() 方法判断当前要验证的 Field 是否是 IndexedList 。如果是，则需要分别对这个 List 中的各个元素进行验证；否则直接执行对与 JavaBean 的特定属性 (property) 执行验证。

3 、 validateForRule(...)
     接受要执行的 ValidatorAction 对象的同时，还是会接受 Map actions 参数，这是因为这个要执行的 ValidatorAction 可能会依赖于其它的 ValidatorAction 。它会先查找以前的验证结果，如果以前没有执行过这个验证，那么执行 runDependentValidators(...) 方法，执行它所依赖于的 ValidatorAction ；如果通过，那么再对要执行的 ValidatorAction ，执行验证。


Commons-Validator （三）

     在 Validator 包中提供了一些 Util 类，同时提供了对基本数据类型，时间， E-mail ，信用卡等格式的验证方法。

一、 org.apache.commons.validator.util.Flags
     这个类用来管理一系列的 Flag ，其中的每个 Flag 的值都是 2 的 N 次方。然后每个 Flag 之间位与 (&) 就得到了整个 Flags 的值。

二、 org.apache.commons.validator.util.ValidatorUtils
     这个类为 Validator 提供一些 Utility 的操作，共有三个方法。

1 、 replace(...)
     这个方法用来将一个字符串中某个特性的字符串替换为另一个字符串，注意这是一个全局替换方法。

2 、 getValueAsString(...)
     这个方法用来获取某个 Bean 中的一个特定的属性，然后把属性值转换为字符串返回。注意， String[] 和 Collection 类型的值，如果里面不包含任何值，则直接返回 "" 。

3 、 copyFastHashMap(...)
     很显然的是对一个特定的 FashHashMap 执行 copy 。这里要注意的是，如果 value 为 Msg ， Arg ， Var 类型的时候需要执行 clone ，然后再保存。

三、 org.apache.commons.validator.ValidatorUtil
     这个类完全通过调用上面的 ValidatorUtils 方法，实现自己的同名方法。只是多了一个 getDelimitedRegExp(...) 方法，用来生成一个正则表达式。

四、 org.apache.commons.validator.DateValidator
     实现了单例模式。这个类用来检查日期类型是否合法，日期的类型要通过参数传递给这个 Validator 。同时还有一个 strict 属性，表示时候检查过渡匹配所要求的日期格式。这个日期检查就是通过 formatter.parse(value) 方法检查时候有异常抛出。

五、 org.apache.commons.validator.EmailValidator
     实现了单例模式。这个类用来检查 Email 类型是否合法。它通过正则表达式实现验证。

六、 org.apache.commons.validator.GenericTypeValidator
     这个类实现了对基本类型 (Byte ， Short ， Int ， Long ， Float, Date) 的检测，方法很简单，就是通过每个类型的构造函数创建相应的对象，如果抛出异常就说明不符合，否则符合。同时，这个类还提供对 CreditCard 验证的实现。


Commons-Validator （四）

     通过调用 Validator 的 validate(...) 方法，启动验证。

一、 org.apache.commons.validator.Validator
     这个类是对一个 Form 执行验证的起点，通过调用这个类的 validate(...) 方法，启动验证。这个类中的 formName 属性，对应于 Form 中的 name 属性。 resources 属性，记录这个 Validator 属于哪一个 ValidatorResources 。 parameters 用来管理执行 validateXXX(...) 方法时所需要的参数，它是一个 Map ， key 为类全名， value 为这个类全名所指的类的一个对象。注意，这个 parameters 是这个 Form 中所有 Field 所要执行的所有 validateXXX(...) 方法时所需要的参数集合。每个 validateXXX(...) 方法，根据自己需要的参数名 ( 类全名 ) ，从这个 parameters 中查取自己所需要的参数。

二、 org.apache.commons.validator.ValidatorAction
     每个 ValidatorAction 对应于配置文件中的一个 <validator/> 。它有如下属性： name ，这个验正动作的标志名，用在 depends 属性的配置中。 classname ，这个验证方法在哪个类中，为类全名。 validationClass ，由 classname 生成的 Class 。 method ，这个验证方法的名称。 validationMethod ，由 method 生成的 Method 。 methodParams ，执行这个验证方法所需要的参数，值为逗号隔开的类全名，默认值为 Validator.BEAN_PARAM,Validator.VALIDATOR_ACTION_PARAM,Validator.FIELD_PARAM 。 parameterClasses ，由 methodParams 生成的 Class 数组。 depends ，依赖何 ValidatorAction 之上。 msg ，如果没有通过此验证，应该返回什么消息。 javascript ，为对应的 javascript 方法的代码内容。 jsFunction ，为对应的 js 文件名称。 jsFunctionName ，对应的 js 中方法的名称。

1 、 executeValidationMethod(...)
     这个方法用对 Field 中的值进行检测。它实际上就是通过反射，根据类名、方法名和参数类型执行相应的验证方法。要注意的是，如果这个 Field 为 indexList 类型的，则需要把 Java Bean 替换为对应的 Array 中 pos 指定的元素。同时 Field 的 key 属性中的 [] 要变为 [pos] 。

2 、这个类还提供了对 js 的基本操作，解释如下：
*generateJsFunction()
     用来生成名为 org.apache.commons.validator.javascript.validateXxxx 的 js 文件名。其中 Xxxx 与 name 相对应。

*readJavascriptFile(...)
     用来读取 js 文件。由于一个 js 文件只包含一个方法，因此会读取所有的内容后，直接返回所读取的所有内容。

三、 org.apache.commons.validator.ValidatorResults
     这个类管理对一个 Form 中的所有 Field 执行验证的结果。它有如下属性： hResults ，用来管理对所有 Field 验证的结果，它的 key 为 field 的 kye 属性，它的 value 为 ValidatorResult 对象。

四、 org.apache.commons.validator.ValidatorResult
     这个类用来管理对于一个 Field 执行验证的时候，所有的验证方法的结果。它有如下属性： field ，所要验证的 Field 对象。 hAction ，用来保存所有验证结果的 Map ，它的 key 为 ValidatorAction 中的 name 属性， value 为 ResultStatus 对象。

五、 org.apache.commons.validator.ResultStatus
     它封装了对某个 Field 执行某个验证后的结果。它有如下属性： valid ，表示是否通过验证。 result ：为执行验证后的结果。



Commons-Validator （五）

     最后，说明 Validator 是如何初始化的。

一、 org.apache.commons.validator.ValidatorResourcesInitializer
     这个类用来初始化 Validator 框架，通过 Digester 包解析用户自定义的 xml 配置文件。然后把解析的结果保存到 ValidatorResources 对象中，最后返回这个 ValidatorResources 对象。

二、 org.apache.commons.validator.ValidatorResources
     这个类用来管理 Validator 框架中的资源。它包含如下属性： hFormSets ，一个 FastHashMap ，用来管理所有的 FormSet ，这个 FastHashMap 的 key 为根据 FormSet 中的本地信息生成的。 hConstants ，一个 FastHashMap ，用来管理 <global/> 中定义的 constant 。 hActions ，一个 FastHashMap ，用来管理 ValidatorAction ，它的 key 为 ValidatorAction 的 name 属性。

三、与 struts 整合时需要增加的配置：
     在 struts-config.xml 文件中加入：
    

<plug-in className="org.apache.struts.validator.ValidatorPlugIn">
        <set-property property="pathnames" value="/WEB-INF/validator-rules.xml,/WEB-INF/validation.xml" />
    </plug-in>

     其中 validator-rules.xml ，为 Struts 自带的配置文件，配置了所有的验证方法；而 validation.xml 为用户自己配置，配置要验证的对象。

四、org.apache.struts.validator.FieldChecks
     这个是 Struts 使用的核心验证类，用来实现各种验证规则。其中， validateXXX(...) 就是想要创建的方法名，只要规则名没有重复即可。 validateXXX(...) 方法的参数说明：
    Object             验证是在此 JavaBean 对象上完成的
    ValidatorAction     当前所执行的 ValidatorAction
      Field               被验证的字段对象
    ActionErrors       如果验证失败，新增 ActionError 对象的错误对象
    HttpServletRequest 当前的请求对象

五、org.apache.commons.validator.ValidatorResources
     这个类用来通过 Arg 替换 Msg 中格式为 {N} 的字符串

六、org.apache.commons.validator.ValidatorPlugIn
     这个类用来初始化 Validator ，然后把初始化生成的 ValidatorResources 对象保存到 ServletContext 中， key 为 VALIDATOR_KEY + config.getPrefix() 。

七、org.apache.struts.validator.Resources
这个类用来初始化一个 Validator 对象，它首先通过 key 值 VALIDATOR_KEY + config.getPrefix() 从 ServletContext 取得相应的 ValidatorResources 对象。它再以这个对象为参数构造一个 Validator 对象，然后把验证方法需要的参数保存到 Validator 对象的 parameters 属性中