Java Bean Validation Basics

1. Overview

In this quick tutorial, we’ll cover the basics of validating a Java bean with the standard JSR-380 framework and its specification of Jakarta Bean Validation 3.0, which builds upon the features of the Bean Validation API introduced in Java EE 7.

Validating user input is a super common requirement in most applications, and the Java Bean Validation framework has become the de facto standard for handling this kind of logic.

2. JSR 380

JSR 380 is a specification of the Java API for bean validation, part of Jakarta EE and JavaSE. It ensures that the properties of a bean meet specific criteria, using annotations such as @NotNull, @Min, and @Max.

Also, it supports the new features introduced in Java 9 and above, like stream and Optional improvements, modules, private interface methods, and more.

For full information on the specifications, we can read through the JSR 380.

3. Dependencies

In the latest version of spring-boot-starter-validation, besides other dependencies, a transitive dependency of hibernate-validator will be available.

If we want to add just the dependency for validation, we can simply add the hibernate-validator in our pom.xml:

<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>9.1.0.Final</version>
</dependency>

A quick note: hibernate-validator is entirely separate from the persistence aspects of Hibernate. So by adding it as a dependency, we’re not adding these persistence aspects into the project.

4. Using Validation Annotations

Here, we’ll take a User bean and work on adding some simple validation to it:

public class User {

    @NotNull(message = "Name cannot be null")
    private String name;

    @AssertTrue(message = "Working must be true")
    private boolean working;

    @Size(min = 10, max = 200, message 
      = "About Me must be between 10 and 200 characters")
    private String aboutMe;

    @Min(value = 18, message = "Age should not be less than 18")
    @Max(value = 150, message = "Age should not be greater than 150")
    private int age;

    @Email(message = "Email should be valid")
    private String email;

    // standard setters and getters 
}

All of the annotations we’ve used in the example are standard JSR annotations, which are part of the jakarta.validation.constraints package:

• @NotNull validates that the annotated property value isn’t null.
• @AssertTrue validates that the annotated property value is true.
• @Size validates that the annotated property value has a size between the attributes min and max. We can apply it to String, Collection, Map, and array properties.
• @Min validates that the annotated property has a value no smaller than the value attribute.
• @Max validates that the annotated property has a value no larger than the value attribute.
• @Email validates that the annotated property is a valid email address.

Some annotations accept additional attributes, but the message attribute is common to all of them. This is the message that will usually be rendered when the value of the respective property fails validation.

Here are some additional annotations we can find in the JSR:

• @NotEmpty validates that the property isn’t null or empty. We can apply it to String, Collection, Map or Array values.
• @NotBlank can be applied only to text values, and validates that the property isn’t null or whitespace.
• @Positive and @PositiveOrZero apply to numeric values, and validate that they’re strictly positive, or positive including 0.
• @Negative and @NegativeOrZero apply to numeric values, and validate that they’re strictly negative, or negative including 0.
• @Past and @PastOrPresent validate that a date value is in the past, or the past including the present. We can apply it to date types, including those added in Java 8.
• @Future and @FutureOrPresent validate that a date value is in the future, or in the future including the present.

We can also apply the validation annotations to elements of a collection:

List<@NotBlank String> preferences;

In this case, any value added to the preferences list will be validated.

Also, the specification supports the new Optional type in Java 8:

private LocalDate dateOfBirth;

public Optional<@Past LocalDate> getDateOfBirth() {
    return Optional.of(dateOfBirth);
}

Here, the validation framework will automatically unwrap the LocalDate value and validate it.

5. Programmatic Validation

Some frameworks, such as Spring, have simple ways to trigger the validation process by just using annotations. This is mainly so that we don’t have to interact with the programmatic validation API.

Now let’s go the manual route and set things up programmatically:

ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
Validator validator = factory.getValidator();

To validate a bean, we’ll first need a Validator object, which is built using a ValidatorFactory.

5.1. Defining the Bean

Then we’ll set up this invalid user with a null name value:

User user = new User();
user.setWorking(true);
user.setAboutMe("Its all about me!");
user.setAge(50);

5.2. Validate the Bean

Now that we have a Validator, we can validate our bean by passing it to the validate method.

Any violations of the constraints defined in the User object will be returned as a Set:

Set<ConstraintViolation<User>> violations = validator.validate(user);

By iterating over the violations, we can get all the violation messages using the getMessage method:

for (ConstraintViolation<User> violation : violations) {
    log.error(violation.getMessage()); 
}

In our example (ifNameIsNull_nameValidationFails), the set would contain a single ConstraintViolation with the message “Name cannot be null”.

6. Testing Validation Annotations

Now that we’ve learned how to use the programmatic validation API, let’s look at how we can use it to write unit tests for our validation annotations.

First, we’ll set up a Validator instance in our test class:

private Validator validator;

@BeforeEach
void setUp() {
    validator = Validation.buildDefaultValidatorFactory().getValidator();
}

We’ll use this Validator instance to validate our User class:

User user = new User();
user.setName("test-name");
user.setWorking(true);
user.setAboutMe("test-about-me");
user.setAge(24);
user.setEmail("[email protected]");

Set<ConstraintViolation<User>> violations = validator.validate(user);

assertTrue(violations.isEmpty());

The validate() method returns an empty set of ConstraintViolation if the User object is valid according to our validation constraints.

Next, let’s verify that an invalid User object fails validation:

User user = new User();
user.setName(null);
user.setWorking(false);
user.setAboutMe("test");
user.setAge(10);
user.setEmail("test-invalid-email");

Set<ConstraintViolation<User>> violations = validator.validate(user);

assertFalse(violations.isEmpty());
assertThat(violations).hasSize(5);
assertThat(violations).extracting(ConstraintViolation::getMessage)
  .containsExactlyInAnyOrder(
    "Name cannot be null",
    "Working must be true", 
    "About Me must be between 10 and 200 characters",
    "Age should not be less than 18", 
    "Email should be valid");

By testing both valid and invalid instances of our User class, we verify that our validation annotations work as expected.

7. Conclusion

In this article, we focused on a simple pass through the standard Java Validation API. We discussed the basics of bean validation using jakarta.validation annotations and APIs.