Support implicit attribute aliases with @AliasFor

Spring Framework 4.2 introduced support for aliases between annotation
attributes that fall into the following two categories.

1) Alias pairs: two attributes in the same annotation that use
   @AliasFor to declare that they are explicit aliases for each other.
2) Meta-annotation attribute overrides: an attribute in one annotation
   uses @AliasFor to declare that it is an explicit override of an
   attribute in a meta-annotation.

However, the existing functionality fails to support the case where two
attributes in the same annotation both use @AliasFor to declare that
they are both explicit overrides of the same attribute in the same
meta-annotation. In such scenarios, one would intuitively assume that
two such attributes would be treated as "implicit" aliases for each
other, analogous to the existing support for explicit alias pairs.
Furthermore, an annotation may potentially declare multiple aliases
that are effectively a set of implicit aliases for each other.

This commit introduces support for implicit aliases configured via
@AliasFor through an extensive overhaul of the support for alias
lookups, validation, etc. Specifically, this commit includes the
following.

- Introduced isAnnotationMetaPresent() in AnnotationUtils.

- Introduced private AliasDescriptor class in AnnotationUtils in order
  to encapsulate the parsing, validation, and comparison of both
  explicit and implicit aliases configured via @AliasFor.

- Switched from single values for alias names to lists of alias names.

- Renamed getAliasedAttributeName() to getAliasedAttributeNames() in
  AnnotationUtils.

- Converted alias map to contain lists of aliases in AnnotationUtils.

- Refactored the following to support multiple implicit aliases:
  getRequiredAttributeWithAlias() in AnnotationAttributes,
  AbstractAliasAwareAnnotationAttributeExtractor,
  MapAnnotationAttributeExtractor, MergedAnnotationAttributesProcessor
  in AnnotatedElementUtils, and postProcessAnnotationAttributes() in
  AnnotationUtils.

- Introduced numerous tests for implicit alias support, including
  AbstractAliasAwareAnnotationAttributeExtractorTestCase,
  DefaultAnnotationAttributeExtractorTests, and
  MapAnnotationAttributeExtractorTests.

- Updated Javadoc in @AliasFor regarding implicit aliases and in
  AnnotationUtils regarding "meta-present".

Issue: SPR-13345

Author: sbrannen

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

@@ -19,6 +19,7 @@
 import java.lang.annotation.Annotation;
 import java.lang.reflect.AnnotatedElement;
 import java.lang.reflect.Method;
+import java.util.List;
 import java.util.Map;
 
 import org.springframework.util.Assert;
@@ -44,7 +45,7 @@ abstract class AbstractAliasAwareAnnotationAttributeExtractor<S> implements Anno
 
 	private final S source;
 
-	private final Map<String, String> attributeAliasMap;
+	private final Map<String, List<String>> attributeAliasMap;
 
 
 	/**
@@ -83,29 +84,33 @@ public final S getSource() {
 
 	@Override
 	public final Object getAttributeValue(Method attributeMethod) {
-		String attributeName = attributeMethod.getName();
+		final String attributeName = attributeMethod.getName();
 		Object attributeValue = getRawAttributeValue(attributeMethod);
 
-		String aliasName = this.attributeAliasMap.get(attributeName);
-		if (aliasName != null) {
-			Object aliasValue = getRawAttributeValue(aliasName);
-			Object defaultValue = AnnotationUtils.getDefaultValue(getAnnotationType(), attributeName);
-
-			if (!ObjectUtils.nullSafeEquals(attributeValue, aliasValue) &&
-					!ObjectUtils.nullSafeEquals(attributeValue, defaultValue) &&
-					!ObjectUtils.nullSafeEquals(aliasValue, defaultValue)) {
-				String elementName = (getAnnotatedElement() != null ? getAnnotatedElement().toString() : "unknown element");
-				throw new AnnotationConfigurationException(String.format(
-						"In annotation [%s] declared on %s and synthesized from [%s], attribute '%s' and its " +
-						"alias '%s' are present with values of [%s] and [%s], but only one is permitted.",
-						getAnnotationType().getName(), elementName, getSource(), attributeName, aliasName,
-						ObjectUtils.nullSafeToString(attributeValue), ObjectUtils.nullSafeToString(aliasValue)));
-			}
-
-			// If the user didn't declare the annotation with an explicit value,
-			// return the value of the alias.
-			if (ObjectUtils.nullSafeEquals(attributeValue, defaultValue)) {
-				attributeValue = aliasValue;
+		List<String> aliasNames = this.attributeAliasMap.get(attributeName);
+		if (aliasNames != null) {
+			final Object defaultValue = AnnotationUtils.getDefaultValue(getAnnotationType(), attributeName);
+			for (String aliasName : aliasNames) {
+				if (aliasName != null) {
+					Object aliasValue = getRawAttributeValue(aliasName);
+
+					if (!ObjectUtils.nullSafeEquals(attributeValue, aliasValue) &&
+							!ObjectUtils.nullSafeEquals(attributeValue, defaultValue) &&
+							!ObjectUtils.nullSafeEquals(aliasValue, defaultValue)) {
+						String elementName = (getAnnotatedElement() != null ? getAnnotatedElement().toString() : "unknown element");
+						throw new AnnotationConfigurationException(String.format(
+								"In annotation [%s] declared on %s and synthesized from [%s], attribute '%s' and its " +
+								"alias '%s' are present with values of [%s] and [%s], but only one is permitted.",
+								getAnnotationType().getName(), elementName, getSource(), attributeName, aliasName,
+								ObjectUtils.nullSafeToString(attributeValue), ObjectUtils.nullSafeToString(aliasValue)));
+					}
+
+					// If the user didn't declare the annotation with an explicit value,
+					// use the value of the alias instead.
+					if (ObjectUtils.nullSafeEquals(attributeValue, defaultValue)) {
+						attributeValue = aliasValue;
+					}
+				}
 			}
 		}
 

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

@@ -29,17 +29,22 @@
  *
  * <h3>Usage Scenarios</h3>
  * <ul>
- * <li><strong>Aliases within an annotation</strong>: within a single
+ * <li><strong>Explicit aliases within an annotation</strong>: within a single
  * annotation, {@code @AliasFor} can be declared on a pair of attributes to
  * signal that they are interchangeable aliases for each other.</li>
- * <li><strong>Alias for attribute in meta-annotation</strong>: if the
+ * <li><strong>Explicit alias for attribute in meta-annotation</strong>: if the
  * {@link #annotation} attribute of {@code @AliasFor} is set to a different
  * annotation than the one that declares it, the {@link #attribute} is
  * interpreted as an alias for an attribute in a meta-annotation (i.e., an
  * explicit meta-annotation attribute override). This enables fine-grained
  * control over exactly which attributes are overridden within an annotation
  * hierarchy. In fact, with {@code @AliasFor} it is even possible to declare
  * an alias for the {@code value} attribute of a meta-annotation.</li>
+ * <li><strong>Implicit aliases within an annotation</strong>: if one or
+ * more attributes within an annotation are declared as explicit
+ * meta-annotation attribute overrides for the same attribute in the
+ * meta-annotation, those attributes will be treated as a set of <em>implicit</em>
+ * aliases for each other, analogous to explicit aliases within an annotation.</li>
  * </ul>
  *
  * <h3>Usage Requirements</h3>
@@ -57,31 +62,44 @@
  *
  * <h3>Implementation Requirements</h3>
  * <ul>
- * <li><strong>Aliases within an annotation</strong>:
+ * <li><strong>Explicit aliases within an annotation</strong>:
  * <ol>
  * <li>Each attribute that makes up an aliased pair must be annotated with
- * {@code @AliasFor}, and either the {@link #attribute} or the {@link #value}
- * attribute must reference the <em>other</em> attribute in the pair.</li>
+ * {@code @AliasFor}, and either {@link #attribute} or {@link #value} must
+ * reference the <em>other</em> attribute in the pair.</li>
  * <li>Aliased attributes must declare the same return type.</li>
  * <li>Aliased attributes must declare a default value.</li>
  * <li>Aliased attributes must declare the same default value.</li>
- * <li>The {@link #annotation} attribute should remain set to the default.</li>
+ * <li>{@link #annotation} should not be declared.</li>
  * </ol>
  * </li>
- * <li><strong>Alias for attribute in meta-annotation</strong>:
+ * <li><strong>Explicit alias for attribute in meta-annotation</strong>:
  * <ol>
  * <li>The attribute that is an alias for an attribute in a meta-annotation
- * must be annotated with {@code @AliasFor}, and the {@link #attribute} must
- * reference the aliased attribute in the meta-annotation.</li>
+ * must be annotated with {@code @AliasFor}, and {@link #attribute} must
+ * reference the attribute in the meta-annotation.</li>
  * <li>Aliased attributes must declare the same return type.</li>
- * <li>The {@link #annotation} must reference the meta-annotation.</li>
+ * <li>{@link #annotation} must reference the meta-annotation.</li>
+ * <li>The referenced meta-annotation must be <em>meta-present</em> on the
+ * annotation class that declares {@code @AliasFor}.</li>
+ * </ol>
+ * </li>
+ * <li><strong>Implicit aliases within an annotation</strong>:
+ * <ol>
+ * <li>Each attribute that belongs to the set of implicit aliases must be
+ * annotated with {@code @AliasFor}, and {@link #attribute} must reference
+ * the same attribute in the same meta-annotation.</li>
+ * <li>Aliased attributes must declare the same return type.</li>
+ * <li>Aliased attributes must declare a default value.</li>
+ * <li>Aliased attributes must declare the same default value.</li>
+ * <li>{@link #annotation} must reference the meta-annotation.</li>
  * <li>The referenced meta-annotation must be <em>meta-present</em> on the
  * annotation class that declares {@code @AliasFor}.</li>
  * </ol>
  * </li>
  * </ul>
  *
- * <h3>Example: Aliases within an Annotation</h3>
+ * <h3>Example: Explicit Aliases within an Annotation</h3>
  * <pre class="code"> public &#064;interface ContextConfiguration {
  *
  *    &#064;AliasFor("locations")
@@ -93,14 +111,28 @@
  *    // ...
  * }</pre>
  *
- * <h3>Example: Alias for Attribute in Meta-annotation</h3>
+ * <h3>Example: Explicit Alias for Attribute in Meta-annotation</h3>
  * <pre class="code"> &#064;ContextConfiguration
  * public &#064;interface MyTestConfig {
  *
  *    &#064;AliasFor(annotation = ContextConfiguration.class, attribute = "locations")
  *    String[] xmlFiles();
  * }</pre>
  *
+ * <h3>Example: Implicit Aliases within an Annotation</h3>
+ * <pre class="code"> &#064;ContextConfiguration
+ * public &#064;interface MyTestConfig {
+ *
+ *    &#064;AliasFor(annotation = ContextConfiguration.class, attribute = "locations")
+ *    String[] value() default {};
+ *
+ *    &#064;AliasFor(annotation = ContextConfiguration.class, attribute = "locations")
+ *    String[] groovyScripts() default {};
+ *
+ *    &#064;AliasFor(annotation = ContextConfiguration.class, attribute = "locations")
+ *    String[] xmlFiles() default {};
+ * }</pre>
+ *
  * <h3>Spring Annotations Supporting Attribute Aliases</h3>
  * <p>As of Spring Framework 4.2, several annotations within core Spring
  * have been updated to use {@code @AliasFor} to configure their internal

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

@@ -31,7 +31,6 @@
 import org.springframework.util.Assert;
 import org.springframework.util.LinkedMultiValueMap;
 import org.springframework.util.MultiValueMap;
-import org.springframework.util.StringUtils;
 
 /**
  * General utility methods for finding annotations and meta-annotations on
@@ -957,13 +956,21 @@ public void postProcess(AnnotatedElement element, Annotation annotation, Annotat
 
 			for (Method attributeMethod : AnnotationUtils.getAttributeMethods(annotation.annotationType())) {
 				String attributeName = attributeMethod.getName();
-				String aliasedAttributeName = AnnotationUtils.getAliasedAttributeName(attributeMethod,
-					targetAnnotationType);
+				List<String> aliases = AnnotationUtils.getAliasedAttributeNames(attributeMethod, targetAnnotationType);
 
 				// Explicit annotation attribute override declared via @AliasFor
-				if (StringUtils.hasText(aliasedAttributeName) && attributes.containsKey(aliasedAttributeName)) {
-					overrideAttribute(element, annotation, attributes, attributeName, aliasedAttributeName);
+				if (!aliases.isEmpty()) {
+					if (aliases.size() != 1) {
+						throw new IllegalStateException(String.format(
+							"Alias list for annotation attribute [%s] must contain at most one element: %s",
+							attributeMethod, aliases));
+					}
+					String aliasedAttributeName = aliases.get(0);
+					if (attributes.containsKey(aliasedAttributeName)) {
+						overrideAttribute(element, annotation, attributes, attributeName, aliasedAttributeName);
+					}
 				}
+
 				// Implicit annotation attribute override based on convention
 				else if (!AnnotationUtils.VALUE.equals(attributeName) && attributes.containsKey(attributeName)) {
 					overrideAttribute(element, annotation, attributes, attributeName, attributeName);

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

@@ -21,6 +21,7 @@
 import java.lang.reflect.Array;
 import java.util.Iterator;
 import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Map;
 
 import org.springframework.util.Assert;
@@ -422,26 +423,38 @@ private <T> T getRequiredAttributeWithAlias(String attributeName, Class<? extend
 		Assert.notNull(expectedType, "expectedType must not be null");
 
 		T attributeValue = getAttribute(attributeName, expectedType);
-		String aliasName = AnnotationUtils.getAttributeAliasMap(annotationType).get(attributeName);
-		T aliasValue = getAttribute(aliasName, expectedType);
-		boolean attributeDeclared = !ObjectUtils.isEmpty(attributeValue);
-		boolean aliasDeclared = !ObjectUtils.isEmpty(aliasValue);
-
-		if (!ObjectUtils.nullSafeEquals(attributeValue, aliasValue) && attributeDeclared && aliasDeclared) {
-			String elementName = (annotationSource == null ? "unknown element" : annotationSource.toString());
-			String msg = String.format("In annotation [%s] declared on [%s], attribute [%s] and its alias [%s] " +
-					"are present with values of [%s] and [%s], but only one is permitted.",
-					annotationType.getName(), elementName, attributeName, aliasName,
-					ObjectUtils.nullSafeToString(attributeValue), ObjectUtils.nullSafeToString(aliasValue));
-			throw new AnnotationConfigurationException(msg);
-		}
 
-		if (!attributeDeclared) {
-			attributeValue = aliasValue;
+		List<String> aliasNames = AnnotationUtils.getAttributeAliasMap(annotationType).get(attributeName);
+		if (aliasNames != null) {
+			for (String aliasName : aliasNames) {
+				T aliasValue = getAttribute(aliasName, expectedType);
+				boolean attributeEmpty = ObjectUtils.isEmpty(attributeValue);
+				boolean aliasEmpty = ObjectUtils.isEmpty(aliasValue);
+
+				if (!attributeEmpty && !aliasEmpty && !ObjectUtils.nullSafeEquals(attributeValue, aliasValue)) {
+					String elementName = (annotationSource == null ? "unknown element" : annotationSource.toString());
+					String msg = String.format("In annotation [%s] declared on [%s], attribute [%s] and its alias [%s] " +
+							"are present with values of [%s] and [%s], but only one is permitted.",
+							annotationType.getName(), elementName, attributeName, aliasName,
+							ObjectUtils.nullSafeToString(attributeValue), ObjectUtils.nullSafeToString(aliasValue));
+					throw new AnnotationConfigurationException(msg);
+				}
+
+				// If we expect an array and the current tracked value is null but the
+				// current alias value is non-null, then replace the current null value
+				// with the non-null value (which may be an empty array).
+				if (expectedType.isArray() && attributeValue == null && aliasValue != null) {
+					attributeValue = aliasValue;
+				}
+				// Else: if we're not expecting an array, we can rely on the behavior of
+				// ObjectUtils.isEmpty().
+				else if (attributeEmpty && !aliasEmpty) {
+					attributeValue = aliasValue;
+				}
+			}
+			assertAttributePresence(attributeName, aliasNames, attributeValue);
 		}
 
-		assertAttributePresence(attributeName, aliasName, attributeValue);
-
 		return attributeValue;
 	}
 
@@ -473,11 +486,11 @@ private void assertAttributePresence(String attributeName, Object attributeValue
 		}
 	}
 
-	private void assertAttributePresence(String attributeName, String aliasName, Object attributeValue) {
+	private void assertAttributePresence(String attributeName, List<String> aliases, Object attributeValue) {
 		if (attributeValue == null) {
 			throw new IllegalArgumentException(String.format(
-					"Neither attribute '%s' nor its alias '%s' was found in attributes for annotation [%s]",
-					attributeName, aliasName, this.displayName));
+					"Neither attribute '%s' nor one of its aliases %s was found in attributes for annotation [%s]",
+					attributeName, aliases, this.displayName));
 		}
 	}