Class ReflectionSupport
ReflectionSupport
provides static utility methods for common
reflection tasks — for example, scanning for classes in the class-path
or module-path, loading classes, finding methods, invoking methods, 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 TypeMethodDescriptionfindAllClassesInClasspathRoot
(URI root, Predicate<Class<?>> classFilter, Predicate<String> classNameFilter) Find all classes in the supplied classpathroot
that match the specifiedclassFilter
andclassNameFilter
predicates.findAllClassesInModule
(String moduleName, Predicate<Class<?>> classFilter, Predicate<String> classNameFilter) Find all classes in the suppliedmoduleName
that match the specifiedclassFilter
andclassNameFilter
predicates.findAllClassesInPackage
(String basePackageName, Predicate<Class<?>> classFilter, Predicate<String> classNameFilter) Find all classes in the suppliedbasePackageName
that match the specifiedclassFilter
andclassNameFilter
predicates.findFields
(Class<?> clazz, Predicate<Field> predicate, HierarchyTraversalMode traversalMode) Find all fields of the supplied class or interface that match the specifiedpredicate
.findMethod
(Class<?> clazz, String methodName, Class<?>... parameterTypes) Find the firstMethod
of the supplied class or interface that meets the specified criteria, beginning with the specified class or interface and traversing up the type hierarchy until such a method is found or the type hierarchy is exhausted.findMethod
(Class<?> clazz, String methodName, String parameterTypeNames) Find the firstMethod
of the supplied class or interface that meets the specified criteria, beginning with the specified class or interface and traversing up the type hierarchy until such a method is found or the type hierarchy is exhausted.findMethods
(Class<?> clazz, Predicate<Method> predicate, HierarchyTraversalMode traversalMode) Find all distinct methods of the supplied class or interface that match the specifiedpredicate
.findNestedClasses
(Class<?> clazz, Predicate<Class<?>> predicate) Find all nested classes within the supplied class, or inherited by the supplied class, that conform to the supplied predicate.static Object
invokeMethod
(Method method, Object target, Object... args) Invoke the supplied method, making it accessible if necessary and masking any checked exception as an unchecked exception.Deprecated.static <T> T
newInstance
(Class<T> clazz, Object... args) Create a new instance of the specifiedClass
by invoking the constructor whose argument list matches the types of the supplied arguments.streamAllClassesInClasspathRoot
(URI root, Predicate<Class<?>> classFilter, Predicate<String> classNameFilter) Find all classes in the supplied classpathroot
that match the specifiedclassFilter
andclassNameFilter
predicates.streamAllClassesInModule
(String moduleName, Predicate<Class<?>> classFilter, Predicate<String> classNameFilter) Find all classes in the suppliedmoduleName
that match the specifiedclassFilter
andclassNameFilter
predicates.streamAllClassesInPackage
(String basePackageName, Predicate<Class<?>> classFilter, Predicate<String> classNameFilter) Find all classes in the suppliedbasePackageName
that match the specifiedclassFilter
andclassNameFilter
predicates.streamFields
(Class<?> clazz, Predicate<Field> predicate, HierarchyTraversalMode traversalMode) Find all fields of the supplied class or interface that match the specifiedpredicate
.streamMethods
(Class<?> clazz, Predicate<Method> predicate, HierarchyTraversalMode traversalMode) Find all distinct methods of the supplied class or interface that match the specifiedpredicate
.streamNestedClasses
(Class<?> clazz, Predicate<Class<?>> predicate) Find all nested classes within the supplied class, or inherited by the supplied class, that conform to the supplied predicate.tryToLoadClass
(String name) Try to load a class by its primitive name or fully qualified name, using the defaultClassLoader
.tryToLoadClass
(String name, ClassLoader classLoader) Try to load a class by its primitive name or fully qualified name, using the suppliedClassLoader
.tryToReadFieldValue
(Field field, Object instance) Try to read the value of a potentially inaccessible field.
-
Method Details
-
loadClass
@API(status=DEPRECATED, since="1.4") @Deprecated public static Optional<Class<?>> loadClass(String name) Deprecated.Please usetryToLoadClass(String)
instead.Load a class by its primitive name or fully qualified name, using the defaultClassLoader
.Class names for arrays may be specified using either the JVM's internal String representation (e.g.,
[[I
forint[][]
,[Ljava.lang.String;
forjava.lang.String[]
, etc.) or source code syntax (e.g.,int[][]
,java.lang.String[]
, etc.).- Parameters:
name
- the name of the class to load; nevernull
or blank- Returns:
- an
Optional
containing the loaded class; nevernull
but potentially empty if no such class could be loaded
-
tryToLoadClass
Try to load a class by its primitive name or fully qualified name, using the defaultClassLoader
.Class names for arrays may be specified using either the JVM's internal String representation (e.g.,
[[I
forint[][]
,[Lava.lang.String;
forjava.lang.String[]
, etc.) or source code syntax (e.g.,int[][]
,java.lang.String[]
, etc.).- Parameters:
name
- the name of the class to load; nevernull
or blank- Returns:
- a successful
Try
containing the loaded class or a failedTry
containing the exception if no such class could be loaded; nevernull
- Since:
- 1.4
- See Also:
-
tryToLoadClass
@API(status=EXPERIMENTAL, since="1.10") public static Try<Class<?>> tryToLoadClass(String name, ClassLoader classLoader) Try to load a class by its primitive name or fully qualified name, using the suppliedClassLoader
.See
tryToLoadClass(String)
for details on support for class names for arrays.- Parameters:
name
- the name of the class to load; nevernull
or blankclassLoader
- theClassLoader
to use; nevernull
- Returns:
- a successful
Try
containing the loaded class or a failedTry
containing the exception if no such class could be loaded; nevernull
- Since:
- 1.10
- See Also:
-
findAllClassesInClasspathRoot
public static List<Class<?>> findAllClassesInClasspathRoot(URI root, Predicate<Class<?>> classFilter, Predicate<String> classNameFilter) Find all classes in the supplied classpathroot
that match the specifiedclassFilter
andclassNameFilter
predicates.The classpath scanning algorithm searches recursively in subpackages beginning with the root of the classpath.
- Parameters:
root
- the URI for the classpath root in which to scan; nevernull
classFilter
- the class type filter; nevernull
classNameFilter
- the class name filter; nevernull
- Returns:
- an immutable list of all such classes found; never
null
but potentially empty - See Also:
-
streamAllClassesInClasspathRoot
@API(status=MAINTAINED, since="1.10") public static Stream<Class<?>> streamAllClassesInClasspathRoot(URI root, Predicate<Class<?>> classFilter, Predicate<String> classNameFilter) Find all classes in the supplied classpathroot
that match the specifiedclassFilter
andclassNameFilter
predicates.The classpath scanning algorithm searches recursively in subpackages beginning with the root of the classpath.
- Parameters:
root
- the URI for the classpath root in which to scan; nevernull
classFilter
- the class type filter; nevernull
classNameFilter
- the class name filter; nevernull
- Returns:
- a stream of all such classes found; never
null
but potentially empty - Since:
- 1.10
- See Also:
-
findAllClassesInPackage
public static List<Class<?>> findAllClassesInPackage(String basePackageName, Predicate<Class<?>> classFilter, Predicate<String> classNameFilter) Find all classes in the suppliedbasePackageName
that match the specifiedclassFilter
andclassNameFilter
predicates.The classpath scanning algorithm searches recursively in subpackages beginning within the supplied base package.
- Parameters:
basePackageName
- the name of the base package in which to start scanning; must not benull
and must be valid in terms of Java syntaxclassFilter
- the class type filter; nevernull
classNameFilter
- the class name filter; nevernull
- Returns:
- an immutable list of all such classes found; never
null
but potentially empty - See Also:
-
streamAllClassesInPackage
@API(status=MAINTAINED, since="1.10") public static Stream<Class<?>> streamAllClassesInPackage(String basePackageName, Predicate<Class<?>> classFilter, Predicate<String> classNameFilter) Find all classes in the suppliedbasePackageName
that match the specifiedclassFilter
andclassNameFilter
predicates.The classpath scanning algorithm searches recursively in subpackages beginning within the supplied base package.
- Parameters:
basePackageName
- the name of the base package in which to start scanning; must not benull
and must be valid in terms of Java syntaxclassFilter
- the class type filter; nevernull
classNameFilter
- the class name filter; nevernull
- Returns:
- a stream of all such classes found; never
null
but potentially empty - Since:
- 1.10
- See Also:
-
findAllClassesInModule
public static List<Class<?>> findAllClassesInModule(String moduleName, Predicate<Class<?>> classFilter, Predicate<String> classNameFilter) Find all classes in the suppliedmoduleName
that match the specifiedclassFilter
andclassNameFilter
predicates.The module-path scanning algorithm searches recursively in all packages contained in the module.
- Parameters:
moduleName
- the name of the module to scan; nevernull
or emptyclassFilter
- the class type filter; nevernull
classNameFilter
- the class name filter; nevernull
- Returns:
- an immutable list of all such classes found; never
null
but potentially empty - Since:
- 1.1.1
- See Also:
-
streamAllClassesInModule
@API(status=MAINTAINED, since="1.10") public static Stream<Class<?>> streamAllClassesInModule(String moduleName, Predicate<Class<?>> classFilter, Predicate<String> classNameFilter) Find all classes in the suppliedmoduleName
that match the specifiedclassFilter
andclassNameFilter
predicates.The module-path scanning algorithm searches recursively in all packages contained in the module.
- Parameters:
moduleName
- the name of the module to scan; nevernull
or emptyclassFilter
- the class type filter; nevernull
classNameFilter
- the class name filter; nevernull
- Returns:
- a stream of all such classes found; never
null
but potentially empty - Since:
- 1.10
- See Also:
-
newInstance
Create a new instance of the specifiedClass
by invoking the constructor whose argument list matches the types of the supplied arguments.The constructor will be made accessible if necessary, and any checked exception will be masked as an unchecked exception.
- Parameters:
clazz
- the class to instantiate; nevernull
args
- the arguments to pass to the constructor, none of which may benull
- Returns:
- the new instance; never
null
- See Also:
-
invokeMethod
Invoke the supplied method, making it accessible if necessary and masking any checked exception as an unchecked exception.- Parameters:
method
- the method to invoke; nevernull
target
- the object on which to invoke the method; may benull
if the method isstatic
args
- the arguments to pass to the method- Returns:
- the value returned by the method invocation or
null
if the return type isvoid
- See Also:
-
findFields
@API(status=MAINTAINED, since="1.4") public static List<Field> findFields(Class<?> clazz, Predicate<Field> predicate, HierarchyTraversalMode traversalMode) Find all fields of the supplied class or interface that match the specifiedpredicate
.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
predicate
- the field filter; nevernull
traversalMode
- the hierarchy traversal mode; nevernull
- Returns:
- an immutable list of all such fields found; never
null
but potentially empty - Since:
- 1.4
-
streamFields
@API(status=MAINTAINED, since="1.10") public static Stream<Field> streamFields(Class<?> clazz, Predicate<Field> predicate, HierarchyTraversalMode traversalMode) Find all fields of the supplied class or interface that match the specifiedpredicate
.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
predicate
- the field filter; nevernull
traversalMode
- the hierarchy traversal mode; nevernull
- Returns:
- a stream of all such fields found; never
null
but potentially empty - Since:
- 1.10
-
tryToReadFieldValue
@API(status=MAINTAINED, since="1.4") public static Try<Object> tryToReadFieldValue(Field field, Object instance) Try to read the value of a potentially inaccessible field.If an exception occurs while reading the field, a failed
Try
is returned that contains the corresponding exception.- Parameters:
field
- the field to read; nevernull
instance
- the instance from which the value is to be read; may benull
for a static field- Since:
- 1.4
-
findMethod
public static Optional<Method> findMethod(Class<?> clazz, String methodName, String parameterTypeNames) Find the firstMethod
of the supplied class or interface that meets the specified criteria, beginning with the specified class or interface and traversing up the type hierarchy until such a method is found or the type hierarchy is exhausted.As of JUnit Platform 1.10, this method uses the
ClassLoader
of the suppliedclazz
to load parameter types instead of using the defaultClassLoader
, which allows parameter types to be resolved in differentClassLoader
arrangements.The algorithm does not search for methods in
Object
.- Parameters:
clazz
- the class or interface in which to find the method; nevernull
methodName
- the name of the method to find; nevernull
or emptyparameterTypeNames
- the fully qualified names of the types of parameters accepted by the method, if any, provided as a comma-separated list- Returns:
- an
Optional
containing the method found; nevernull
but potentially empty if no such method could be found - See Also:
-
findMethod
public static Optional<Method> findMethod(Class<?> clazz, String methodName, Class<?>... parameterTypes) Find the firstMethod
of the supplied class or interface that meets the specified criteria, beginning with the specified class or interface and traversing up the type hierarchy until such a method is found or the type hierarchy is exhausted.The algorithm does not search for methods in
Object
.- Parameters:
clazz
- the class or interface in which to find the method; nevernull
methodName
- the name of the method to find; nevernull
or emptyparameterTypes
- the types of parameters accepted by the method, if any; nevernull
- Returns:
- an
Optional
containing the method found; nevernull
but potentially empty if no such method could be found - See Also:
-
findMethods
public static List<Method> findMethods(Class<?> clazz, Predicate<Method> predicate, HierarchyTraversalMode traversalMode) Find all distinct methods of the supplied class or interface that match the specifiedpredicate
.The results will not contain instance methods that are overridden or
static
methods that are hidden.If you are looking for methods annotated with a certain annotation type, consider using
AnnotationSupport.findAnnotatedMethods(Class, Class, HierarchyTraversalMode)
.- Parameters:
clazz
- the class or interface in which to find the methods; nevernull
predicate
- the method filter; nevernull
traversalMode
- the hierarchy traversal mode; nevernull
- Returns:
- an immutable list of all such methods found; never
null
but potentially empty
-
streamMethods
@API(status=MAINTAINED, since="1.10") public static Stream<Method> streamMethods(Class<?> clazz, Predicate<Method> predicate, HierarchyTraversalMode traversalMode) Find all distinct methods of the supplied class or interface that match the specifiedpredicate
.The results will not contain instance methods that are overridden or
static
methods that are hidden.If you are looking for methods annotated with a certain annotation type, consider using
AnnotationSupport.findAnnotatedMethods(Class, Class, HierarchyTraversalMode)
.- Parameters:
clazz
- the class or interface in which to find the methods; nevernull
predicate
- the method filter; nevernull
traversalMode
- the hierarchy traversal mode; nevernull
- Returns:
- a stream of all such methods found; never
null
but potentially empty - Since:
- 1.10
-
findNestedClasses
public static List<Class<?>> findNestedClasses(Class<?> clazz, Predicate<Class<?>> predicate) throws JUnitException Find all nested classes within the supplied class, or inherited by the supplied class, that conform to the supplied predicate.This method does not search for nested classes recursively.
As of JUnit Platform 1.6, this method detects cycles in inner class hierarchies — from the supplied class up to the outermost enclosing class — and throws a
JUnitException
if such a cycle is detected. Cycles within inner class hierarchies below the supplied class are not detected by this method.- Parameters:
clazz
- the class to be searched; nevernull
predicate
- the predicate against which the list of nested classes is checked; nevernull
- Returns:
- an immutable list of all such classes found; never
null
but potentially empty - Throws:
JUnitException
- if a cycle is detected within an inner class hierarchy
-
streamNestedClasses
@API(status=MAINTAINED, since="1.10") public static Stream<Class<?>> streamNestedClasses(Class<?> clazz, Predicate<Class<?>> predicate) throws JUnitException Find all nested classes within the supplied class, or inherited by the supplied class, that conform to the supplied predicate.This method does not search for nested classes recursively.
As of JUnit Platform 1.6, this method detects cycles in inner class hierarchies — from the supplied class up to the outermost enclosing class — and throws a
JUnitException
if such a cycle is detected. Cycles within inner class hierarchies below the supplied class are not detected by this method.- Parameters:
clazz
- the class to be searched; nevernull
predicate
- the predicate against which the list of nested classes is checked; nevernull
- Returns:
- a stream of all such classes found; never
null
but potentially empty - Throws:
JUnitException
- if a cycle is detected within an inner class hierarchy- Since:
- 1.10
-
tryToLoadClass(String)
instead.