org.plumelib.reflection

Class ReflectionPlume

java.lang.Object

org.plumelib.reflection.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 and Description
private static class	ReflectionPlume.PromiscuousLoader This static nested class has no purpose but to define defineClassFromFile.

Field Summary

Fields

Modifier and Type	Field and 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 and Description
private	ReflectionPlume() This class is a collection of methods; it does not represent anything.

Method Summary

Modifier and Type	Method and 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(java.util.List<? extends java.lang.Object> objects) Returns the least upper bound of the classes of the given objects.
static <T> @Nullable java.lang.Class<T>	leastUpperBound(@PolyNull @PolyMustCall java.lang.Object[] objects) Returns the least upper bound of the classes of the given objects.
static java.lang.reflect.Method	methodForName(java.lang.String method) Given a method signature, return the method.
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.String	nameWithoutPackage(java.lang.Class<?> c) Returns the class name, including outer classes but without the package.
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

primitiveClasses

private static java.util.HashMap<java.lang.String,java.lang.Class<?>> primitiveClasses

Used by classForName(java.lang.String).

thePromiscuousLoader

private static ReflectionPlume.PromiscuousLoader thePromiscuousLoader

A ClassLoader that can call defineClassFromFile.

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

nameWithoutPackage

public static java.lang.String nameWithoutPackage(java.lang.Class<?> c)

Returns the class name, including outer classes but without the package. Uses "." as the separator between outer an inner classes, as in Java source code.

Parameters:

c - a class

Returns:

the class name, including outer classes but without the package

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 @PolyMustCall 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 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