内容


Valang Validator 攻略

Comments

Valang 是 Validation Language 的缩写,Valang Validator 的字面含义就是“使用验证语言的验证器”,它是一种支持声明的验证器。作为新出的验证工具,它拥有不同于现有其它相似工具的特点:

  • 基于声明的验证工具包,大多数情况下可以避免手工书写代码。
  • 提供了一套精巧的 DSL(Domain Specific language),支持表达式语言。语法非常简洁,且支持扩展方便。
  • 配置精简,可读性高、易维护。
  • 包含在 Spring Module 中,简化了 Spring Framework 的 Validator 使用。
  • 支持 JavaScript,对于 Web 应用,支持客户端的验证。

本文将带领读者对以上特点一一寻访,在进一步阅读本文之前,请确保读者具有 Spring Framework 的使用经验,如果有 Spring MVC 的经验更佳。

使用概览

Valang Validator 属于 Spring Module 的 Validation 模块。Spring Module 是一组扩展 Spring Framework 功能的工具集,当前的版本是 0.6。它作为独立于 Spring Framework 的项目而存在,其目的非常单纯:方便 Spring Framework 与其它框架的集成,避免为此修改 Spring Framework 的核心。

使用 Valang Validator 必须先了解它的两个重要组件:

  • valang,即验证语法,使用者使用它将约束定义转化为 ValangValidator 能解析的验证规则。
  • ValangValidator,它是 Spring Validator 接口的具体实现。负责验证规则解析,完成实际的验证工作。

了解了这些关于 Valang Validator 的信息之后,不妨从一个例子来了解它的使用。本例使用的环境:JDK 1.5、Spring Framework2.0 和 Spring Module 0.6。

问题描述

为了尽可能的体现 Valang Validator 的特点,例子中需要验证的对象有意地被设计得稍微有些复杂:首先,属性是最常见的 3 种类型,而且其中还有一个是在 Java 中有些烦人的Date;其次,它还包含了一个成员类属性。关于类结构和相关的约束如下表:

类结构约束
public class User { private String name; private int age; private Date birthday; private Address address; …… } public class Address { private String state; private String town; private String street; …… }name,必填,且长度不超过 50。
 age,非必填,必须大于等于 0,小于等于 60。
 birthday,非必填,必须在 2000-01-01 之后。
 address.state,必填,长度不超过 50。
 address.town,必填,长度不超过 50。
 address.street,必填,长度不超过 200。

实现 Validator

实现 Valang Validator 就是要完成两部分工作:定义 valang 描述和 Validator 创建。Validator 的创建可以使用 Java 代码进行,也可使用 Spring DI 完成。本例采用后一种方法,Bean 定义如下(文件名:valang.xml):

<bean id="userValidator" class=
  "org.springmodules.validation.valang.ValangValidator">
  <property name="valang">
    <value>
      <![CDATA[
        { name  : ? is not null and ? has text and length(?)<= 50 
: 'Name is empty or too long.'}
        { age : ? between 0 and 60 : 'Age should between 0 and 60.'}
        { birthday : ? is null or ? >[20000101]
 : 'Birthday should be after 2000-01-01.'}
                { address : ? is not null : 'Address is empty.'}
        { address.state : address is null or ( ? is not null and
                                 ? has text and length(?)<=50 )
: 'state is empty or too long.'}
                { address.town : address is null or ( ? is not null and  
? has text and length(?)<=50 )
: 'town is empty or too long.'}
                { address.street : address is null or ( ? is not null and
 ? has text and length(?)<=50 )
: 'street is empty or too long.'}  
      ]]>
    </value>
  </property>
  <property name="dateParsers">
    <map>
      <entry key="^\\d{8}$" value="yyyyMMdd" />
    </map>
  </property>
</bean>

瞧,没有一行 Java 代码,居然完成了一个 Validator 的定义。这其中的秘密就是 valang 属性,它定义了验证规则。再看看它的语法,是不是很酷?!另一个属性 dateParsers 定义了日期转换的格式。关于它们的解释在后面有详细的介绍。

技巧:

如果 Adress 对象被多个对象引用,且对于 Address 的验证约束相同,那么以上的 address 相关的约束规则就需要重复书写。这样,既繁且不利于维护。此时,可以将 address 相关的约束组织成一个 validator,实现约束的复用。具体步骤:

a) 抽取 Address 的约束到 addressValidator。

<bean id="addressValidator" class="org.springmodules.validation.valang.ValangValidator">
  <property name="valang">
    <value>
      <![CDATA[
      { state : ? is not null and  ? has text and length(?)<=50
 : 'state is empty or too long.'}
            { town : ? is not null and  ? has text and length(?)<=50
 : 'town is empty or too long.'}
            { street : ? is not null and  ? has text and length(?)<=50
 : 'street is empty or too long.'}
      ]]>      
    </value>
  </property>
</bean>

b) 实现继承 ValangValidator 的 UserValidator,包含 addressValidator:

public class UserValidator extends ValangValidator {
private Validator addressValidator;

    public void setAddressValidator(Validator addressValidator) {
        this.addressValidator = addressValidator;
    }
    
    public void validate(Object target, Errors errors){
        super.validate( target, errors);
        Address address= ((User)target).getAddress();
        // address 为 null 时,不进行进一步的验证。
        if( null!= address){
            //注意与 popNestedPath 成对使用
            errors.pushNestedPath("address");
            //验证 address
            addressValidator.validate( address, errors);
            errors.popNestedPath();
        }
    }
}

c) 修改 userValidator 的配置。

<bean id="userValidator" class="包名.UserValidator">
    <property name="addressValidator" ref="addressValidator"/>
  <property name="valang">
    <value>
      <![CDATA[
      { name : ? is not null and ? has text and length(?)<= 50
: 'Name is empty or too long.'}
    { age : ? between 0 and 60 : 'Age should between 0 and 60.'}
    { birthday : ? is null or ? >[20000101] : 'Birthday should be after 2000-01-01.'}
            { address : ? is not null : 'Address is empty.'}
      ]]>      
    </value>
  </property>
  <property name="dateParsers">
    <map>
      <entry key="^\\d{8}$" value="yyyyMMdd" />
    </map>
  </property>
</bean>

单元测试

对 ValangValidator 进行单元测试非常简单,需要注意的是它的实例化。这里使用 BeanFactory 来创建待测的 Validator。Spring 提供了测试用例基类 AbstractDependencyInjectionSpringContextTests,使得手工创建完全避免:

public class UserValidatorTest extends AbstractDependencyInjectionSpringContextTests {
    private Validator userValidator;
    
    public UserValidatorTest(){
        super();
        //缺省是AUTOWIRE_BY_TYPE,当Bean文件有2个以上的同类型
        //Bean定义时就应该采用AUTOWIRE_BY_NAME方式。
        setAutowireMode(AUTOWIRE_BY_NAME);
    }

protected String[] getConfigLocations() {
    //指明配置文件的位置
        return new String[]{"file:文件路径/valang.xml"};
    }
    //基类调用该方法完成依赖注入(DI)
    public void setUserValidator(Validator userValidator) {
        this.userValidator = userValidator;
    }
    
    public void testEmptyObject(){
        User user= new User();
        BindException errors= new BindException(user, "target");
        userValidator.validate( user, errors);
        assertTrue( errors.getAllErrors().size()== 2);
        ObjectError error1= (ObjectError)(errors.getAllErrors().get(0));
        assertEquals(error1.getDefaultMessage(), "Name is empty or too long.");
        ObjectError error2= (ObjectError)(errors.getAllErrors().get(1));
        assertEquals(error2.getDefaultMessage(), "Address is empty.");
}
……
}

使用 Validator

上面的单元测试已经展示了 ValangValidator 的使用,除此之外,也可使用 BeanFactory 将它注入某个控制器中使用:

<bean id="userController" class="……">
    ……
  <property name="validator" ref="userValidator"/>
</bean>

从上面的例子来看,ValangValidator 的使用相当简单。尤其对于有过 Spring 经验的用户来说,除了需要掌握 valang 语法之外,其余的根本就和 Spring Validator 使用一样。而且,例子中 valang 的语法所展示的简洁、直观给人留下了深刻的印象。

Valang 语法

很酷!这是我看到 valang 的第一印象。Spring 数据绑定语法相同的属性表达式,灵活、便捷、易学的语法。这些,都使得另一个被广泛使用的声明性验证工具 Commons Validator 显得相形见绌。虽然作为早期的声明性验证工具的实现,Commons Validator 的功绩不可磨灭,但是其配置的繁琐也使人厌烦不已。

“以数据为中心”是 ValangValidator 的设计思路,此处的数据就是 valang 描述。valang 由一系列的规则组成,对于每个规则,它的结构如下:

{ <key> : <predicate_expression> : <message> [: <error_code> [: <args> ]] }

其中:

  • <key>,属性表达式。它是要验证的属性名,必填。
  • <predicate_expression>,谓词表达式。期望满足的条件,必填。
  • <message>,缺省消息。当不满足预期表达式时显示的消息,必填。
  • <error_code>,错误码。国际化时使用的消息键值,当它存在时缺省消息被忽略,可选。
  • <args>,参数。逗号分隔的参数值,用于替换错误码中定义的站位符,可选。

这些参数,除了谓词表达式之外,都可以在 Spring 中见到它们的踪影。而它们的含义、用法也丝毫没有发生变化。因此,让我们把关注的焦点集中在谓词表达式上。

表达式语法

valang 将谓词表达式定义成如下结构:

<expression> ::= <expression> ( ( "AND" | "OR" ) <expression> )+ | <predicate>

其中的谓词(<predicate>),是由操作符、文字常量、bean 属性、数学表达式和函数组成的可计算实体。

1.操作符

valang 的操作符有三种:一元操作符,二元操作符和其他操作符。支持的操作符如下表:

类型支持类型操作符说明
一元对象NULL | IS NULL为空
NOT NULL | IS NOT NULL非空
字符串HAS TEXT包含非空格的字符
HAS NO TEXTnull或只有空格字符
HAS LENGTH | IS NOT BLANK长度>0
HAS NO LENGTH | IS BLANKnull或长度=0
IS UPPERCASE | IS UPPER CASE |
IS UPPER
所有字母大写
IS NOT UPPERCASE |
IS NOT UPPER CASE |
IS NOT UPPER
不是所有字母大写
IS LOWERCASE | IS LOWER CASE | IS LOWER所有字母小写
IS NOT LOWERCASE |
IS NOT LOWER CASE |
IS NOT LOWER
不是所有字母小写
IS WORD 
IS NOT WORD 
二元字符串、日期、布尔和数字= | == | IS | EQUALS相等
!= | <> | >< | IS NOT | NOT EQUALS不等
数字、日期>|GREATER THAN |
IS GREATER THAN
大于
< | LESS THAN | IS LESS THAN小于
>= | => |
GREATER THAN OR EQUALS |
IS GREATER THAN OR EQUALS
大于等于
<= | =< | LESS THAN OR EQUALS | IS LESS THAN OR EQUALS小于等于
其他数字、日期BETWEEN A AND B大于等于A,且小于等于B
NOT BETWEEN A AND B小于A,或大于B
字符串、日期、布尔和数字IN <value> (, <value>)*在值列表中
NOT IN <value> (, <value>)*不在值列表中
布尔表达式NOT取反

这些操作符是大小写非敏感的,另外在使用时需要注意:

  • 避免在验证时出现 NullException,这一点可以在 userValidator 的例子中看到。
  • 二元操作符两边的操作数类型必须一致。

2.文字常数

Valang 支持 4 种文字常数:字符串、数字、日期和布尔。这四种类型的文字常数如下表:

类型说明
字符串字符串使用单引号包含,如 ’foxgem’。
数字数字被转换为 java.math.BigDecimal。
布尔布尔值必须是:TRUE、YES、FALSE、NO 中的一个,且不要使用单引号。
日期日期值使用 [] 包含,如 [2000-01-01]。

valang 对于日期类型的处理非常特殊,而且有趣:

  • 使用 T 来代表当前时间, 如 [T]。
  • 提供了移位操作,语法是:日期 > 时间单位,日期 < 时间单位。前者表示将日期中对应的单位部分向后滚动到该时间单位的最大值;后者表示将日期中对应的单位部分向前滚动到该时间单位的最小值。支持的时间单位和对应范围:

    1) 秒(s):0~999 毫秒
    2) 分钟(m):0秒0毫秒 ~ 59秒999毫秒
    3) 小时(H):0分0秒0毫秒 ~ 59分59秒999毫秒
    4) 天(d):0时0分0秒0毫秒 ~ 23时59分59秒999毫秒
    5) 星期(w):周一0时0分0秒0毫秒 ~ 周日23时59分59秒999毫秒
    6) 月(M):月第一天0时0分0秒0毫秒 ~ 月最后一天23时59分59秒999毫秒
    7) 年(y):年第一天0时0分0秒0毫秒 ~ 年最后一天23时59分59秒999毫秒

    如:[T>d],表示当天的 23 时 59 分 59 秒 999 毫秒。

  • 支持日期的增减运算。增减分别对应:“+”和“-”;数量对应:i 时间单位,i 表示整数。如:[T>d-1d+2H],表示先将当前时间后滚至当天的最后时刻,再减去一天,再加上 2 个小时。

    日期格式在 valang 中也有很好的支持,可以很方便的定义自己的格式。日期解析过程如下:

    1) 取出日期字符串,在 dateParsers 中定义 Map 的正则表达式键集合中进行匹配。
    2) 当找到符合的正则表达式时,以它为键值获取对应的日期格式串。
    3) 使用 SimpleDateFomat,将日期字符串按照日期格式串转化为对应的 Date 类型。

    因此,如果要在 valang 中使用 yyyy-MM-dd 的格式时,那么使用以下的定义:

    <entry key="^\\d{4}-\\d{2}-\\d{2}$" value="yyyy-MM-dd" />

3. bean 属性

bean 属性的用法和属性表达式的用法一样,在运行时它的值会被取出。另外,valang 使用“?”来表示在规则中定义的属性表达式的值。

4. 数学表达式

valang 支持的数学运算符有:+、-、*、/(或 div)、%(或 mod)。

5.函数

valang 内置的函数如下:

函数说明
length | len | size |count如果传入参数是集合或数组,那么返回它们的大小;否则,返回传入参数的 toString 所返回字符串的长度。
使用例子:length(?)<50
match | matches传入参数(参数 2)的 toString 返回的字符串是否匹配给定的正则表达式(参数1)。
使用例子:match('^\\d{2}$', ?) is true
email传入参数的 toString 返回的字符串是有效的 email。
使用例子:email(?) is true
upper将传入参数的 toString 返回的字符串转换为大写。
使用例子:upper(?)=='VALANG'
lower将传入参数的 toString 返回的字符串转换为小写。
使用例子:lower(?)=='valang'
!布尔值取反
使用例子:!(?) is true。

注意:它不能内嵌表达式,如“!(length(?)<= 50) is true”将会出错。
resolve解析消息码。
inRole传入参数是角色名,如果当前用户有这个角色,则返回 true。

valang 对于函数的支持并不是只仅仅提供几个简单的函数,它还允许用户自定义函数。这大大的扩展了它的表现力。

自定义函数

org.springmodules.validation.valang.functions.AbstractFunction 是 valang 函数的基类,所有的内置函数都是它的子类,自定义函数也必须从它继承。AbstractFunction 有几个重要的方法需要注意:

  • 构造函数,子类必须实现,不要忘了先调用 super。
  • definedExactNumberOfArguments、definedMaxNumberOfArguments、definedMinNumberOfArguments,分别是定义函数的参数个数,函数的最大参数个数、函数的最小参数个数。它们在构造函数中被调用。
  • init,在所有属性被设置后调用,负责初始化。
  • isAutowireByName 和 isAutowireByType,分别指定了函数的属性被 BeanFactory 自动装配采用的方法。
  • doGetResult,返回函数的结果。

下面通过实现一个自定义版本的 length 函数来了解自定义函数的编写和配置:

函数定义:

public class AnotherLengthFunction extends AbstractFunction {

    public AnotherLengthFunction(Function[] functions, int line, int column) {
        super(functions, line, column);
        //AnotherLengthFunction只支持一个参数
        definedExactNumberOfArguments(1);
    }

protected Object doGetResult(Object target) throws Exception {
    //返回参数1的toString的值。如果有多个参数,那么:
    //参数2:getArguments()[1].getResult(target).toString();以此类推。
//另外getArguments()的个数就是实际传入的参数个数。
        String value= getArguments()[0].getResult(target).toString();
        return new Integer(value.length());
    }

}

函数配置:

<property name="customFunctions">
  <map>
        <!-- 前者是函数使用的名字,后者对应函数实现的class。
            使用例子:anotherLength(?)<50
-->
    <entry key="anotherLength" value="AnotherLengthFunction"/>
  </map>
</property>

当自定义的函数需要外部的资源,如数据库连接、网络连接、文件等,可以通过 BeanFactory 自动装配来完成。此时需要覆盖 isAutowireByName 或 isAutowireByType,指定自动装配的类型,这两个函数不能同时覆盖。

客户端验证

对于 Web 应用程序来说,服务器的验证固然是必须的,但如果提供了客户端验证的话,那无疑是锦上添花的事情。幸运的是,Valang Validator 已经做到了这一点。要使用这一功能,需要先了解 2 个组件:

1. org.springmodules.validation.valang.javascript.taglib.ValangRulesExportInterceptor

这个拦截器的作用是输出被当前请求处理器所使用的 valang 验证规则到 ModelAndView 中,使 <validate> 可以利用这些信息。

在以下情况下之一时,该拦截器不做任何事情:

  • 当被拦截的请求处理器不是 BaseCommandController。
  • 请求处理器使用的 Validator 不是 ValangValidator 实例。
  • 请求处理器不输出一个 Command 对象到 model 中。

2. valang 标签库

valang 标签库完成客户端脚本的产生,并进行实际的客户端验证。它包含了 2 个标签:

标签作用属性说明
codebase产生被翻译的 javascript 验证规则执行所需要的代码。它应该每页包含一次,且在被产生的验证规则之前。includeScriptTags非必须,指示产生的 javascript 代码是否被 <script> 包含。
fieldErrorsIdSuffix非必须,指明用来包含属性错误信息的 <div> 或 <span> 的 id 的后缀。整个 id 的最后组成:
<属性名 >< fieldErrorsIdSuffix >
globalErrorsId非必须,指明用来包含全局错误信息的 <div> 或 <span> 的 id。
validate将valang规则翻译成对应的 javascript 验证规则。commandName非必须,指明需要验证的 command 对象名字。

接下来我们以一个例子来展示如何应用以上所学。例子本身并不复杂,就是在以上的 userValidator 例子的基础上,完成一个 Controller 和相关的 JSP 页面。例子的步骤和说明如下:

1. Controller 负责初始化 User 对象,在提交时取出 User 各属性的值放入到 ModelAndView 中。

public class UserController extends SimpleFormController {
    
    protected Object formBackingObject(HttpServletRequest request){
        User user= new User();
        user.setAddress( new Address());
        return user;
    }
    
    protected ModelAndView onSubmit(Object command) throws Exception{
        User user=(User)command;
        ModelAndView mav= new ModelAndView(getSuccessView());
        //取出user的属性,放到mav中。
        mav.addObject("isSubmit", "true");//提交处理的标志。
        return mav;
    }
    
    protected void initBinder(HttpServletRequest request,
                              ServletRequestDataBinder binder)
                              throws Exception{
        SimpleDateFormat format= new SimpleDateFormat("yyyy-MM-dd");
        binder.registerCustomEditor(Date.class, "birthday"
                                  , new CustomDateEditor(format, true));
    }
}

2. JSP 页面既充当 User 的编辑页面,又是 Controller 提交后的属性显示页面。它演示了 valang 标签库的配置和使用,是本例的重头戏。本例中使用了 Spring 2.0 中提供的 Spring Form 标签,关于它的使用请参见 Spring 手册。

<%@ page contentType="text/html" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="form" uri="http://www.springframework.org/tags/form" %>
<!-- 包含valang标签库 -->
<%@ taglib prefix="valang" uri="http://www.springmodules.org/tags/valang" %>
   
<html>
  <head>
<title>User Detail</title>
<!-- 请将codebase包含在<head>中,确保在页面显示时,
所需要的环境已经产生 -->
    <valang:codebase includeScriptTags="true" fieldErrorsIdSuffix="_error" 
                     globalErrorsId="global_error"/>
  </head>

  <body>
    <c:if test="${not empty param.isSubmit}">
      <!-- 显示提交之后的User各属性值 -->
    </c:if>
    <c:if test="${empty param.isSubmit}">
<form:form commandName="user" method="post">
  <!-- validate需要包含在<form>中,commandName
是UserController的CommandName -->
      <valang:validate commandName="user"/>
      <div id="global_error">
      </div>
      <table>
        <tr>
          <td>name:</td>
          <td>
          <form:input path="name" />
            <!-- 注意id的命名。在_error之前的属性名实际是
在valang验证规则中出现的属性表达式的名字。否则,将出错。
如:以上的userValidator的例子中,如果将address相关的属性
合并到一个中:
{ address: ? is not null 
          and address.state is not null and length(address.state)<= 50
and address.town is not null and length(address.town)<= 50
          and address.street is not null and length(address.street)<= 50
         : 'Invalida address.'}
那么,下面的 address 相关的属性对应的 <span> 的 id 就应该是:
address_error,且只有一个。因为多个时,会引起 javascript 的错误。
 -->
          <span id="name_error"><form:errors path="name"/></span>
          </td>
        </tr>
        <tr>
          <td>age:</td>
          <td>
          <form:input path="age" />
          <span id="age_error"><form:errors path="age" /></span>
          </td>
        </tr>
        <tr>
          <td>birthday:</td>
          <td>
          <form:input path="birthday" />
         <span id="birthday_error"><form:errors path="birthday" /></span>
          </td>
        </tr>
        <tr>
          <td>state:</td>
          <td>
          <form:input path="address.state" />
          <span id="address.state_error"><form:errors 
            path="address.state" /></span>
          </td>
        </tr>
        <tr>
          <td>town:</td>
          <td>
          <form:input path="address.town" />
          <span id="address.town_error"><form:errors 
              path="address.town" /></span>
          </td>
        </tr>
        <tr>
          <td>street:</td>
          <td>
          <form:input path="address.street" />
          <span id="address.street_error"><form:errors 
                  path="address.street" /></span>
          </td>
        </tr>
        <tr>
          <td colspan="2">
          <input type="submit" value="Submit" />
          </td>
        </tr>
      </table>
    </form:form>
    </c:if>
  </body>
</html>

3. 相关配置。

<bean id="handlerMapping" 
class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
  <property name="interceptors">
    <list>
      <ref bean="valangInterceptor"/>
    </list>
  </property>
  <property name="urlMap">
    <map>
     <entry key="/userDetail.htm"><ref bean="userController"/></entry>
    </map>
  </property>
</bean>

<bean id="userController" name="/userDetail.htm" class="example.UserController">
  <property name="formView" value="userDetail"/>
  <property name="successView" value="redirect:/userDetail.htm"/>
  <property name="validator" ref="userValidator"/>
    <property name="commandName" value="user"/>
    <property name="commandClass" value="example.User"/>
</bean>

<bean id="valangInterceptor"
 class="org.springmodules.validation.valang.javascript.taglib.
         ValangRulesExportInterceptor"/>

<bean id="viewResolver"
 class="org.springframework.web.servlet.view.InternalResourceViewResolver">
<property name="prefix" value="/WEB-INF/jsp/"/>
<property name="suffix" value=".jsp"/>
<property name="viewClass" value="org.springframework.web.servlet.view.JstlView"/>
</bean>

结束语

本文详细的介绍了 ValangValidator 的使用和相关所需的配置。作为一种新型的验证工具,它提供的验证语言(valang)具有简单、易学,易扩展等特点。由于采用验证语言,在大多数的情形下,避免了书写 Java 验证代码的需要。这些特性,极大的简化了通常繁琐的验证实现。与 Spring Framework 结合,也对于它的推广有了很好的起点。同时,在使用时也需注意,由于目前它的 1.0 版本尚未正式的发布,API 尚不稳定。对于这一点,使用者也需有心理准备。


相关主题


评论

添加或订阅评论,请先登录注册

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=10
Zone=Open source, Java technology
ArticleID=208875
ArticleTitle=Valang Validator 攻略
publish-date=04122007