org.springframework.core.annotation

## Class AnnotationUtils

- java.lang.Object
- - org.springframework.core.annotation.AnnotationUtils

-     public abstract class AnnotationUtils
      extends Object

  General utility methods for working with annotations, handling bridge methods (which the compiler generates for generic declarations) as well as super methods (for optional "annotation inheritance"). Note that none of this is provided by the JDK's introspection facilities themselves.

  As a general rule for runtime-retained annotations (e.g. for transaction control, authorization, or service exposure), always use the lookup methods on this class (e.g., `findAnnotation(Method, Class)`, `getAnnotation(Method, Class)`, and `getAnnotations(Method)`) 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)`).

  Since:
    2.0
  Author:
    Rob Harrop, Juergen Hoeller, Sam Brannen, Mark Fisher, Chris Beams, Phillip Webb
  See Also:
    `AccessibleObject.getAnnotations()`, `Method.getAnnotation(Class)`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `VALUE` The attribute name for annotations with a single element

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AnnotationUtils()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <A extends Annotation> A` | `findAnnotation(Class<?> clazz, Class<A> annotationType)` Find a single `Annotation` of `annotationType` on the supplied `Class`, traversing its interfaces, annotations, and superclasses if the annotation is not present on the given class itself.
    `static <A extends Annotation> A` | `findAnnotation(Method method, Class<A> annotationType)` Find a single `Annotation` of `annotationType` from the supplied `Method`, traversing its super methods (i.e., from super classes and interfaces) if no annotation can be found on the given method itself.
    `static Class<?>` | `findAnnotationDeclaringClass(Class<? extends Annotation> annotationType, Class<?> clazz)` Find the first `Class` in the inheritance hierarchy of the specified `clazz` (including the specified `clazz` itself) which declares an annotation for the specified `annotationType`, or `null` if not found.
    `static Class<?>` | `findAnnotationDeclaringClassForTypes(List<Class<? extends Annotation>> annotationTypes, Class<?> clazz)` Find the first `Class` in the inheritance hierarchy of the specified `clazz` (including the specified `clazz` itself) which declares at least one of the specified `annotationTypes`, or `null` if none of the specified annotation types could be found.
    `static <T extends Annotation> T` | `getAnnotation(AnnotatedElement ae, Class<T> annotationType)` Get a single `Annotation` of `annotationType` from the supplied Method, Constructor or Field.
    `static <T extends Annotation> T` | `getAnnotation(Annotation ann, Class<T> annotationType)` Get a single `Annotation` of `annotationType` from the supplied annotation: either the given annotation itself or a meta-annotation thereof.
    `static <A extends Annotation> A` | `getAnnotation(Method method, Class<A> annotationType)` Get a single `Annotation` of `annotationType` from the supplied `Method`.
    `static Map<String,Object>` | `getAnnotationAttributes(Annotation annotation)` Retrieve the given annotation's attributes as a Map, preserving all attribute types as-is.
    `static Map<String,Object>` | `getAnnotationAttributes(Annotation annotation, boolean classValuesAsString)` Retrieve the given annotation's attributes as a Map.
    `static AnnotationAttributes` | `getAnnotationAttributes(Annotation annotation, boolean classValuesAsString, boolean nestedAnnotationsAsMap)` Retrieve the given annotation's attributes as an `AnnotationAttributes` map structure.
    `static Annotation[]` | `getAnnotations(Method method)` Get all `Annotations` from the supplied `Method`.
    `static Object` | `getDefaultValue(Annotation annotation)` Retrieve the default value of the `&quot;value&quot;` attribute of a single-element Annotation, given an annotation instance.
    `static Object` | `getDefaultValue(Annotation annotation, String attributeName)` Retrieve the default value of a named Annotation attribute, given an annotation instance.
    `static Object` | `getDefaultValue(Class<? extends Annotation> annotationType)` Retrieve the default value of the `&quot;value&quot;` attribute of a single-element Annotation, given the `annotation type`.
    `static Object` | `getDefaultValue(Class<? extends Annotation> annotationType, String attributeName)` Retrieve the default value of a named Annotation attribute, given the `annotation type`.
    `static <A extends Annotation> Set<A>` | `getRepeatableAnnotation(AnnotatedElement annotatedElement, Class<? extends Annotation> containerAnnotationType, Class<A> annotationType)` Get the possibly repeating `Annotation`s of `annotationType` from the supplied `AnnotatedElement`.
    `static <A extends Annotation> Set<A>` | `getRepeatableAnnotation(Method method, Class<? extends Annotation> containerAnnotationType, Class<A> annotationType)` Get the possibly repeating `Annotation`s of `annotationType` from the supplied `Method`.
    `static Object` | `getValue(Annotation annotation)` Retrieve the value of the `&quot;value&quot;` attribute of a single-element Annotation, given an annotation instance.
    `static Object` | `getValue(Annotation annotation, String attributeName)` Retrieve the value of a named Annotation attribute, given an annotation instance.
    `static boolean` | `isAnnotationDeclaredLocally(Class<? extends Annotation> annotationType, Class<?> clazz)` Determine whether an annotation for the specified `annotationType` is declared locally on the supplied `clazz`.
    `static boolean` | `isAnnotationInherited(Class<? extends Annotation> annotationType, Class<?> clazz)` Determine whether an annotation for the specified `annotationType` is present on the supplied `clazz` and is inherited (i.e., not declared locally for the class).
    `static boolean` | `isInJavaLangAnnotationPackage(Annotation annotation)` Determine if the supplied `Annotation` is defined in the `java.lang.annotation` package.

    - ### Methods inherited from class java.lang.Object

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

- - ### 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 <T extends Annotation> T getAnnotation(Annotation ann,
                                                               Class<T> annotationType)

      Get a single `Annotation` of `annotationType` from the supplied annotation: either the given annotation itself or a meta-annotation thereof.
      Parameters:
        `ann` - the Annotation to check
        `annotationType` - the annotation class to look for, both locally and as a meta-annotation
      Returns:
        the matching annotation or `null` if not found
      Since:
        4.0

    - #### getAnnotation

          public static <T extends Annotation> T getAnnotation(AnnotatedElement ae,
                                                               Class<T> annotationType)

      Get a single `Annotation` of `annotationType` from the supplied Method, Constructor or Field. Meta-annotations will be searched if the annotation is not declared locally on the supplied element.
      Parameters:
        `ae` - the Method, Constructor or Field from which to get the annotation
        `annotationType` - the annotation class to look for, both locally and as a meta-annotation
      Returns:
        the matching annotation or `null` if not found
      Since:
        3.1

    - #### getAnnotations

          public static Annotation[] getAnnotations(Method method)

      Get all `Annotations` from the supplied `Method`.

      Correctly handles bridge `Methods` generated by the compiler.

      Parameters:
        `method` - the method to look for annotations on
      Returns:
        the annotations found
      See Also:
        `BridgeMethodResolver.findBridgedMethod(Method)`

    - #### getAnnotation

          public static <A extends Annotation> A getAnnotation(Method method,
                                                               Class<A> annotationType)

      Get a single `Annotation` of `annotationType` from the supplied `Method`.

      Correctly handles bridge `Methods` generated by the compiler.

      Parameters:
        `method` - the method to look for annotations on
        `annotationType` - the annotation class to look for
      Returns:
        the annotations found
      See Also:
        `BridgeMethodResolver.findBridgedMethod(Method)`

    - #### getRepeatableAnnotation

          public static <A extends Annotation> Set<A> getRepeatableAnnotation(Method method,
                                                                              Class<? extends Annotation> containerAnnotationType,
                                                                              Class<A> annotationType)

      Get the possibly repeating `Annotation`s of `annotationType` from the supplied `Method`. Deals with both a single direct annotation and repeating annotations nested within a containing annotation.

      Correctly handles bridge `Methods` generated by the compiler.

      Parameters:
        `method` - the method to look for annotations on
        `containerAnnotationType` - the class of the container that holds the annotations
        `annotationType` - the annotation class to look for
      Returns:
        the annotations found
      Since:
        4.0
      See Also:
        `BridgeMethodResolver.findBridgedMethod(Method)`

    - #### getRepeatableAnnotation

          public static <A extends Annotation> Set<A> getRepeatableAnnotation(AnnotatedElement annotatedElement,
                                                                              Class<? extends Annotation> containerAnnotationType,
                                                                              Class<A> annotationType)

      Get the possibly repeating `Annotation`s of `annotationType` from the supplied `AnnotatedElement`. Deals with both a single direct annotation and repeating annotations nested within a containing annotation.

      Correctly handles bridge `Methods` generated by the compiler.

      Parameters:
        `annotatedElement` - the element to look for annotations on
        `containerAnnotationType` - the class of the container that holds the annotations
        `annotationType` - the annotation class to look for
      Returns:
        the annotations found
      Since:
        4.0
      See Also:
        `BridgeMethodResolver.findBridgedMethod(Method)`

    - #### findAnnotation

          public static <A extends Annotation> A findAnnotation(Method method,
                                                                Class<A> annotationType)

      Find a single `Annotation` of `annotationType` from the supplied `Method`, traversing its super methods (i.e., from super classes and interfaces) if no annotation can be found on the given method itself.

      Annotations on methods are not inherited by default, so we need to handle this explicitly.

      Parameters:
        `method` - the method to look for annotations on
        `annotationType` - the annotation class to look for
      Returns:
        the annotation found, or `null` if none found

    - #### findAnnotation

          public static <A extends Annotation> A findAnnotation(Class<?> clazz,
                                                                Class<A> annotationType)

      Find a single `Annotation` of `annotationType` on the supplied `Class`, traversing its interfaces, annotations, and superclasses if the annotation is not 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:

      1. Search for the annotation on the given class and return it if found.
      2. Recursively search through all interfaces that the given class declares.
      3. Recursively search through all annotations that the given class declares.
      4. 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 on
        `annotationType` - the type of annotation to look for
      Returns:
        the annotation if found, or `null` if not found

    - #### findAnnotationDeclaringClass

          public static Class<?> findAnnotationDeclaringClass(Class<? extends Annotation> annotationType,
                                                              Class<?> clazz)

      Find the first `Class` in the inheritance hierarchy of the specified `clazz` (including the specified `clazz` itself) which declares an annotation for the specified `annotationType`, or `null` if not found. If the supplied `clazz` is `null`, `null` will be returned.

      If the supplied `clazz` is an interface, only the interface itself will be checked; the inheritance hierarchy for interfaces will not be traversed.

      The standard `Class` API does not provide a mechanism for determining which class in an inheritance hierarchy actually declares an `Annotation`, so we need to handle this explicitly.

      Parameters:
        `annotationType` - the annotation class to look for, both locally and as a meta-annotation
        `clazz` - the class on which to check for the annotation, or `null`
      Returns:
        the first `Class` in the inheritance hierarchy of the specified `clazz` which declares an annotation for the specified `annotationType`, or `null` 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 first `Class` in the inheritance hierarchy of the specified `clazz` (including the specified `clazz` itself) which declares at least one of the specified `annotationTypes`, or `null` if none of the specified annotation types could be found.

      If the supplied `clazz` is `null`, `null` will be returned.

      If the supplied `clazz` is an interface, only the interface itself will be checked; the inheritance hierarchy for interfaces will not be traversed.

      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 list of Class objects corresponding to the annotation types
        `clazz` - the Class object corresponding to the class on which to check for the annotations, or `null`
      Returns:
        the first `Class` in the inheritance hierarchy of the specified `clazz` which declares an annotation of at least one of the specified `annotationTypes`, or `null` 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 for the specified `annotationType` is declared locally on the supplied `clazz`. The supplied `Class` may represent any type.

      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 Class object corresponding to the annotation type
        `clazz` - the Class object corresponding to the class on which to check for the annotation
      Returns:
        `true` if an annotation for the specified `annotationType` is declared locally on the supplied `clazz`
      See Also:
        `Class.getDeclaredAnnotations()`, `isAnnotationInherited(Class, Class)`

    - #### isAnnotationInherited

          public static boolean isAnnotationInherited(Class<? extends Annotation> annotationType,
                                                      Class<?> clazz)

      Determine whether an annotation for the specified `annotationType` is present on the supplied `clazz` and is inherited (i.e., not declared locally for the class).

      If the supplied `clazz` is an interface, only the interface itself will be checked. In accordance with standard meta-annotation semantics, 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 Class object corresponding to the annotation type
        `clazz` - the Class object corresponding to the class on which to check for the annotation
      Returns:
        `true` if an annotation for the specified `annotationType` is present on the supplied `clazz` and is inherited
      See Also:
        `Class.isAnnotationPresent(Class)`, `isAnnotationDeclaredLocally(Class, Class)`

    - #### isInJavaLangAnnotationPackage

          public static boolean isInJavaLangAnnotationPackage(Annotation annotation)

      Determine if the supplied `Annotation` is defined in the `java.lang.annotation` package.
      Parameters:
        `annotation` - the annotation to check; never `null`
      Returns:
        `true` if the annotation is in the `java.lang.annotation` package

    - #### getAnnotationAttributes

          public static Map<String,Object> getAnnotationAttributes(Annotation annotation)

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

      Note: As of Spring 3.1.1, the returned map is actually an `AnnotationAttributes` instance, however the Map signature of this method 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

    - #### getAnnotationAttributes

          public static Map<String,Object> getAnnotationAttributes(Annotation annotation,
                                                                   boolean classValuesAsString)

      Retrieve the given annotation's attributes as a Map. Equivalent to calling `getAnnotationAttributes(Annotation, boolean, boolean)` with the `nestedAnnotationsAsMap` parameter set to `false`.

      Note: As of Spring 3.1.1, the returned map is actually an `AnnotationAttributes` instance, however the Map signature of this method has been preserved for binary compatibility.

      Parameters:
        `annotation` - the annotation to retrieve the attributes for
        `classValuesAsString` - whether to turn Class references into Strings (for compatibility with `AnnotationMetadata` or to preserve them as Class references
      Returns:
        the Map of annotation attributes, with attribute names as keys and corresponding attribute values as values

    - #### getAnnotationAttributes

          public static AnnotationAttributes getAnnotationAttributes(Annotation annotation,
                                                                     boolean classValuesAsString,
                                                                     boolean nestedAnnotationsAsMap)

      Retrieve the given annotation's attributes as an `AnnotationAttributes` map structure. Implemented in Spring 3.1.1 to provide fully recursive annotation reading capabilities on par with that of the reflection-based `StandardAnnotationMetadata`.
      Parameters:
        `annotation` - the annotation to retrieve the attributes for
        `classValuesAsString` - whether to turn Class references into Strings (for compatibility with `AnnotationMetadata` or to preserve them as Class references
        `nestedAnnotationsAsMap` - whether to turn nested Annotation instances into `AnnotationAttributes` maps (for compatibility with `AnnotationMetadata` or to preserve them as Annotation instances
      Returns:
        the annotation attributes (a specialized Map) with attribute names as keys and corresponding attribute values as values
      Since:
        3.1.1

    - #### getValue

          public static Object getValue(Annotation annotation)

      Retrieve the value of the `&quot;value&quot;` 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
      See Also:
        `getValue(Annotation, String)`

    - #### getValue

          public static Object getValue(Annotation annotation,
                                        String attributeName)

      Retrieve the value of a named Annotation attribute, given an annotation instance.
      Parameters:
        `annotation` - the annotation instance from which to retrieve the value
        `attributeName` - the name of the attribute value to retrieve
      Returns:
        the attribute value, or `null` if not found
      See Also:
        `getValue(Annotation)`

    - #### getDefaultValue

          public static Object getDefaultValue(Annotation annotation)

      Retrieve the default value of the `&quot;value&quot;` 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 Annotation attribute, given an annotation instance.
      Parameters:
        `annotation` - the annotation instance from which to retrieve the default value
        `attributeName` - 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 the `&quot;value&quot;` attribute of a single-element Annotation, given the `annotation 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 Annotation attribute, given the `annotation type`.
      Parameters:
        `annotationType` - the annotation type for which the default value should be retrieved
        `attributeName` - 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)`