Revise RepeatableContainers API to better guide developers

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 to combine
@⁠Repeatable support with convention-based repeatable annotations.

In light of the above, this commit revises 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.

Specifically:

- RepeatableContainers.of() is now deprecated in favor of the new
  RepeatableContainers.explicitRepeatable() method.

- RepeatableContainers.and() is now deprecated in favor of the new
  RepeatableContainers.plus() method which declares the repeatable and
  container arguments in the same order as the rest of Spring
  Framework's 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)

Developers are now be able to use:

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

This commit also overhauls the Javadoc for RepeatableContainers and
explicitly points 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)

See gh-20279
Closes gh-34637

Author: sbrannen

spring-core/src/main/java/org/springframework/core/annotation/AnnotatedElementUtils.java

@@ -443,13 +443,17 @@ public static <A extends Annotation> Set<A> getMergedRepeatableAnnotations(
 	 * support such a use case, favor {@link #getMergedRepeatableAnnotations(AnnotatedElement, Class)}
 	 * over this method or alternatively use the {@link MergedAnnotations} API
 	 * directly in conjunction with {@link RepeatableContainers} that are
-	 * {@linkplain RepeatableContainers#and(Class, Class) composed} to support
-	 * multiple repeatable annotation types.
+	 * {@linkplain RepeatableContainers#plus(Class, Class) composed} to support
+	 * multiple repeatable annotation types &mdash; for example:
+	 * <pre class="code">
+	 * RepeatableContainers.standardRepeatables()
+	 *     .plus(MyRepeatable1.class, MyContainer1.class)
+	 *     .plus(MyRepeatable2.class, MyContainer2.class);</pre>
 	 * @param element the annotated element (never {@code null})
-	 * @param annotationType the annotation type to find (never {@code null})
-	 * @param containerType the type of the container that holds the annotations;
-	 * may be {@code null} if the container type should be looked up via
-	 * {@link java.lang.annotation.Repeatable}
+	 * @param annotationType the repeatable annotation type to find (never {@code null})
+	 * @param containerType the type of the container that holds the repeatable
+	 * annotations; may be {@code null} if the container type should be looked up
+	 * via {@link java.lang.annotation.Repeatable @Repeatable}
 	 * @return the set of all merged repeatable {@code Annotations} found,
 	 * or an empty set if none were found
 	 * @throws IllegalArgumentException if the {@code element} or {@code annotationType}
@@ -740,13 +744,17 @@ public static <A extends Annotation> Set<A> findMergedRepeatableAnnotations(Anno
 	 * support such a use case, favor {@link #findMergedRepeatableAnnotations(AnnotatedElement, Class)}
 	 * over this method or alternatively use the {@link MergedAnnotations} API
 	 * directly in conjunction with {@link RepeatableContainers} that are
-	 * {@linkplain RepeatableContainers#and(Class, Class) composed} to support
-	 * multiple repeatable annotation types.
+	 * {@linkplain RepeatableContainers#plus(Class, Class) composed} to support
+	 * multiple repeatable annotation types &mdash; for example:
+	 * <pre class="code">
+	 * RepeatableContainers.standardRepeatables()
+	 *     .plus(MyRepeatable1.class, MyContainer1.class)
+	 *     .plus(MyRepeatable2.class, MyContainer2.class);</pre>
 	 * @param element the annotated element (never {@code null})
-	 * @param annotationType the annotation type to find (never {@code null})
-	 * @param containerType the type of the container that holds the annotations;
-	 * may be {@code null} if the container type should be looked up via
-	 * {@link java.lang.annotation.Repeatable}
+	 * @param annotationType the repeatable annotation type to find (never {@code null})
+	 * @param containerType the type of the container that holds the repeatable
+	 * annotations; may be {@code null} if the container type should be looked up
+	 * via {@link java.lang.annotation.Repeatable @Repeatable}
 	 * @return the set of all merged repeatable {@code Annotations} found,
 	 * or an empty set if none were found
 	 * @throws IllegalArgumentException if the {@code element} or {@code annotationType}
@@ -775,7 +783,7 @@ private static MergedAnnotations getRepeatableAnnotations(AnnotatedElement eleme
 
 		RepeatableContainers repeatableContainers;
 		if (containerType == null) {
-			// Invoke RepeatableContainers.of() in order to adhere to the contract of
+			// Invoke RepeatableContainers.explicitRepeatable() in order to adhere to the contract of
 			// getMergedRepeatableAnnotations() which states that an IllegalArgumentException
 			// will be thrown if the container cannot be resolved.
 			//
@@ -784,11 +792,11 @@ private static MergedAnnotations getRepeatableAnnotations(AnnotatedElement eleme
 			// annotation types).
 			//
 			// See https://github.com/spring-projects/spring-framework/issues/20279
-			RepeatableContainers.of(annotationType, null);
+			RepeatableContainers.explicitRepeatable(annotationType, null);
 			repeatableContainers = RepeatableContainers.standardRepeatables();
 		}
 		else {
-			repeatableContainers = RepeatableContainers.of(annotationType, containerType);
+			repeatableContainers = RepeatableContainers.explicitRepeatable(annotationType, containerType);
 		}
 		return MergedAnnotations.from(element, SearchStrategy.INHERITED_ANNOTATIONS, repeatableContainers);
 	}
@@ -802,7 +810,7 @@ private static MergedAnnotations findRepeatableAnnotations(AnnotatedElement elem
 
 		RepeatableContainers repeatableContainers;
 		if (containerType == null) {
-			// Invoke RepeatableContainers.of() in order to adhere to the contract of
+			// Invoke RepeatableContainers.explicitRepeatable() in order to adhere to the contract of
 			// findMergedRepeatableAnnotations() which states that an IllegalArgumentException
 			// will be thrown if the container cannot be resolved.
 			//
@@ -811,11 +819,11 @@ private static MergedAnnotations findRepeatableAnnotations(AnnotatedElement elem
 			// annotation types).
 			//
 			// See https://github.com/spring-projects/spring-framework/issues/20279
-			RepeatableContainers.of(annotationType, null);
+			RepeatableContainers.explicitRepeatable(annotationType, null);
 			repeatableContainers = RepeatableContainers.standardRepeatables();
 		}
 		else {
-			repeatableContainers = RepeatableContainers.of(annotationType, containerType);
+			repeatableContainers = RepeatableContainers.explicitRepeatable(annotationType, containerType);
 		}
 		return MergedAnnotations.from(element, SearchStrategy.TYPE_HIERARCHY, repeatableContainers);
 	}

spring-core/src/main/java/org/springframework/core/annotation/AnnotationUtils.java

@@ -370,7 +370,7 @@ public static <A extends Annotation> Set<A> getRepeatableAnnotations(AnnotatedEl
 			Class<A> annotationType, @Nullable Class<? extends Annotation> containerAnnotationType) {
 
 		RepeatableContainers repeatableContainers = (containerAnnotationType != null ?
-				RepeatableContainers.of(annotationType, containerAnnotationType) :
+				RepeatableContainers.explicitRepeatable(annotationType, containerAnnotationType) :
 				RepeatableContainers.standardRepeatables());
 
 		return MergedAnnotations.from(annotatedElement, SearchStrategy.SUPERCLASS, repeatableContainers)
@@ -451,7 +451,7 @@ public static <A extends Annotation> Set<A> getDeclaredRepeatableAnnotations(Ann
 			Class<A> annotationType, @Nullable Class<? extends Annotation> containerAnnotationType) {
 
 		RepeatableContainers repeatableContainers = containerAnnotationType != null ?
-				RepeatableContainers.of(annotationType, containerAnnotationType) :
+				RepeatableContainers.explicitRepeatable(annotationType, containerAnnotationType) :
 				RepeatableContainers.standardRepeatables();
 
 		return MergedAnnotations.from(annotatedElement, SearchStrategy.DIRECT, repeatableContainers)

spring-core/src/main/java/org/springframework/core/annotation/RepeatableContainers.java

@@ -30,15 +30,38 @@
 import org.springframework.util.ObjectUtils;
 
 /**
- * Strategy used to determine annotations that act as containers for other
- * annotations. The {@link #standardRepeatables()} method provides a default
- * strategy that respects Java's {@link Repeatable @Repeatable} support and
- * should be suitable for most situations.
+ * Strategy used to find repeatable annotations within container annotations.
  *
- * <p>The {@link #of} method can be used to register relationships for
- * annotations that do not wish to use {@link Repeatable @Repeatable}.
+ * <p>{@link #standardRepeatables() RepeatableContainers.standardRepeatables()}
+ * provides a default strategy that respects Java's {@link Repeatable @Repeatable}
+ * support and is suitable for most situations.
  *
- * <p>To completely disable repeatable support use {@link #none()}.
+ * <p>If you need to register repeatable annotation types that do not make use of
+ * {@code @Repeatable}, you should typically use {@code standardRepeatables()}
+ * combined with {@link #plus(Class, Class)}. Note that multiple invocations of
+ * {@code plus()} can be chained together to register multiple repeatable/container
+ * type pairs. For example:
+ *
+ * <pre class="code">
+ * RepeatableContainers repeatableContainers =
+ *     RepeatableContainers.standardRepeatables()
+ *         .plus(MyRepeatable1.class, MyContainer1.class)
+ *         .plus(MyRepeatable2.class, MyContainer2.class);</pre>
+ *
+ * <p>For special use cases where you are certain that you do not need Java's
+ * {@code @Repeatable} support, you can use {@link #explicitRepeatable(Class, Class)
+ * RepeatableContainers.explicitRepeatable()} to create an instance of
+ * {@code RepeatableContainers} that only supports explicit repeatable/container
+ * type pairs. As with {@code standardRepeatables()}, {@code plus()} can be used
+ * to register additional repeatable/container type pairs. For example:
+ *
+ * <pre class="code">
+ * RepeatableContainers repeatableContainers =
+ *     RepeatableContainers.explicitRepeatable(MyRepeatable1.class, MyContainer1.class)
+ *         .plus(MyRepeatable2.class, MyContainer2.class);</pre>
+ *
+ * <p>To completely disable repeatable annotation support use
+ * {@link #none() RepeatableContainers.none()}.
  *
  * @author Phillip Webb
  * @author Sam Brannen
@@ -55,22 +78,46 @@ private RepeatableContainers(@Nullable RepeatableContainers parent) {
 		this.parent = parent;
 	}
 
+	/**
+	 * Register a pair of repeatable and container annotation types.
+	 * <p>See the {@linkplain RepeatableContainers class-level javadoc} for examples.
+	 * @param repeatable the repeatable annotation type
+	 * @param container the container annotation type
+	 * @return a new {@code RepeatableContainers} instance that is chained to
+	 * the current instance
+	 * @since 7.0
+	 */
+	public final RepeatableContainers plus(Class<? extends Annotation> repeatable,
+			Class<? extends Annotation> container) {
+
+		return new ExplicitRepeatableContainer(this, repeatable, container);
+	}
 
 	/**
-	 * Add an additional explicit relationship between a container and
-	 * repeatable annotation.
-	 * <p>WARNING: the arguments supplied to this method are in the reverse order
-	 * of those supplied to {@link #of(Class, Class)}.
+	 * Register a pair of container and repeatable annotation types.
+	 * <p><strong>WARNING</strong>: The arguments supplied to this method are in
+	 * the reverse order of those supplied to {@link #plus(Class, Class)},
+	 * {@link #explicitRepeatable(Class, Class)}, and {@link #of(Class, Class)}.
 	 * @param container the container annotation type
 	 * @param repeatable the repeatable annotation type
-	 * @return a new {@link RepeatableContainers} instance
+	 * @return a new {@code RepeatableContainers} instance that is chained to
+	 * the current instance
+	 * @deprecated as of Spring Framework 7.0, in favor of {@link #plus(Class, Class)}
 	 */
+	@Deprecated(since = "7.0")
 	public RepeatableContainers and(Class<? extends Annotation> container,
 			Class<? extends Annotation> repeatable) {
 
-		return new ExplicitRepeatableContainer(this, repeatable, container);
+		return plus(repeatable, container);
 	}
 
+	/**
+	 * Find repeated annotations contained in the supplied {@code annotation}.
+	 * @param annotation the candidate container annotation
+	 * @return the repeated annotations found in the supplied container annotation
+	 * (potentially an empty array), or {@code null} if the supplied annotation is
+	 * not a supported container annotation
+	 */
 	Annotation @Nullable [] findRepeatedAnnotations(Annotation annotation) {
 		if (this.parent == null) {
 			return null;
@@ -98,41 +145,92 @@ public int hashCode() {
 
 
 	/**
-	 * Create a {@link RepeatableContainers} instance that searches using Java's
-	 * {@link Repeatable @Repeatable} annotation.
-	 * @return a {@link RepeatableContainers} instance
+	 * Create a {@link RepeatableContainers} instance that searches for repeated
+	 * annotations according to the semantics of Java's {@link Repeatable @Repeatable}
+	 * annotation.
+	 * <p>See the {@linkplain RepeatableContainers class-level javadoc} for examples.
+	 * @return a {@code RepeatableContainers} instance that supports {@code @Repeatable}
+	 * @see #plus(Class, Class)
 	 */
 	public static RepeatableContainers standardRepeatables() {
 		return StandardRepeatableContainers.INSTANCE;
 	}
 
 	/**
-	 * Create a {@link RepeatableContainers} instance that uses predefined
-	 * repeatable and container types.
-	 * <p>WARNING: the arguments supplied to this method are in the reverse order
-	 * of those supplied to {@link #and(Class, Class)}.
+	 * Create a {@link RepeatableContainers} instance that searches for repeated
+	 * annotations by taking into account the supplied repeatable and container
+	 * annotation types.
+	 * <p><strong>WARNING</strong>: The {@code RepeatableContainers} instance
+	 * returned by this factory method does <strong>not</strong> respect Java's
+	 * {@link Repeatable @Repeatable} support. Use {@link #standardRepeatables()}
+	 * for standard {@code @Repeatable} support, optionally combined with
+	 * {@link #plus(Class, Class)}.
+	 * <p>If the supplied container annotation type is not {@code null}, it must
+	 * declare a {@code value} attribute returning an array of repeatable
+	 * annotations. If the supplied container annotation type is {@code null}, the
+	 * container will be deduced by inspecting the {@code @Repeatable} annotation
+	 * on the {@code repeatable} annotation type.
+	 * <p>See the {@linkplain RepeatableContainers class-level javadoc} for examples.
 	 * @param repeatable the repeatable annotation type
-	 * @param container the container annotation type or {@code null}. If specified,
-	 * this annotation must declare a {@code value} attribute returning an array
-	 * of repeatable annotations. If not specified, the container will be
-	 * deduced by inspecting the {@code @Repeatable} annotation on
-	 * {@code repeatable}.
-	 * @return a {@link RepeatableContainers} instance
+	 * @param container the container annotation type or {@code null}
+	 * @return a {@code RepeatableContainers} instance that does not support
+	 * {@link Repeatable @Repeatable}
 	 * @throws IllegalArgumentException if the supplied container type is
 	 * {@code null} and the annotation type is not a repeatable annotation
 	 * @throws AnnotationConfigurationException if the supplied container type
 	 * is not a properly configured container for a repeatable annotation
+	 * @since 7.0
+	 * @see #standardRepeatables()
+	 * @see #plus(Class, Class)
 	 */
-	public static RepeatableContainers of(
+	public static RepeatableContainers explicitRepeatable(
 			Class<? extends Annotation> repeatable, @Nullable Class<? extends Annotation> container) {
 
 		return new ExplicitRepeatableContainer(null, repeatable, container);
 	}
 
+	/**
+	 * Create a {@link RepeatableContainers} instance that searches for repeated
+	 * annotations by taking into account the supplied repeatable and container
+	 * annotation types.
+	 * <p><strong>WARNING</strong>: The {@code RepeatableContainers} instance
+	 * returned by this factory method does <strong>not</strong> respect Java's
+	 * {@link Repeatable @Repeatable} support. Use {@link #standardRepeatables()}
+	 * for standard {@code @Repeatable} support, optionally combined with
+	 * {@link #plus(Class, Class)}.
+	 * <p><strong>WARNING</strong>: The arguments supplied to this method are in
+	 * the reverse order of those supplied to {@link #and(Class, Class)}.
+	 * <p>If the supplied container annotation type is not {@code null}, it must
+	 * declare a {@code value} attribute returning an array of repeatable
+	 * annotations. If the supplied container annotation type is {@code null}, the
+	 * container will be deduced by inspecting the {@code @Repeatable} annotation
+	 * on the {@code repeatable} annotation type.
+	 * @param repeatable the repeatable annotation type
+	 * @param container the container annotation type or {@code null}
+	 * @return a {@code RepeatableContainers} instance that does not support
+	 * {@link Repeatable @Repeatable}
+	 * @throws IllegalArgumentException if the supplied container type is
+	 * {@code null} and the annotation type is not a repeatable annotation
+	 * @throws AnnotationConfigurationException if the supplied container type
+	 * is not a properly configured container for a repeatable annotation
+	 * @deprecated as of Spring Framework 7.0, in favor of {@link #explicitRepeatable(Class, Class)}
+	 */
+	@Deprecated(since = "7.0")
+	public static RepeatableContainers of(
+			Class<? extends Annotation> repeatable, @Nullable Class<? extends Annotation> container) {
+
+		return explicitRepeatable(repeatable, container);
+	}
+
 	/**
 	 * Create a {@link RepeatableContainers} instance that does not support any
 	 * repeatable annotations.
-	 * @return a {@link RepeatableContainers} instance
+	 * <p>Note, however, that {@link #plus(Class, Class)} may still be invoked on
+	 * the {@code RepeatableContainers} instance returned from this method.
+	 * <p>See the {@linkplain RepeatableContainers class-level javadoc} for examples
+	 * and further details.
+	 * @return a {@code RepeatableContainers} instance that does not support
+	 * repeatable annotations
 	 */
 	public static RepeatableContainers none() {
 		return NoRepeatableContainers.INSTANCE;

spring-core/src/test/java/org/springframework/core/annotation/MergedAnnotationsRepeatableAnnotationTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -274,7 +274,7 @@ private <A extends Annotation> Set<A> getAnnotations(Class<? extends Annotation>
 	private <A extends Annotation> Set<A> getAnnotations(Class<? extends Annotation> container,
 			Class<A> repeatable, SearchStrategy searchStrategy, AnnotatedElement element, AnnotationFilter annotationFilter) {
 
-		RepeatableContainers containers = RepeatableContainers.of(repeatable, container);
+		RepeatableContainers containers = RepeatableContainers.explicitRepeatable(repeatable, container);
 		MergedAnnotations annotations = MergedAnnotations.from(element, searchStrategy, containers, annotationFilter);
 		return annotations.stream(repeatable).collect(MergedAnnotationCollectors.toAnnotationSet());
 	}

spring-core/src/test/java/org/springframework/core/annotation/MergedAnnotationsTests.java

@@ -136,7 +136,7 @@ void searchFromClassWithCustomAnnotationFilter() {
 		@Test
 		void searchFromClassWithCustomRepeatableContainers() {
 			assertThat(MergedAnnotations.from(HierarchyClass.class).stream(TestConfiguration.class)).isEmpty();
-			RepeatableContainers containers = RepeatableContainers.of(TestConfiguration.class, Hierarchy.class);
+			RepeatableContainers containers = RepeatableContainers.explicitRepeatable(TestConfiguration.class, Hierarchy.class);
 
 			MergedAnnotations annotations = MergedAnnotations.search(SearchStrategy.DIRECT)
 					.withRepeatableContainers(containers)
@@ -1364,7 +1364,7 @@ void streamRepeatableDeclaredOnMethod() throws Exception {
 	@SuppressWarnings("deprecation")
 	void streamRepeatableDeclaredOnClassWithAttributeAliases() {
 		assertThat(MergedAnnotations.from(HierarchyClass.class).stream(TestConfiguration.class)).isEmpty();
-		RepeatableContainers containers = RepeatableContainers.of(TestConfiguration.class, Hierarchy.class);
+		RepeatableContainers containers = RepeatableContainers.explicitRepeatable(TestConfiguration.class, Hierarchy.class);
 		MergedAnnotations annotations = MergedAnnotations.from(HierarchyClass.class,
 				SearchStrategy.DIRECT, containers, AnnotationFilter.NONE);
 		assertThat(annotations.stream(TestConfiguration.class)
@@ -1440,7 +1440,7 @@ private void testJavaRepeatables(SearchStrategy searchStrategy, Class<?> element
 
 	private void testExplicitRepeatables(SearchStrategy searchStrategy, Class<?> element, String[] expected) {
 		MergedAnnotations annotations = MergedAnnotations.from(element, searchStrategy,
-				RepeatableContainers.of(MyRepeatable.class, MyRepeatableContainer.class));
+				RepeatableContainers.explicitRepeatable(MyRepeatable.class, MyRepeatableContainer.class));
 		Stream<String> values = annotations.stream(MyRepeatable.class)
 				.filter(MergedAnnotationPredicates.firstRunOf(MergedAnnotation::getAggregateIndex))
 				.map(annotation -> annotation.getString("value"));