@Retention(value=RUNTIME)
@Target(value=METHOD)
@Documented
public @interface AliasFor
@AliasFor
is an annotation that is used to declare aliases for
annotation attributes.
@AliasFor
can be declared on a pair of attributes to
signal that they are interchangeable aliases for each other.annotation()
attribute of @AliasFor
is set to a different
annotation than the one that declares it, the 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 @AliasFor
it is even possible to declare
an alias for the value
attribute of a meta-annotation.Like with any annotation in Java, the mere presence of @AliasFor
on its own will not enforce alias semantics. For alias semantics to be
enforced, annotations must be loaded via the utility methods in
AnnotationUtils
. Behind the scenes, Spring will synthesize
an annotation by wrapping it in a dynamic proxy that transparently enforces
attribute alias semantics for annotation attributes that are
annotated with @AliasFor
. Similarly, AnnotatedElementUtils
supports explicit meta-annotation attribute overrides when @AliasFor
is used within an annotation hierarchy. Typically you will not need to
manually synthesize annotations on your own since Spring will do that for
you transparently when looking up annotations on Spring-managed components.
@AliasFor
, and either attribute()
or value()
must
reference the other attribute in the pair.annotation()
should not be declared.@AliasFor
, and attribute()
must
reference the attribute in the meta-annotation.annotation()
must reference the meta-annotation.@AliasFor
.@AliasFor
, and attribute()
must reference
the same attribute in the same meta-annotation (either directly or
transitively via other explicit meta-annotation attribute overrides
within the annotation hierarchy).annotation()
must reference an appropriate meta-annotation.@AliasFor
.In @ContextConfiguration
, value
and locations
are explicit aliases for each other.
public @interface ContextConfiguration { @AliasFor("locations") String[] value() default {}; @AliasFor("value") String[] locations() default {}; // ... }
In @XmlTestConfig
, xmlFiles
is an explicit alias for
locations
in @ContextConfiguration
. In other words,
xmlFiles
overrides the locations
attribute in
@ContextConfiguration
.
@ContextConfiguration public @interface XmlTestConfig { @AliasFor(annotation = ContextConfiguration.class, attribute = "locations") String[] xmlFiles(); }
In @MyTestConfig
, value
, groovyScripts
, and
xmlFiles
are all explicit meta-annotation attribute overrides for
the locations
attribute in @ContextConfiguration
. These
three attributes are therefore also implicit aliases for each other.
@ContextConfiguration public @interface MyTestConfig { @AliasFor(annotation = ContextConfiguration.class, attribute = "locations") String[] value() default {}; @AliasFor(annotation = ContextConfiguration.class, attribute = "locations") String[] groovyScripts() default {}; @AliasFor(annotation = ContextConfiguration.class, attribute = "locations") String[] xmlFiles() default {}; }
In @GroovyOrXmlTestConfig
, groovy
is an explicit
override for the groovyScripts
attribute in @MyTestConfig
;
whereas, xml
is an explicit override for the locations
attribute in @ContextConfiguration
. Furthermore, groovy
and xml
are transitive implicit aliases for each other, since they
both effectively override the locations
attribute in
@ContextConfiguration
.
@MyTestConfig public @interface GroovyOrXmlTestConfig { @AliasFor(annotation = MyTestConfig.class, attribute = "groovyScripts") String[] groovy() default {}; @AliasFor(annotation = ContextConfiguration.class, attribute = "locations") String[] xml() default {}; }
As of Spring Framework 4.2, several annotations within core Spring
have been updated to use @AliasFor
to configure their internal
attribute aliases. Consult the Javadoc for individual annotations as well
as the reference manual for details.
AnnotatedElementUtils
,
AnnotationUtils
,
AnnotationUtils.synthesizeAnnotation(Annotation, java.lang.reflect.AnnotatedElement)
,
SynthesizedAnnotation
Modifier and Type | Optional Element and Description |
---|---|
java.lang.Class<? extends java.lang.annotation.Annotation> |
annotation
The type of annotation in which the aliased
attribute() is declared. |
java.lang.String |
attribute
The name of the attribute that this attribute is an alias for.
|
java.lang.String |
value
Alias for
attribute() . |
@AliasFor(value="attribute") public abstract java.lang.String value
attribute()
.
Intended to be used instead of attribute()
when annotation()
is not declared — for example: @AliasFor("value")
instead of
@AliasFor(attribute = "value")
.
public abstract java.lang.Class<? extends java.lang.annotation.Annotation> annotation
attribute()
is declared.
Defaults to Annotation
, implying that the aliased attribute is
declared in the same annotation as this attribute.