• Published:

Spring validation often presents three annotations that seem to overlap: @NotNull, @NotEmpty, and @NotBlank. They all reject null, but they do not check the same thing. The difference becomes clear when a value is an empty collection, an empty string, or a string made only of spaces.

@NotNull

@NotNull is the simplest constraint. It can be placed on any type, and it only guarantees that the annotated element is not null. For a collection, map, or array, it does not require the object to contain elements; an empty collection is still valid under @NotNull.

/**
 * The annotated element must not be {@code null}.
 * Accepts any type.
 *
 * @author Emmanuel Bernard
 */
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
@Documented
@Constraint(validatedBy = { })
public @interface NotNull {

    String message() default "{javax.validation.constraints.NotNull.message}";

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

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

    /**
     * Defines several {@link NotNull} annotations on the same element.
     *
     * @see javax.validation.constraints.NotNull
     */
    @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
    @Retention(RUNTIME)
    @Documented
    @interface List {

        NotNull[] value();
    }
}

@NotEmpty

@NotEmpty goes further. It applies to String, Collection, Map, and Array values. The value must not be null, and its size must be greater than zero. In other words, an empty string, an empty collection, an empty map, or an empty array will fail validation.

The annotation itself is built from two constraints: @NotNull and @Size(min = 1). Because it also carries @ReportAsSingleViolation, the combined check is reported as one violation rather than two separate ones.

/**
 * Asserts that the annotated string, collection, map or array is not {@code null} or empty.
 *
 * @author Emmanuel Bernard
 * @author Hardy Ferentschik
 */
@Documented
@Constraint(validatedBy = { })
@SupportedValidationTarget(ValidationTarget.ANNOTATED_ELEMENT)
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
@ReportAsSingleViolation
@NotNull
@Size(min = 1)
public @interface NotEmpty {
    String message() default "{org.hibernate.validator.constraints.NotEmpty.message}";

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

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

    /**
     * Defines several {@code @NotEmpty} annotations on the same element.
     */
    @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
    @Retention(RUNTIME)
    @Documented
    public @interface List {
        NotEmpty[] value();
    }
}

@NotBlank

@NotBlank is designed for String values. It checks whether the string is null or empty after removing leading and trailing whitespace. A string containing only spaces, tabs, or other whitespace therefore fails. This is the key difference from @NotEmpty: @NotBlank ignores surrounding whitespace before deciding whether the value is empty, while @NotEmpty does not.

Its source declaration includes @NotNull, but it does not include a @Size constraint. The meaningful work is the trimming and blank check on the string content.

/**
 * Validate that the annotated string is not {@code null} or empty.
 * The difference to {@code NotEmpty} is that trailing whitespaces are getting ignored.
 *
 * @author Hardy Ferentschik
 */
@Documented
@Constraint(validatedBy = { })
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
@ReportAsSingleViolation
@NotNull
public @interface NotBlank {
    String message() default "{org.hibernate.validator.constraints.NotBlank.message}";

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

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

    /**
     * Defines several {@code @NotBlank} annotations on the same element.
     */
    @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
    @Retention(RUNTIME)
    @Documented
    public @interface List {
        NotBlank[] value();
    }
}

The practical choice follows from the data type. Use @NotNull when the object itself must be present and content or size is irrelevant. Use @NotEmpty when a string, collection, map, or array must contain at least one element. Use @NotBlank when a string must contain visible text rather than just whitespace.

Related Posts