Difference Between @NotNull, @NotEmpty, and @NotBlank Constraints in Bean Validation

1. Overview

Bean Validation is a standard validation specification that allows us to easily validate domain objects by using a set of constraints declared in the form of annotations.

While overall the use of bean validation implementations, such as Hibernate Validator, are fairly straightforward, it’s worth exploring some subtle, yet relevant, differences regarding how some of these constraints are implemented.

In this tutorial, we’ll explore the differences between the @NotNull, @NotEmpty, and @NotBlank constraints.

2. The Maven Dependencies

To quickly set up a working environment and test the behavior of the @NotNull, @NotEmpty, and @NotBlank constraints, first we need to add the required Maven dependencies.

In this case, we’ll use Hibernate Validator, the bean validation reference implementation, for validating our domain objects.

Here’s the relevant section of our pom.xml file:

<dependencies> 
   <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-validation</artifactId>
   </dependency>
</dependencies>

This dependency will import the related Hibernate Validator dependency transitively. If not using Spring-Boot, we can just import Hibernate Validator library:

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

We’ll use JUnit and AssertJ in our unit tests, so make sure to check the latest versions of hibernate-validator, GlassFish’s EL implementation, junit, and assertj-core on Maven Central.

3. The @NotNull Constraint

Moving forward, let’s implement a naive UserNotNull domain class and constrain its name field with the @NotNull annotation:

public class UserNotNull {
    
    @NotNull(message = "Name may not be null")
    private String name;
    
    // standard constructors / getters / toString   
}

Now we need to examine how @NotNull actually works under the hood. 

To do so, let’s create a simple unit test for the class, and validate a few instances of it:

@BeforeClass
public static void setupValidatorInstance() {
    validator = Validation.buildDefaultValidatorFactory().getValidator();
}

@Test
public void whenNotNullName_thenNoConstraintViolations() {
    UserNotNull user = new UserNotNull("John");
    Set<ConstraintViolation<UserNotNull>> violations = validator.validate(user);
 
    assertThat(violations.size()).isEqualTo(0);
}
    
@Test
public void whenNullName_thenOneConstraintViolation() {
    UserNotNull user = new UserNotNull(null);
    Set<ConstraintViolation<UserNotNull>> violations = validator.validate(user);
 
    assertThat(violations.size()).isEqualTo(1);
}
    
@Test
public void whenEmptyName_thenNoConstraintViolations() {
    UserNotNull user = new UserNotNull("");
    Set<ConstraintViolation<UserNotNull>> violations = validator.validate(user);
 
    assertThat(violations.size()).isEqualTo(0);
}

As expected, the @NotNull constraint won’t allow null values for the constrained field(s). However, the field(s) can be empty.

To better understand this, let’s look at the NotNullValidator class‘ isValid() method, which the @NotNull constraint uses. The method implementation is really trivial:

public boolean isValid(Object object) {
    return object != null;  
}

As shown above, a field (e.g. CharSequence, Collection, Map, or Array) constrained with @NotNull must be not null. An empty value, however, is perfectly legal.

4. The @NotEmpty Constraint

Now let’s implement a sample UserNotEmpty class and use the @NotEmpty constraint:

public class UserNotEmpty {
    
    @NotEmpty(message = "Name may not be empty")
    private String name;
    
    // standard constructors / getters / toString
}

With the class in place, let’s test it by assigning different values to the name field:

@Test
public void whenNotEmptyName_thenNoConstraintViolations() {
    UserNotEmpty user = new UserNotEmpty("John");
    Set<ConstraintViolation<UserNotEmpty>> violations = validator.validate(user);
 
    assertThat(violations.size()).isEqualTo(0);
}
    
@Test
public void whenEmptyName_thenOneConstraintViolation() {
    UserNotEmpty user = new UserNotEmpty("");
    Set<ConstraintViolation<UserNotEmpty>> violations = validator.validate(user);
 
    assertThat(violations.size()).isEqualTo(1);
}
    
@Test
public void whenNullName_thenOneConstraintViolation() {
    UserNotEmpty user = new UserNotEmpty(null);
    Set<ConstraintViolation<UserNotEmpty>> violations = validator.validate(user);
 
    assertThat(violations.size()).isEqualTo(1);
}

The @NotEmpty annotation makes use of the @NotNull class’ isValid() implementation, and also checks that the size/length of the supplied object (of course, this varies according to the type of object being validated) is greater than zero.

In a nutshell, this means that a field (e.g. CharSequence, Collection, Map, or Array) constrained with @NotEmpty must be not null, and its size/length must be greater than zero.

Additionally, we can be even more restrictive if we use the @NotEmpty annotation in conjunction with @Size.

In doing so, we’d also enforce that the object’s min and max size values are within the specified min/max range:

@NotEmpty(message = "Name may not be empty")
@Size(min = 2, max = 32, message = "Name must be between 2 and 32 characters long") 
private String name;

5. The @NotBlank Constraint

Similarly, we can constrain a class field with the @NotBlank annotation:

public class UserNotBlank {

    @NotBlank(message = "Name may not be blank")
    private String name;
    
    // standard constructors / getters / toString

}

Along the same lines, we can implement a unit test to understand how the @NotBlank constraint works:

@Test
public void whenNotBlankName_thenNoConstraintViolations() {
    UserNotBlank user = new UserNotBlank("John");
    Set<ConstraintViolation<UserNotBlank>> violations = validator.validate(user);
 
    assertThat(violations.size()).isEqualTo(0);
}
    
@Test
public void whenBlankName_thenOneConstraintViolation() {
    UserNotBlank user = new UserNotBlank(" ");
    Set<ConstraintViolation<UserNotBlank>> violations = validator.validate(user);
 
    assertThat(violations.size()).isEqualTo(1);
}
    
@Test
public void whenEmptyName_thenOneConstraintViolation() {
    UserNotBlank user = new UserNotBlank("");
    Set<ConstraintViolation<UserNotBlank>> violations = validator.validate(user);
 
    assertThat(violations.size()).isEqualTo(1);
}
    
@Test
public void whenNullName_thenOneConstraintViolation() {
    UserNotBlank user = new UserNotBlank(null);
    Set<ConstraintViolation<UserNotBlank>> violations = validator.validate(user);
 
    assertThat(violations.size()).isEqualTo(1);
}

The @NotBlank annotation uses the NotBlankValidator class, which checks that a character sequence’s trimmed length is not empty:

public boolean isValid(
  CharSequence charSequence, 
  ConstraintValidatorContext constraintValidatorContext)
    if (charSequence == null ) {
        return false; 
    } 
    return charSequence.toString().trim().length() > 0;
}

The method returns false for null values.

To put it simply, a String field constrained with @NotBlank must be not null, and the trimmed length must be greater than zero.

6. A Side-by-Side Comparison

So far, we’ve taken an in-depth look at how the @NotNull, @NotEmpty, and @NotBlank constraints operate individually on class fields.

Let’s perform a quick side-by-side comparison, so we can have a bird’s eye view of the constraints’ functionality and easily spot their differences:

• @NotNull: a constrained CharSequence, Collection, Map, or Array is valid as long as it’s not null, but it can be empty.
• @NotEmpty: a constrained CharSequence, Collection, Map, or Array is valid as long as it’s not null, and its size/length is greater than zero.
• @NotBlank: a constrained String is valid as long as it’s not null, and the trimmed length is greater than zero.

7. Conclusion

In this article, we looked at the @NotNull, @NotEmpty, and @NotBlank constraints implemented in Bean Validation, and highlighted their similarities and differences.