Deprecate AnnotationFilter.NONE and document MergedAnnotations design

Closes gh-24932

Author: jhoeller

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -21,8 +21,15 @@
 /**
  * Callback interface that can be used to filter specific annotation types.
  *
+ * <p>Note that the {@link MergedAnnotations} model (which this interface has been
+ * designed for) always ignores lang annotations according to the {@link #PLAIN}
+ * filter (for efficiency reasons). Any additional filters and even custom filter
+ * implementations apply within this boundary and may only narrow further from here.
+ *
  * @author Phillip Webb
+ * @author Juergen Hoeller
  * @since 5.2
+ * @see MergedAnnotations
  */
 @FunctionalInterface
 public interface AnnotationFilter {
@@ -31,6 +38,7 @@ public interface AnnotationFilter {
 	 * {@link AnnotationFilter} that matches annotations in the
 	 * {@code java.lang} and {@code org.springframework.lang} packages
 	 * and their subpackages.
+	 * <p>This is the default filter in the {@link MergedAnnotations} model.
 	 */
 	AnnotationFilter PLAIN = packages("java.lang", "org.springframework.lang");
 
@@ -66,7 +74,12 @@ public String toString() {
 	/**
 	 * {@link AnnotationFilter} that never matches and can be used when no
 	 * filtering is needed (allowing for any annotation types to be present).
+	 * @deprecated as of 5.2.6 since the {@link MergedAnnotations} model
+	 * always ignores lang annotations according to the {@link #PLAIN} filter
+	 * (for efficiency reasons)
+	 * @see #PLAIN
 	 */
+	@Deprecated
 	AnnotationFilter NONE = new AnnotationFilter() {
 		@Override
 		public boolean matches(Annotation annotation) {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -119,6 +119,13 @@
  *     .forEach(System.out::println);
  * </pre>
  *
+ * <p><b>NOTE: The {@code MergedAnnotations} API and its underlying model have
+ * been designed for composable annotations in Spring's common component model,
+ * with a focus on attribute aliasing and meta-annotation relationships.</b>
+ * There is no support for retrieving plain Java annotations with this API;
+ * please use standard Java reflection or Spring's {@link AnnotationUtils}
+ * for simple annotation retrieval purposes.
+ *
  * @author Phillip Webb
  * @author Sam Brannen
  * @since 5.2

spring-core/src/main/java/org/springframework/core/type/StandardAnnotationMetadata.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -24,7 +24,6 @@
 import java.util.Set;
 
 import org.springframework.core.annotation.AnnotatedElementUtils;
-import org.springframework.core.annotation.AnnotationFilter;
 import org.springframework.core.annotation.AnnotationUtils;
 import org.springframework.core.annotation.MergedAnnotation;
 import org.springframework.core.annotation.MergedAnnotations;
@@ -85,8 +84,7 @@ public StandardAnnotationMetadata(Class<?> introspectedClass) {
 	public StandardAnnotationMetadata(Class<?> introspectedClass, boolean nestedAnnotationsAsMap) {
 		super(introspectedClass);
 		this.mergedAnnotations = MergedAnnotations.from(introspectedClass,
-				SearchStrategy.INHERITED_ANNOTATIONS, RepeatableContainers.none(),
-				AnnotationFilter.NONE);
+				SearchStrategy.INHERITED_ANNOTATIONS, RepeatableContainers.none());
 		this.nestedAnnotationsAsMap = nestedAnnotationsAsMap;
 	}