Intro to Apache BVal

1. Introduction

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

2. Maven Dependencies

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

<dependency>
    <groupId>org.apache.bval</groupId>
    <artifactId>bval-jsr</artifactId>
    <version>3.0.1</version>
</dependency>
<dependency>
    <groupId>jakarta.validation</groupId>
    <artifactId>jakarta.validation-api</artifactId>
    <version>3.1.0</version>
</dependency>

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

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

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

3. Applying Constraints

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

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

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

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

4.1. Obtaining a ValidatorFactory

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

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

4.2. Obtaining a Validator

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

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().

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

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.

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

@Test
public void givenUser_whenValidate_thenValidationViolations() {
    User user
      = new User("[email protected]", "pass", "nameTooLong_______________", 15);

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

4.4. validateProperty() API

The validateProperty() method can be used to validate a single property of a 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:

@Test
public void givenInvalidAge_whenValidateProperty_thenConstraintViolation() {
    User user = new User("[email protected]", "pass", "Ana", 12);

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

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.

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

@Test
public void givenValidAge_whenValidateValue_thenNoConstraintViolation() {
    User user = new User("[email protected]", "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

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

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

5. Non-JSR Constraints

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.

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.

The rest of the custom BVal constraints are provided in the optional package 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.

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

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

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

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

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:

@Test
public void whenValidateNonJSR_thenCorrect() {
    User user = new User("[email protected]", "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.

6. Custom Constraints

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:

@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:

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:

@Password(length = 8)
private String password;

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

@Test
public void givenValidPassword_whenValidatePassword_thenNoConstraintViolation() {
    User user = new User("[email protected]", "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:

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

7. Conclusion

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