@API(status=MAINTAINED,
since="1.0")
public final class AnnotationSupport
extends java.lang.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.
ClassSupport
,
ModifierSupport
,
ReflectionSupport
Modifier | Constructor and Description |
---|---|
private |
AnnotationSupport() |
Modifier and Type | Method and Description |
---|---|
static java.util.List<java.lang.reflect.Field> |
findAnnotatedFields(java.lang.Class<?> clazz,
java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)
Find all fields of the supplied class or interface
that are annotated or meta-annotated with the specified
annotationType , using top-down search semantics within the type
hierarchy. |
static java.util.List<java.lang.reflect.Field> |
findAnnotatedFields(java.lang.Class<?> clazz,
java.lang.Class<? extends java.lang.annotation.Annotation> annotationType,
java.util.function.Predicate<java.lang.reflect.Field> predicate,
HierarchyTraversalMode traversalMode)
Find all fields of the supplied class or interface
that are annotated or meta-annotated with the specified
annotationType and match the specified predicate , using
the supplied hierarchy traversal mode. |
static java.util.List<java.lang.Object> |
findAnnotatedFieldValues(java.lang.Class<?> clazz,
java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)
Find the values of all static fields of the supplied
class or interface that are annotated or meta-annotated with the
specified
annotationType , using top-down search semantics within
the type hierarchy. |
static <T> java.util.List<T> |
findAnnotatedFieldValues(java.lang.Class<?> clazz,
java.lang.Class<? extends java.lang.annotation.Annotation> annotationType,
java.lang.Class<T> fieldType)
Find the values of all static fields of the supplied
class or interface that are declared to be of the specified
fieldType and are annotated or meta-annotated with the
specified annotationType , using top-down search semantics within
the type hierarchy. |
static java.util.List<java.lang.Object> |
findAnnotatedFieldValues(java.lang.Object instance,
java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)
Find the values of all non-static fields of the supplied
instance that are annotated or meta-annotated with the
specified annotationType , using top-down search semantics within
the type hierarchy. |
static <T> java.util.List<T> |
findAnnotatedFieldValues(java.lang.Object instance,
java.lang.Class<? extends java.lang.annotation.Annotation> annotationType,
java.lang.Class<T> fieldType)
Find the values of all non-static fields of the supplied
instance that are declared to be of the specified fieldType
and are annotated or meta-annotated with the specified
annotationType , using top-down search semantics within the type
hierarchy. |
static java.util.List<java.lang.reflect.Method> |
findAnnotatedMethods(java.lang.Class<?> clazz,
java.lang.Class<? extends java.lang.annotation.Annotation> annotationType,
HierarchyTraversalMode traversalMode)
Find all methods of the supplied class or interface
that are annotated or meta-annotated with the specified
annotationType . |
static <A extends java.lang.annotation.Annotation> |
findAnnotation(java.lang.reflect.AnnotatedElement element,
java.lang.Class<A> annotationType)
Find the first annotation of
annotationType that is either
directly present, meta-present, or indirectly
present on the supplied element . |
static <A extends java.lang.annotation.Annotation> |
findAnnotation(java.util.Optional<? extends java.lang.reflect.AnnotatedElement> element,
java.lang.Class<A> annotationType)
Find the first annotation of
annotationType that is either
present or meta-present on the supplied optional
element . |
static java.util.List<java.lang.reflect.Field> |
findPublicAnnotatedFields(java.lang.Class<?> clazz,
java.lang.Class<?> fieldType,
java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)
Find all
public fields of the supplied class
or interface that are declared to be of the specified fieldType
and are annotated or meta-annotated with the specified
annotationType . |
static <A extends java.lang.annotation.Annotation> |
findRepeatableAnnotations(java.lang.reflect.AnnotatedElement element,
java.lang.Class<A> annotationType)
Find all repeatable annotations of
annotationType that are either present, indirectly
present, or meta-present on the supplied AnnotatedElement . |
static boolean |
isAnnotated(java.lang.reflect.AnnotatedElement element,
java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)
Determine if an annotation of
annotationType is either
present or meta-present on the supplied
element . |
static boolean |
isAnnotated(java.util.Optional<? extends java.lang.reflect.AnnotatedElement> element,
java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)
Determine if an annotation of
annotationType is either
present or meta-present on the supplied optional
element . |
@API(status=MAINTAINED, since="1.3") public static boolean isAnnotated(java.util.Optional<? extends java.lang.reflect.AnnotatedElement> element, java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)
annotationType
is either
present or meta-present on the supplied optional
element
.element
- an Optional
containing the element on which to
search for the annotation; may be null
or emptyannotationType
- the annotation type to search for; never null
true
if the annotation is present or meta-presentisAnnotated(AnnotatedElement, Class)
,
findAnnotation(Optional, Class)
public static boolean isAnnotated(java.lang.reflect.AnnotatedElement element, java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)
annotationType
is either
present or meta-present on the supplied
element
.element
- the element on which to search for the annotation; may be
null
annotationType
- the annotation type to search for; never null
true
if the annotation is present or meta-presentisAnnotated(Optional, Class)
,
findAnnotation(AnnotatedElement, Class)
@API(status=MAINTAINED, since="1.1") public static <A extends java.lang.annotation.Annotation> java.util.Optional<A> findAnnotation(java.util.Optional<? extends java.lang.reflect.AnnotatedElement> element, java.lang.Class<A> annotationType)
annotationType
that is either
present or meta-present on the supplied optional
element
.A
- the annotation typeelement
- an Optional
containing the element on which to
search for the annotation; may be null
or emptyannotationType
- the annotation type to search for; never null
Optional
containing the annotation; never null
but
potentially emptyfindAnnotation(AnnotatedElement, Class)
public static <A extends java.lang.annotation.Annotation> java.util.Optional<A> findAnnotation(java.lang.reflect.AnnotatedElement element, java.lang.Class<A> annotationType)
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.
A
- the annotation typeelement
- the element on which to search for the annotation; may be
null
annotationType
- the annotation type to search for; never null
Optional
containing the annotation; never null
but
potentially emptypublic static <A extends java.lang.annotation.Annotation> java.util.List<A> findRepeatableAnnotations(java.lang.reflect.AnnotatedElement element, java.lang.Class<A> annotationType)
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 simply
returns an empty list.
A
- the annotation typeelement
- the element to search on; may be null
annotationType
- the repeatable annotation type to search for; never null
null
nor mutableRepeatable
,
Inherited
public static java.util.List<java.lang.reflect.Field> findPublicAnnotatedFields(java.lang.Class<?> clazz, java.lang.Class<?> fieldType, java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)
public
fields of the supplied class
or interface that are declared to be of the specified fieldType
and are annotated or meta-annotated with the specified
annotationType
.
Consult the Javadoc for Class.getFields()
for details on
inheritance and ordering.
clazz
- the class or interface in which to find the fields; never null
fieldType
- the declared type of fields to find; never null
annotationType
- the annotation type to search for; never null
null
nor mutableClass.getFields()
,
Field.getType()
,
findAnnotatedFields(Class, Class)
,
findAnnotatedFields(Class, Class, Predicate, HierarchyTraversalMode)
,
ReflectionSupport.findFields(Class, Predicate, HierarchyTraversalMode)
,
ReflectionSupport.tryToReadFieldValue(Field, Object)
@API(status=MAINTAINED, since="1.4") public static java.util.List<java.lang.reflect.Field> findAnnotatedFields(java.lang.Class<?> clazz, java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)
annotationType
, 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.
clazz
- the class or interface in which to find the fields; never null
annotationType
- the annotation type to search for; never null
null
nor mutableClass.getDeclaredFields()
,
findPublicAnnotatedFields(Class, Class, Class)
,
findAnnotatedFields(Class, Class, Predicate, HierarchyTraversalMode)
,
ReflectionSupport.findFields(Class, Predicate, HierarchyTraversalMode)
,
ReflectionSupport.tryToReadFieldValue(Field, Object)
@API(status=MAINTAINED, since="1.4") public static java.util.List<java.lang.reflect.Field> findAnnotatedFields(java.lang.Class<?> clazz, java.lang.Class<? extends java.lang.annotation.Annotation> annotationType, java.util.function.Predicate<java.lang.reflect.Field> predicate, HierarchyTraversalMode traversalMode)
annotationType
and match the specified predicate
, 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.
clazz
- the class or interface in which to find the fields; never null
annotationType
- the annotation type to search for; never null
predicate
- the field filter; never null
traversalMode
- the hierarchy traversal mode; never null
null
nor mutableClass.getDeclaredFields()
,
findAnnotatedFields(Class, Class)
,
ReflectionSupport.findFields(Class, Predicate, HierarchyTraversalMode)
,
ReflectionSupport.tryToReadFieldValue(Field, Object)
@API(status=MAINTAINED, since="1.4") public static java.util.List<java.lang.Object> findAnnotatedFieldValues(java.lang.Object instance, java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)
instance
that are annotated or meta-annotated with the
specified annotationType
, 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.
instance
- the instance in which to find the fields; never null
annotationType
- the annotation type to search for; never null
null
nor mutablefindAnnotatedFields(Class, Class)
,
findAnnotatedFields(Class, Class, Predicate, HierarchyTraversalMode)
,
ReflectionSupport.findFields(Class, Predicate, HierarchyTraversalMode)
,
ReflectionSupport.tryToReadFieldValue(Field, Object)
@API(status=MAINTAINED, since="1.4") public static java.util.List<java.lang.Object> findAnnotatedFieldValues(java.lang.Class<?> clazz, java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)
annotationType
, 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.
clazz
- the class or interface in which to find the fields; never null
annotationType
- the annotation type to search for; never null
null
nor mutablefindAnnotatedFields(Class, Class)
,
findAnnotatedFields(Class, Class, Predicate, HierarchyTraversalMode)
,
ReflectionSupport.findFields(Class, Predicate, HierarchyTraversalMode)
,
ReflectionSupport.tryToReadFieldValue(Field, Object)
@API(status=MAINTAINED, since="1.4") public static <T> java.util.List<T> findAnnotatedFieldValues(java.lang.Object instance, java.lang.Class<? extends java.lang.annotation.Annotation> annotationType, java.lang.Class<T> fieldType)
instance
that are declared to be of the specified fieldType
and are annotated or meta-annotated with the specified
annotationType
, 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.
instance
- the instance in which to find the fields; never null
annotationType
- the annotation type to search for; never null
fieldType
- the declared type of fields to find; never null
null
nor mutableField.getType()
,
findAnnotatedFields(Class, Class)
,
findAnnotatedFields(Class, Class, Predicate, HierarchyTraversalMode)
,
ReflectionSupport.findFields(Class, Predicate, HierarchyTraversalMode)
,
ReflectionSupport.tryToReadFieldValue(Field, Object)
@API(status=MAINTAINED, since="1.4") public static <T> java.util.List<T> findAnnotatedFieldValues(java.lang.Class<?> clazz, java.lang.Class<? extends java.lang.annotation.Annotation> annotationType, java.lang.Class<T> fieldType)
fieldType
and are annotated or meta-annotated with the
specified annotationType
, 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.
clazz
- the class or interface in which to find the fields; never null
annotationType
- the annotation type to search for; never null
fieldType
- the declared type of fields to find; never null
null
nor mutableField.getType()
,
findAnnotatedFields(Class, Class)
,
findAnnotatedFields(Class, Class, Predicate, HierarchyTraversalMode)
,
ReflectionSupport.findFields(Class, Predicate, HierarchyTraversalMode)
,
ReflectionSupport.tryToReadFieldValue(Field, Object)
public static java.util.List<java.lang.reflect.Method> findAnnotatedMethods(java.lang.Class<?> clazz, java.lang.Class<? extends java.lang.annotation.Annotation> annotationType, HierarchyTraversalMode traversalMode)
annotationType
.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
null
nor mutable