Class AnnotationSupport
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:
-
Method Summary
Modifier and TypeMethodDescriptionfindAnnotatedFields
(Class<?> clazz, Class<? extends Annotation> annotationType) Find all fields of the supplied class or interface that are annotated or meta-annotated with the specifiedannotationType
, using top-down search semantics within the type hierarchy.findAnnotatedFields
(Class<?> clazz, Class<? extends Annotation> annotationType, Predicate<Field> predicate, HierarchyTraversalMode traversalMode) Find all fields of the supplied class or interface that are annotated or meta-annotated with the specifiedannotationType
and match the specifiedpredicate
, using the supplied hierarchy traversal mode.findAnnotatedFieldValues
(Class<?> clazz, Class<? extends Annotation> annotationType) Find the values of all static fields of the supplied class or interface that are annotated or meta-annotated with the specifiedannotationType
, using top-down search semantics within the type hierarchy.static <T> List<T>
findAnnotatedFieldValues
(Class<?> clazz, Class<? extends Annotation> annotationType, Class<T> fieldType) Find the values of all static fields of the supplied class or interface that are declared to be of the specifiedfieldType
and are annotated or meta-annotated with the specifiedannotationType
, using top-down search semantics within the type hierarchy.findAnnotatedFieldValues
(Object instance, Class<? extends Annotation> annotationType) Find the values of all non-static fields of the suppliedinstance
that are annotated or meta-annotated with the specifiedannotationType
, using top-down search semantics within the type hierarchy.static <T> List<T>
findAnnotatedFieldValues
(Object instance, Class<? extends Annotation> annotationType, Class<T> fieldType) Find the values of all non-static fields of the suppliedinstance
that are declared to be of the specifiedfieldType
and are annotated or meta-annotated with the specifiedannotationType
, using top-down search semantics within the type hierarchy.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 specifiedannotationType
.static <A extends Annotation>
Optional<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.static <A extends Annotation>
Optional<A>findAnnotation
(AnnotatedElement element, Class<A> annotationType) Find the first annotation ofannotationType
that is either directly present, meta-present, or indirectly present on the suppliedelement
.static <A extends Annotation>
Optional<A>findAnnotation
(Optional<? extends AnnotatedElement> element, Class<A> annotationType) Find the first annotation ofannotationType
that is either present or meta-present on the supplied optionalelement
.findPublicAnnotatedFields
(Class<?> clazz, Class<?> fieldType, Class<? extends Annotation> annotationType) Find allpublic
fields of the supplied class or interface that are declared to be of the specifiedfieldType
and are annotated or meta-annotated with the specifiedannotationType
.static <A extends Annotation>
List<A>findRepeatableAnnotations
(AnnotatedElement element, Class<A> annotationType) Find all repeatable annotations of the suppliedannotationType
that are either present, indirectly present, or meta-present on the suppliedAnnotatedElement
.static <A extends Annotation>
List<A>findRepeatableAnnotations
(Optional<? extends AnnotatedElement> element, Class<A> annotationType) Find all repeatable annotations of the suppliedannotationType
that are either present, indirectly present, or meta-present on the supplied optionalelement
.static boolean
isAnnotated
(AnnotatedElement element, Class<? extends Annotation> annotationType) Determine if an annotation ofannotationType
is either present or meta-present on the suppliedelement
.static boolean
isAnnotated
(Optional<? extends AnnotatedElement> element, Class<? extends Annotation> annotationType) Determine if an annotation ofannotationType
is either present or meta-present on the supplied optionalelement
.
-
Method Details
-
isAnnotated
@API(status=MAINTAINED, since="1.3") public static boolean isAnnotated(Optional<? extends AnnotatedElement> element, Class<? extends Annotation> annotationType) Determine if an annotation ofannotationType
is either present or meta-present on the supplied optionalelement
.- Parameters:
element
- anOptional
containing the element on which to search for the annotation; may benull
or emptyannotationType
- the annotation type to search for; nevernull
- Returns:
true
if the annotation is present or meta-present- Since:
- 1.3
- See Also:
-
isAnnotated
public static boolean isAnnotated(AnnotatedElement element, Class<? extends Annotation> annotationType) Determine if an annotation ofannotationType
is either present or meta-present on the suppliedelement
.- Parameters:
element
- the element on which to search for the annotation; may benull
annotationType
- the annotation type to search for; nevernull
- Returns:
true
if the annotation is present or meta-present- See Also:
-
findAnnotation
@API(status=MAINTAINED, since="1.1") public static <A extends Annotation> Optional<A> findAnnotation(Optional<? extends AnnotatedElement> element, Class<A> annotationType) Find the first annotation ofannotationType
that is either present or meta-present on the supplied optionalelement
.- Type Parameters:
A
- the annotation type- Parameters:
element
- anOptional
containing the element on which to search for the annotation; may benull
or emptyannotationType
- the annotation type to search for; nevernull
- Returns:
- an
Optional
containing the annotation; nevernull
but potentially empty - Since:
- 1.1
- See Also:
-
findAnnotation
public static <A extends Annotation> Optional<A> findAnnotation(AnnotatedElement element, Class<A> annotationType) Find the first annotation ofannotationType
that is either directly present, meta-present, or indirectly present on the suppliedelement
.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 benull
annotationType
- the annotation type to search for; nevernull
- Returns:
- an
Optional
containing the annotation; nevernull
but potentially empty
-
findAnnotation
@API(status=EXPERIMENTAL, since="1.8") public static <A extends Annotation> Optional<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 asfindAnnotation(AnnotatedElement, Class)
.- Type Parameters:
A
- the annotation type- Parameters:
clazz
- the class on which to search for the annotation; may benull
annotationType
- the annotation type to search for; nevernull
searchOption
- theSearchOption
to use; nevernull
- Returns:
- an
Optional
containing the annotation; nevernull
but potentially empty - Since:
- 1.8
- See Also:
-
findRepeatableAnnotations
@API(status=MAINTAINED, since="1.5") public static <A extends Annotation> List<A> findRepeatableAnnotations(Optional<? extends AnnotatedElement> element, Class<A> annotationType) Find all repeatable annotations of the suppliedannotationType
that are either present, indirectly present, or meta-present on the supplied optionalelement
.See
findRepeatableAnnotations(AnnotatedElement, Class)
for details of the algorithm used.- Type Parameters:
A
- the annotation type- Parameters:
element
- anOptional
containing the element on which to search for the annotation; may benull
or emptyannotationType
- the repeatable annotation type to search for; nevernull
- Returns:
- an immutable list of all such annotations found; never
null
- Since:
- 1.5
- See Also:
-
findRepeatableAnnotations
public static <A extends Annotation> List<A> findRepeatableAnnotations(AnnotatedElement element, Class<A> annotationType) Find all repeatable annotations of the suppliedannotationType
that are either present, indirectly present, or meta-present on the suppliedAnnotatedElement
.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
isnull
, 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 benull
annotationType
- the repeatable annotation type to search for; nevernull
- Returns:
- an immutable list of all such annotations found; never
null
- See Also:
-
findPublicAnnotatedFields
public static List<Field> findPublicAnnotatedFields(Class<?> clazz, Class<?> fieldType, Class<? extends Annotation> annotationType) Find allpublic
fields of the supplied class or interface that are declared to be of the specifiedfieldType
and are annotated or meta-annotated with the specifiedannotationType
.Consult the Javadoc for
Class.getFields()
for details on inheritance and ordering.- Parameters:
clazz
- the class or interface in which to find the fields; nevernull
fieldType
- the declared type of fields to find; nevernull
annotationType
- the annotation type to search for; nevernull
- Returns:
- the list of all such fields found; neither
null
nor mutable - See Also:
-
findAnnotatedFields
@API(status=MAINTAINED, since="1.4") public static List<Field> findAnnotatedFields(Class<?> clazz, Class<? extends Annotation> annotationType) Find all fields of the supplied class or interface that are annotated or meta-annotated with the specifiedannotationType
, using top-down search semantics within the type hierarchy.Fields declared in the same class or interface will be ordered using an algorithm that is deterministic but intentionally nonobvious.
The results will not contain fields that are hidden or synthetic.
- Parameters:
clazz
- the class or interface in which to find the fields; nevernull
annotationType
- the annotation type to search for; nevernull
- Returns:
- the list of all such fields found; neither
null
nor mutable - Since:
- 1.4
- See Also:
-
findAnnotatedFields
@API(status=MAINTAINED, since="1.4") public static List<Field> findAnnotatedFields(Class<?> clazz, Class<? extends Annotation> annotationType, Predicate<Field> predicate, HierarchyTraversalMode traversalMode) Find all fields of the supplied class or interface that are annotated or meta-annotated with the specifiedannotationType
and match the specifiedpredicate
, using the supplied hierarchy traversal mode.Fields declared in the same class or interface will be ordered using an algorithm that is deterministic but intentionally nonobvious.
The results will not contain fields that are hidden or synthetic.
- Parameters:
clazz
- the class or interface in which to find the fields; nevernull
annotationType
- the annotation type to search for; nevernull
predicate
- the field filter; nevernull
traversalMode
- the hierarchy traversal mode; nevernull
- Returns:
- the list of all such fields found; neither
null
nor mutable - Since:
- 1.4
- See Also:
-
findAnnotatedFieldValues
@API(status=MAINTAINED, since="1.4") public static List<Object> findAnnotatedFieldValues(Object instance, Class<? extends Annotation> annotationType) Find the values of all non-static fields of the suppliedinstance
that are annotated or meta-annotated with the specifiedannotationType
, using top-down search semantics within the type hierarchy.Values from fields declared in the same class or interface will be ordered using an algorithm that is deterministic but intentionally nonobvious.
The results will not contain values from fields that are hidden or synthetic.
- Parameters:
instance
- the instance in which to find the fields; nevernull
annotationType
- the annotation type to search for; nevernull
- Returns:
- the list of all such field values found; neither
null
nor mutable - Since:
- 1.4
- See Also:
-
findAnnotatedFieldValues
@API(status=MAINTAINED, since="1.4") public static List<Object> findAnnotatedFieldValues(Class<?> clazz, Class<? extends Annotation> annotationType) Find the values of all static fields of the supplied class or interface that are annotated or meta-annotated with the specifiedannotationType
, using top-down search semantics within the type hierarchy.Values from fields declared in the same class or interface will be ordered using an algorithm that is deterministic but intentionally nonobvious.
The results will not contain values from fields that are hidden or synthetic.
- Parameters:
clazz
- the class or interface in which to find the fields; nevernull
annotationType
- the annotation type to search for; nevernull
- Returns:
- the list of all such field values found; neither
null
nor mutable - Since:
- 1.4
- See Also:
-
findAnnotatedFieldValues
@API(status=MAINTAINED, since="1.4") public static <T> List<T> findAnnotatedFieldValues(Object instance, Class<? extends Annotation> annotationType, Class<T> fieldType) Find the values of all non-static fields of the suppliedinstance
that are declared to be of the specifiedfieldType
and are annotated or meta-annotated with the specifiedannotationType
, using top-down search semantics within the type hierarchy.Values from fields declared in the same class or interface will be ordered using an algorithm that is deterministic but intentionally nonobvious.
The results will not contain values from fields that are hidden or synthetic.
- Parameters:
instance
- the instance in which to find the fields; nevernull
annotationType
- the annotation type to search for; nevernull
fieldType
- the declared type of fields to find; nevernull
- Returns:
- the list of all such field values found; neither
null
nor mutable - Since:
- 1.4
- See Also:
-
findAnnotatedFieldValues
@API(status=MAINTAINED, since="1.4") public static <T> List<T> findAnnotatedFieldValues(Class<?> clazz, Class<? extends Annotation> annotationType, Class<T> fieldType) Find the values of all static fields of the supplied class or interface that are declared to be of the specifiedfieldType
and are annotated or meta-annotated with the specifiedannotationType
, using top-down search semantics within the type hierarchy.Values from fields declared in the same class or interface will be ordered using an algorithm that is deterministic but intentionally nonobvious.
The results will not contain values from fields that are hidden or synthetic.
- Parameters:
clazz
- the class or interface in which to find the fields; nevernull
annotationType
- the annotation type to search for; nevernull
fieldType
- the declared type of fields to find; nevernull
- Returns:
- the list of all such field values found; neither
null
nor mutable - Since:
- 1.4
- See Also:
-
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 specifiedannotationType
.- Parameters:
clazz
- the class or interface in which to find the methods; nevernull
annotationType
- the annotation type to search for; nevernull
traversalMode
- the hierarchy traversal mode; nevernull
- Returns:
- the list of all such methods found; neither
null
nor mutable
-