Merge from sbrannen/SPR-13345

* SPR-13345:
  Support implicit attribute aliases with @AliasFor

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));
 		}
 	}