Validating Container Elements with Jakarta Bean Validation 3.0

1. Overview

The previous 2.0 Version of the Java Bean Validation specification has already added several new features, among which is the possibility to validate elements of containers.

This new functionality took advantage of type annotations introduced in Java 8. Therefore it required Java version 8 or higher to work.

However, in this article, Jakarta Bean Validation 3.0 is used, which requires Java 17 as we are using the latest Spring Boot 3 to get the reference implementation Hibernate Validator 8.x.

Validation annotations can be added to containers such as collections, Optional objects, and other built-in as well as custom containers.

For an introduction to Java Bean Validation and how to setup the Maven dependencies we need, check out our previous article here.

In the following sections, we’ll focus on validating elements of each type of container.

2. Collection Elements

We can add validation annotations to elements of collections of type java.util.Iterable, java.util.List and java.util.Map.

Let’s see an example of validating the elements of a List:

public class Customer {    
     List<@NotBlank(message="Address must not be blank") String> addresses;
    
    // standard getters, setters 
}

In the example above, we’ve defined an addresses property for a Customer class, which contains elements that cannot be empty Strings.

Note that the @NotBlank validation applies to the String elements, and not the entire collection. If the collection is empty, then no validation is applied.

Let’s verify that if we attempt to add an empty String to the addresses list, the validation framework will return a ConstraintViolation:

@Test
public void whenEmptyAddress_thenValidationFails() {
    Customer customer = new Customer();
    customer.setName("John");

    customer.setAddresses(Collections.singletonList(" "));
    Set<ConstraintViolation<Customer>> violations = 
      validator.validate(customer);
    
    assertEquals(1, violations.size());
    assertEquals("Address must not be blank", 
      violations.iterator().next().getMessage());
}

Next, let’s see how we can validate the elements of a collection of type Map:

public class CustomerMap {
    
    private Map<@Email String, @NotNull Customer> customers;
    
    // standard getters, setters
}

Notice that we can add validation annotations for both the key and the value of a Map element.

Let’s verify that adding an entry with an invalid email will result in a validation error:

@Test
public void whenInvalidEmail_thenValidationFails() {
    CustomerMap map = new CustomerMap();
    map.setCustomers(Collections.singletonMap("john", new Customer()));
    Set<ConstraintViolation<CustomerMap>> violations
      = validator.validate(map);
 
    assertEquals(1, violations.size());
    assertEquals(
      "Must be a valid email", 
      violations.iterator().next().getMessage());
}

3. Optional Values

Validation constraints can also be applied to an Optional value:

private Integer age;

public Optional<@Min(18) Integer> getAge() {
    return Optional.ofNullable(age);
}

Let’s create a Customer with an age that is too low – and verify that this results in a validation error:

@Test
public void whenAgeTooLow_thenValidationFails() {
    Customer customer = new Customer();
    customer.setName("John");
    customer.setAge(15);
    Set<ConstraintViolation<Customer>> violations
      = validator.validate(customer);
 
    assertEquals(1, violations.size());
}

On the other hand, if the age is null, then the Optional value is not validated:

@Test
public void whenAgeNull_thenValidationSucceeds() {
    Customer customer = new Customer();
    customer.setName("John");
    Set<ConstraintViolation<Customer>> violations
      = validator.validate(customer);
 
    assertEquals(0, violations.size());
}

4. Non-Generic Container Elements

Besides adding annotations for type arguments, we can also apply validation to non-generic containers, as long as there is a value extractor for the type with the @UnwrapByDefault annotation.

Value extractors are the classes that extract the values from the containers for validation.

The reference implementation contains value extractors for OptionalInt, OptionalLong and OptionalDouble:

@Min(1)
private OptionalInt numberOfOrders;

In this case, the @Min annotation applies to the wrapped Integer value, and not the container.

5. Custom Container Elements

In addition to the built-in value extractors, we can also define our own and register them with a container type.

In this way, we can add validation annotations to elements of our custom containers.

Let’s add a new Profile class that contains a companyName property:

public class Profile {
    private String companyName;
    
    // standard getters, setters 
}

Next, we want to add a Profile property in the Customer class with a @NotBlank annotation – which verifies the companyName is not an empty String:

@NotBlank
private Profile profile;

For this to work, we need a value extractor that determines the validation to be applied to the companyName property and not the profile object directly.

Let’s add a ProfileValueExtractor class that implements the ValueExtractor interface and overrides the extractValue() method:

@UnwrapByDefault
public class ProfileValueExtractor 
  implements ValueExtractor<@ExtractedValue(type = String.class) Profile> {

    @Override
    public void extractValues(Profile originalValue, 
      ValueExtractor.ValueReceiver receiver) {
        receiver.value(null, originalValue.getCompanyName());
    }
}

This class also need to specify the type of the value extracted using the @ExtractedValue annotation.

Also, we’ve added the @UnwrapByDefault annotation that specifies the validation should be applied to the unwrapped value and not the container.

Finally, we need to register the class by adding a file called javax.validation.valueextraction.ValueExtractor to the META-INF/services directory, which contains the full name of our ProfileValueExtractor class:

org.baeldung.javaxval.container.validation.valueextractors.ProfileValueExtractor

Now, when we validate a Customer object with a profile property with an empty companyName, we will see a validation error:

@Test
public void whenProfileCompanyNameBlank_thenValidationFails() {
    Customer customer = new Customer();
    customer.setName("John");
    Profile profile = new Profile();
    profile.setCompanyName(" ");
    customer.setProfile(profile);
    Set<ConstraintViolation<Customer>> violations
     = validator.validate(customer);
 
    assertEquals(1, violations.size());
}

Note that if you are using hibernate-validator-annotation-processor, adding a validation annotation to a custom container class, when it’s marked as @UnwrapByDefault, will result in a compilation error in version 6.0.2.

This is a known issue and will likely be resolved in a future version.

6. Conclusion

In this article, we’ve shown how we can validate several types of container elements using Jakarta Bean Validation 3.0.