Revise RepeatableContainers API to better guide developers

[sbrannen]

Overview

Historically, the Spring Framework first had support for repeatable annotations based on convention and later added explicit support for Java 8's @Repeatable facility. Consequently, the support for both types of repeatable annotations has grown a bit intertwined over the years. However, modern Java applications typically make use of @Repeatable, and convention-based repeatable annotations have become more of a niche.

The RepeatableContainers API supports both types of repeatable annotations with @Repeatable support being the default. However, RepeatableContainers.of() makes it very easy to enable support for convention-based repeatable annotations while accidentally disabling support for @Repeatable, which can lead to subtle bugs – for example, if convention-based annotations are combined with @Repeatable annotations. In addition, it is not readily clear how one can combine @Repeatable support with convention-based repeatable annotations.

In light of the above, we have decided to revise the RepeatableContainers API to better guide developers to use @Repeatable support for almost all use cases while still supporting convention-based repeatable annotations for special use cases.

To achieve this, we will effectively rename RepeatableContainers.of() to RepeatableContainers.explicitRepeatable(), deprecating the former.

In addition, since the arguments supplied to RepeatableContainers.and() are in the reverse order of those supplied to all other repeatable annotation related methods (in RepeatableContainers, AnnotationUtils, and AnnotatedElementUtils), we will effectively rename add() to plus() and deprecate the former, and plus() will accept arguments in the same order as the rest of our repeated annotation APIs.

For example, instead of the following confusing mixture of repeatable/container and container/repeatable:

RepeatableContainers.of(A.class, A.Container.class).and(B.Container.class, B.class)

One will now be able to use:

RepeatableContainers.explicitRepeatable(A.class, A.Container.class).plus(B.class, B.Container.class)

We will also improve the documentation to point out that the following is the recommended approach to support convention-based repeatable annotations while retaining support for @Repeatable.

RepeatableContainers.standardRepeatables()
    .plus(MyRepeatable1.class, MyContainer1.class)
    .plus(MyRepeatable2.class, MyContainer2.class)

Related Issues

• AnnotatedElementUtils does not find merged repeatable annotations on other repeatable annotations #20279