Class AnnotationSupport


  • @API(status=MAINTAINED,
         since="1.0")
    public final class AnnotationSupport
    extends Object
    AnnotationSupport provides static utility methods for common tasks regarding annotations — for example, checking if a class, method, or field is annotated with a particular annotation; finding annotations on a given class, method, or field; finding fields or methods annotated with a particular annotation, etc.

    TestEngine and extension authors are encouraged to use these supported methods in order to align with the behavior of the JUnit Platform.

    Since:
    1.0
    See Also:
    ClassSupport, ModifierSupport, ReflectionSupport
    • Method Detail

      • isAnnotated

        @API(status=MAINTAINED,
             since="1.3")
        public static boolean isAnnotated​(Optional<? extends AnnotatedElement> element,
                                          Class<? extends Annotation> annotationType)
        Determine if an annotation of annotationType is either present or meta-present on the supplied optional element.
        Parameters:
        element - an Optional containing the element on which to search for the annotation; may be null or empty
        annotationType - the annotation type to search for; never null
        Returns:
        true if the annotation is present or meta-present
        Since:
        1.3
        See Also:
        isAnnotated(AnnotatedElement, Class), findAnnotation(Optional, Class)
      • isAnnotated

        public static boolean isAnnotated​(AnnotatedElement element,
                                          Class<? extends Annotation> annotationType)
        Determine if an annotation of annotationType is either present or meta-present on the supplied element.
        Parameters:
        element - the element on which to search for the annotation; may be null
        annotationType - the annotation type to search for; never null
        Returns:
        true if the annotation is present or meta-present
        See Also:
        isAnnotated(Optional, Class), findAnnotation(AnnotatedElement, Class)
      • findAnnotation

        @API(status=MAINTAINED,
             since="1.1")
        public static <A extends AnnotationOptional<A> findAnnotation​(Optional<? extends AnnotatedElement> element,
                                                                        Class<A> annotationType)
        Find the first annotation of annotationType that is either present or meta-present on the supplied optional element.
        Type Parameters:
        A - the annotation type
        Parameters:
        element - an Optional containing the element on which to search for the annotation; may be null or empty
        annotationType - the annotation type to search for; never null
        Returns:
        an Optional containing the annotation; never null but potentially empty
        Since:
        1.1
        See Also:
        findAnnotation(AnnotatedElement, Class)
      • findAnnotation

        public static <A extends AnnotationOptional<A> findAnnotation​(AnnotatedElement element,
                                                                        Class<A> annotationType)
        Find the first annotation of annotationType that is either directly present, meta-present, or indirectly present on the supplied element.

        If the element is a class and the annotation is neither directly present nor meta-present on the class, this method will additionally search on interfaces implemented by the class before finding an annotation that is indirectly present on the class.

        Type Parameters:
        A - the annotation type
        Parameters:
        element - the element on which to search for the annotation; may be null
        annotationType - the annotation type to search for; never null
        Returns:
        an Optional containing the annotation; never null but potentially empty
      • findAnnotation

        @API(status=EXPERIMENTAL,
             since="1.8")
        public static <A extends AnnotationOptional<A> findAnnotation​(Class<?> clazz,
                                                                        Class<A> annotationType,
                                                                        SearchOption searchOption)
        Find the first annotation of the specified type that is either directly present, meta-present, or indirectly present on the supplied class.

        If the annotation is neither directly present nor meta-present on the class, this method will additionally search on interfaces implemented by the class before searching for an annotation that is indirectly present on the class (i.e., within the class inheritance hierarchy).

        If the annotation still has not been found, this method will optionally search recursively through the enclosing class hierarchy if SearchOption.INCLUDE_ENCLOSING_CLASSES is specified.

        If SearchOption.DEFAULT is specified, this method has the same semantics as findAnnotation(AnnotatedElement, Class).

        Type Parameters:
        A - the annotation type
        Parameters:
        clazz - the class on which to search for the annotation; may be null
        annotationType - the annotation type to search for; never null
        searchOption - the SearchOption to use; never null
        Returns:
        an Optional containing the annotation; never null but potentially empty
        Since:
        1.8
        See Also:
        SearchOption, findAnnotation(AnnotatedElement, Class)
      • findRepeatableAnnotations

        public static <A extends AnnotationList<A> findRepeatableAnnotations​(AnnotatedElement element,
                                                                               Class<A> annotationType)
        Find all repeatable annotations of the supplied annotationType that are either present, indirectly present, or meta-present on the supplied AnnotatedElement.

        This method extends the functionality of AnnotatedElement.getAnnotationsByType(Class) with additional support for meta-annotations.

        In addition, if the element is a class and the repeatable annotation is @Inherited, this method will search on superclasses first in order to support top-down semantics. The result is that this algorithm finds repeatable annotations that would be shadowed and therefore not visible according to Java's standard semantics for inherited, repeatable annotations, but most developers will naturally assume that all repeatable annotations in JUnit are discovered regardless of whether they are declared stand-alone, in a container, or as a meta-annotation (e.g., multiple declarations of @ExtendWith within a test class hierarchy).

        If the element is a class and the repeatable annotation is not discovered within the class hierarchy, this method will additionally search on interfaces implemented by each class in the hierarchy.

        If the supplied element is null, this method returns an empty list.

        As of JUnit Platform 1.5, the search algorithm will also find repeatable annotations used as meta-annotations on other repeatable annotations.

        Type Parameters:
        A - the annotation type
        Parameters:
        element - the element to search on; may be null
        annotationType - the repeatable annotation type to search for; never null
        Returns:
        an immutable list of all such annotations found; never null
        See Also:
        Repeatable, Inherited
      • findAnnotatedMethods

        public static List<Method> findAnnotatedMethods​(Class<?> clazz,
                                                        Class<? extends Annotation> annotationType,
                                                        HierarchyTraversalMode traversalMode)
        Find all methods of the supplied class or interface that are annotated or meta-annotated with the specified annotationType.
        Parameters:
        clazz - the class or interface in which to find the methods; never null
        annotationType - the annotation type to search for; never null
        traversalMode - the hierarchy traversal mode; never null
        Returns:
        the list of all such methods found; neither null nor mutable