Package org.junit.platform.commons.support

Class AnnotationSupport

java.lang.Object

org.junit.platform.commons.support.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 Summary

Modifier and Type	Method	Description
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 specified annotationType, using top-down search semantics within the type hierarchy.
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 specified annotationType and match the specified predicate, using the supplied hierarchy traversal mode.
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 specified annotationType, 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 specified fieldType and are annotated or meta-annotated with the specified annotationType, using top-down search semantics within the type hierarchy.
static List<Object>	findAnnotatedFieldValues(Object instance, Class<? extends 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> List<T>	findAnnotatedFieldValues(Object instance, Class<? extends Annotation> annotationType, 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 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.
static <A extends Annotation> Optional<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.
static <A extends Annotation> Optional<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.
static List<Field>	findPublicAnnotatedFields(Class<?> clazz, Class<?> fieldType, Class<? extends 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 Annotation> List<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.
static <A extends Annotation> List<A>	findRepeatableAnnotations(Optional<? extends 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 optional element.
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.
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.

Methods inherited from class java.lang.Object

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

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 Annotation> Optional<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 Annotation> Optional<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

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 supplied annotationType that are either present, indirectly present, or meta-present on the supplied optional element.

See findRepeatableAnnotations(AnnotatedElement, Class) for details of the algorithm used.

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 repeatable annotation type to search for; never null

Returns:

an immutable list of all such annotations found; never null

Since:

1.5

See Also:

Repeatable, Inherited, findRepeatableAnnotations(AnnotatedElement, Class)

findRepeatableAnnotations

public static <A extends Annotation> List<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 simply 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

findPublicAnnotatedFields

public static List<Field> findPublicAnnotatedFields(Class<?> clazz,
                                                    Class<?> fieldType,
                                                    Class<? extends 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.

Consult the Javadoc for Class.getFields() for details on inheritance and ordering.

Parameters:

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

Returns:

the list of all such fields found; neither null nor mutable

See Also:

Class.getFields(), Field.getType(), findAnnotatedFields(Class, Class), findAnnotatedFields(Class, Class, Predicate, HierarchyTraversalMode), ReflectionSupport.findFields(Class, Predicate, HierarchyTraversalMode), ReflectionSupport.tryToReadFieldValue(Field, Object)

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 specified 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.

Parameters:

clazz - the class or interface in which to find the fields; never null

annotationType - the annotation type to search for; never null

Returns:

the list of all such fields found; neither null nor mutable

Since:

1.4

See Also:

Class.getDeclaredFields(), findPublicAnnotatedFields(Class, Class, Class), findAnnotatedFields(Class, Class, Predicate, HierarchyTraversalMode), ReflectionSupport.findFields(Class, Predicate, HierarchyTraversalMode), ReflectionSupport.tryToReadFieldValue(Field, Object)

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 specified 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.

Parameters:

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

Returns:

the list of all such fields found; neither null nor mutable

Since:

1.4

See Also:

Class.getDeclaredFields(), findAnnotatedFields(Class, Class), ReflectionSupport.findFields(Class, Predicate, HierarchyTraversalMode), ReflectionSupport.tryToReadFieldValue(Field, Object)

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 supplied 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.

Parameters:

instance - the instance in which to find the fields; never null

annotationType - the annotation type to search for; never null

Returns:

the list of all such field values found; neither null nor mutable

Since:

1.4

See Also:

findAnnotatedFields(Class, Class), findAnnotatedFields(Class, Class, Predicate, HierarchyTraversalMode), ReflectionSupport.findFields(Class, Predicate, HierarchyTraversalMode), ReflectionSupport.tryToReadFieldValue(Field, Object)

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 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.

Parameters:

clazz - the class or interface in which to find the fields; never null

annotationType - the annotation type to search for; never null

Returns:

the list of all such field values found; neither null nor mutable

Since:

1.4

See Also:

findAnnotatedFields(Class, Class), findAnnotatedFields(Class, Class, Predicate, HierarchyTraversalMode), ReflectionSupport.findFields(Class, Predicate, HierarchyTraversalMode), ReflectionSupport.tryToReadFieldValue(Field, Object)

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 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.

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; never null

annotationType - the annotation type to search for; never null

fieldType - the declared type of fields to find; never null

Returns:

the list of all such field values found; neither null nor mutable

Since:

1.4

See Also:

Field.getType(), findAnnotatedFields(Class, Class), findAnnotatedFields(Class, Class, Predicate, HierarchyTraversalMode), ReflectionSupport.findFields(Class, Predicate, HierarchyTraversalMode), ReflectionSupport.tryToReadFieldValue(Field, Object)

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 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.

Parameters:

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

Returns:

the list of all such field values found; neither null nor mutable

Since:

1.4

See Also:

Field.getType(), findAnnotatedFields(Class, Class), findAnnotatedFields(Class, Class, Predicate, HierarchyTraversalMode), ReflectionSupport.findFields(Class, Predicate, HierarchyTraversalMode), ReflectionSupport.tryToReadFieldValue(Field, Object)

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