Class ReflectionSupport


  • @API(status=MAINTAINED,
         since="1.0")
    public final class ReflectionSupport
    extends Object
    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:
    AnnotationSupport, ClassSupport, ModifierSupport
    • Method Detail

      • loadClass

        @API(status=DEPRECATED,
             since="1.4")
        @Deprecated
        public static Optional<Class<?>> loadClass​(String name)
        Deprecated.
        Please use tryToLoadClass(String) instead.
        Load a class by its primitive name or fully qualified name, using the default ClassLoader.

        Class names for arrays may be specified using either the JVM's internal String representation (e.g., [[I for int[][], [Ljava.lang.String; for java.lang.String[], etc.) or source code syntax (e.g., int[][], java.lang.String[], etc.).

        Parameters:
        name - the name of the class to load; never null or blank
        Returns:
        an Optional containing the loaded class; never null but potentially empty if no such class could be loaded
      • tryToLoadClass

        @API(status=MAINTAINED,
             since="1.4")
        public static Try<Class<?>> tryToLoadClass​(String name)
        Try to load a class by its primitive name or fully qualified name, using the default ClassLoader.

        Class names for arrays may be specified using either the JVM's internal String representation (e.g., [[I for int[][], [Lava.lang.String; for java.lang.String[], etc.) or source code syntax (e.g., int[][], java.lang.String[], etc.).

        Parameters:
        name - the name of the class to load; never null or blank
        Returns:
        a successful Try containing the loaded class or a failed Try containing the exception if no such class could be loaded; never null
        Since:
        1.4
      • findAllClassesInClasspathRoot

        public static List<Class<?>> findAllClassesInClasspathRoot​(URI root,
                                                                   Predicate<Class<?>> classFilter,
                                                                   Predicate<String> classNameFilter)
        Find all classes in the supplied classpath root that match the specified classFilter and classNameFilter 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; never null
        classFilter - the class type filter; never null
        classNameFilter - the class name filter; never null
        Returns:
        an immutable list of all such classes found; never null but potentially empty
        See Also:
        findAllClassesInPackage(String, Predicate, Predicate), findAllClassesInModule(String, Predicate, Predicate)
      • findAllClassesInPackage

        public static List<Class<?>> findAllClassesInPackage​(String basePackageName,
                                                             Predicate<Class<?>> classFilter,
                                                             Predicate<String> classNameFilter)
        Find all classes in the supplied basePackageName that match the specified classFilter and classNameFilter 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 be null and must be valid in terms of Java syntax
        classFilter - the class type filter; never null
        classNameFilter - the class name filter; never null
        Returns:
        an immutable list of all such classes found; never null but potentially empty
        See Also:
        findAllClassesInClasspathRoot(URI, Predicate, Predicate), findAllClassesInModule(String, Predicate, Predicate)
      • newInstance

        public static <T> T newInstance​(Class<T> clazz,
                                        Object... args)
        Create a new instance of the specified Class 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; never null
        args - the arguments to pass to the constructor, none of which may be null
        Returns:
        the new instance; never null
        See Also:
        ExceptionUtils.throwAsUncheckedException(Throwable)
      • invokeMethod

        public 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.
        Parameters:
        method - the method to invoke; never null
        target - the object on which to invoke the method; may be null if the method is static
        args - the arguments to pass to the method
        Returns:
        the value returned by the method invocation or null if the return type is void
        See Also:
        ExceptionUtils.throwAsUncheckedException(Throwable)
      • 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 specified predicate.

        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
        predicate - the field filter; never null
        traversalMode - the hierarchy traversal mode; never null
        Returns:
        an immutable list of all such fields found; never null but potentially empty
        Since:
        1.4
      • 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; never null
        instance - the instance from which the value is to be read; may be null for a static field
        Since:
        1.4
      • findMethod

        public static Optional<Method> findMethod​(Class<?> clazz,
                                                  String methodName,
                                                  String parameterTypeNames)
        Find the first Method 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; never null
        methodName - the name of the method to find; never null or empty
        parameterTypeNames - 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; never null but potentially empty if no such method could be found
        See Also:
        findMethod(Class, String, Class...)
      • findMethod

        public static Optional<Method> findMethod​(Class<?> clazz,
                                                  String methodName,
                                                  Class<?>... parameterTypes)
        Find the first Method 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; never null
        methodName - the name of the method to find; never null or empty
        parameterTypes - the types of parameters accepted by the method, if any; never null
        Returns:
        an Optional containing the method found; never null but potentially empty if no such method could be found
        See Also:
        findMethod(Class, String, String)
      • findMethods

        public static List<Method> findMethods​(Class<?> clazz,
                                               Predicate<Method> predicate,
                                               HierarchyTraversalMode traversalMode)
        Find all methods of the supplied class or interface that match the specified predicate.

        The results will not contain instance methods that are overridden or static methods that are hidden.

        If you're 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; never null
        predicate - the method filter; never null
        traversalMode - the hierarchy traversal mode; never null
        Returns:
        an immutable list of all such methods found; never null but potentially empty
      • 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; never null
        predicate - the predicate against which the list of nested classes is checked; never null
        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