org.springframework.core.annotation

Class AnnotatedElementUtils

java.lang.Object

org.springframework.core.annotation.AnnotatedElementUtils

public class AnnotatedElementUtils
extends Object

General utility methods for finding annotations and meta-annotations on AnnotatedElements.

AnnotatedElementUtils defines the public API for Spring's meta-annotation programming model with support for annotation attribute overrides. If you do not need support for annotation attribute overrides, consider using AnnotationUtils instead.

Note that the features of this class are not provided by the JDK's introspection facilities themselves.

Annotation Attribute Overrides

Support for meta-annotations with attribute overrides in composed annotations is provided by all variants of the getMergedAnnotationAttributes(), getMergedAnnotation(), findMergedAnnotationAttributes(), and findMergedAnnotation() methods.

Find vs. Get Semantics

The search algorithms used by methods in this class follow either find or get semantics. Consult the Javadoc for each individual method for details on which search algorithm is used.

Get semantics are limited to searching for annotations that are either present on an AnnotatedElement (i.e., declared locally or inherited) or declared within the annotation hierarchy above the AnnotatedElement.

Find semantics are much more exhaustive, providing get semantics plus support for the following:

• Searching on interfaces, if the annotated element is a class
• Searching on superclasses, if the annotated element is a class
• Resolving bridged methods, if the annotated element is a method
• Searching on methods in interfaces, if the annotated element is a method
• Searching on methods in superclasses, if the annotated element is a method

Support for @Inherited

Methods following get semantics will honor the contract of Java's @Inherited annotation except that locally declared annotations (including custom composed annotations) will be favored over inherited annotations. In contrast, methods following find semantics will completely ignore the presence of @Inherited since the find search algorithm manually traverses type and method hierarchies and thereby implicitly supports annotation inheritance without the need for @Inherited.

Since:

4.0

Author:

Phillip Webb, Juergen Hoeller, Sam Brannen

See Also:

AliasFor, AnnotationAttributes, AnnotationUtils, BridgeMethodResolver

Constructor Summary

Constructors

Constructor and Description
AnnotatedElementUtils()

Method Summary

Modifier and Type	Method and Description
static <A extends Annotation> A	findMergedAnnotation(AnnotatedElement element, Class<A> annotationType) Find the first annotation of the specified annotationType within the annotation hierarchy above the supplied element, merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy, and synthesize the result back into an annotation of the specified annotationType.
static <A extends Annotation> A	findMergedAnnotation(AnnotatedElement element, String annotationName) Find the first annotation of the specified annotationName within the annotation hierarchy above the supplied element, merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy, and synthesize the result back into an annotation of the specified annotationName.
static AnnotationAttributes	findMergedAnnotationAttributes(AnnotatedElement element, String annotationName, boolean classValuesAsString, boolean nestedAnnotationsAsMap) Find the first annotation of the specified annotationName within the annotation hierarchy above the supplied element and merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy.
static MultiValueMap<String,Object>	getAllAnnotationAttributes(AnnotatedElement element, String annotationName) Get the annotation attributes of all annotations of the specified annotationName in the annotation hierarchy above the supplied AnnotatedElement and store the results in a MultiValueMap.
static MultiValueMap<String,Object>	getAllAnnotationAttributes(AnnotatedElement element, String annotationName, boolean classValuesAsString, boolean nestedAnnotationsAsMap) Get the annotation attributes of all annotations of the specified annotationName in the annotation hierarchy above the supplied AnnotatedElement and store the results in a MultiValueMap.
static AnnotationAttributes	getAnnotationAttributes(AnnotatedElement element, String annotationName) Deprecated. As of Spring Framework 4.2, use getMergedAnnotationAttributes(AnnotatedElement, String) instead.
static AnnotationAttributes	getAnnotationAttributes(AnnotatedElement element, String annotationName, boolean classValuesAsString, boolean nestedAnnotationsAsMap) Deprecated. As of Spring Framework 4.2, use getMergedAnnotationAttributes(AnnotatedElement, String, boolean, boolean) instead.
static <A extends Annotation> A	getMergedAnnotation(AnnotatedElement element, Class<A> annotationType) Get the first annotation of the specified annotationType within the annotation hierarchy above the supplied element, merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy, and synthesize the result back into an annotation of the specified annotationType.
static AnnotationAttributes	getMergedAnnotationAttributes(AnnotatedElement element, Class<? extends Annotation> annotationType) Get the first annotation of the specified annotationType within the annotation hierarchy above the supplied element and merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy.
static AnnotationAttributes	getMergedAnnotationAttributes(AnnotatedElement element, String annotationName) Get the first annotation of the specified annotationName within the annotation hierarchy above the supplied element and merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy.
static AnnotationAttributes	getMergedAnnotationAttributes(AnnotatedElement element, String annotationName, boolean classValuesAsString, boolean nestedAnnotationsAsMap) Get the first annotation of the specified annotationName within the annotation hierarchy above the supplied element and merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy.
static Set<String>	getMetaAnnotationTypes(AnnotatedElement element, Class<? extends Annotation> annotationType) Get the fully qualified class names of all meta-annotation types present on the annotation (of the specified annotationType) on the supplied AnnotatedElement.
static Set<String>	getMetaAnnotationTypes(AnnotatedElement element, String annotationName) Get the fully qualified class names of all meta-annotation types present on the annotation (of the specified annotationName) on the supplied AnnotatedElement.
static boolean	hasMetaAnnotationTypes(AnnotatedElement element, String annotationName) Determine if the supplied AnnotatedElement is annotated with a composed annotation that is meta-annotated with an annotation of the specified annotationName.
static boolean	isAnnotated(AnnotatedElement element, String annotationName) Determine if an annotation of the specified annotationName is present on the supplied AnnotatedElement or within the annotation hierarchy above the specified element.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AnnotatedElementUtils

public AnnotatedElementUtils()

Method Detail

getMetaAnnotationTypes

public static Set<String> getMetaAnnotationTypes(AnnotatedElement element,
                                                 Class<? extends Annotation> annotationType)

Get the fully qualified class names of all meta-annotation types present on the annotation (of the specified annotationType) on the supplied AnnotatedElement.

This method follows get semantics as described in the class-level Javadoc.

Parameters:

element - the annotated element; never null

annotationType - the annotation type on which to find meta-annotations; never null

Returns:

the names of all meta-annotations present on the annotation, or null if not found

Since:

4.2

See Also:

getMetaAnnotationTypes(AnnotatedElement, String), hasMetaAnnotationTypes(java.lang.reflect.AnnotatedElement, java.lang.String)

getMetaAnnotationTypes

public static Set<String> getMetaAnnotationTypes(AnnotatedElement element,
                                                 String annotationName)

Get the fully qualified class names of all meta-annotation types present on the annotation (of the specified annotationName) on the supplied AnnotatedElement.

This method follows get semantics as described in the class-level Javadoc.

Parameters:

element - the annotated element; never null

annotationName - the fully qualified class name of the annotation type on which to find meta-annotations; never null or empty

Returns:

the names of all meta-annotations present on the annotation, or null if not found

See Also:

getMetaAnnotationTypes(AnnotatedElement, Class), hasMetaAnnotationTypes(java.lang.reflect.AnnotatedElement, java.lang.String)

hasMetaAnnotationTypes

public static boolean hasMetaAnnotationTypes(AnnotatedElement element,
                                             String annotationName)

Determine if the supplied AnnotatedElement is annotated with a composed annotation that is meta-annotated with an annotation of the specified annotationName.

This method follows get semantics as described in the class-level Javadoc.

Parameters:

element - the annotated element; never null

annotationName - the fully qualified class name of the meta-annotation type to find; never null or empty

Returns:

true if a matching meta-annotation is present

See Also:

getMetaAnnotationTypes(java.lang.reflect.AnnotatedElement, java.lang.Class<? extends java.lang.annotation.Annotation>)

isAnnotated

public static boolean isAnnotated(AnnotatedElement element,
                                  String annotationName)

Determine if an annotation of the specified annotationName is present on the supplied AnnotatedElement or within the annotation hierarchy above the specified element.

If this method returns true, then getMergedAnnotationAttributes(java.lang.reflect.AnnotatedElement, java.lang.Class<? extends java.lang.annotation.Annotation>) will return a non-null value.

This method follows get semantics as described in the class-level Javadoc.

Parameters:

element - the annotated element; never null

annotationName - the fully qualified class name of the annotation type to find; never null or empty

Returns:

true if a matching annotation is present

getMergedAnnotation

public static <A extends Annotation> A getMergedAnnotation(AnnotatedElement element,
                                                           Class<A> annotationType)

Get the first annotation of the specified annotationType within the annotation hierarchy above the supplied element, merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy, and synthesize the result back into an annotation of the specified annotationType.

@AliasFor semantics are fully supported, both within a single annotation and within the annotation hierarchy.

This method delegates to getMergedAnnotationAttributes(AnnotatedElement, Class) and AnnotationUtils.synthesizeAnnotation(Map, Class, AnnotatedElement).

Parameters:

element - the annotated element; never null

annotationType - the annotation type to find; never null

Returns:

the merged, synthesized Annotation, or null if not found

Since:

4.2

See Also:

getMergedAnnotationAttributes(AnnotatedElement, Class), findMergedAnnotation(AnnotatedElement, Class), AnnotationUtils.synthesizeAnnotation(Map, Class, AnnotatedElement)

getMergedAnnotationAttributes

public static AnnotationAttributes getMergedAnnotationAttributes(AnnotatedElement element,
                                                                 Class<? extends Annotation> annotationType)

Get the first annotation of the specified annotationType within the annotation hierarchy above the supplied element and merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy.

@AliasFor semantics are fully supported, both within a single annotation and within the annotation hierarchy.

This method delegates to getMergedAnnotationAttributes(AnnotatedElement, String).

Parameters:

element - the annotated element; never null

annotationType - the annotation type to find; never null

Returns:

the merged AnnotationAttributes, or null if not found

Since:

4.2

See Also:

getMergedAnnotationAttributes(AnnotatedElement, String, boolean, boolean), findMergedAnnotationAttributes(AnnotatedElement, String, boolean, boolean), getMergedAnnotation(AnnotatedElement, Class), findMergedAnnotation(AnnotatedElement, Class)

getAnnotationAttributes

@Deprecated
public static AnnotationAttributes getAnnotationAttributes(AnnotatedElement element,
                                                                       String annotationName)

Deprecated. As of Spring Framework 4.2, use getMergedAnnotationAttributes(AnnotatedElement, String) instead.

getMergedAnnotationAttributes

public static AnnotationAttributes getMergedAnnotationAttributes(AnnotatedElement element,
                                                                 String annotationName)

Get the first annotation of the specified annotationName within the annotation hierarchy above the supplied element and merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy.

@AliasFor semantics are fully supported, both within a single annotation and within the annotation hierarchy.

This method delegates to getMergedAnnotationAttributes(AnnotatedElement, String, boolean, boolean), supplying false for classValuesAsString and nestedAnnotationsAsMap.

Parameters:

element - the annotated element; never null

annotationName - the fully qualified class name of the annotation type to find; never null or empty

Returns:

the merged AnnotationAttributes, or null if not found

Since:

4.2

See Also:

getMergedAnnotationAttributes(AnnotatedElement, String, boolean, boolean), findMergedAnnotationAttributes(AnnotatedElement, String, boolean, boolean), findMergedAnnotation(AnnotatedElement, Class), getAllAnnotationAttributes(AnnotatedElement, String)

getAnnotationAttributes

@Deprecated
public static AnnotationAttributes getAnnotationAttributes(AnnotatedElement element,
                                                                       String annotationName,
                                                                       boolean classValuesAsString,
                                                                       boolean nestedAnnotationsAsMap)

Deprecated. As of Spring Framework 4.2, use getMergedAnnotationAttributes(AnnotatedElement, String, boolean, boolean) instead.

getMergedAnnotationAttributes

public static AnnotationAttributes getMergedAnnotationAttributes(AnnotatedElement element,
                                                                 String annotationName,
                                                                 boolean classValuesAsString,
                                                                 boolean nestedAnnotationsAsMap)

Get the first annotation of the specified annotationName within the annotation hierarchy above the supplied element and merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy.

Attributes from lower levels in the annotation hierarchy override attributes of the same name from higher levels, and @AliasFor semantics are fully supported, both within a single annotation and within the annotation hierarchy.

In contrast to getAllAnnotationAttributes(java.lang.reflect.AnnotatedElement, java.lang.String), the search algorithm used by this method will stop searching the annotation hierarchy once the first annotation of the specified annotationName has been found. As a consequence, additional annotations of the specified annotationName will be ignored.

This method follows get semantics as described in the class-level Javadoc.

Parameters:

element - the annotated element; never null

annotationName - the fully qualified class name of the annotation type to find; never null or empty

classValuesAsString - whether to convert Class references into Strings or to preserve them as Class references

nestedAnnotationsAsMap - whether to convert nested Annotation instances into AnnotationAttributes maps or to preserve them as Annotation instances

Returns:

the merged AnnotationAttributes, or null if not found

Since:

4.2

See Also:

findMergedAnnotation(AnnotatedElement, Class), findMergedAnnotationAttributes(AnnotatedElement, String, boolean, boolean), getAllAnnotationAttributes(AnnotatedElement, String, boolean, boolean)

findMergedAnnotation

public static <A extends Annotation> A findMergedAnnotation(AnnotatedElement element,
                                                            Class<A> annotationType)

Find the first annotation of the specified annotationType within the annotation hierarchy above the supplied element, merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy, and synthesize the result back into an annotation of the specified annotationType.

@AliasFor semantics are fully supported, both within a single annotation and within the annotation hierarchy.

This method delegates to findMergedAnnotation(AnnotatedElement, String).

Parameters:

element - the annotated element; never null

annotationType - the annotation type to find; never null

Returns:

the merged, synthesized Annotation, or null if not found

Since:

4.2

See Also:

findMergedAnnotation(AnnotatedElement, String), findMergedAnnotationAttributes(AnnotatedElement, String, boolean, boolean), getMergedAnnotationAttributes(AnnotatedElement, Class)

findMergedAnnotation

public static <A extends Annotation> A findMergedAnnotation(AnnotatedElement element,
                                                            String annotationName)

Find the first annotation of the specified annotationName within the annotation hierarchy above the supplied element, merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy, and synthesize the result back into an annotation of the specified annotationName.

@AliasFor semantics are fully supported, both within a single annotation and within the annotation hierarchy.

This method delegates to findMergedAnnotationAttributes(AnnotatedElement, String, boolean, boolean) (supplying false for classValuesAsString and nestedAnnotationsAsMap) and AnnotationUtils.synthesizeAnnotation(Map, Class, AnnotatedElement).

Parameters:

element - the annotated element; never null

annotationName - the fully qualified class name of the annotation type to find; never null or empty

Returns:

the merged, synthesized Annotation, or null if not found

Since:

4.2

See Also:

findMergedAnnotation(AnnotatedElement, Class), findMergedAnnotationAttributes(AnnotatedElement, String, boolean, boolean), AnnotationUtils.synthesizeAnnotation(Map, Class, AnnotatedElement)

findMergedAnnotationAttributes

public static AnnotationAttributes findMergedAnnotationAttributes(AnnotatedElement element,
                                                                  String annotationName,
                                                                  boolean classValuesAsString,
                                                                  boolean nestedAnnotationsAsMap)

Find the first annotation of the specified annotationName within the annotation hierarchy above the supplied element and merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy.

Attributes from lower levels in the annotation hierarchy override attributes of the same name from higher levels, and @AliasFor semantics are fully supported, both within a single annotation and within the annotation hierarchy.

In contrast to getAllAnnotationAttributes(java.lang.reflect.AnnotatedElement, java.lang.String), the search algorithm used by this method will stop searching the annotation hierarchy once the first annotation of the specified annotationName has been found. As a consequence, additional annotations of the specified annotationName will be ignored.

This method follows find semantics as described in the class-level Javadoc.

Parameters:

element - the annotated element; never null

annotationName - the fully qualified class name of the annotation type to find; never null or empty

classValuesAsString - whether to convert Class references into Strings or to preserve them as Class references

nestedAnnotationsAsMap - whether to convert nested Annotation instances into AnnotationAttributes maps or to preserve them as Annotation instances

Returns:

the merged AnnotationAttributes, or null if not found

Since:

4.2

See Also:

findMergedAnnotation(AnnotatedElement, Class), getMergedAnnotationAttributes(AnnotatedElement, String, boolean, boolean)

getAllAnnotationAttributes

public static MultiValueMap<String,Object> getAllAnnotationAttributes(AnnotatedElement element,
                                                                      String annotationName)

Get the annotation attributes of all annotations of the specified annotationName in the annotation hierarchy above the supplied AnnotatedElement and store the results in a MultiValueMap.

Note: in contrast to getMergedAnnotationAttributes(AnnotatedElement, String), this method does not support attribute overrides.

This method follows get semantics as described in the class-level Javadoc.

Parameters:

element - the annotated element; never null

annotationName - the fully qualified class name of the annotation type to find; never null or empty

Returns:

a MultiValueMap keyed by attribute name, containing the annotation attributes from all annotations found, or null if not found

See Also:

getAllAnnotationAttributes(AnnotatedElement, String, boolean, boolean)

getAllAnnotationAttributes

public static MultiValueMap<String,Object> getAllAnnotationAttributes(AnnotatedElement element,
                                                                      String annotationName,
                                                                      boolean classValuesAsString,
                                                                      boolean nestedAnnotationsAsMap)

Get the annotation attributes of all annotations of the specified annotationName in the annotation hierarchy above the supplied AnnotatedElement and store the results in a MultiValueMap.

Note: in contrast to getMergedAnnotationAttributes(AnnotatedElement, String), this method does not support attribute overrides.

This method follows get semantics as described in the class-level Javadoc.

Parameters:

element - the annotated element; never null

annotationName - the fully qualified class name of the annotation type to find; never null or empty

classValuesAsString - whether to convert Class references into Strings or to preserve them as Class references

nestedAnnotationsAsMap - whether to convert nested Annotation instances into AnnotationAttributes maps or to preserve them as Annotation instances

Returns:

a MultiValueMap keyed by attribute name, containing the annotation attributes from all annotations found, or null if not found