Deprecate StandardMetadata constructors

Deprecate the public `StandardMetadata` constructors to make it clearer
that these classes should not be instantiated directly. A new
`AnnotationMetadata.introspect` factory method has been added which
can now be used to obtain instances.

This change will allow use to make the constructors package private
and drop the `nestedAnnotationsAsMap` parameter in a future release.

Closes gh-22906

Author: philwebb

spring-beans/src/main/java/org/springframework/beans/factory/annotation/AnnotatedGenericBeanDefinition.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -55,7 +55,7 @@ public class AnnotatedGenericBeanDefinition extends GenericBeanDefinition implem
 	 */
 	public AnnotatedGenericBeanDefinition(Class<?> beanClass) {
 		setBeanClass(beanClass);
-		this.metadata = new StandardAnnotationMetadata(beanClass, true);
+		this.metadata = AnnotationMetadata.introspect(beanClass);
 	}
 
 	/**

spring-context/src/main/java/org/springframework/context/annotation/ConfigurationClass.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -29,7 +29,6 @@
 import org.springframework.core.io.DescriptiveResource;
 import org.springframework.core.io.Resource;
 import org.springframework.core.type.AnnotationMetadata;
-import org.springframework.core.type.StandardAnnotationMetadata;
 import org.springframework.core.type.classreading.MetadataReader;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
@@ -104,7 +103,7 @@ public ConfigurationClass(MetadataReader metadataReader, @Nullable Configuration
 	 */
 	public ConfigurationClass(Class<?> clazz, String beanName) {
 		Assert.notNull(beanName, "Bean name must not be null");
-		this.metadata = new StandardAnnotationMetadata(clazz, true);
+		this.metadata = AnnotationMetadata.introspect(clazz);
 		this.resource = new DescriptiveResource(clazz.getName());
 		this.beanName = beanName;
 	}
@@ -118,7 +117,7 @@ public ConfigurationClass(Class<?> clazz, String beanName) {
 	 * @since 3.1.1
 	 */
 	public ConfigurationClass(Class<?> clazz, @Nullable ConfigurationClass importedBy) {
-		this.metadata = new StandardAnnotationMetadata(clazz, true);
+		this.metadata = AnnotationMetadata.introspect(clazz);
 		this.resource = new DescriptiveResource(clazz.getName());
 		this.importedBy.add(importedBy);
 	}

spring-context/src/main/java/org/springframework/context/annotation/ConfigurationClassParser.java

@@ -913,7 +913,7 @@ private class SourceClass implements Ordered {
 		public SourceClass(Object source) {
 			this.source = source;
 			if (source instanceof Class) {
-				this.metadata = new StandardAnnotationMetadata((Class<?>) source, true);
+				this.metadata = AnnotationMetadata.introspect((Class<?>) source);
 			}
 			else {
 				this.metadata = ((MetadataReader) source).getAnnotationMetadata();

spring-context/src/main/java/org/springframework/context/annotation/ConfigurationClassUtils.java

@@ -36,7 +36,6 @@
 import org.springframework.core.annotation.AnnotationUtils;
 import org.springframework.core.annotation.Order;
 import org.springframework.core.type.AnnotationMetadata;
-import org.springframework.core.type.StandardAnnotationMetadata;
 import org.springframework.core.type.classreading.MetadataReader;
 import org.springframework.core.type.classreading.MetadataReaderFactory;
 import org.springframework.lang.Nullable;
@@ -106,7 +105,7 @@ else if (beanDef instanceof AbstractBeanDefinition && ((AbstractBeanDefinition)
 					EventListenerFactory.class.isAssignableFrom(beanClass)) {
 				return false;
 			}
-			metadata = new StandardAnnotationMetadata(beanClass, true);
+			metadata = AnnotationMetadata.introspect(beanClass);
 		}
 		else {
 			try {

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

@@ -115,4 +115,16 @@ default boolean hasAnnotatedMethods(String annotationName) {
 	 */
 	Set<MethodMetadata> getAnnotatedMethods(String annotationName);
 
+
+	/**
+	 * Factory method to create a new {@link AnnotationMetadata} instance
+	 * for the given class using standard reflection.
+	 * @param type the class to introspect
+	 * @return a new {@link AnnotationMetadata} instance
+	 * @since 5.2
+	 */
+	static AnnotationMetadata introspect(Class<?> type) {
+		return StandardAnnotationMetadata.from(type);
+	}
+
 }

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

@@ -26,6 +26,7 @@
 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;
 import org.springframework.core.annotation.MergedAnnotations.SearchStrategy;
 import org.springframework.core.annotation.RepeatableContainers;
@@ -56,7 +57,9 @@ public class StandardAnnotationMetadata extends StandardClassMetadata implements
 	 * Create a new {@code StandardAnnotationMetadata} wrapper for the given Class.
 	 * @param introspectedClass the Class to introspect
 	 * @see #StandardAnnotationMetadata(Class, boolean)
+	 * @deprecated since 5.2 in favor of the factory method {@link AnnotationMetadata#introspect(Class)}
 	 */
+	@Deprecated
 	public StandardAnnotationMetadata(Class<?> introspectedClass) {
 		this(introspectedClass, false);
 	}
@@ -71,7 +74,12 @@ public StandardAnnotationMetadata(Class<?> introspectedClass) {
 	 * {@link org.springframework.core.annotation.AnnotationAttributes} for compatibility
 	 * with ASM-based {@link AnnotationMetadata} implementations
 	 * @since 3.1.1
+	 * @deprecated since 5.2 in favor of the factory method {@link AnnotationMetadata#introspect(Class)}.
+	 * Use {@link MergedAnnotation#asMap(org.springframework.core.annotation.MergedAnnotation.Adapt...) MergedAnnotation.asMap}
+	 * from {@link #getAnnotations()} rather than {@link #getAnnotationAttributes(String)}
+	 * if {@code nestedAnnotationsAsMap} is {@code false}
 	 */
+	@Deprecated
 	public StandardAnnotationMetadata(Class<?> introspectedClass, boolean nestedAnnotationsAsMap) {
 		super(introspectedClass);
 		this.mergedAnnotations = MergedAnnotations.from(introspectedClass,
@@ -138,6 +146,7 @@ public boolean hasAnnotatedMethods(String annotationName) {
 	}
 
 	@Override
+	@SuppressWarnings("deprecation")
 	public Set<MethodMetadata> getAnnotatedMethods(String annotationName) {
 		Set<MethodMetadata> annotatedMethods = null;
 		if (AnnotationUtils.isCandidateClass(getIntrospectedClass(), annotationName)) {
@@ -164,4 +173,9 @@ private boolean isAnnotatedMethod(Method method, String annotationName) {
 				AnnotatedElementUtils.isAnnotated(method, annotationName);
 	}
 
+
+	static AnnotationMetadata from(Class<?> introspectedClass) {
+		return new StandardAnnotationMetadata(introspectedClass, true);
+	}
+
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -38,7 +38,9 @@ public class StandardClassMetadata implements ClassMetadata {
 	/**
 	 * Create a new StandardClassMetadata wrapper for the given Class.
 	 * @param introspectedClass the Class to introspect
+	 * @deprecated since 5.2 in favor of {@link StandardAnnotationMetadata}
 	 */
+	@Deprecated
 	public StandardClassMetadata(Class<?> introspectedClass) {
 		Assert.notNull(introspectedClass, "Class must not be null");
 		this.introspectedClass = introspectedClass;

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

@@ -51,7 +51,9 @@ public class StandardMethodMetadata implements MethodMetadata {
 	/**
 	 * Create a new StandardMethodMetadata wrapper for the given Method.
 	 * @param introspectedMethod the Method to introspect
+	 * @deprecated since 5.2 in favor of obtaining instances via {@link AnnotationMetadata}
 	 */
+	@Deprecated
 	public StandardMethodMetadata(Method introspectedMethod) {
 		this(introspectedMethod, false);
 	}
@@ -66,7 +68,9 @@ public StandardMethodMetadata(Method introspectedMethod) {
 	 * {@link org.springframework.core.annotation.AnnotationAttributes} for compatibility
 	 * with ASM-based {@link AnnotationMetadata} implementations
 	 * @since 3.1.1
+	 * @deprecated since 5.2 in favor of obtaining instances via {@link AnnotationMetadata}
 	 */
+	@Deprecated
 	public StandardMethodMetadata(Method introspectedMethod, boolean nestedAnnotationsAsMap) {
 		Assert.notNull(introspectedMethod, "Method must not be null");
 		this.introspectedMethod = introspectedMethod;

spring-core/src/test/java/org/springframework/core/type/AnnotationMetadataTests.java

@@ -55,7 +55,7 @@ public class AnnotationMetadataTests {
 
 	@Test
 	public void standardAnnotationMetadata() {
-		AnnotationMetadata metadata = new StandardAnnotationMetadata(AnnotatedComponent.class, true);
+		AnnotationMetadata metadata = AnnotationMetadata.introspect(AnnotatedComponent.class);
 		doTestAnnotationInfo(metadata);
 		doTestMethodAnnotationInfo(metadata);
 	}
@@ -71,7 +71,7 @@ public void asmAnnotationMetadata() throws Exception {
 
 	@Test
 	public void standardAnnotationMetadataForSubclass() {
-		AnnotationMetadata metadata = new StandardAnnotationMetadata(AnnotatedComponentSubClass.class, true);
+		AnnotationMetadata metadata = AnnotationMetadata.introspect(AnnotatedComponentSubClass.class);
 		doTestSubClassAnnotationInfo(metadata);
 	}
 
@@ -107,7 +107,7 @@ private void doTestSubClassAnnotationInfo(AnnotationMetadata metadata) {
 
 	@Test
 	public void standardAnnotationMetadataForInterface() {
-		AnnotationMetadata metadata = new StandardAnnotationMetadata(AnnotationMetadata.class, true);
+		AnnotationMetadata metadata = AnnotationMetadata.introspect(AnnotationMetadata.class);
 		doTestMetadataForInterfaceClass(metadata);
 	}
 
@@ -135,7 +135,7 @@ private void doTestMetadataForInterfaceClass(AnnotationMetadata metadata) {
 
 	@Test
 	public void standardAnnotationMetadataForAnnotation() {
-		AnnotationMetadata metadata = new StandardAnnotationMetadata(Component.class, true);
+		AnnotationMetadata metadata = AnnotationMetadata.introspect(Component.class);
 		doTestMetadataForAnnotationClass(metadata);
 	}
 
@@ -174,6 +174,7 @@ private void doTestMetadataForAnnotationClass(AnnotationMetadata metadata) {
 	 * 'true' as is done in the main test above.
 	 */
 	@Test
+	@Deprecated
 	public void standardAnnotationMetadata_nestedAnnotationsAsMap_false() {
 		AnnotationMetadata metadata = new StandardAnnotationMetadata(AnnotatedComponent.class);
 		AnnotationAttributes specialAttrs = (AnnotationAttributes) metadata.getAnnotationAttributes(SpecialAttr.class.getName());
@@ -182,6 +183,7 @@ public void standardAnnotationMetadata_nestedAnnotationsAsMap_false() {
 	}
 
 	@Test
+	@Deprecated
 	public void metaAnnotationOverridesUsingStandardAnnotationMetadata() {
 		AnnotationMetadata metadata = new StandardAnnotationMetadata(ComposedConfigurationWithAttributeOverridesClass.class);
 		assertMetaAnnotationOverrides(metadata);
@@ -209,7 +211,7 @@ private void assertMetaAnnotationOverrides(AnnotationMetadata metadata) {
 
 	@Test  // SPR-11649
 	public void multipleAnnotationsWithIdenticalAttributeNamesUsingStandardAnnotationMetadata() {
-		AnnotationMetadata metadata = new StandardAnnotationMetadata(NamedAnnotationsClass.class);
+		AnnotationMetadata metadata = AnnotationMetadata.introspect(NamedAnnotationsClass.class);
 		assertMultipleAnnotationsWithIdenticalAttributeNames(metadata);
 	}
 
@@ -223,7 +225,7 @@ public void multipleAnnotationsWithIdenticalAttributeNamesUsingAnnotationMetadat
 
 	@Test  // SPR-11649
 	public void composedAnnotationWithMetaAnnotationsWithIdenticalAttributeNamesUsingStandardAnnotationMetadata() {
-		AnnotationMetadata metadata = new StandardAnnotationMetadata(NamedComposedAnnotationClass.class);
+		AnnotationMetadata metadata = AnnotationMetadata.introspect(NamedComposedAnnotationClass.class);
 		assertMultipleAnnotationsWithIdenticalAttributeNames(metadata);
 	}
 
@@ -237,7 +239,7 @@ public void composedAnnotationWithMetaAnnotationsWithIdenticalAttributeNamesUsin
 
 	@Test
 	public void inheritedAnnotationWithMetaAnnotationsWithIdenticalAttributeNamesUsingStandardAnnotationMetadata() {
-		AnnotationMetadata metadata = new StandardAnnotationMetadata(NamedComposedAnnotationExtended.class);
+		AnnotationMetadata metadata = AnnotationMetadata.introspect(NamedComposedAnnotationExtended.class);
 		assertFalse(metadata.hasAnnotation(NamedComposedAnnotation.class.getName()));
 	}
 

spring-core/src/test/java/org/springframework/core/type/StandardAnnotationMetadataTests.java

@@ -24,6 +24,7 @@
 public class StandardAnnotationMetadataTests extends AbstractAnnotationMetadataTests {
 
 	@Override
+	@SuppressWarnings("deprecation")
 	protected AnnotationMetadata get(Class<?> source) {
 		return new StandardAnnotationMetadata(source);
 	}

spring-core/src/test/java/org/springframework/core/type/StandardClassMetadataMemberClassTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2011 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -25,6 +25,7 @@ public class StandardClassMetadataMemberClassTests
 		extends AbstractClassMetadataMemberClassTests {
 
 	@Override
+	@SuppressWarnings("deprecation")
 	public ClassMetadata getClassMetadataFor(Class<?> clazz) {
 		return new StandardClassMetadata(clazz);
 	}

spring-core/src/test/java/org/springframework/core/type/StandardMethodMetadataTests.java

@@ -25,7 +25,7 @@ public class StandardMethodMetadataTests extends AbstractMethodMetadataTests {
 
 	@Override
 	protected AnnotationMetadata get(Class<?> source) {
-		return new StandardAnnotationMetadata(source);
+		return AnnotationMetadata.introspect(source);
 	}
 
 }