org.springframework.core.annotation

Class 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 lookup on the given class level only (getAnnotation(Method, Class)) and 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
    See Also:
    AccessibleObject.getAnnotations(), Method.getAnnotation(Class)

    • Constructor Detail

      • AnnotationUtils

        public AnnotationUtils()

    • Method Detail

      • 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 type to look for, both locally and as a meta-annotation
        Returns:
        the matching annotation, or null if none found
        Since:
        3.1

      • findAnnotation

        public static <A extends Annotation> A findAnnotation(Method method,
                                      Class<A> annotationType)
        Get a single Annotation of annotationType from the supplied Method, traversing its super methods 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 type to look for
        Returns:
        the annotation found, or null if none

      • findAnnotation

        public static <A extends Annotation> A findAnnotation(Class<?> clazz,
                                      Class<A> annotationType)
        Find a single Annotation of annotationType from the supplied Class, traversing its interfaces and superclasses if no annotation can be found on the given class itself.

        This method explicitly handles class-level annotations which are not declared as inheritedas well as annotations on interfaces.

        The algorithm operates as follows: Searches for an annotation on the given class and returns it if found. Else searches all interfaces that the given class declares, returning the annotation from the first matching candidate, if any. Else proceeds with introspection of the superclass of the given class, checking the superclass itself; if no annotation found there, proceeds with the interfaces that the superclass declares. Recursing up through the entire superclass hierarchy if no match is found.

        Parameters:
        clazz - the class to look for annotations on
        annotationType - the annotation type to look for
        Returns:
        the annotation found, or null if none 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 type to look for, both locally and as a meta-annotation
        clazz - the class on which to check for the annotation (may be 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)

      • 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)
Group Id org.springframework
Artifact Id spring-core
Version 3.2.10.RELEASE
Last Release 6.0.2
Navigation Index Tree Deprecated Help
Last Updated 2014-07-16