What does this nested annotation do / allow?

Question

I was looking at the @org.hibernate.validator.constaints.NotEmpty annotation:

@Documented
@Constraint(validatedBy = { })
@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();
    }
}

I'm confused by the last part:

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

I'm not sure how that works, nor how to use it. From my understanding, anything under Java 8 does not allow repeated annotations on the same element.

Can anybody clarify?

Answer 1

Reason why NotEmpty.List exists, is to go around the fact that same annotation cannot be repeated for same element. With the help of NotEmpty.List multiple NotEmpty annotations are effectively applied to one element. Annotation processing checks through the list of NotEmpty annotations that are the value of NotEmpty.List.

In the case of NotEmpty one reason for using List of validators could be use of groups and assigning different messages per group.

For the sake of example, let's take entity which can represent either company or person. In both cases name should not be null, but messages differ:

@NotEmpty.List({
    @NotEmpty( message = "Person name should not be empty",   
               groups=PersonValidations.class),
    @NotEmpty( message = "Company name should not be empty",    
               groups=CompanyValidations.class),
})
private String name;