spring-framework / org.springframework.core.annotation / AnnotatedElementUtils

AnnotatedElementUtils

open class AnnotatedElementUtils

General utility methods for finding annotations, meta-annotations, and repeatable annotations on AnnotatedElement.

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(), getAllMergedAnnotations(), getMergedRepeatableAnnotations(), findMergedAnnotationAttributes(), findMergedAnnotation(), findAllMergedAnnotations(), and findMergedRepeatableAnnotations() methods.

Find vs. Get Semantics

The search algorithms used by methods in this class follow either find or get semantics. Consult the javadocs 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 java.lang.annotation.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 java.lang.annotation.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.

Author
Phillip Webb

Author
Juergen Hoeller

Author
Sam Brannen

Since
4.0

See Also
AliasForAnnotationAttributesAnnotationUtilsBridgeMethodResolver

Constructors

AnnotatedElementUtils()

General utility methods for finding annotations, meta-annotations, and repeatable annotations on AnnotatedElement.

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(), getAllMergedAnnotations(), getMergedRepeatableAnnotations(), findMergedAnnotationAttributes(), findMergedAnnotation(), findAllMergedAnnotations(), and findMergedRepeatableAnnotations() methods.

Find vs. Get Semantics

The search algorithms used by methods in this class follow either find or get semantics. Consult the javadocs 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 java.lang.annotation.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 java.lang.annotation.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.

Functions

findAllMergedAnnotations	`open static fun <A : Annotation> findAllMergedAnnotations(element: AnnotatedElement, annotationType: Class<A>): MutableSet<A>` Find all annotations of the specified `annotationType` within the annotation hierarchy above the supplied `element`; and for each annotation found, merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy and synthesize the results back into an annotation of the specified `annotationType`. AliasFor semantics are fully supported, both within a single annotation and within annotation hierarchies. This method follows find semantics as described in the AnnotatedElementUtils.
findMergedAnnotation	`open static fun <A : Annotation> findMergedAnnotation(element: AnnotatedElement, annotationType: Class<A>): A` 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 follows find semantics as described in the AnnotatedElementUtils.
findMergedAnnotationAttributes	`open static fun findMergedAnnotationAttributes(element: AnnotatedElement, annotationType: Class<out Annotation>, classValuesAsString: Boolean, nestedAnnotationsAsMap: Boolean): AnnotationAttributes` Find 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. 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`, the search algorithm used by this method will stop searching the annotation hierarchy once the first annotation of the specified `annotationType` has been found. As a consequence, additional annotations of the specified `annotationType` will be ignored. This method follows find semantics as described in the AnnotatedElementUtils. `open static fun findMergedAnnotationAttributes(element: AnnotatedElement, annotationName: String, classValuesAsString: Boolean, nestedAnnotationsAsMap: Boolean): AnnotationAttributes` 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`, 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 AnnotatedElementUtils.
findMergedRepeatableAnnotations	`open static fun <A : Annotation> findMergedRepeatableAnnotations(element: AnnotatedElement, annotationType: Class<A>): MutableSet<A>` Find all repeatable annotations of the specified `annotationType` within the annotation hierarchy above the supplied `element`; and for each annotation found, merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy and synthesize the results back into an annotation of the specified `annotationType`. The container type that holds the repeatable annotations will be looked up via java.lang.annotation.Repeatable. AliasFor semantics are fully supported, both within a single annotation and within annotation hierarchies. This method follows find semantics as described in the AnnotatedElementUtils. `open static fun <A : Annotation> findMergedRepeatableAnnotations(element: AnnotatedElement, annotationType: Class<A>, containerType: Class<out Annotation>): MutableSet<A>` Find all repeatable annotations of the specified `annotationType` within the annotation hierarchy above the supplied `element`; and for each annotation found, merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy and synthesize the results back into an annotation of the specified `annotationType`. AliasFor semantics are fully supported, both within a single annotation and within annotation hierarchies. This method follows find semantics as described in the AnnotatedElementUtils.
forAnnotations	`open static fun forAnnotations(vararg annotations: Annotation): AnnotatedElement` Build an adapted AnnotatedElement for the given annotations, typically for use with other methods on AnnotatedElementUtils.
getAllAnnotationAttributes	`open static fun getAllAnnotationAttributes(element: AnnotatedElement, annotationName: String): MultiValueMap<String, Any>` `open static fun getAllAnnotationAttributes(element: AnnotatedElement, annotationName: String, classValuesAsString: Boolean, nestedAnnotationsAsMap: Boolean): MultiValueMap<String, Any>` 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 AnnotatedElementUtils.
getAllMergedAnnotations	`open static fun <A : Annotation> getAllMergedAnnotations(element: AnnotatedElement, annotationType: Class<A>): MutableSet<A>` Get all annotations of the specified `annotationType` within the annotation hierarchy above the supplied `element`; and for each annotation found, merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy and synthesize the results back into an annotation of the specified `annotationType`. AliasFor semantics are fully supported, both within a single annotation and within annotation hierarchies. This method follows get semantics as described in the AnnotatedElementUtils.
getMergedAnnotation	`open static fun <A : Annotation> getMergedAnnotation(element: AnnotatedElement, annotationType: Class<A>): A` 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)`.
getMergedAnnotationAttributes	`open static fun getMergedAnnotationAttributes(element: AnnotatedElement, annotationType: Class<out Annotation>): AnnotationAttributes` 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)`. `open static fun getMergedAnnotationAttributes(element: AnnotatedElement, annotationName: String): AnnotationAttributes` 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`. `open static fun getMergedAnnotationAttributes(element: AnnotatedElement, annotationName: String, classValuesAsString: Boolean, nestedAnnotationsAsMap: Boolean): AnnotationAttributes` 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`, 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 AnnotatedElementUtils.
getMergedRepeatableAnnotations	`open static fun <A : Annotation> getMergedRepeatableAnnotations(element: AnnotatedElement, annotationType: Class<A>): MutableSet<A>` Get all repeatable annotations of the specified `annotationType` within the annotation hierarchy above the supplied `element`; and for each annotation found, merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy and synthesize the results back into an annotation of the specified `annotationType`. The container type that holds the repeatable annotations will be looked up via java.lang.annotation.Repeatable. AliasFor semantics are fully supported, both within a single annotation and within annotation hierarchies. This method follows get semantics as described in the AnnotatedElementUtils. `open static fun <A : Annotation> getMergedRepeatableAnnotations(element: AnnotatedElement, annotationType: Class<A>, containerType: Class<out Annotation>): MutableSet<A>` Get all repeatable annotations of the specified `annotationType` within the annotation hierarchy above the supplied `element`; and for each annotation found, merge that annotation's attributes with matching attributes from annotations in lower levels of the annotation hierarchy and synthesize the results back into an annotation of the specified `annotationType`. AliasFor semantics are fully supported, both within a single annotation and within annotation hierarchies. This method follows get semantics as described in the AnnotatedElementUtils.
getMetaAnnotationTypes	`open static fun getMetaAnnotationTypes(element: AnnotatedElement, annotationType: Class<out Annotation>): MutableSet<String>` 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 AnnotatedElementUtils. `open static fun getMetaAnnotationTypes(element: AnnotatedElement, annotationName: String): MutableSet<String>` 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 AnnotatedElementUtils.
hasAnnotation	`open static fun hasAnnotation(element: AnnotatedElement, annotationType: Class<out Annotation>): Boolean` Determine if an annotation of the specified `annotationType` is available on the supplied AnnotatedElement or within the annotation hierarchy above the specified element. If this method returns `true`, then `#findMergedAnnotationAttributes` will return a non-null value. This method follows find semantics as described in the AnnotatedElementUtils.
hasMetaAnnotationTypes	`open static fun hasMetaAnnotationTypes(element: AnnotatedElement, annotationType: Class<out Annotation>): Boolean` Determine if the supplied AnnotatedElement is annotated with a composed annotation that is meta-annotated with an annotation of the specified `annotationType`. This method follows get semantics as described in the AnnotatedElementUtils. `open static fun hasMetaAnnotationTypes(element: AnnotatedElement, annotationName: String): Boolean` 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 AnnotatedElementUtils.
isAnnotated	`open static fun isAnnotated(element: AnnotatedElement, annotationType: Class<out Annotation>): Boolean` Determine if an annotation of the specified `annotationType` is present on the supplied AnnotatedElement or within the annotation hierarchy above the specified element. If this method returns `true`, then `#getMergedAnnotationAttributes` will return a non-null value. This method follows get semantics as described in the AnnotatedElementUtils. `open static fun isAnnotated(element: AnnotatedElement, annotationName: String): Boolean` 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` will return a non-null value. This method follows get semantics as described in the AnnotatedElementUtils.