diff --git a/spring-core/src/main/java/org/springframework/core/annotation/AnnotatedElementUtils.java b/spring-core/src/main/java/org/springframework/core/annotation/AnnotatedElementUtils.java index 32c2c927e27..726e5cf2173 100644 --- a/spring-core/src/main/java/org/springframework/core/annotation/AnnotatedElementUtils.java +++ b/spring-core/src/main/java/org/springframework/core/annotation/AnnotatedElementUtils.java @@ -659,21 +659,42 @@ public class AnnotatedElementUtils { return null; } + /** - * Callback interface that is used to process a target annotation (or - * multiple instances of the target annotation) that has been found by - * the currently executing search and to post-process the result as the - * search algorithm goes back down the annotation hierarchy from the - * target annotation to the initial {@link AnnotatedElement} that was - * supplied to the search algorithm. + * Callback interface that is used to process annotations during a search. + * + *
Depending on the use case, a processor may choose to + * {@linkplain #process} a single target annotation, multiple target + * annotations, or all annotations discovered by the currently executing + * search. The term "target" in this context refers to a matching + * annotation (i.e., a specific annotation type that was found during + * the search). Returning a non-null value from the {@link #process} + * method instructs the search algorithm to stop searching further; + * whereas, returning {@code null} from the {@link #process} method + * instructs the search algorithm to continue searching for additional + * annotations. + * + *
Processors can optionally {@linkplain #postProcess post-process}
+ * the result of the {@link #process} method as the search algorithm
+ * goes back down the annotation hierarchy from an invocation of
+ * {@link #process} that returned a non-null value down to the
+ * {@link AnnotatedElement} that was supplied as the starting point to
+ * the search algorithm.
*
* @param Depending on the use case, the supplied annotation may be an
+ * actual target annotation that has been found by the search
+ * algorithm, or it may be some other annotation within the
+ * annotation hierarchy. In the latter case, the {@code metaDepth}
+ * should have a value greater than {@code 0}. In any case, it is
+ * up to concrete implementations of this method to decide what to
+ * do with the supplied annotation.
*
* The {@code metaDepth} parameter represents the depth of the
* annotation relative to the first annotated element in the
@@ -685,7 +706,7 @@ public class AnnotatedElementUtils {
* @param annotation the annotation to process
* @param metaDepth the meta-depth of the annotation
* @return the result of the processing, or {@code null} to continue
- * searching for additional target annotations
+ * searching for additional annotations
*/
T process(Annotation annotation, int metaDepth);
@@ -694,8 +715,8 @@ public class AnnotatedElementUtils {
*
* The {@code annotation} supplied to this method is an annotation
* that is present in the annotation hierarchy, between the initial
- * {@link AnnotatedElement} and a target annotation found by the
- * search algorithm.
+ * {@link AnnotatedElement} and an invocation of {@link #process}
+ * that returned a non-null value.
*
* @param annotation the annotation to post-process
* @param result the result to post-process