Introduce 'value' alias for 'attribute' in @AliasFor

SPR-11512 introduced support for annotation attribute aliases via
@AliasFor, requiring the explicit declaration of the 'attribute'
attribute. However, for aliases within an annotation, this explicit
declaration is unnecessary.

This commit improves the readability of alias pairs declared within an
annotation by introducing a 'value' attribute in @AliasFor that is an
alias for the existing 'attribute' attribute. This allows annotations
such as @ContextConfiguration from the spring-test module to declare
aliases as follows.

public @interface ContextConfiguration {

     @AliasFor("locations")
     String[] value() default {};

     @AliasFor("value")
     String[] locations() default {};

    // ...
}

Issue: SPR-13289

Author: sbrannen

spring-context/src/main/java/org/springframework/cache/annotation/CacheEvict.java

@@ -44,7 +44,7 @@
 	/**
 	 * Alias for {@link #cacheNames}.
 	 */
-	@AliasFor(attribute = "cacheNames")
+	@AliasFor("cacheNames")
 	String[] value() default {};
 
 	/**
@@ -55,7 +55,7 @@
 	 * @see #value
 	 * @see CacheConfig#cacheNames
 	 */
-	@AliasFor(attribute = "value")
+	@AliasFor("value")
 	String[] cacheNames() default {};
 
 	/**

spring-context/src/main/java/org/springframework/cache/annotation/CachePut.java

@@ -50,7 +50,7 @@
 	/**
 	 * Alias for {@link #cacheNames}.
 	 */
-	@AliasFor(attribute = "cacheNames")
+	@AliasFor("cacheNames")
 	String[] value() default {};
 
 	/**
@@ -61,7 +61,7 @@
 	 * @see #value
 	 * @see CacheConfig#cacheNames
 	 */
-	@AliasFor(attribute = "value")
+	@AliasFor("value")
 	String[] cacheNames() default {};
 
 	/**

spring-context/src/main/java/org/springframework/cache/annotation/Cacheable.java

@@ -55,7 +55,7 @@
 	/**
 	 * Alias for {@link #cacheNames}.
 	 */
-	@AliasFor(attribute = "cacheNames")
+	@AliasFor("cacheNames")
 	String[] value() default {};
 
 	/**
@@ -66,7 +66,7 @@
 	 * @see #value
 	 * @see CacheConfig#cacheNames
 	 */
-	@AliasFor(attribute = "value")
+	@AliasFor("value")
 	String[] cacheNames() default {};
 
 	/**

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

@@ -62,7 +62,7 @@
 	 * are needed — for example, {@code @ComponentScan("org.my.pkg")}
 	 * instead of {@code @ComponentScan(basePackages = "org.my.pkg")}.
 	 */
-	@AliasFor(attribute = "basePackages")
+	@AliasFor("basePackages")
 	String[] value() default {};
 
 	/**
@@ -72,7 +72,7 @@
 	 * <p>Use {@link #basePackageClasses} for a type-safe alternative to
 	 * String-based package names.
 	 */
-	@AliasFor(attribute = "value")
+	@AliasFor("value")
 	String[] basePackages() default {};
 
 	/**
@@ -166,7 +166,7 @@
 		 * Alias for {@link #classes}.
 		 * @see #classes
 		 */
-		@AliasFor(attribute = "classes")
+		@AliasFor("classes")
 		Class<?>[] value() default {};
 
 		/**
@@ -190,7 +190,7 @@
 		 * @see #value
 		 * @see #type
 		 */
-		@AliasFor(attribute = "value")
+		@AliasFor("value")
 		Class<?>[] classes() default {};
 
 		/**

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

@@ -59,7 +59,7 @@
 	 * @see #locations
 	 * @see #reader
 	 */
-	@AliasFor(attribute = "locations")
+	@AliasFor("locations")
 	String[] value() default {};
 
 	/**
@@ -72,7 +72,7 @@
 	 * @see #value
 	 * @see #reader
 	 */
-	@AliasFor(attribute = "value")
+	@AliasFor("value")
 	String[] locations() default {};
 
 	/**

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

@@ -61,7 +61,7 @@
 	 * Alias for {@link #scopeName}.
 	 * @see #scopeName
 	 */
-	@AliasFor(attribute = "scopeName")
+	@AliasFor("scopeName")
 	String value() default "";
 
 	/**
@@ -75,7 +75,7 @@
 	 * @see org.springframework.web.context.WebApplicationContext#SCOPE_SESSION
 	 * @see #value
 	 */
-	@AliasFor(attribute = "value")
+	@AliasFor("value")
 	String scopeName() default "";
 
 	/**

spring-context/src/main/java/org/springframework/context/event/EventListener.java

@@ -69,7 +69,7 @@
 	/**
 	 * Alias for {@link #classes}.
 	 */
-	@AliasFor(attribute = "classes")
+	@AliasFor("classes")
 	Class<?>[] value() default {};
 
 	/**
@@ -79,7 +79,7 @@
 	 * attribute is specified with multiple values, the annotated method
 	 * must <em>not</em> declare any parameters.
 	 */
-	@AliasFor(attribute = "value")
+	@AliasFor("value")
 	Class<?>[] classes() default {};
 
 	/**

spring-context/src/main/java/org/springframework/jmx/export/annotation/ManagedResource.java

@@ -49,10 +49,10 @@
 	/**
 	 * Alias for the {@link #objectName} attribute, for simple default usage.
 	 */
-	@AliasFor(attribute = "objectName")
+	@AliasFor("objectName")
 	String value() default "";
 
-	@AliasFor(attribute = "value")
+	@AliasFor("value")
 	String objectName() default "";
 
 	String description() default "";

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

@@ -119,10 +119,22 @@
 @Documented
 public @interface AliasFor {
 
+	/**
+	 * Alias for {@link #attribute}.
+	 * <p>Intended to be used instead of {@link #attribute} when {@link #annotation}
+	 * is not declared &mdash; for example: {@code @AliasFor("value")} instead of
+	 * {@code @AliasFor(attribute = "value")}.
+	 */
+	@AliasFor("attribute")
+	String value() default "";
+
 	/**
 	 * The name of the attribute that <em>this</em> attribute is an alias for.
+	 * @see #value
 	 */
-	String attribute();
+	@AliasFor("value")
+	String attribute() default "";
+
 
 	/**
 	 * The type of annotation in which the aliased {@link #attribute} is declared.

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

@@ -1427,7 +1427,7 @@ else if (Annotation.class.isAssignableFrom(returnType)) {
 	 * @see #getAliasedAttributeName(Method, Class)
 	 */
 	static String getAliasedAttributeName(Method attribute) {
-		return getAliasedAttributeName(attribute, null);
+		return getAliasedAttributeName(attribute, (Class<? extends Annotation>) null);
 	}
 
 	/**
@@ -1471,7 +1471,7 @@ static String getAliasedAttributeName(Method attribute, Class<? extends Annotati
 		}
 
 		String attributeName = attribute.getName();
-		String aliasedAttributeName = aliasFor.attribute();
+		String aliasedAttributeName = getAliasedAttributeName(aliasFor, attribute);
 
 		if (!StringUtils.hasText(aliasedAttributeName)) {
 			String msg = String.format(
@@ -1503,7 +1503,7 @@ static String getAliasedAttributeName(Method attribute, Class<? extends Annotati
 				throw new AnnotationConfigurationException(msg);
 			}
 
-			String mirrorAliasedAttributeName = mirrorAliasFor.attribute();
+			String mirrorAliasedAttributeName = getAliasedAttributeName(mirrorAliasFor, aliasedAttribute);
 			if (!attributeName.equals(mirrorAliasedAttributeName)) {
 				String msg = String.format(
 						"Attribute [%s] in annotation [%s] must be declared as an @AliasFor [%s], not [%s].",
@@ -1543,6 +1543,38 @@ static String getAliasedAttributeName(Method attribute, Class<? extends Annotati
 		return aliasedAttributeName;
 	}
 
+	/**
+	 * Get the name of the aliased attribute configured via the supplied
+	 * {@link AliasFor @AliasFor} annotation on the supplied {@code attribute}.
+	 * <p>This method returns the value of either the {@code attribute}
+	 * or {@code value} attribute of {@code @AliasFor}, ensuring that only
+	 * one of the attributes has been declared.
+	 * @param aliasFor the {@code @AliasFor} annotation from which to retrieve
+	 * the aliased attribute name
+	 * @param attribute the attribute that is annotated with {@code @AliasFor},
+	 * used solely for building an exception message
+	 * @return the name of the aliased attribute, potentially an empty string
+	 * @throws AnnotationConfigurationException if invalid configuration of
+	 * {@code @AliasFor} is detected
+	 * @since 4.2
+	 * @see #getAliasedAttributeName(Method, Class)
+	 */
+	private static String getAliasedAttributeName(AliasFor aliasFor, Method attribute) {
+		String attributeName = aliasFor.attribute();
+		String value = aliasFor.value();
+		boolean attributeDeclared = StringUtils.hasText(attributeName);
+		boolean valueDeclared = StringUtils.hasText(value);
+
+		if (attributeDeclared && valueDeclared) {
+			throw new AnnotationConfigurationException(String.format(
+				"In @AliasFor declared on attribute [%s] in annotation [%s], attribute 'attribute' and its alias 'value' "
+				+ "are present with values of [%s] and [%s], but only one is permitted.",
+				attribute.getName(), attribute.getDeclaringClass().getName(), attributeName, value));
+		}
+
+		return (attributeDeclared ? attributeName : value);
+	}
+
 	/**
 	 * Get all methods declared in the supplied {@code annotationType} that
 	 * match Java's requirements for annotation <em>attributes</em>.

spring-core/src/test/java/org/springframework/core/annotation/AnnotationUtilsTests.java

@@ -714,10 +714,30 @@ public void synthesizeAlreadySynthesizedAnnotation() throws Exception {
 		assertEquals("actual value attribute: ", "/test", synthesizedAgainWebMapping.value());
 	}
 
+	@Test
+	public void synthesizeAnnotationWhereAliasForIsMissingAttributeDeclaration() throws Exception {
+		AliasForWithMissingAttributeDeclaration annotation = AliasForWithMissingAttributeDeclarationClass.class.getAnnotation(AliasForWithMissingAttributeDeclaration.class);
+		exception.expect(AnnotationConfigurationException.class);
+		exception.expectMessage(containsString("@AliasFor declaration on attribute [foo] in annotation"));
+		exception.expectMessage(containsString(AliasForWithMissingAttributeDeclaration.class.getName()));
+		exception.expectMessage(containsString("is missing required 'attribute' value"));
+		synthesizeAnnotation(annotation);
+	}
+
+	@Test
+	public void synthesizeAnnotationWhereAliasForHasDuplicateAttributeDeclaration() throws Exception {
+		AliasForWithDuplicateAttributeDeclaration annotation = AliasForWithDuplicateAttributeDeclarationClass.class.getAnnotation(AliasForWithDuplicateAttributeDeclaration.class);
+		exception.expect(AnnotationConfigurationException.class);
+		exception.expectMessage(containsString("In @AliasFor declared on attribute [foo] in annotation"));
+		exception.expectMessage(containsString(AliasForWithDuplicateAttributeDeclaration.class.getName()));
+		exception.expectMessage(containsString("attribute 'attribute' and its alias 'value' are present with values of [baz] and [bar]"));
+		exception.expectMessage(containsString("but only one is permitted"));
+		synthesizeAnnotation(annotation);
+	}
+
 	@Test
 	public void synthesizeAnnotationWithAttributeAliasForNonexistentAttribute() throws Exception {
-		AliasForNonexistentAttribute annotation =
-				AliasForNonexistentAttributeClass.class.getAnnotation(AliasForNonexistentAttribute.class);
+		AliasForNonexistentAttribute annotation = AliasForNonexistentAttributeClass.class.getAnnotation(AliasForNonexistentAttribute.class);
 		exception.expect(AnnotationConfigurationException.class);
 		exception.expectMessage(containsString("Attribute [foo] in"));
 		exception.expectMessage(containsString(AliasForNonexistentAttribute.class.getName()));
@@ -1434,7 +1454,7 @@ enum RequestMethod {
 
 		String name();
 
-		@AliasFor(attribute = "path")
+		@AliasFor("path")
 		String value() default "";
 
 		@AliasFor(attribute = "value")
@@ -1472,21 +1492,21 @@ public void handleMappedWithDifferentPathAndValueAttributes() {
 	@Retention(RetentionPolicy.RUNTIME)
 	@interface ContextConfig {
 
-		@AliasFor(attribute = "locations")
+		@AliasFor("locations")
 		String value() default "";
 
-		@AliasFor(attribute = "value")
+		@AliasFor("value")
 		String locations() default "";
 	}
 
 	@Retention(RetentionPolicy.RUNTIME)
 	@interface BrokenContextConfig {
 
 		// Intentionally missing:
-		// @AliasFor(attribute = "locations")
+		// @AliasFor("locations")
 		String value() default "";
 
-		@AliasFor(attribute = "value")
+		@AliasFor("value")
 		String locations() default "";
 	}
 
@@ -1530,10 +1550,32 @@ static class GroupOfCharsClass {
 	}
 
 
+	@Retention(RetentionPolicy.RUNTIME)
+	@interface AliasForWithMissingAttributeDeclaration {
+
+		@AliasFor
+		String foo() default "";
+	}
+
+	@AliasForWithMissingAttributeDeclaration
+	static class AliasForWithMissingAttributeDeclarationClass {
+	}
+
+	@Retention(RetentionPolicy.RUNTIME)
+	@interface AliasForWithDuplicateAttributeDeclaration {
+
+		@AliasFor(value = "bar", attribute = "baz")
+		String foo() default "";
+	}
+
+	@AliasForWithDuplicateAttributeDeclaration
+	static class AliasForWithDuplicateAttributeDeclarationClass {
+	}
+
 	@Retention(RetentionPolicy.RUNTIME)
 	@interface AliasForNonexistentAttribute {
 
-		@AliasFor(attribute = "bar")
+		@AliasFor("bar")
 		String foo() default "";
 	}
 
@@ -1544,7 +1586,7 @@ static class AliasForNonexistentAttributeClass {
 	@Retention(RetentionPolicy.RUNTIME)
 	@interface AliasForWithoutMirroredAliasFor {
 
-		@AliasFor(attribute = "bar")
+		@AliasFor("bar")
 		String foo() default "";
 
 		String bar() default "";
@@ -1571,10 +1613,10 @@ static class AliasForWithMirroredAliasForWrongAttributeClass {
 	@Retention(RetentionPolicy.RUNTIME)
 	@interface AliasForAttributeOfDifferentType {
 
-		@AliasFor(attribute = "bar")
+		@AliasFor("bar")
 		String[] foo() default "";
 
-		@AliasFor(attribute = "foo")
+		@AliasFor("foo")
 		boolean bar() default true;
 	}
 
@@ -1599,10 +1641,10 @@ static class AliasForWithMissingDefaultValuesClass {
 	@Retention(RetentionPolicy.RUNTIME)
 	@interface AliasForAttributeWithDifferentDefaultValue {
 
-		@AliasFor(attribute = "bar")
+		@AliasFor("bar")
 		String foo() default "X";
 
-		@AliasFor(attribute = "foo")
+		@AliasFor("foo")
 		String bar() default "Z";
 	}
 

spring-core/src/test/java/org/springframework/core/annotation/subpackage/NonPublicAliasedAnnotation.java

@@ -32,9 +32,9 @@
 
 	String name();
 
-	@AliasFor(attribute = "path")
+	@AliasFor("path")
 	String value() default "";
 
-	@AliasFor(attribute = "value")
+	@AliasFor("value")
 	String path() default "";
 }