Top Description Inners Fields Constructors Methods
org.springframework.core.annotation

public abstract Class AnnotationUtils

extends Object
Class Inheritance
Imports
java.lang.annotation.Annotation, java.lang.reflect.AnnotatedElement, .Array, .InvocationHandler, .Method, .Modifier, .Proxy, java.util.Collection, .Collections, .List, .Map, .NoSuchElementException, .Set, org.springframework.core.BridgeMethodResolver, org.springframework.core.annotation.AnnotationTypeMapping.MirrorSets.MirrorSet, .MergedAnnotation.Adapt, .MergedAnnotations.SearchStrategy, org.springframework.lang.Nullable, org.springframework.util.CollectionUtils, .ConcurrentReferenceHashMap, .ReflectionUtils, .StringUtils
General utility methods for working with annotations, handling meta-annotations, bridge methods (which the compiler generates for generic declarations) as well as super methods (for optional annotation inheritance).

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

As a general rule for runtime-retained application annotations (e.g. for transaction control, authorization, or service exposure), always use the lookup methods on this class (e.g. findAnnotation(Method, Class) or getAnnotation(Method, Class)) instead of the plain annotation lookup methods in the JDK. You can still explicitly choose between a get lookup on the given class level only (getAnnotation(Method, Class)) and a find lookup in the entire inheritance hierarchy of the given method (findAnnotation(Method, Class)).

Terminology

The terms directly present, indirectly present, and present have the same meanings as defined in the class-level javadoc for AnnotatedElement (in Java 8).

An annotation is meta-present on an element if the annotation is declared as a meta-annotation on some other annotation which is present on the element. Annotation A is meta-present on another annotation if A is either directly present or meta-present on the other annotation.

Meta-annotation Support

Most find*() methods and some get*() methods in this class provide support for finding annotations used as meta-annotations. Consult the javadoc for each method in this class for details. For fine-grained support for meta-annotations with attribute overrides in composed annotations, consider using AnnotatedElementUtils's more specific methods instead.

Attribute Aliases

All public methods in this class that return annotations, arrays of annotations, or AnnotationAttributes transparently support attribute aliases configured via @AliasFor. Consult the various synthesizeAnnotation*(..) methods for details.

Search Scope

The search algorithms used by methods in this class stop searching for an annotation once the first annotation of the specified type has been found. As a consequence, additional annotations of the specified type will be silently ignored.

Authors
Rob Harrop, Juergen Hoeller, Sam Brannen, Mark Fisher, Chris Beams, Phillip Webb, Oleg Zhurakousky
Since
2.0
See Also
AliasFor, AnnotationAttributes, AnnotatedElementUtils, BridgeMethodResolver, java.lang.reflect.AnnotatedElement#getAnnotations(), java.lang.reflect.AnnotatedElement#getAnnotation(Class), java.lang.reflect.AnnotatedElement#getDeclaredAnnotations()

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
AnnotationUtils.DefaultValueHolder

Internal holder used to wrap default values.

Field Summary

Modifier and TypeField and Description
private static final Map<Class<? extends Annotation>, Map<String, AnnotationUtils.DefaultValueHolder>>
defaultValuesCache

private static final AnnotationFilter
JAVA_LANG_ANNOTATION_FILTER

public static final String
VALUE

The attribute name for annotations with a single element.

Constructor Summary

AccessConstructor and Description
public
AnnotationUtils()

Method Summary

Modifier and TypeMethod and Description
private static Object
adaptValue(Object annotatedElement, Object value, boolean classValuesAsString)

public static void
clearCache()

Clear the internal annotation metadata cache.

private static Map<String, AnnotationUtils.DefaultValueHolder>
computeDefaultValues(Class<? extends Annotation> annotationType)

public static <A extends Annotation> A

Returns:

the first matching annotation, or null if not found
findAnnotation(AnnotatedElement
the AnnotatedElement on which to find the annotation
annotatedElement, Class<A>
the annotation type to look for, both locally and as a meta-annotation
annotationType)

Find a single Annotation of annotationType on the supplied AnnotatedElement.

public static <A extends Annotation> A

Returns:

the first matching annotation, or null if not found
findAnnotation(Method
the method to look for annotations on
method, Class<A>
the annotation type to look for
annotationType)

Find a single Annotation of annotationType on the supplied Method, traversing its super methods (i.e. from superclasses and interfaces) if the annotation is not directly present on the given method itself.

public static <A extends Annotation> A

Returns:

the first matching annotation, or null if not found
findAnnotation(Class<?>
the class to look for annotations on
clazz, Class<A>
the type of annotation to look for
annotationType)

Find a single Annotation of annotationType on the supplied Class, traversing its interfaces, annotations, and superclasses if the annotation is not directly present on the given class itself.

public static Class<?>

Returns:

the first Class in the inheritance hierarchy that declares an annotation of the specified annotationType, or null if not found
findAnnotationDeclaringClass(Class<? extends Annotation>
the annotation type to look for
annotationType, Class<?>
the class to check for the annotation on (may be null)
clazz)

Deprecated as of 5.2 since it is superseded by the MergedAnnotations API
Find the first Class in the inheritance hierarchy of the specified clazz (including the specified clazz itself) on which an annotation of the specified annotationType is directly present.
public static Class<?>

Returns:

the first Class in the inheritance hierarchy that declares an annotation of at least one of the specified annotationTypes, or null if not found
findAnnotationDeclaringClassForTypes(List<Class<? extends Annotation>>
the annotation types to look for
annotationTypes, Class<?>
the class to check for the annotation on (may be null)
clazz)

Deprecated as of 5.2 since it is superseded by the MergedAnnotations API
Find the first Class in the inheritance hierarchy of the specified clazz (including the specified clazz itself) on which at least one of the specified annotationTypes is directly present.
public static <A extends Annotation> A

Returns:

the first matching annotation, or null if not found
getAnnotation(Annotation
the Annotation to check
annotation, Class<A>
the annotation type to look for, both locally and as a meta-annotation
annotationType)

Get a single Annotation of annotationType from the supplied annotation: either the given annotation itself or a direct meta-annotation thereof.

public static <A extends Annotation> A

Returns:

the first matching annotation, or null if not found
getAnnotation(AnnotatedElement
the AnnotatedElement from which to get the annotation
annotatedElement, Class<A>
the annotation type to look for, both locally and as a meta-annotation
annotationType)

Get a single Annotation of annotationType from the supplied AnnotatedElement, where the annotation is either present or meta-present on the AnnotatedElement.

public static <A extends Annotation> A

Returns:

the first matching annotation, or null if not found
getAnnotation(Method
the method to look for annotations on
method, Class<A>
the annotation type to look for
annotationType)

Get a single Annotation of annotationType from the supplied Method, where the annotation is either present or meta-present on the method.

public static Map<String, Object>

Returns:

the Map of annotation attributes, with attribute names as keys and corresponding attribute values as values (never null)
getAnnotationAttributes(Annotation
the annotation to retrieve the attributes for
annotation)

Retrieve the given annotation's attributes as a Map, preserving all attribute types.

public static Map<String, Object>

Returns:

the Map of annotation attributes, with attribute names as keys and corresponding attribute values as values (never null)
getAnnotationAttributes(Annotation
the annotation to retrieve the attributes for
annotation, boolean
whether to convert Class references into Strings (for compatibility with org.springframework.core.type.AnnotationMetadata) or to preserve them as Class references
classValuesAsString)

Retrieve the given annotation's attributes as a Map.

public static AnnotationAttributes

Returns:

the annotation attributes (a specialized Map) with attribute names as keys and corresponding attribute values as values (never null)
getAnnotationAttributes(Annotation
the annotation to retrieve the attributes for
annotation, boolean
whether to convert Class references into Strings (for compatibility with org.springframework.core.type.AnnotationMetadata) or to preserve them as Class references
classValuesAsString, boolean
whether to convert nested annotations into AnnotationAttributes maps (for compatibility with org.springframework.core.type.AnnotationMetadata) or to preserve them as Annotation instances
nestedAnnotationsAsMap)

Retrieve the given annotation's attributes as an AnnotationAttributes map.

public static AnnotationAttributes

Returns:

the annotation attributes (a specialized Map) with attribute names as keys and corresponding attribute values as values (never null)
getAnnotationAttributes(AnnotatedElement
the element that is annotated with the supplied annotation; may be null if unknown
annotatedElement, Annotation
the annotation to retrieve the attributes for
annotation)

Retrieve the given annotation's attributes as an AnnotationAttributes map.

public static AnnotationAttributes

Returns:

the annotation attributes (a specialized Map) with attribute names as keys and corresponding attribute values as values (never null)
getAnnotationAttributes(AnnotatedElement
the element that is annotated with the supplied annotation; may be null if unknown
annotatedElement, Annotation
the annotation to retrieve the attributes for
annotation, boolean
whether to convert Class references into Strings (for compatibility with org.springframework.core.type.AnnotationMetadata) or to preserve them as Class references
classValuesAsString, boolean
whether to convert nested annotations into AnnotationAttributes maps (for compatibility with org.springframework.core.type.AnnotationMetadata) or to preserve them as Annotation instances
nestedAnnotationsAsMap)

Retrieve the given annotation's attributes as an AnnotationAttributes map.

public static Annotation[]

Returns:

the annotations found, an empty array, or null if not resolvable (e.g. because nested Class values in annotation attributes failed to resolve at runtime)
getAnnotations(AnnotatedElement
the Method, Constructor or Field to retrieve annotations from
annotatedElement)

Deprecated as of 5.2 since it is superseded by the MergedAnnotations API
Get all Annotations that are present on the supplied AnnotatedElement.
public static Annotation[]

Returns:

the annotations found, an empty array, or null if not resolvable (e.g. because nested Class values in annotation attributes failed to resolve at runtime)
getAnnotations(Method
the Method to retrieve annotations from
method)

Deprecated as of 5.2 since it is superseded by the MergedAnnotations API
Get all Annotations that are present on the supplied Method.
private static Object
getAttributeValueForMirrorResolution(Method attribute, Object attributes)

public static <A extends Annotation> Set<A>

Returns:

the annotations found or an empty set (never null)
getDeclaredRepeatableAnnotations(AnnotatedElement
the element to look for annotations on
annotatedElement, Class<A>
the annotation type to look for
annotationType)

Deprecated as of 5.2 since it is superseded by the MergedAnnotations API
Get the declared repeatable annotations of annotationType from the supplied AnnotatedElement, where such annotations are either directly present, indirectly present, or meta-present on the element.
public static <A extends Annotation> Set<A>

Returns:

the annotations found or an empty set (never null)
getDeclaredRepeatableAnnotations(AnnotatedElement
the element to look for annotations on
annotatedElement, Class<A>
the annotation type to look for
annotationType, Class<? extends Annotation>
the type of the container that holds the annotations; may be null if a container is not supported or if it should be looked up via @java.lang.annotation.Repeatable when running on Java 8 or higher
containerAnnotationType)

Deprecated as of 5.2 since it is superseded by the MergedAnnotations API
Get the declared repeatable annotations of annotationType from the supplied AnnotatedElement, where such annotations are either directly present, indirectly present, or meta-present on the element.
public static Object

Returns:

the default value, or null if not found
getDefaultValue(Annotation
the annotation instance from which to retrieve the default value
annotation)

Retrieve the default value of the value attribute of a single-element Annotation, given an annotation instance.

public static Object

Returns:

the default value of the named attribute, or null if not found
getDefaultValue(Annotation
the annotation instance from which to retrieve the default value
annotation, String
the name of the attribute value to retrieve
attributeName)

Retrieve the default value of a named attribute, given an annotation instance.

public static Object

Returns:

the default value, or null if not found
getDefaultValue(Class<? extends Annotation>
the annotation type for which the default value should be retrieved
annotationType)

Retrieve the default value of the value attribute of a single-element Annotation, given the annotation type.

public static Object

Returns:

the default value of the named attribute, or null if not found
getDefaultValue(Class<? extends Annotation>
the annotation type for which the default value should be retrieved
annotationType, String
the name of the attribute value to retrieve.
attributeName)

Retrieve the default value of a named attribute, given the annotation type.

private static Map<String, AnnotationUtils.DefaultValueHolder>
getDefaultValues(Class<? extends Annotation> annotationType)

public static <A extends Annotation> Set<A>

Returns:

the annotations found or an empty set (never null)
getRepeatableAnnotations(AnnotatedElement
the element to look for annotations on
annotatedElement, Class<A>
the annotation type to look for
annotationType)

Deprecated as of 5.2 since it is superseded by the MergedAnnotations API
Get the repeatable annotations of annotationType from the supplied AnnotatedElement, where such annotations are either present, indirectly present, or meta-present on the element.
public static <A extends Annotation> Set<A>

Returns:

the annotations found or an empty set (never null)
getRepeatableAnnotations(AnnotatedElement
the element to look for annotations on
annotatedElement, Class<A>
the annotation type to look for
annotationType, Class<? extends Annotation>
the type of the container that holds the annotations; may be null if a container is not supported or if it should be looked up via @java.lang.annotation.Repeatable when running on Java 8 or higher
containerAnnotationType)

Deprecated as of 5.2 since it is superseded by the MergedAnnotations API
Get the repeatable annotations of annotationType from the supplied AnnotatedElement, where such annotations are either present, indirectly present, or meta-present on the element.
public static Object

Returns:

the attribute value, or null if not found unless the attribute value cannot be retrieved due to an AnnotationConfigurationException, in which case such an exception will be rethrown
getValue(Annotation
the annotation instance from which to retrieve the value
annotation)

Retrieve the value of the value attribute of a single-element Annotation, given an annotation instance.

public static Object

Returns:

the attribute value, or null if not found unless the attribute value cannot be retrieved due to an AnnotationConfigurationException, in which case such an exception will be rethrown
getValue(Annotation
the annotation instance from which to retrieve the value
annotation, String
the name of the attribute value to retrieve
attributeName)

Retrieve the value of a named attribute, given an annotation instance.

pack-priv static void
handleIntrospectionFailure(AnnotatedElement
the element that we tried to introspect annotations on
element, Throwable
the exception that we encountered
ex)

Handle the supplied annotation introspection exception.

private static void
handleValueRetrievalFailure(Annotation
the annotation instance from which to retrieve the value
annotation, Throwable
the exception that we encountered
ex)

Handle the supplied value retrieval exception.

pack-priv static Object

Returns:

the value returned from the method invocation
invokeAnnotationMethod(Method
the method to invoke
method, Object
the annotation on which to invoke the method
annotation)

Invoke the supplied annotation attribute Method on the supplied Annotation.

public static boolean

Returns:

true if an annotation of the specified annotationType is directly present
isAnnotationDeclaredLocally(Class<? extends Annotation>
the annotation type to look for
annotationType, Class<?>
the class to check for the annotation on
clazz)

Determine whether an annotation of the specified annotationType is declared locally (i.e. directly present) on the supplied clazz.

public static boolean

Returns:

true if an annotation of the specified annotationType is present and inherited
isAnnotationInherited(Class<? extends Annotation>
the annotation type to look for
annotationType, Class<?>
the class to check for the annotation on
clazz)

Deprecated as of 5.2 since it is superseded by the MergedAnnotations API
Determine whether an annotation of the specified annotationType is present on the supplied clazz and is inherited (i.e. not directly present).
public static boolean

Returns:

true if such an annotation is meta-present
isAnnotationMetaPresent(Class<? extends Annotation>
the annotation type to search on
annotationType, Class<? extends Annotation>
the type of meta-annotation to search for
metaAnnotationType)

Deprecated as of 5.2 since it is superseded by the MergedAnnotations API
Determine if an annotation of type metaAnnotationType is meta-present on the supplied annotationType.
public static boolean

Returns:

false if the class is known to have no such annotations at any level; true otherwise. Callers will usually perform full method/field introspection if true is being returned here.
isCandidateClass(Class<?>
the class to introspect
clazz, Collection<Class<? extends Annotation>>
the searchable annotation types
annotationTypes)

Determine whether the given class is a candidate for carrying one of the specified annotations (at type, method or field level).

public static boolean

Returns:

false if the class is known to have no such annotations at any level; true otherwise. Callers will usually perform full method/field introspection if true is being returned here.
isCandidateClass(Class<?>
the class to introspect
clazz, Class<? extends Annotation>
the searchable annotation type
annotationType)

Determine whether the given class is a candidate for carrying the specified annotation (at type, method or field level).

public static boolean

Returns:

false if the class is known to have no such annotations at any level; true otherwise. Callers will usually perform full method/field introspection if true is being returned here.
isCandidateClass(Class<?>
the class to introspect
clazz, String
the fully-qualified name of the searchable annotation type
annotationName)

Determine whether the given class is a candidate for carrying the specified annotation (at type, method or field level).

public static boolean

Returns:

true if the annotation is in the java.lang.annotation package
isInJavaLangAnnotationPackage(Annotation
the annotation to check
annotation)

Determine if the supplied Annotation is defined in the core JDK java.lang.annotation package.

public static boolean

Returns:

true if the annotation is in the java.lang.annotation package
isInJavaLangAnnotationPackage(String
the name of the annotation type to check
annotationType)

Determine if the Annotation with the supplied name is defined in the core JDK java.lang.annotation package.

private static <A extends Annotation> boolean
isSingleLevelPresent(MergedAnnotation<A> mergedAnnotation)

public static boolean

Returns:

true if the supplied annotation is a synthesized annotation
isSynthesizedAnnotation(Annotation
the annotation to check
annotation)

Determine if the supplied Annotation has been synthesized by Spring (i.e. wrapped in a dynamic proxy) with additional functionality such as attribute alias handling.

public static void
postProcessAnnotationAttributes(Object
the element that is annotated with an annotation or annotation hierarchy from which the supplied attributes were created; may be null if unknown
annotatedElement, AnnotationAttributes
the annotation attributes to post-process
attributes, boolean
whether to convert Class references into Strings (for compatibility with org.springframework.core.type.AnnotationMetadata) or to preserve them as Class references
classValuesAsString)

Post-process the supplied AnnotationAttributes, preserving nested annotations as Annotation instances.

public static void
registerDefaultValues(AnnotationAttributes
the annotation attributes to process
attributes)

Register the annotation-declared default values for the given attributes, if available.

pack-priv static void
rethrowAnnotationConfigurationException(Throwable
the throwable to inspect
ex)

If the supplied throwable is an AnnotationConfigurationException, it will be cast to an AnnotationConfigurationException and thrown, allowing it to propagate to the caller.

public static <A extends Annotation> A

Returns:

the synthesized annotation if the supplied annotation is synthesizable; null if the supplied annotation is null; otherwise the supplied annotation unmodified
synthesizeAnnotation(A
the annotation to synthesize
annotation, AnnotatedElement
the element that is annotated with the supplied annotation; may be null if unknown
annotatedElement)

Synthesize an annotation from the supplied annotation by wrapping it in a dynamic proxy that transparently enforces attribute alias semantics for annotation attributes that are annotated with @AliasFor.

public static <A extends Annotation> A

Returns:

the synthesized annotation
synthesizeAnnotation(Class<A>
the type of annotation to synthesize
annotationType)

Synthesize an annotation from its default attributes values.

public static <A extends Annotation> A

Returns:

the synthesized annotation
synthesizeAnnotation(Map<String, Object>
the map of annotation attributes to synthesize
attributes, Class<A>
the type of annotation to synthesize
annotationType, AnnotatedElement
the element that is annotated with the annotation corresponding to the supplied attributes; may be null if unknown
annotatedElement)

Synthesize an annotation from the supplied map of annotation attributes by wrapping the map in a dynamic proxy that implements an annotation of the specified annotationType and transparently enforces attribute alias semantics for annotation attributes that are annotated with @AliasFor.

pack-priv static Annotation[]

Returns:

a new array of synthesized annotations, or null if the supplied array is null
synthesizeAnnotationArray(Annotation[]
the array of annotations to synthesize
annotations, AnnotatedElement
the element that is annotated with the supplied array of annotations; may be null if unknown
annotatedElement)

Synthesize an array of annotations from the supplied array of annotations by creating a new array of the same size and type and populating it with synthesized versions of the annotations from the input array.

public static void
validateAnnotation(Annotation
the annotation to validate
annotation)

Check the declared attributes of the given annotation, in particular covering Google App Engine's late arrival of TypeNotPresentExceptionProxy for Class values (instead of early Class.getAnnotations() failure).

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait