Intro to Apache BVal – Apache BVal介绍

1. Introduction

1.介绍

In this article, we will take a look at the Apache BVal library’s implementation of the Java Bean Validation specification (JSR 349).

在这篇文章中，我们将看看Apache BVal库对Java Bean验证规范（JSR 349）的实现。

2. Maven Dependencies

2.Maven的依赖性

In order to use Apache BVal, we first need to add the following dependencies to our pom.xml file:

为了使用Apache BVal，我们首先需要在pom.xml文件中添加以下依赖项。

<dependency>
    <groupId>org.apache.bval</groupId>
    <artifactId>bval-jsr</artifactId>
    <version>1.1.2</version>
</dependency>
<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>1.1.0.Final</version>
</dependency>

Custom BVal constraints can be found in the optional bval-extras dependency:

自定义BVal约束可以在可选的bval-extras依赖中找到。

<dependency>
    <groupId>org.apache.bval</groupId>
    <artifactId>bval-extras</artifactId>
    <version>1.1.2</version>
</dependency>

The latest versions of bval-jsr, bval-extras, and validation-api can be downloaded from Maven Central.

bval-jsr、bval-extras和validation-api的最新版本可以从Maven中央下载。

3. Applying Constraints

3.应用约束条件

Apache BVal provides implementations for all the constraints defined in the javax.validation package. In order to apply a constraint to a property of a bean, we can add the constraint annotation to the property declaration.

Apache BVal为javax.validation包中定义的所有约束提供实现。为了将约束条件应用于Bean的某个属性，我们可以在属性声明中添加约束条件注释。

Let’s create a User class which has four attributes, then apply the @NotNull, @Size, and @Min annotations:

让我们创建一个有四个属性的User类，然后应用@NotNull、@Size和@Min注释。

public class User {
    
    @NotNull
    private String email;
    
    private String password;

    @Size(min=1, max=20)
    private String name;

    @Min(18)
    private int age;

    // standard constructor, getters, setters
}

4. Validating Beans

4.验证Bean

To validate the constraints applied on the User class, we need to obtain a ValidatorFactory instance and one or more Validator instances.

为了验证应用于User类的约束，我们需要获得一个ValidatorFactory实例和一个或多个Validator实例。

4.1. Obtaining a ValidatorFactory

4.1.获取一个ValidatorFactory

It is recommended by the Apache BVal documentation to obtain a single instance of this class, as factory creation is a demanding process:

Apache BVal文档建议获得该类的单个实例，因为工厂创建是一个苛刻的过程。

ValidatorFactory validatorFactory 
  = Validation.byProvider(ApacheValidationProvider.class)
  .configure().buildValidatorFactory();

4.2. Obtaining a Validator

4.2.获得一个验证器

Next, we need to get a Validator instance from the validatorFactory defined above:

接下来，我们需要从上面定义的validatorFactory中获得一个Validator实例。

Validator validator = validatorFactory.getValidator();

This is a thread-safe implementation, so we can safely reuse already created instances.

这是一个线程安全的实现，所以我们可以安全地重复使用已经创建的实例。

The Validator class offers three methods for determining the validity of a bean: validate(), validateProperty() and validateValue().

Validator类提供了三种方法来确定Bean的有效性：validate()、validateProperty()和validateValue()。

Each of these methods returns a set of ConstraintViolation objects that contain information about the constraint that was not obeyed.

这些方法中的每一个都会返回一组ConstraintViolation对象，这些对象包含了关于不遵守的约束的信息。

4.3. validate() API

4.3.validate() API

The validate() method checks the validity of the whole bean which means that it verifies all the constraints applied to properties of an object that is passed as a parameter.

validate()方法检查整个Bean的有效性，这意味着它验证了应用于作为参数传递的对象的属性的所有约束。

Let’s create a JUnit test where we define a User object and use the validate() method to test its properties:

让我们创建一个JUnit测试，我们定义一个User对象，并使用validate()方法来测试其属性。

@Test
public void givenUser_whenValidate_thenValidationViolations() {
    User user
      = new User("ana@yahoo.com", "pass", "nameTooLong_______________", 15);

    Set<ConstraintViolation<User>> violations = validator.validate(user);
    assertTrue("no violations", violations.size() > 0);
}

4.4. validateProperty() API

4.4.validateProperty() API

The validateProperty() method can be used to validate a single property of a bean.

validateProperty()方法可用于验证Bean的单个属性。

Let’s create a JUnit test in which we will define a User object with an age property less than the required minimum value of 18 and verify that validating this property results in one violation:

让我们创建一个JUnit测试，其中我们将定义一个User对象，其age属性小于规定的最小值18，并验证验证该属性的结果是一个违规。

@Test
public void givenInvalidAge_whenValidateProperty_thenConstraintViolation() {
    User user = new User("ana@yahoo.com", "pass", "Ana", 12);

    Set<ConstraintViolation<User>> propertyViolations
      = validator.validateProperty(user, "age");
 
    assertEquals("size is not 1", 1, propertyViolations.size());
}

4.5. validateValue() API

4.5.validateValue() API

The validateValue() method can be used to check if some value would be a valid value for a property of a bean before setting it on the bean.

validateValue()方法可用于检查某个值是否是Bean的某个属性的有效值，然后将其设置在Bean上。

Let’s create a JUnit test with a User object, then verify that the value 20 is a valid value for the age property:

让我们用一个User对象创建一个JUnit测试，然后验证20值是age属性的有效值。

@Test
public void givenValidAge_whenValidateValue_thenNoConstraintViolation() {
    User user = new User("ana@yahoo.com", "pass", "Ana", 18);
    
    Set<ConstraintViolation<User>> valueViolations
      = validator.validateValue(User.class, "age", 20);
 
    assertEquals("size is not 0", 0, valueViolations.size());
}

4.6. Closing the ValidatorFactory

4.6.关闭ValidatorFactory

After using the ValidatorFactory, we must remember to close it at the end:

在使用ValidatorFactory之后，我们必须记得在最后关闭它。

if (validatorFactory != null) {
    validatorFactory.close();
}

5. Non-JSR Constraints

5.非JSR制约因素

The Apache BVal library also provides a series of constraints that are not a part of the JSR specification and provide additional and more powerful validation capabilities.

Apache BVal库还提供了一系列不属于JSR规范的约束条件，并提供了额外和更强大的验证能力。

The bval-jsr package contains two additional constraints: @Email for validating a valid email address, and @NotEmpty for ensuring that a value is not empty.

bval-jsr包包含两个额外的约束。@Email用于验证有效的电子邮件地址，以及@NotEmpty用于确保一个值不是空的。

The rest of the custom BVal constraints are provided in the optional package bval-extras.

其余的自定义BVal约束在可选包bval-extras中提供。

This package contains constraints for verifying various number formats such as the @IBAN annotation that ensures a number is a valid International Bank Account Number, the @Isbn annotation that verifies a valid Standard Book Number, and the @EAN13 annotation for verifying an International Article Number.

该软件包包含用于验证各种号码格式的约束条件，如用于确保号码是有效的国际银行账号的@IBAN注释，用于验证有效的标准图书编号的@Isbn注释，以及用于验证国际物品编号的@EAN13注释。

The library also provides annotations for ensuring the validity of various types of credit card numbers: @AmericanExpress, @Diners, @Discover, @Mastercard, and @Visa.

该库还提供注释，以确保各种类型的信用卡号码的有效性。@AmericanExpress, @Diners, @Discover, @Mastercard, 和@Visa。

You can determine if a value contains a valid domain or Internet Address by using the @Domain and @InetAddress annotations.

你可以通过使用@Domain和@InetAddress注解来确定一个值是否包含有效的域或Internet地址。

And finally, the package contains the @Directory and @NotDirectory annotations for verifying whether a File object is a directory or not.

最后，该包包含@Directory和@NotDirectory注解，用于验证文件对象是否是目录。

Let’s define additional properties on our User class and apply some of the non-JSR annotations to them:

让我们在我们的User类上定义额外的属性，并对它们应用一些非JSR注释。

public class User {
    
    @NotNull
    @Email
    private String email;
    
    @NotEmpty
    private String password;

    @Size(min=1, max=20)
    private String name;

    @Min(18)
    private int age;
    
    @Visa
    private String cardNumber = "";
    
    @IBAN
    private String iban = "";
    
    @InetAddress
    private String website = "";

    @Directory
    private File mainDirectory = new File(".");

    // standard constructor, getters, setters
}

The constraints can be tested in a similar manner to the JSR constraints:

这些约束可以用类似于JSR约束的方式来测试。

@Test
public void whenValidateNonJSR_thenCorrect() {
    User user = new User("ana@yahoo.com", "pass", "Ana", 20);
    user.setCardNumber("1234");
    user.setIban("1234");
    user.setWebsite("10.0.2.50");
    user.setMainDirectory(new File("."));
    
    Set<ConstraintViolation<User>> violations 
      = validator.validateProperty(user,"iban");
 
    assertEquals("size is not 1", 1, violations.size());
 
    violations = validator.validateProperty(user,"website");
 
    assertEquals("size is not 0", 0, violations.size());

    violations = validator.validateProperty(user, "mainDirectory");
 
    assertEquals("size is not 0", 0, violations.size());
}

While these additional annotations are convenient for potential validation needs, the one disadvantage of using annotations which are not part of the JSR specification is that you cannot easily switch to a different JSR implementation should that become necessary later on.

虽然这些额外的注解对于潜在的验证需求很方便，但使用不属于JSR规范的注解的一个缺点是，如果以后有必要，你不能轻易地切换到不同的JSR实现。

6. Custom Constraints

6.自定义限制条件

In order to define our own constraints, we first need to create an annotation following the standard syntax.

为了定义我们自己的约束，我们首先需要按照标准语法创建一个注释。

Let’s create a Password annotation that will define the conditions that a user’s password must satisfy:

让我们创建一个Password注解，它将定义一个用户的密码必须满足的条件。

@Constraint(validatedBy = { PasswordValidator.class })
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RetentionPolicy.RUNTIME)
public @interface Password {
    String message() default "Invalid password";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};

    int length() default 6;

    int nonAlpha() default 1;
}

The actual validation of the password value is done in a class that implements the ConstraintValidator interface — in our case, the PasswordValidator class. This class overrides the isValid() method and verifies if the length of the password is less than the length attribute, and if it contains fewer than the specified number of non-alphanumeric characters in the nonAlpha attribute:

对password值的实际验证是在一个实现ConstraintValidator接口的类中完成的 – 在我们的例子中，是PasswordValidator类。这个类重写了isValid()方法，并验证password的长度是否小于length属性，以及nonAlpha属性中是否包含少于指定数量的非字母数字字符。

public class PasswordValidator 
  implements ConstraintValidator<Password, String> {

    private int length;
    private int nonAlpha;

    @Override
    public void initialize(Password password) {
        this.length = password.length();
        this.nonAlpha = password.nonAlpha();
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext ctx) {
        if (value.length() < length) {
            return false;
        }
        int nonAlphaNr = 0;
        for (int i = 0; i < value.length(); i++) {
            if (!Character.isLetterOrDigit(value.charAt(i))) {
                nonAlphaNr++;
            }
        }
        if (nonAlphaNr < nonAlpha) {
            return false;
        }
        return true;
    }
}

Let’s apply our custom constraint to the password property of User class:

让我们对User类的password属性应用我们的自定义约束。

@Password(length = 8)
private String password;

We can create a JUnit test to verify that an invalid password value results in a constraint violation:

我们可以创建一个JUnit测试来验证无效的password值会导致违反约束条件。

@Test
public void givenValidPassword_whenValidatePassword_thenNoConstraintViolation() {
    User user = new User("ana@yahoo.com", "password", "Ana", 20);
    Set<ConstraintViolation<User>> violations 
      = validator.validateProperty(user, "password");
 
    assertEquals(
      "message incorrect",
      "Invalid password", 
      violations.iterator().next().getMessage());
}

Now let’s create a JUnit test in which we verify a valid password value:

现在让我们创建一个JUnit测试，在其中我们验证一个有效的password值。

@Test
public void givenValidPassword_whenValidatePassword_thenNoConstraintViolation() {
    User user = new User("ana@yahoo.com", "password#", "Ana", 20);
		
    Set<ConstraintViolation<User>> violations 
      = validator.validateProperty(user, "password");
    assertEquals("size is not 0", 0, violations.size());
}

7. Conclusion

7.结论

In this article, we have exemplified the use of the Apache BVal bean validation implementation.

在这篇文章中，我们举例说明了Apache BValBean验证实现的使用。

The complete source code for this article can be found over on GitHub.

本文的完整源代码可以在GitHub上找到over。