Class AnnotationUtils
- java.lang.Object
- org.springframework.core.annotation.AnnotationUtils
public abstract class AnnotationUtils extends Object
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)
orgetAnnotation(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 forAnnotatedElement
(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 ifA
is either directly present or meta-present on the other annotation.Meta-annotation Support
Most
find*()
methods and someget*()
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 usingAnnotatedElementUtils
'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 varioussynthesizeAnnotation*(..)
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.
- Since:
- 2.0
- Author:
- Rob Harrop, Juergen Hoeller, Sam Brannen, Mark Fisher, Chris Beams, Phillip Webb
- See Also:
AliasFor
,AnnotationAttributes
,AnnotatedElementUtils
,BridgeMethodResolver
,AnnotatedElement.getAnnotations()
,AnnotatedElement.getAnnotation(Class)
,AnnotatedElement.getDeclaredAnnotations()
Constructor Summary
Constructors Constructor Description AnnotationUtils()
Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static void
clearCache()
Clear the internal annotation metadata cache.static <A extends Annotation>
AfindAnnotation(Class<?> clazz, Class<A> annotationType)
Find a singleAnnotation
ofannotationType
on the suppliedClass
, traversing its interfaces, annotations, and superclasses if the annotation is not directly present on the given class itself.static <A extends Annotation>
AfindAnnotation(AnnotatedElement annotatedElement, Class<A> annotationType)
static <A extends Annotation>
AfindAnnotation(Method method, Class<A> annotationType)
Find a singleAnnotation
ofannotationType
on the suppliedMethod
, traversing its super methods (i.e.static Class<?>
findAnnotationDeclaringClass(Class<? extends Annotation> annotationType, Class<?> clazz)
Find the firstClass
in the inheritance hierarchy of the specifiedclazz
(including the specifiedclazz
itself) on which an annotation of the specifiedannotationType
is directly present.static Class<?>
findAnnotationDeclaringClassForTypes(List<Class<? extends Annotation>> annotationTypes, Class<?> clazz)
Find the firstClass
in the inheritance hierarchy of the specifiedclazz
(including the specifiedclazz
itself) on which at least one of the specifiedannotationTypes
is directly present.static <A extends Annotation>
AgetAnnotation(Annotation annotation, Class<A> annotationType)
Get a singleAnnotation
ofannotationType
from the supplied annotation: either the given annotation itself or a direct meta-annotation thereof.static <A extends Annotation>
AgetAnnotation(AnnotatedElement annotatedElement, Class<A> annotationType)
Get a singleAnnotation
ofannotationType
from the suppliedAnnotatedElement
, where the annotation is either present or meta-present on theAnnotatedElement
.static <A extends Annotation>
AgetAnnotation(Method method, Class<A> annotationType)
Get a singleAnnotation
ofannotationType
from the suppliedMethod
, where the annotation is either present or meta-present on the method.static Map<String,Object>
getAnnotationAttributes(Annotation annotation)
Retrieve the given annotation's attributes as aMap
, preserving all attribute types.static Map<String,Object>
getAnnotationAttributes(Annotation annotation, boolean classValuesAsString)
Retrieve the given annotation's attributes as aMap
.static AnnotationAttributes
getAnnotationAttributes(Annotation annotation, boolean classValuesAsString, boolean nestedAnnotationsAsMap)
Retrieve the given annotation's attributes as anAnnotationAttributes
map.static AnnotationAttributes
getAnnotationAttributes(AnnotatedElement annotatedElement, Annotation annotation)
Retrieve the given annotation's attributes as anAnnotationAttributes
map.static AnnotationAttributes
getAnnotationAttributes(AnnotatedElement annotatedElement, Annotation annotation, boolean classValuesAsString, boolean nestedAnnotationsAsMap)
Retrieve the given annotation's attributes as anAnnotationAttributes
map.static Annotation[]
getAnnotations(AnnotatedElement annotatedElement)
Get allAnnotations
that are present on the suppliedAnnotatedElement
.static Annotation[]
getAnnotations(Method method)
Get allAnnotations
that are present on the suppliedMethod
.static <A extends Annotation>
Set<A>getDeclaredRepeatableAnnotations(AnnotatedElement annotatedElement, Class<A> annotationType)
Get the declared repeatableannotations ofannotationType
from the suppliedAnnotatedElement
, where such annotations are either directly present, indirectly present, or meta-present on the element.static <A extends Annotation>
Set<A>getDeclaredRepeatableAnnotations(AnnotatedElement annotatedElement, Class<A> annotationType, Class<? extends Annotation> containerAnnotationType)
Get the declared repeatableannotations ofannotationType
from the suppliedAnnotatedElement
, where such annotations are either directly present, indirectly present, or meta-present on the element.static Object
getDefaultValue(Annotation annotation)
Retrieve the default value of thevalue
attribute of a single-element Annotation, given an annotation instance.static Object
getDefaultValue(Annotation annotation, String attributeName)
Retrieve the default value of a named attribute, given an annotation instance.static Object
getDefaultValue(Class<? extends Annotation> annotationType)
Retrieve the default value of thevalue
attribute of a single-element Annotation, given theannotation type
.static Object
getDefaultValue(Class<? extends Annotation> annotationType, String attributeName)
Retrieve the default value of a named attribute, given theannotation type
.static <A extends Annotation>
Set<A>getRepeatableAnnotation(AnnotatedElement annotatedElement, Class<? extends Annotation> containerAnnotationType, Class<A> annotationType)
Deprecated.As of Spring Framework 4.2, usegetRepeatableAnnotations()
orgetDeclaredRepeatableAnnotations()
instead.static <A extends Annotation>
Set<A>getRepeatableAnnotation(Method method, Class<? extends Annotation> containerAnnotationType, Class<A> annotationType)
Deprecated.As of Spring Framework 4.2, usegetRepeatableAnnotations()
orgetDeclaredRepeatableAnnotations()
instead.static <A extends Annotation>
Set<A>getRepeatableAnnotations(AnnotatedElement annotatedElement, Class<A> annotationType)
Get the repeatableannotations ofannotationType
from the suppliedAnnotatedElement
, where such annotations are either present, indirectly present, or meta-present on the element.static <A extends Annotation>
Set<A>getRepeatableAnnotations(AnnotatedElement annotatedElement, Class<A> annotationType, Class<? extends Annotation> containerAnnotationType)
Get the repeatableannotations ofannotationType
from the suppliedAnnotatedElement
, where such annotations are either present, indirectly present, or meta-present on the element.static Object
getValue(Annotation annotation)
Retrieve the value of thevalue
attribute of a single-element Annotation, given an annotation instance.static Object
getValue(Annotation annotation, String attributeName)
Retrieve the value of a named attribute, given an annotation instance.static boolean
isAnnotationDeclaredLocally(Class<? extends Annotation> annotationType, Class<?> clazz)
Determine whether an annotation of the specifiedannotationType
is declared locally (i.e., directly present) on the suppliedclazz
.static boolean
isAnnotationInherited(Class<? extends Annotation> annotationType, Class<?> clazz)
Determine whether an annotation of the specifiedannotationType
is present on the suppliedclazz
and is inherited (i.e., not directly present).static boolean
isAnnotationMetaPresent(Class<? extends Annotation> annotationType, Class<? extends Annotation> metaAnnotationType)
Determine if an annotation of typemetaAnnotationType
is meta-present on the suppliedannotationType
.static boolean
isInJavaLangAnnotationPackage(Annotation annotation)
Determine if the suppliedAnnotation
is defined in the core JDKjava.lang.annotation
package.static boolean
isInJavaLangAnnotationPackage(String annotationType)
Determine if theAnnotation
with the supplied name is defined in the core JDKjava.lang.annotation
package.static void
postProcessAnnotationAttributes(Object annotatedElement, AnnotationAttributes attributes, boolean classValuesAsString)
Post-process the suppliedAnnotationAttributes
, preserving nested annotations asAnnotation
instances.static void
registerDefaultValues(AnnotationAttributes attributes)
Register the annotation-declared default values for the given attributes, if available.static <A extends Annotation>
AsynthesizeAnnotation(A annotation, AnnotatedElement annotatedElement)
Synthesize an annotation from the suppliedannotation
by wrapping it in a dynamic proxy that transparently enforces attribute alias semantics for annotation attributes that are annotated with@AliasFor
.static <A extends Annotation>
AsynthesizeAnnotation(Class<A> annotationType)
Synthesize an annotation from its default attributes values.static <A extends Annotation>
AsynthesizeAnnotation(Map<String,Object> attributes, Class<A> annotationType, AnnotatedElement 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 specifiedannotationType
and transparently enforces attribute alias semantics for annotation attributes that are annotated with@AliasFor
.static void
validateAnnotation(Annotation annotation)
Check the declared attributes of the given annotation, in particular covering Google App Engine's late arrival ofTypeNotPresentExceptionProxy
forClass
values (instead of earlyClass.getAnnotations() failure
.
Field Detail
VALUE
public static final String VALUE
The attribute name for annotations with a single element.- See Also:
- Constant Field Values
Constructor Detail
AnnotationUtils
public AnnotationUtils()
Method Detail
getAnnotation
public static <A extends Annotation> A getAnnotation(Annotation annotation, Class<A> annotationType)
Get a singleAnnotation
ofannotationType
from the supplied annotation: either the given annotation itself or a direct meta-annotation thereof.Note that this method supports only a single level of meta-annotations. For support for arbitrary levels of meta-annotations, use one of the
find*()
methods instead.- Parameters:
annotation
- the Annotation to checkannotationType
- the annotation type to look for, both locally and as a meta-annotation- Returns:
- the first matching annotation, or
null
if not found - Since:
- 4.0
getAnnotation
public static <A extends Annotation> A getAnnotation(AnnotatedElement annotatedElement, Class<A> annotationType)
Get a singleAnnotation
ofannotationType
from the suppliedAnnotatedElement
, where the annotation is either present or meta-present on theAnnotatedElement
.Note that this method supports only a single level of meta-annotations. For support for arbitrary levels of meta-annotations, use
findAnnotation(AnnotatedElement, Class)
instead.- Parameters:
annotatedElement
- theAnnotatedElement
from which to get the annotationannotationType
- the annotation type to look for, both locally and as a meta-annotation- Returns:
- the first matching annotation, or
null
if not found - Since:
- 3.1
getAnnotation
public static <A extends Annotation> A getAnnotation(Method method, Class<A> annotationType)
Get a singleAnnotation
ofannotationType
from the suppliedMethod
, where the annotation is either present or meta-present on the method.Correctly handles bridge
Methods
generated by the compiler.Note that this method supports only a single level of meta-annotations. For support for arbitrary levels of meta-annotations, use
findAnnotation(Method, Class)
instead.- Parameters:
method
- the method to look for annotations onannotationType
- the annotation type to look for- Returns:
- the first matching annotation, or
null
if not found - See Also:
BridgeMethodResolver.findBridgedMethod(Method)
,getAnnotation(AnnotatedElement, Class)
getAnnotations
public static Annotation[] getAnnotations(AnnotatedElement annotatedElement)
Get allAnnotations
that are present on the suppliedAnnotatedElement
.Meta-annotations will not be searched.
- Parameters:
annotatedElement
- the Method, Constructor or Field to retrieve annotations from- 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) - Since:
- 4.0.8
- See Also:
AnnotatedElement.getAnnotations()
getAnnotations
public static Annotation[] getAnnotations(Method method)
Get allAnnotations
that are present on the suppliedMethod
.Correctly handles bridge
Methods
generated by the compiler.Meta-annotations will not be searched.
- Parameters:
method
- the Method to retrieve annotations from- 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) - See Also:
BridgeMethodResolver.findBridgedMethod(Method)
,AnnotatedElement.getAnnotations()
getRepeatableAnnotation
@Deprecated public static <A extends Annotation> Set<A> getRepeatableAnnotation(Method method, Class<? extends Annotation> containerAnnotationType, Class<A> annotationType)
Deprecated.As of Spring Framework 4.2, usegetRepeatableAnnotations()
orgetDeclaredRepeatableAnnotations()
instead.Delegates togetRepeatableAnnotations(AnnotatedElement, Class, Class)
.
getRepeatableAnnotation
@Deprecated public static <A extends Annotation> Set<A> getRepeatableAnnotation(AnnotatedElement annotatedElement, Class<? extends Annotation> containerAnnotationType, Class<A> annotationType)
Deprecated.As of Spring Framework 4.2, usegetRepeatableAnnotations()
orgetDeclaredRepeatableAnnotations()
instead.Delegates togetRepeatableAnnotations(AnnotatedElement, Class, Class)
.
getRepeatableAnnotations
public static <A extends Annotation> Set<A> getRepeatableAnnotations(AnnotatedElement annotatedElement, Class<A> annotationType)
Get the repeatableannotations ofannotationType
from the suppliedAnnotatedElement
, where such annotations are either present, indirectly present, or meta-present on the element.This method mimics the functionality of Java 8's
AnnotatedElement.getAnnotationsByType(Class)
with support for automatic detection of a container annotation declared via @Repeatable
(when running on Java 8 or higher) and with additional support for meta-annotations.Handles both single annotations and annotations nested within a container annotation.
Correctly handles bridge methods generated by the compiler if the supplied element is a
Method
.Meta-annotations will be searched if the annotation is not present on the supplied element.
- Parameters:
annotatedElement
- the element to look for annotations onannotationType
- the annotation type to look for- Returns:
- the annotations found or an empty set (never
null
) - Since:
- 4.2
- See Also:
getRepeatableAnnotations(AnnotatedElement, Class, Class)
,getDeclaredRepeatableAnnotations(AnnotatedElement, Class, Class)
,AnnotatedElementUtils.getMergedRepeatableAnnotations(AnnotatedElement, Class)
,BridgeMethodResolver.findBridgedMethod(java.lang.reflect.Method)
,Repeatable
,AnnotatedElement.getAnnotationsByType(java.lang.Class<T>)
getRepeatableAnnotations
public static <A extends Annotation> Set<A> getRepeatableAnnotations(AnnotatedElement annotatedElement, Class<A> annotationType, Class<? extends Annotation> containerAnnotationType)
Get the repeatableannotations ofannotationType
from the suppliedAnnotatedElement
, where such annotations are either present, indirectly present, or meta-present on the element.This method mimics the functionality of Java 8's
AnnotatedElement.getAnnotationsByType(Class)
with additional support for meta-annotations.Handles both single annotations and annotations nested within a container annotation.
Correctly handles bridge methods generated by the compiler if the supplied element is a
Method
.Meta-annotations will be searched if the annotation is not present on the supplied element.
- Parameters:
annotatedElement
- the element to look for annotations onannotationType
- the annotation type to look forcontainerAnnotationType
- the type of the container that holds the annotations; may benull
if a container is not supported or if it should be looked up via @Repeatable
when running on Java 8 or higher- Returns:
- the annotations found or an empty set (never
null
) - Since:
- 4.2
- See Also:
getRepeatableAnnotations(AnnotatedElement, Class)
,getDeclaredRepeatableAnnotations(AnnotatedElement, Class)
,getDeclaredRepeatableAnnotations(AnnotatedElement, Class, Class)
,AnnotatedElementUtils.getMergedRepeatableAnnotations(AnnotatedElement, Class, Class)
,BridgeMethodResolver.findBridgedMethod(java.lang.reflect.Method)
,Repeatable
,AnnotatedElement.getAnnotationsByType(java.lang.Class<T>)
getDeclaredRepeatableAnnotations
public static <A extends Annotation> Set<A> getDeclaredRepeatableAnnotations(AnnotatedElement annotatedElement, Class<A> annotationType)
Get the declared repeatableannotations ofannotationType
from the suppliedAnnotatedElement
, where such annotations are either directly present, indirectly present, or meta-present on the element.This method mimics the functionality of Java 8's
AnnotatedElement.getDeclaredAnnotationsByType(Class)
with support for automatic detection of a container annotation declared via @Repeatable
(when running on Java 8 or higher) and with additional support for meta-annotations.Handles both single annotations and annotations nested within a container annotation.
Correctly handles bridge methods generated by the compiler if the supplied element is a
Method
.Meta-annotations will be searched if the annotation is not present on the supplied element.
- Parameters:
annotatedElement
- the element to look for annotations onannotationType
- the annotation type to look for- Returns:
- the annotations found or an empty set (never
null
) - Since:
- 4.2
- See Also:
getRepeatableAnnotations(AnnotatedElement, Class)
,getRepeatableAnnotations(AnnotatedElement, Class, Class)
,getDeclaredRepeatableAnnotations(AnnotatedElement, Class, Class)
,AnnotatedElementUtils.getMergedRepeatableAnnotations(AnnotatedElement, Class)
,BridgeMethodResolver.findBridgedMethod(java.lang.reflect.Method)
,Repeatable
,AnnotatedElement.getDeclaredAnnotationsByType(java.lang.Class<T>)
getDeclaredRepeatableAnnotations
public static <A extends Annotation> Set<A> getDeclaredRepeatableAnnotations(AnnotatedElement annotatedElement, Class<A> annotationType, Class<? extends Annotation> containerAnnotationType)
Get the declared repeatableannotations ofannotationType
from the suppliedAnnotatedElement
, where such annotations are either directly present, indirectly present, or meta-present on the element.This method mimics the functionality of Java 8's
AnnotatedElement.getDeclaredAnnotationsByType(Class)
with additional support for meta-annotations.Handles both single annotations and annotations nested within a container annotation.
Correctly handles bridge methods generated by the compiler if the supplied element is a
Method
.Meta-annotations will be searched if the annotation is not present on the supplied element.
- Parameters:
annotatedElement
- the element to look for annotations onannotationType
- the annotation type to look forcontainerAnnotationType
- the type of the container that holds the annotations; may benull
if a container is not supported or if it should be looked up via @Repeatable
when running on Java 8 or higher- Returns:
- the annotations found or an empty set (never
null
) - Since:
- 4.2
- See Also:
getRepeatableAnnotations(AnnotatedElement, Class)
,getRepeatableAnnotations(AnnotatedElement, Class, Class)
,getDeclaredRepeatableAnnotations(AnnotatedElement, Class)
,AnnotatedElementUtils.getMergedRepeatableAnnotations(AnnotatedElement, Class, Class)
,BridgeMethodResolver.findBridgedMethod(java.lang.reflect.Method)
,Repeatable
,AnnotatedElement.getDeclaredAnnotationsByType(java.lang.Class<T>)
findAnnotation
public static <A extends Annotation> A findAnnotation(AnnotatedElement annotatedElement, Class<A> annotationType)
Find a singleAnnotation
ofannotationType
on the suppliedAnnotatedElement
.Meta-annotations will be searched if the annotation is not directly present on the supplied element.
Warning: this method operates generically on annotated elements. In other words, this method does not execute specialized search algorithms for classes or methods. If you require the more specific semantics of
findAnnotation(Class, Class)
orfindAnnotation(Method, Class)
, invoke one of those methods instead.- Parameters:
annotatedElement
- theAnnotatedElement
on which to find the annotationannotationType
- the annotation type to look for, both locally and as a meta-annotation- Returns:
- the first matching annotation, or
null
if not found - Since:
- 4.2
findAnnotation
public static <A extends Annotation> A findAnnotation(Method method, Class<A> annotationType)
Find a singleAnnotation
ofannotationType
on the suppliedMethod
, traversing its super methods (i.e. from superclasses and interfaces) if the annotation is not directly present on the given method itself.Correctly handles bridge
Methods
generated by the compiler.Meta-annotations will be searched if the annotation is not directly present on the method.
Annotations on methods are not inherited by default, so we need to handle this explicitly.
- Parameters:
method
- the method to look for annotations onannotationType
- the annotation type to look for- Returns:
- the first matching annotation, or
null
if not found - See Also:
getAnnotation(Method, Class)
findAnnotation
public static <A extends Annotation> A findAnnotation(Class<?> clazz, Class<A> annotationType)
Find a singleAnnotation
ofannotationType
on the suppliedClass
, traversing its interfaces, annotations, and superclasses if the annotation is not directly present on the given class itself.This method explicitly handles class-level annotations which are not declared as
inherited
as well as meta-annotations and annotations on interfaces.The algorithm operates as follows:
- Search for the annotation on the given class and return it if found.
- Recursively search through all annotations that the given class declares.
- Recursively search through all interfaces that the given class declares.
- Recursively search through the superclass hierarchy of the given class.
Note: in this context, the term recursively means that the search process continues by returning to step #1 with the current interface, annotation, or superclass as the class to look for annotations on.
- Parameters:
clazz
- the class to look for annotations onannotationType
- the type of annotation to look for- Returns:
- the first matching annotation, or
null
if not found
findAnnotationDeclaringClass
public static Class<?> findAnnotationDeclaringClass(Class<? extends Annotation> annotationType, Class<?> clazz)
Find the firstClass
in the inheritance hierarchy of the specifiedclazz
(including the specifiedclazz
itself) on which an annotation of the specifiedannotationType
is directly present.If the supplied
clazz
is an interface, only the interface itself will be checked; the inheritance hierarchy for interfaces will not be traversed.Meta-annotations will not be searched.
The standard
Class
API does not provide a mechanism for determining which class in an inheritance hierarchy actually declares anAnnotation
, so we need to handle this explicitly.- Parameters:
annotationType
- the annotation type to look forclazz
- the class to check for the annotation on (may benull
)- Returns:
- the first
Class
in the inheritance hierarchy that declares an annotation of the specifiedannotationType
, ornull
if not found - See Also:
Class.isAnnotationPresent(Class)
,Class.getDeclaredAnnotations()
,findAnnotationDeclaringClassForTypes(List, Class)
,isAnnotationDeclaredLocally(Class, Class)
findAnnotationDeclaringClassForTypes
public static Class<?> findAnnotationDeclaringClassForTypes(List<Class<? extends Annotation>> annotationTypes, Class<?> clazz)
Find the firstClass
in the inheritance hierarchy of the specifiedclazz
(including the specifiedclazz
itself) on which at least one of the specifiedannotationTypes
is directly present.If the supplied
clazz
is an interface, only the interface itself will be checked; the inheritance hierarchy for interfaces will not be traversed.Meta-annotations will not be searched.
The standard
Class
API does not provide a mechanism for determining which class in an inheritance hierarchy actually declares one of several candidate annotations, so we need to handle this explicitly.- Parameters:
annotationTypes
- the annotation types to look forclazz
- the class to check for the annotations on, ornull
- Returns:
- the first
Class
in the inheritance hierarchy that declares an annotation of at least one of the specifiedannotationTypes
, ornull
if not found - Since:
- 3.2.2
- See Also:
Class.isAnnotationPresent(Class)
,Class.getDeclaredAnnotations()
,findAnnotationDeclaringClass(Class, Class)
,isAnnotationDeclaredLocally(Class, Class)
isAnnotationDeclaredLocally
public static boolean isAnnotationDeclaredLocally(Class<? extends Annotation> annotationType, Class<?> clazz)
Determine whether an annotation of the specifiedannotationType
is declared locally (i.e., directly present) on the suppliedclazz
.The supplied
Class
may represent any type.Meta-annotations will not be searched.
Note: This method does not determine if the annotation is inherited. For greater clarity regarding inherited annotations, consider using
isAnnotationInherited(Class, Class)
instead.- Parameters:
annotationType
- the annotation type to look forclazz
- the class to check for the annotation on- Returns:
true
if an annotation of the specifiedannotationType
is directly present- See Also:
Class.getDeclaredAnnotations()
,Class.getDeclaredAnnotation(Class)
,isAnnotationInherited(Class, Class)
isAnnotationInherited
public static boolean isAnnotationInherited(Class<? extends Annotation> annotationType, Class<?> clazz)
Determine whether an annotation of the specifiedannotationType
is present on the suppliedclazz
and is inherited (i.e., not directly present).Meta-annotations will not be searched.
If the supplied
clazz
is an interface, only the interface itself will be checked. In accordance with standard meta-annotation semantics in Java, the inheritance hierarchy for interfaces will not be traversed. See the javadoc for the@Inherited
meta-annotation for further details regarding annotation inheritance.- Parameters:
annotationType
- the annotation type to look forclazz
- the class to check for the annotation on- Returns:
true
if an annotation of the specifiedannotationType
is present and inherited- See Also:
Class.isAnnotationPresent(Class)
,isAnnotationDeclaredLocally(Class, Class)
isAnnotationMetaPresent
public static boolean isAnnotationMetaPresent(Class<? extends Annotation> annotationType, Class<? extends Annotation> metaAnnotationType)
Determine if an annotation of typemetaAnnotationType
is meta-present on the suppliedannotationType
.- Parameters:
annotationType
- the annotation type to search onmetaAnnotationType
- the type of meta-annotation to search for- Returns:
true
if such an annotation is meta-present- Since:
- 4.2.1
isInJavaLangAnnotationPackage
public static boolean isInJavaLangAnnotationPackage(Annotation annotation)
Determine if the suppliedAnnotation
is defined in the core JDKjava.lang.annotation
package.- Parameters:
annotation
- the annotation to check- Returns:
true
if the annotation is in thejava.lang.annotation
package
isInJavaLangAnnotationPackage
public static boolean isInJavaLangAnnotationPackage(String annotationType)
Determine if theAnnotation
with the supplied name is defined in the core JDKjava.lang.annotation
package.- Parameters:
annotationType
- the name of the annotation type to check- Returns:
true
if the annotation is in thejava.lang.annotation
package- Since:
- 4.2
validateAnnotation
public static void validateAnnotation(Annotation annotation)
Check the declared attributes of the given annotation, in particular covering Google App Engine's late arrival ofTypeNotPresentExceptionProxy
forClass
values (instead of earlyClass.getAnnotations() failure
.This method not failing indicates that
getAnnotationAttributes(Annotation)
won't failure either (when attempted later on).- Parameters:
annotation
- the annotation to validate- Throws:
IllegalStateException
- if a declaredClass
attribute could not be read- Since:
- 4.3.15
- See Also:
Class.getAnnotations()
,getAnnotationAttributes(Annotation)
getAnnotationAttributes
public static Map<String,Object> getAnnotationAttributes(Annotation annotation)
Retrieve the given annotation's attributes as aMap
, preserving all attribute types.Equivalent to calling
getAnnotationAttributes(Annotation, boolean, boolean)
with theclassValuesAsString
andnestedAnnotationsAsMap
parameters set tofalse
.Note: This method actually returns an
AnnotationAttributes
instance. However, theMap
signature has been preserved for binary compatibility.- Parameters:
annotation
- the annotation to retrieve the attributes for- Returns:
- the Map of annotation attributes, with attribute names as keys and corresponding attribute values as values (never
null
) - See Also:
getAnnotationAttributes(AnnotatedElement, Annotation)
,getAnnotationAttributes(Annotation, boolean, boolean)
,getAnnotationAttributes(AnnotatedElement, Annotation, boolean, boolean)
getAnnotationAttributes
public static Map<String,Object> getAnnotationAttributes(Annotation annotation, boolean classValuesAsString)
Retrieve the given annotation's attributes as aMap
.Equivalent to calling
getAnnotationAttributes(Annotation, boolean, boolean)
with thenestedAnnotationsAsMap
parameter set tofalse
.Note: This method actually returns an
AnnotationAttributes
instance. However, theMap
signature has been preserved for binary compatibility.- Parameters:
annotation
- the annotation to retrieve the attributes forclassValuesAsString
- whether to convert Class references into Strings (for compatibility withAnnotationMetadata
) or to preserve them as Class references- Returns:
- the Map of annotation attributes, with attribute names as keys and corresponding attribute values as values (never
null
) - See Also:
getAnnotationAttributes(Annotation, boolean, boolean)
getAnnotationAttributes
public static AnnotationAttributes getAnnotationAttributes(Annotation annotation, boolean classValuesAsString, boolean nestedAnnotationsAsMap)
Retrieve the given annotation's attributes as anAnnotationAttributes
map.This method provides fully recursive annotation reading capabilities on par with the reflection-based
StandardAnnotationMetadata
.- Parameters:
annotation
- the annotation to retrieve the attributes forclassValuesAsString
- whether to convert Class references into Strings (for compatibility withAnnotationMetadata
) or to preserve them as Class referencesnestedAnnotationsAsMap
- whether to convert nested annotations intoAnnotationAttributes
maps (for compatibility withAnnotationMetadata
) or to preserve them asAnnotation
instances- Returns:
- the annotation attributes (a specialized Map) with attribute names as keys and corresponding attribute values as values (never
null
) - Since:
- 3.1.1
getAnnotationAttributes
public static AnnotationAttributes getAnnotationAttributes(AnnotatedElement annotatedElement, Annotation annotation)
Retrieve the given annotation's attributes as anAnnotationAttributes
map.Equivalent to calling
getAnnotationAttributes(AnnotatedElement, Annotation, boolean, boolean)
with theclassValuesAsString
andnestedAnnotationsAsMap
parameters set tofalse
.- Parameters:
annotatedElement
- the element that is annotated with the supplied annotation; may benull
if unknownannotation
- the annotation to retrieve the attributes for- Returns:
- the annotation attributes (a specialized Map) with attribute names as keys and corresponding attribute values as values (never
null
) - Since:
- 4.2
- See Also:
getAnnotationAttributes(AnnotatedElement, Annotation, boolean, boolean)
getAnnotationAttributes
public static AnnotationAttributes getAnnotationAttributes(AnnotatedElement annotatedElement, Annotation annotation, boolean classValuesAsString, boolean nestedAnnotationsAsMap)
Retrieve the given annotation's attributes as anAnnotationAttributes
map.This method provides fully recursive annotation reading capabilities on par with the reflection-based
StandardAnnotationMetadata
.- Parameters:
annotatedElement
- the element that is annotated with the supplied annotation; may benull
if unknownannotation
- the annotation to retrieve the attributes forclassValuesAsString
- whether to convert Class references into Strings (for compatibility withAnnotationMetadata
) or to preserve them as Class referencesnestedAnnotationsAsMap
- whether to convert nested annotations intoAnnotationAttributes
maps (for compatibility withAnnotationMetadata
) or to preserve them asAnnotation
instances- Returns:
- the annotation attributes (a specialized Map) with attribute names as keys and corresponding attribute values as values (never
null
) - Since:
- 4.2
registerDefaultValues
public static void registerDefaultValues(AnnotationAttributes attributes)
Register the annotation-declared default values for the given attributes, if available.- Parameters:
attributes
- the annotation attributes to process- Since:
- 4.3.2
postProcessAnnotationAttributes
public static void postProcessAnnotationAttributes(Object annotatedElement, AnnotationAttributes attributes, boolean classValuesAsString)
Post-process the suppliedAnnotationAttributes
, preserving nested annotations asAnnotation
instances.Specifically, this method enforces attribute alias semantics for annotation attributes that are annotated with
@AliasFor
and replaces default value placeholders with their original default values.- Parameters:
annotatedElement
- the element that is annotated with an annotation or annotation hierarchy from which the supplied attributes were created; may benull
if unknownattributes
- the annotation attributes to post-processclassValuesAsString
- whether to convert Class references into Strings (for compatibility withAnnotationMetadata
) or to preserve them as Class references- Since:
- 4.3.2
- See Also:
postProcessAnnotationAttributes(Object, AnnotationAttributes, boolean, boolean)
,getDefaultValue(Class, String)
getValue
public static Object getValue(Annotation annotation)
Retrieve the value of thevalue
attribute of a single-element Annotation, given an annotation instance.- Parameters:
annotation
- the annotation instance from which to retrieve the value- Returns:
- the attribute value, or
null
if not found unless the attribute value cannot be retrieved due to anAnnotationConfigurationException
, in which case such an exception will be rethrown - See Also:
getValue(Annotation, String)
getValue
public static Object getValue(Annotation annotation, String attributeName)
Retrieve the value of a named attribute, given an annotation instance.- Parameters:
annotation
- the annotation instance from which to retrieve the valueattributeName
- the name of the attribute value to retrieve- Returns:
- the attribute value, or
null
if not found unless the attribute value cannot be retrieved due to anAnnotationConfigurationException
, in which case such an exception will be rethrown - See Also:
getValue(Annotation)
,rethrowAnnotationConfigurationException(Throwable)
getDefaultValue
public static Object getDefaultValue(Annotation annotation)
Retrieve the default value of thevalue
attribute of a single-element Annotation, given an annotation instance.- Parameters:
annotation
- the annotation instance from which to retrieve the default value- Returns:
- the default value, or
null
if not found - See Also:
getDefaultValue(Annotation, String)
getDefaultValue
public static Object getDefaultValue(Annotation annotation, String attributeName)
Retrieve the default value of a named attribute, given an annotation instance.- Parameters:
annotation
- the annotation instance from which to retrieve the default valueattributeName
- the name of the attribute value to retrieve- Returns:
- the default value of the named attribute, or
null
if not found - See Also:
getDefaultValue(Class, String)
getDefaultValue
public static Object getDefaultValue(Class<? extends Annotation> annotationType)
Retrieve the default value of thevalue
attribute of a single-element Annotation, given theannotation type
.- Parameters:
annotationType
- the annotation type for which the default value should be retrieved- Returns:
- the default value, or
null
if not found - See Also:
getDefaultValue(Class, String)
getDefaultValue
public static Object getDefaultValue(Class<? extends Annotation> annotationType, String attributeName)
Retrieve the default value of a named attribute, given theannotation type
.- Parameters:
annotationType
- the annotation type for which the default value should be retrievedattributeName
- the name of the attribute value to retrieve.- Returns:
- the default value of the named attribute, or
null
if not found - See Also:
getDefaultValue(Annotation, String)
synthesizeAnnotation
public static <A extends Annotation> A synthesizeAnnotation(A annotation, AnnotatedElement annotatedElement)
Synthesize an annotation from the suppliedannotation
by wrapping it in a dynamic proxy that transparently enforces attribute alias semantics for annotation attributes that are annotated with@AliasFor
.- Parameters:
annotation
- the annotation to synthesizeannotatedElement
- the element that is annotated with the supplied annotation; may benull
if unknown- Returns:
- the synthesized annotation if the supplied annotation is synthesizable;
null
if the supplied annotation isnull
; otherwise the supplied annotation unmodified - Throws:
AnnotationConfigurationException
- if invalid configuration of@AliasFor
is detected- Since:
- 4.2
- See Also:
synthesizeAnnotation(Map, Class, AnnotatedElement)
,synthesizeAnnotation(Class)
synthesizeAnnotation
public static <A extends Annotation> A synthesizeAnnotation(Map<String,Object> attributes, Class<A> annotationType, AnnotatedElement 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 specifiedannotationType
and transparently enforces attribute alias semantics for annotation attributes that are annotated with@AliasFor
.The supplied map must contain a key-value pair for every attribute defined in the supplied
annotationType
that is not aliased or does not have a default value. Nested maps and nested arrays of maps will be recursively synthesized into nested annotations or nested arrays of annotations, respectively.Note that
AnnotationAttributes
is a specialized type ofMap
that is an ideal candidate for this method'sattributes
argument.- Parameters:
attributes
- the map of annotation attributes to synthesizeannotationType
- the type of annotation to synthesizeannotatedElement
- the element that is annotated with the annotation corresponding to the supplied attributes; may benull
if unknown- Returns:
- the synthesized annotation, or
null
if the supplied attributes map isnull
- Throws:
IllegalArgumentException
- if a required attribute is missing or if an attribute is not of the correct typeAnnotationConfigurationException
- if invalid configuration of@AliasFor
is detected- Since:
- 4.2
- See Also:
synthesizeAnnotation(Annotation, AnnotatedElement)
,synthesizeAnnotation(Class)
,getAnnotationAttributes(AnnotatedElement, Annotation)
,getAnnotationAttributes(AnnotatedElement, Annotation, boolean, boolean)
synthesizeAnnotation
public static <A extends Annotation> A synthesizeAnnotation(Class<A> annotationType)
Synthesize an annotation from its default attributes values.This method simply delegates to
synthesizeAnnotation(Map, Class, AnnotatedElement)
, supplying an empty map for the source attribute values andnull
for theAnnotatedElement
.- Parameters:
annotationType
- the type of annotation to synthesize- Returns:
- the synthesized annotation
- Throws:
IllegalArgumentException
- if a required attribute is missingAnnotationConfigurationException
- if invalid configuration of@AliasFor
is detected- Since:
- 4.2
- See Also:
synthesizeAnnotation(Map, Class, AnnotatedElement)
,synthesizeAnnotation(Annotation, AnnotatedElement)
clearCache
public static void clearCache()
Clear the internal annotation metadata cache.- Since:
- 4.3.15