Top Description Fields Constructors Methods
org.junit.platform.commons.util

public final Class AnnotationUtils

extends Object
Class Inheritance
Annotations
@API
status:INTERNAL
since:1.0
Static Imports
java.util.Arrays.asList, .Objects.requireNonNull, org.apiguardian.api.API.Status.INTERNAL, org.junit.platform.commons.util.ReflectionUtils.isInnerClass
Collection of utilities for working with annotations.

DISCLAIMER

These utilities are intended solely for usage within the JUnit framework itself. Any usage by external parties is not supported. Use at your own risk!

Some utilities are published via the maintained AnnotationSupport class.

Since
1.0
See Also
Annotation, AnnotatedElement, org.junit.platform.commons.support.AnnotationSupport

Field Summary

Modifier and TypeField and Description
private static final ConcurrentHashMap<Class<? extends Annotation>, Boolean>
repeatableAnnotationContainerCache

Constructor Summary

AccessConstructor and Description
private
AnnotationUtils()

Method Summary

Modifier and TypeMethod and Description
public static List<Field>
findAnnotatedFields(Class<?> clazz, Class<? extends Annotation> annotationType, Predicate<Field> predicate)

public static List<Field>

Returns:

the list of all such fields found; neither null nor mutable
findAnnotatedFields(Class<?>
the class or interface in which to find the fields; never null
clazz, Class<? extends Annotation>
the annotation type to search for; never null
annotationType, Predicate<Field>
the field filter; never null
predicate, ReflectionUtils.HierarchyTraversalMode
the hierarchy traversal mode; never null
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.

public static List<Method>
findAnnotatedMethods(Class<?> clazz, Class<? extends Annotation> annotationType, ReflectionUtils.HierarchyTraversalMode traversalMode)

public static <A extends Annotation> Optional<A>
findAnnotation(@Nullable Optional<? extends AnnotatedElement> element, Class<A> annotationType)

public static <A extends Annotation> Optional<A>
findAnnotation(Parameter parameter, int index, Class<A> annotationType)

public static <A extends Annotation> Optional<A>
findAnnotation(@Nullable AnnotatedElement element, Class<A> annotationType)

private static <A extends Annotation> Optional<A>
findAnnotation(@Nullable AnnotatedElement element, Class<A> annotationType, boolean inherited, Set<Annotation> visited)

public static <
the annotation type
A extends Annotation> Optional<A>

Returns:

an Optional containing the annotation; never null but potentially empty
findAnnotation(@Nullable Class<?>
the class on which to search for the annotation; may be null
clazz, Class<A>
the annotation type to search for; never null
annotationType, boolean
whether the enclosing class hierarchy should be searched
searchEnclosingClasses)

Find the first annotation of the specified type that is either directly present, meta-present, or indirectly present on the supplied class, optionally searching recursively through the enclosing class hierarchy if not found on the supplied class.

private static <A extends Annotation> Optional<A>
findMetaAnnotation(Class<A> annotationType, Annotation[] candidates, boolean inherited, Set<Annotation> visited)

public static List<Field>
findPublicAnnotatedFields(Class<?> clazz, Class<?> fieldType, Class<? extends Annotation> annotationType)

public static <A extends Annotation> List<A>
findRepeatableAnnotations(@Nullable Optional<? extends AnnotatedElement> element, Class<A> annotationType)

public static <A extends Annotation> List<A>
findRepeatableAnnotations(Parameter parameter, int index, Class<A> annotationType)

public static <A extends Annotation> List<A>
findRepeatableAnnotations(@Nullable AnnotatedElement element, Class<A> annotationType)

private static <A extends Annotation> void
findRepeatableAnnotations(AnnotatedElement element, Class<A> annotationType, Class<? extends Annotation> containerType, boolean inherited, Set<A> found, Set<Annotation> visited)

private static <A extends Annotation> void
findRepeatableAnnotations(Annotation[] candidates, Class<A> annotationType, Class<? extends Annotation> containerType, boolean inherited, Set<A> found, Set<Annotation> visited)

private static @Nullable AnnotatedElement

Returns:

the supplied Parameter, or the effective Parameter if the aforementioned bug is detected, or null if the bug is detected and the supplied index is 0
getEffectiveAnnotatedParameter(Parameter parameter, int index)

Due to a bug in javac on JDK versions prior to JDK 9, looking up annotations directly on a Parameter will fail for inner class constructors.

public static boolean
isAnnotated(@Nullable 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.

public static boolean
isAnnotated(Parameter parameter, int index, Class<? extends Annotation> annotationType)

public static boolean

Returns:

true if the annotation is present or meta-present
isAnnotated(@Nullable AnnotatedElement
the element on which to search for the annotation; may be null
element, Class<? extends Annotation>
the annotation type to search for; never null
annotationType)

Determine if an annotation of annotationType is either present or meta-present on the supplied element.

private static boolean
isInJavaLangAnnotationPackage(Class<? extends Annotation> annotationType)

private static boolean
isRepeatableAnnotationContainer(Class<? extends Annotation> candidateContainerType)

Determine if the supplied annotation type is a container for a repeatable annotation.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

repeatableAnnotationContainerCacheback to summary
private static final ConcurrentHashMap<Class<? extends Annotation>, Boolean> repeatableAnnotationContainerCache

Constructor Detail

AnnotationUtilsback to summary
private AnnotationUtils()

Method Detail

findAnnotatedFieldsback to summary
public static List<Field> findAnnotatedFields(Class<?> clazz, Class<? extends Annotation> annotationType, Predicate<Field> predicate)
See Also
org.junit.platform.commons.support.AnnotationSupport#findAnnotatedFields(Class, Class, Predicate), findAnnotatedFields(Class, Class, Predicate, HierarchyTraversalMode)
findAnnotatedFieldsback to summary
public static List<Field> findAnnotatedFields(Class<?> clazz, Class<? extends Annotation> annotationType, Predicate<Field> predicate, ReflectionUtils.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.

Parameters
clazz:Class<?>

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

annotationType:Class<? extends Annotation>

the annotation type to search for; never null

predicate:Predicate<Field>

the field filter; never null

traversalMode:ReflectionUtils.HierarchyTraversalMode

the hierarchy traversal mode; never null

Returns:List<Field>

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

findAnnotatedMethodsback to summary
public static List<Method> findAnnotatedMethods(Class<?> clazz, Class<? extends Annotation> annotationType, ReflectionUtils.HierarchyTraversalMode traversalMode)
See Also
org.junit.platform.commons.support.AnnotationSupport#findAnnotatedMethods(Class, Class, org.junit.platform.commons.support.HierarchyTraversalMode)
findAnnotationback to summary
public static <A extends Annotation> Optional<A> findAnnotation(@Nullable Optional<? extends AnnotatedElement> element, Class<A> annotationType)
Annotations
@SuppressWarnings:OptionalAssignedToNull, NullableOptional
See Also
org.junit.platform.commons.support.AnnotationSupport#findAnnotation(Optional, Class)
findAnnotationback to summary
public static <A extends Annotation> Optional<A> findAnnotation(Parameter parameter, int index, Class<A> annotationType)
Since
1.8
See Also
findAnnotation(AnnotatedElement, Class)
findAnnotationback to summary
public static <A extends Annotation> Optional<A> findAnnotation(@Nullable AnnotatedElement element, Class<A> annotationType)
See Also
org.junit.platform.commons.support.AnnotationSupport#findAnnotation(AnnotatedElement, Class)
findAnnotationback to summary
private static <A extends Annotation> Optional<A> findAnnotation(@Nullable AnnotatedElement element, Class<A> annotationType, boolean inherited, Set<Annotation> visited)
findAnnotationback to summary
public static <A extends Annotation> Optional<A> findAnnotation(@Nullable Class<?> clazz, Class<A> annotationType, boolean searchEnclosingClasses)

Find the first annotation of the specified type that is either directly present, meta-present, or indirectly present on the supplied class, optionally searching recursively through the enclosing class hierarchy if not found on the supplied class.

The enclosing class hierarchy will only be searched above an inner class (i.e., a non-static member class).

Parameters
<A>
the annotation type
clazz:@Nullable Class<?>

the class on which to search for the annotation; may be null

annotationType:Class<A>

the annotation type to search for; never null

searchEnclosingClasses:boolean

whether the enclosing class hierarchy should be searched

Returns:Optional<A>

an Optional containing the annotation; never null but potentially empty

Since
1.8
See Also
findAnnotation(AnnotatedElement, Class)
findMetaAnnotationback to summary
private static <A extends Annotation> Optional<A> findMetaAnnotation(Class<A> annotationType, Annotation[] candidates, boolean inherited, Set<Annotation> visited)
findPublicAnnotatedFieldsback to summary
public static List<Field> findPublicAnnotatedFields(Class<?> clazz, Class<?> fieldType, Class<? extends Annotation> annotationType)
See Also
org.junit.platform.commons.support.AnnotationSupport#findPublicAnnotatedFields(Class, Class, Class)
findRepeatableAnnotationsback to summary
public static <A extends Annotation> List<A> findRepeatableAnnotations(@Nullable Optional<? extends AnnotatedElement> element, Class<A> annotationType)
Annotations
@SuppressWarnings:OptionalAssignedToNull, NullableOptional
Since
1.5
See Also
org.junit.platform.commons.support.AnnotationSupport#findRepeatableAnnotations(Optional, Class)
findRepeatableAnnotationsback to summary
public static <A extends Annotation> List<A> findRepeatableAnnotations(Parameter parameter, int index, Class<A> annotationType)
Since
1.8
See Also
findRepeatableAnnotations(AnnotatedElement, Class)
findRepeatableAnnotationsback to summary
public static <A extends Annotation> List<A> findRepeatableAnnotations(@Nullable AnnotatedElement element, Class<A> annotationType)
See Also
org.junit.platform.commons.support.AnnotationSupport#findRepeatableAnnotations(AnnotatedElement, Class)
findRepeatableAnnotationsback to summary
private static <A extends Annotation> void findRepeatableAnnotations(AnnotatedElement element, Class<A> annotationType, Class<? extends Annotation> containerType, boolean inherited, Set<A> found, Set<Annotation> visited)
findRepeatableAnnotationsback to summary
private static <A extends Annotation> void findRepeatableAnnotations(Annotation[] candidates, Class<A> annotationType, Class<? extends Annotation> containerType, boolean inherited, Set<A> found, Set<Annotation> visited)
Annotations
@SuppressWarnings:unchecked, GetClassOnAnnotation
getEffectiveAnnotatedParameterback to summary
private static @Nullable AnnotatedElement getEffectiveAnnotatedParameter(Parameter parameter, int index)

Due to a bug in javac on JDK versions prior to JDK 9, looking up annotations directly on a Parameter will fail for inner class constructors.

Bug in javac on JDK versions prior to JDK 9

The parameter annotations array in the compiled byte code for the user's class excludes an entry for the implicit enclosing instance parameter for an inner class constructor.

Workaround

This method provides a workaround for this off-by-one error by helping JUnit maintainers and extension authors to access annotations on the preceding Parameter object (i.e., index - 1). If the supplied index is zero in such situations this method will return null since the parameter for the implicit enclosing instance will never be annotated.

WARNING

The AnnotatedElement returned by this method should never be cast and treated as a Parameter since the metadata (e.g., Parameter#getName(), Parameter#getType(), etc.) will not match those for the declared parameter at the given index in an inner class constructor for code compiled with JDK 8.

Returns:@Nullable AnnotatedElement

the supplied Parameter, or the effective Parameter if the aforementioned bug is detected, or null if the bug is detected and the supplied index is 0

Since
1.8
isAnnotatedback to summary
public static boolean isAnnotated(@Nullable 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.

Annotations
@SuppressWarnings:NullableOptional
@Contract:null, _ -> false
See Also
findAnnotation(Optional, Class), org.junit.platform.commons.support.AnnotationSupport#isAnnotated(Optional, Class)
isAnnotatedback to summary
public static boolean isAnnotated(Parameter parameter, int index, Class<? extends Annotation> annotationType)
Since
1.8
See Also
findAnnotation(Parameter, int, Class)
isAnnotatedback to summary
public static boolean isAnnotated(@Nullable AnnotatedElement element, Class<? extends Annotation> annotationType)

Determine if an annotation of annotationType is either present or meta-present on the supplied element.

Parameters
element:@Nullable AnnotatedElement

the element on which to search for the annotation; may be null

annotationType:Class<? extends Annotation>

the annotation type to search for; never null

Returns:boolean

true if the annotation is present or meta-present

Annotations
@Contract:null, _ -> false
See Also
findAnnotation(AnnotatedElement, Class), org.junit.platform.commons.support.AnnotationSupport#isAnnotated(AnnotatedElement, Class)
isInJavaLangAnnotationPackageback to summary
private static boolean isInJavaLangAnnotationPackage(Class<? extends Annotation> annotationType)
isRepeatableAnnotationContainerback to summary
private static boolean isRepeatableAnnotationContainer(Class<? extends Annotation> candidateContainerType)

Determine if the supplied annotation type is a container for a repeatable annotation.

Since
1.5