Hibernate.orgCommunity Documentation

第 1 章 开始入门

1.1. 第一个Maven项目
1.2. 添加约束
1.3. 校验约束
1.4. 更进一步

本章将会告诉你如何使用Hibernate Validator, 在开始之前,你需要准备好下面的环境:

注意

Hibernate Validator uses JAXB for XML parsing. JAXB is part of the Java Class Library since Java 6 which means that if you run Hibernate Validator with Java 5 you will have to add additional JAXB dependencies. Using Maven you have to add the following dependencies:

<dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
    <version>2.2</version>
</dependency>
<dependency>
    <groupId>com.sun.xml.bind</groupId>
    <artifactId>jaxb-impl</artifactId>
    <version>2.1.12</version>
</dependency>

if you are using the SourceForge package you find the necessary libraries in the lib/jdk5 directory. In case you are not using the XML configuration you can also disable it explicitly by calling Configuration.ignoreXmlConfiguration() during ValidationFactory creation. In this case the JAXB dependencies are not needed.

1.1. 第一个Maven项目

使用Maven archetype插件来创建一个新的Maven 项目

例 1.2. 使用Maven archetype 插件来创建一个简单的基于Hibernate Validator的项目

mvn archetype:generate -DarchetypeGroupId=org.hibernate \
                       -DarchetypeArtifactId=hibernate-validator-quickstart-archetype \
                       -DarchetypeVersion=4.2.0.Final \
                       -DarchetypeRepository=http://repository.jboss.org/nexus/content/groups/public-jboss/ \
                       -DgroupId=com.mycompany \
                       -DartifactId=hv-quickstart


Maven 将会把你的项目创建在hv-quickstart目录中. 进入这个目录并且执行:

mvn test

这样, Maven会编译示例代码并且运行单元测试, 接下来,让我们看看生成的代码.

注意

From version 4.2.0.Beta2, the maven command mvn archetype:create will be no longer supported and will fail. You should use the command described in the above listing. If you want more details, look at Maven Archetype plugin page.

1.2. 添加约束

在你喜欢的IDE中打开这个项目中的Car类:

例 1.3. 带约束性标注(annotated with constraints)的Car 类

package com.mycompany;


import javax.validation.constraints.Min;

import javax.validation.constraints.NotNull;

import javax.validation.constraints.Size;


public class Car {


    @NotNull

    private String manufacturer;


    @NotNull

    @Size(min = 2, max = 14)

    private String licensePlate;


    @Min(2)

    private int seatCount;

    

    public Car(String manufacturer, String licencePlate, int seatCount) {

        this.manufacturer = manufacturer;

        this.licensePlate = licencePlate;

        this.seatCount = seatCount;

    }


    //getters and setters ...

}

@NotNull, @Size and @Min就是上面所属的约束性标注( constraint annotations), 我们就是使用它们来声明约束, 例如在Car的字段中我们可以看到:

  • manufacturer永远不能为null

  • licensePlate永远不能为null,并且它的值字符串的长度要在2到14之间

  • seatCount的值要不能小于2

1.3. 校验约束

我们需要使用Validator来对上面的那些约束进行校验. 让我们来看看CarTest这个类:

例 1.4. 在CarTest中使用校验

package com.mycompany;


import static org.junit.Assert.*;


import java.util.Set;


import javax.validation.ConstraintViolation;

import javax.validation.Validation;

import javax.validation.Validator;

import javax.validation.ValidatorFactory;


import org.junit.BeforeClass;

import org.junit.Test;


public class CarTest {


    private static Validator validator;


    @BeforeClass

    public static void setUp() {

        ValidatorFactory factory = Validation.buildDefaultValidatorFactory();

        validator = factory.getValidator();

    }


    @Test

    public void manufacturerIsNull() {

        Car car = new Car(null, "DD-AB-123", 4);


        Set<ConstraintViolation<Car>> constraintViolations =

            validator.validate(car);


        assertEquals(1, constraintViolations.size());

        assertEquals("may not be null", constraintViolations.iterator().next().getMessage());

    }


    @Test

    public void licensePlateTooShort() {

        Car car = new Car("Morris", "D", 4);


        Set<ConstraintViolation<Car>> constraintViolations = 

            validator.validate(car);


        assertEquals(1, constraintViolations.size());

        assertEquals("size must be between 2 and 14", constraintViolations.iterator().next().getMessage());

    }

    

    @Test

    public void seatCountTooLow() {

        Car car = new Car("Morris", "DD-AB-123", 1);


        Set<ConstraintViolation<Car>> constraintViolations =

            validator.validate(car);


        assertEquals(1, constraintViolations.size());

        assertEquals("must be greater than or equal to 2", constraintViolations.iterator().next().getMessage());

    }


    @Test

    public void carIsValid() {

        Car car = new Car("Morris", "DD-AB-123", 2);


        Set<ConstraintViolation<Car>> constraintViolations =

            validator.validate(car);


        assertEquals(0, constraintViolations.size());

    }

}

在setUp()方法中,我们通过ValidatorFactory得到了一个Validator的实例. Validator是线程安全的,并且可以重复使用, 所以我们把它保存成一个类变量. 现在我们可以在test方法中使用这个validator的实例来校验不同的car实例了.

validate()方法会返回一个set的ConstraintViolation的实例的集合, 我们可以通过遍历它来查看有哪些验证错误. 前面三个测试用例显示了一些预期的校验约束:

  • 在manufacturerIsNull()中可以看到manufacturer违反了@NotNull约束

  • licensePlateTooShort()中的licensePlate违反了@Size约束

  • 而seatCountTooLow()中则导致seatCount违反了@Min约束

如果一个对象没有校验出问题的话,那么validate() 会返回一个空的set对象.

注意,我们只使用了Bean Validation API中的package javax.validation中的类, 并没有直接调用参考实现中的任何类,所以, 没有任何问题如果切换到其他的实现.

1.4. 更进一步

That concludes our 5 minute tour through the world of Hibernate Validator. Continue exploring the code examples or look at further examples referenced in 第 10 章 进一步阅读. To deepen your understanding of Hibernate Validator just continue reading 第 2 章 Validation step by step. In case your application has specific validation requirements have a look at 第 3 章 创建自己的约束规则.

版权 © 2009 - 2011 Red Hat, Inc. & Gunnar Morling