diff --git a/spring-core/src/main/java/org/springframework/core/annotation/AliasFor.java b/spring-core/src/main/java/org/springframework/core/annotation/AliasFor.java index c116695245..afde3cded2 100644 --- a/spring-core/src/main/java/org/springframework/core/annotation/AliasFor.java +++ b/spring-core/src/main/java/org/springframework/core/annotation/AliasFor.java @@ -41,10 +41,11 @@ import java.lang.annotation.Target; * hierarchy. In fact, with {@code @AliasFor} it is even possible to declare * an alias for the {@code value} attribute of a meta-annotation. *
  • Implicit aliases within an annotation: 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 implicit - * aliases for each other, analogous to explicit aliases within an annotation.
  • + * more attributes within an annotation are declared as attribute overrides + * for the same meta-annotation attribute (either directly or transitively), + * those attributes will be treated as a set of implicit aliases + * for each other, resulting in behavior analogous to that for explicit + * aliases within an annotation. * * *

    Usage Requirements

    @@ -86,13 +87,15 @@ import java.lang.annotation.Target; * *
  • Implicit aliases within an annotation: *
      - *
    1. Each attribute that belongs to the set of implicit aliases must be + *
    2. Each attribute that belongs to a set of implicit aliases must be * annotated with {@code @AliasFor}, and {@link #attribute} must reference - * the same attribute in the same meta-annotation.
    3. + * the same attribute in the same meta-annotation (either directly or + * transitively via other explicit meta-annotation attribute overrides + * within the annotation hierarchy). *
    4. Aliased attributes must declare the same return type.
    5. *
    6. Aliased attributes must declare a default value.
    7. *
    8. Aliased attributes must declare the same default value.
    9. - *
    10. {@link #annotation} must reference the meta-annotation.
    11. + *
    12. {@link #annotation} must reference an appropriate meta-annotation.
    13. *
    14. The referenced meta-annotation must be meta-present on the * annotation class that declares {@code @AliasFor}.
    15. *
    @@ -100,6 +103,9 @@ import java.lang.annotation.Target; * * *

    Example: Explicit Aliases within an Annotation

    + *

    In {@code @ContextConfiguration}, {@code value} and {@code locations} + * are explicit aliases for each other. + * *

     public @interface ContextConfiguration {
      *
      *    @AliasFor("locations")
    @@ -112,14 +118,24 @@ import java.lang.annotation.Target;
      * }
    * *

    Example: Explicit Alias for Attribute in Meta-annotation

    + *

    In {@code @XmlTestConfig}, {@code xmlFiles} is an explicit alias for + * {@code locations} in {@code @ContextConfiguration}. In other words, + * {@code xmlFiles} overrides the {@code locations} attribute in + * {@code @ContextConfiguration}. + * *

     @ContextConfiguration
    - * public @interface MyTestConfig {
    + * public @interface XmlTestConfig {
      *
      *    @AliasFor(annotation = ContextConfiguration.class, attribute = "locations")
      *    String[] xmlFiles();
      * }
    * *

    Example: Implicit Aliases within an Annotation

    + *

    In {@code @MyTestConfig}, {@code value}, {@code groovyScripts}, and + * {@code xmlFiles} are all explicit meta-annotation attribute overrides for + * the {@code locations} attribute in {@code @ContextConfiguration}. These + * three attributes are therefore also implicit aliases for each other. + * *

     @ContextConfiguration
      * public @interface MyTestConfig {
      *
    @@ -133,6 +149,25 @@ import java.lang.annotation.Target;
      *    String[] xmlFiles() default {};
      * }
    * + *

    Example: Transitive Implicit Aliases within an Annotation

    + *

    In {@code @GroovyOrXmlTestConfig}, {@code groovy} is an explicit + * override for the {@code groovyScripts} attribute in {@code @MyTestConfig}; + * whereas, {@code xml} is an explicit override for the {@code locations} + * attribute in {@code @ContextConfiguration}. Furthermore, {@code groovy} + * and {@code xml} are transitive implicit aliases for each other, since they + * both effectively override the {@code locations} attribute in + * {@code @ContextConfiguration}. + * + *

     @MyTestConfig
    + * public @interface GroovyOrXmlTestConfig {
    + *
    + *    @AliasFor(annotation = MyTestConfig.class, attribute = "groovyScripts")
    + *    String[] groovy() default {};
    + *
    + *    @AliasFor(annotation = ContextConfiguration.class, attribute = "locations")
    + *    String[] xml() default {};
    + * }
    + * *

    Spring Annotations Supporting Attribute Aliases

    *

    As of Spring Framework 4.2, several annotations within core Spring * have been updated to use {@code @AliasFor} to configure their internal