Package org.plumelib.reflection

Class ReflectionPlume

  • public final class ReflectionPlume
extends java.lang.Object
    Utility functions related to reflection, Class, Method, ClassLoader, and classpath.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static class  ReflectionPlume.PromiscuousLoader
      This static nested class has no purpose but to define defineClassFromFile.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      (package private) static java.util.HashMap<java.lang.String,​java.lang.Class<?>[]> args_seen
      Maps from a comma-delimited string of arg types, such as appears in a method signature, to an array of Class objects, one for each arg type.
      private static java.util.HashMap<java.lang.String,​java.lang.Class<?>> primitiveClasses
      Used by classForName(java.lang.String).
      private static ReflectionPlume.PromiscuousLoader thePromiscuousLoader
      A ClassLoader that can call defineClassFromFile.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private ReflectionPlume()
      This class is a collection of methods; it does not represent anything.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void addToClasspath​(java.lang.String dir)
      Add the directory to the system classpath.
      static java.lang.Class<?> classForName​(@ClassGetName java.lang.String className)
      Like Class.forName(String): given a string representing a non-array class, returns the Class.
      static java.lang.String classpathToString()
      Returns the classpath as a multi-line string.
      private static java.lang.String classpathToStringJava8Only()
      Returns the classpath as a multi-line string.
      static java.lang.Class<?> defineClassFromFile​(@BinaryName java.lang.String className, java.lang.String pathname)
      Converts the bytes in a file into an instance of class Class, and resolves (links) the class.
      static @ClassGetSimpleName java.lang.String fullyQualifiedNameToSimpleName​(@FullyQualifiedName java.lang.String qualifiedName)
      Returns the simple unqualified class name that corresponds to the specified fully qualified name.
      static @Nullable java.lang.Object getPrivateField​(java.lang.Object o, java.lang.String fieldName)
      Reads the given field, which may be private.
      static boolean isSubtype​(java.lang.Class<?> sub, java.lang.Class<?> sup)
      Return true iff sub is a subtype of sup.
      static <T> @Nullable java.lang.Class<T> leastUpperBound​(@Nullable java.lang.Class<T>[] classes)
      Returns the least upper bound of all the given classes.
      static <T> @Nullable java.lang.Class<T> leastUpperBound​(@Nullable java.lang.Class<T> a, @Nullable java.lang.Class<T> b)
      Returns the least upper bound of the given classes.
      static <T> @Nullable java.lang.Class<T> leastUpperBound​(@PolyNull java.lang.Object[] objects)
      Returns the least upper bound of the classes of the given objects.
      static <T> @Nullable java.lang.Class<T> leastUpperBound​(java.util.List<? extends @Nullable java.lang.Object> objects)
      Returns the least upper bound of the classes of the given objects.
      static java.lang.reflect.Method methodForName​(@BinaryName java.lang.String classname, java.lang.String methodname, java.lang.Class<?>[] params)
      Given a class name and a method name in that class, return the method.
      static java.lang.reflect.Method methodForName​(java.lang.String method)
      Given a method signature, return the method.
      static void setFinalField​(java.lang.Object o, java.lang.String fieldName, @Interned java.lang.Object value)
      Sets the given field, which may be final and/or private.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • args_seen

        static java.util.HashMap<java.lang.String,​java.lang.Class<?>[]> args_seen
        Maps from a comma-delimited string of arg types, such as appears in a method signature, to an array of Class objects, one for each arg type. Example keys include: "java.lang.String, java.lang.String, java.lang.Class[]" and "int,int".

    • Constructor Detail

      • ReflectionPlume

        private ReflectionPlume()
        This class is a collection of methods; it does not represent anything.

    • Method Detail

      • isSubtype

        @Pure
public static boolean isSubtype​(java.lang.Class<?> sub,
                                java.lang.Class<?> sup)
        Return true iff sub is a subtype of sup. If sub == sup, then sub is considered a subtype of sub and this method returns true.
        Parameters:
        sub - class to test for being a subtype
        sup - class to test for being a supertype
        Returns:
        true iff sub is a subtype of sup

      • classForName

        public static java.lang.Class<?> classForName​(@ClassGetName java.lang.String className)
                                       throws java.lang.ClassNotFoundException
        Like Class.forName(String): given a string representing a non-array class, returns the Class. Unlike Class.forName(String), the argument may be a primitive type or a fully-qualified name (in addition to a binary name).

        If the given name can't be found, this method changes the last '.' to a dollar sign ($) and tries again. This accounts for inner classes that are incorrectly passed in in fully-qualified format instead of binary format. (It should try multiple dollar signs, not just at the last position.)

        Recall the rather odd specification for Class.forName(String): the argument is a binary name for non-arrays, but a field descriptor for arrays. This method uses the same rules, but additionally handles primitive types and, for non-arrays, fully-qualified names.

        Parameters:
        className - name of the class
        Returns:
        the Class corresponding to className
        Throws:
        java.lang.ClassNotFoundException - if the class is not found

      • fullyQualifiedNameToSimpleName

        public static @ClassGetSimpleName java.lang.String fullyQualifiedNameToSimpleName​(@FullyQualifiedName java.lang.String qualifiedName)
        Returns the simple unqualified class name that corresponds to the specified fully qualified name. For example, if qualifiedName is java.lang.String, String will be returned.
        Parameters:
        qualifiedName - the fully-qualified name of a class
        Returns:
        the simple unqualified name of the class

      • defineClassFromFile

        public static java.lang.Class<?> defineClassFromFile​(@BinaryName java.lang.String className,
                                                     java.lang.String pathname)
                                              throws java.io.FileNotFoundException,
                                                     java.io.IOException
        Converts the bytes in a file into an instance of class Class, and resolves (links) the class. Like ClassLoader.defineClass(String,byte[],int,int), but takes a file name rather than an array of bytes as an argument, and also resolves (links) the class.
        Parameters:
        className - the name of the class to define, or null if not known
        pathname - the pathname of a .class file
        Returns:
        a Java Object corresponding to the Class defined in the .class file
        Throws:
        java.io.FileNotFoundException - if the file cannot be found
        java.io.IOException - if there is trouble reading the file
        See Also:
        ClassLoader.defineClass(String,byte[],int,int)

      • addToClasspath

        public static void addToClasspath​(java.lang.String dir)
        Add the directory to the system classpath.
        Parameters:
        dir - directory to add to the system classpath

      • classpathToStringJava8Only

        private static java.lang.String classpathToStringJava8Only()
        Returns the classpath as a multi-line string.
        Returns:
        the classpath as a multi-line string

      • classpathToString

        public static java.lang.String classpathToString()
        Returns the classpath as a multi-line string.
        Returns:
        the classpath as a multi-line string

      • methodForName

        public static java.lang.reflect.Method methodForName​(java.lang.String method)
                                              throws java.lang.ClassNotFoundException,
                                                     java.lang.NoSuchMethodException,
                                                     java.lang.SecurityException
        Given a method signature, return the method.

        Example calls are: 

         UtilPlume.methodForName("org.plumelib.reflection.ReflectionPlume.methodForName(java.lang.String, java.lang.String, java.lang.Class[])")
 UtilPlume.methodForName("org.plumelib.reflection.ReflectionPlume.methodForName(java.lang.String,java.lang.String,java.lang.Class[])")
 UtilPlume.methodForName("java.lang.Math.min(int,int)")
        Parameters:
        method - a method signature
        Returns:
        the method corresponding to the given signature
        Throws:
        java.lang.ClassNotFoundException - if the class is not found
        java.lang.NoSuchMethodException - if the method is not found
        java.lang.SecurityException

      • methodForName

        public static java.lang.reflect.Method methodForName​(@BinaryName java.lang.String classname,
                                                     java.lang.String methodname,
                                                     java.lang.Class<?>[] params)
                                              throws java.lang.ClassNotFoundException,
                                                     java.lang.NoSuchMethodException,
                                                     java.lang.SecurityException
        Given a class name and a method name in that class, return the method.
        Parameters:
        classname - class in which to find the method
        methodname - the method name
        params - the parameters of the method
        Returns:
        the method named classname.methodname with parameters params
        Throws:
        java.lang.ClassNotFoundException - if the class is not found
        java.lang.NoSuchMethodException - if the method is not found
        java.lang.SecurityException

      • setFinalField

        public static void setFinalField​(java.lang.Object o,
                                 java.lang.String fieldName,
                                 @Interned java.lang.Object value)
                          throws java.lang.NoSuchFieldException
        Sets the given field, which may be final and/or private. Leaves the field accessible.
        Parameters:
        o - object in which to set the field; null iff the field is static
        fieldName - name of field to set
        value - new value of field; may be null iff the field is nullable
        Throws:
        java.lang.NoSuchFieldException - if the field does not exist in the object

      • getPrivateField

        public static @Nullable java.lang.Object getPrivateField​(java.lang.Object o,
                                                         java.lang.String fieldName)
                                                  throws java.lang.NoSuchFieldException
        Reads the given field, which may be private. Leaves the field accessible. Use with care!
        Parameters:
        o - object in which to set the field
        fieldName - name of field to set
        Returns:
        new value of field
        Throws:
        java.lang.NoSuchFieldException - if the field does not exist in the object

      • leastUpperBound

        public static <T> @Nullable java.lang.Class<T> leastUpperBound​(@Nullable java.lang.Class<T> a,
                                                               @Nullable java.lang.Class<T> b)
        Returns the least upper bound of the given classes.
        Type Parameters:
        T - the (inferred) least upper bound of the two arguments
        Parameters:
        a - a class
        b - a class
        Returns:
        the least upper bound of the two classes, or null if both are null

      • leastUpperBound

        public static <T> @Nullable java.lang.Class<T> leastUpperBound​(@Nullable java.lang.Class<T>[] classes)
        Returns the least upper bound of all the given classes.
        Type Parameters:
        T - the (inferred) least upper bound of the arguments
        Parameters:
        classes - a non-empty list of classes
        Returns:
        the least upper bound of all the given classes

      • leastUpperBound

        public static <T> @Nullable java.lang.Class<T> leastUpperBound​(@PolyNull java.lang.Object[] objects)
        Returns the least upper bound of the classes of the given objects.
        Type Parameters:
        T - the (inferred) least upper bound of the arguments
        Parameters:
        objects - a list of objects
        Returns:
        the least upper bound of the classes of the given objects, or null if all arguments are null

      • leastUpperBound

        public static <T> @Nullable java.lang.Class<T> leastUpperBound​(java.util.List<? extends @Nullable java.lang.Object> objects)
        Returns the least upper bound of the classes of the given objects.
        Type Parameters:
        T - the (inferred) least upper bound of the arguments
        Parameters:
        objects - a non-empty list of objects
        Returns:
        the least upper bound of the classes of the given objects, or null if all arguments are null