org.jboss.solder.reflection
Class Reflections

java.lang.Object
  org.jboss.solder.reflection.Reflections

public class Reflections
extends Object

Utility class for working with JDK Reflection and also CDI's Annotated metadata.

Author:

Stuart Douglas, Pete Muir

Field Summary

static Annotation[]	EMPTY_ANNOTATION_ARRAY An empty array of type Annotation, useful converting lists to arrays.
static Class<?>[]	EMPTY_CLASSES
static Object[]	EMPTY_OBJECT_ARRAY An empty array of type Object, useful for converting lists to arrays.
static Type[]	EMPTY_TYPES

Method Summary

static Map<Class<?>,Type>	buildTypeMap(Set<Type> types)
static <T> T	cast(Object obj) Perform a runtime cast.
static Class<?>	classForName(String name, ClassLoader... loaders) Loads and initializes a class for the given name.
static boolean	containsWildcards(Type[] types)
static Constructor<?>	findDeclaredConstructor(Class<?> clazz, Class<?>... args) Search the class hierarchy for a constructor with the given arguments.
static Field	findDeclaredField(Class<?> clazz, String name) Search the class hierarchy for a field with the given name.
static Method	findDeclaredMethod(Class<?> clazz, String name, Class<?>... args) Search the class hierarchy for a method with the given name and arguments.
static Type[]	getActualTypeArguments(Class<?> clazz) Gets the actual type arguments of a class
static Type[]	getActualTypeArguments(Type type) Gets the actual type arguments of a Type
static Set<Constructor<?>>	getAllDeclaredConstructors(Class<?> clazz) Get all the declared constructors on the class hierarchy.
static Set<Field>	getAllDeclaredFields(Class<?> clazz) Get all the declared fields on the class hierarchy.
static Set<Method>	getAllDeclaredMethods(Class<?> clazz) Get all the declared methods on the class hierarchy.
static Set<Annotation>	getAnnotationsWithMetaAnnotation(Set<Annotation> annotations, Class<? extends Annotation> metaAnnotationType) Search for annotations with the specified meta annotation type
static <X> AnnotatedField<? super X>	getField(AnnotatedType<X> annotatedType, Field field) Search the annotatedType for the field, returning the AnnotatedField
static Object	getFieldValue(Field field, Object instance)
static <T> T	getFieldValue(Field field, Object instance, Class<T> expectedType) Get the value of the field, on the specified instance, casting the value of the field to the expected type.
static Class<?>	getMemberType(Member member) Get the type of the member
static int	getNesting(Class<?> clazz)
static Object	getNonPrivateFinalMethodOrType(Class<?> type)
static String	getPropertyName(Method method) Gets the property name from a getter method.
static Set<Annotation>	getQualifiers(Set<Annotation> annotations, BeanManager beanManager) Extract any qualifiers from the set of annotations
static <T> Class<T>	getRawType(Type type) Extract the raw type, given a type.
static <T> T	invokeMethod(boolean setAccessible, Method method, Class<T> expectedReturnType, Object instance, Object... args) Invoke the method on the instance, with any arguments specified, casting the result of invoking the method to the expected return type.
static Object	invokeMethod(boolean setAccessible, Method method, Object instance, Object... args) Invoke the specified method on the provided instance, passing any additional arguments included in this method as arguments to the specified method.
static <T> T	invokeMethod(Method method, Class<T> expectedReturnType, Object instance, Object... args) Invoke the specified method on the provided instance, passing any additional arguments included in this method as arguments to the specified method.
static Object	invokeMethod(Method method, Object instance, Object... args) Invoke the specified method on the provided instance, passing any additional arguments included in this method as arguments to the specified method.
static boolean	isAbstract(Method method) Checks if a method is abstract
static boolean	isArrayType(Class<?> rawType) Checks if raw type is array type
static boolean	isAssignableFrom(Class<?> rawType1, Type[] actualTypeArguments1, Class<?> rawType2, Type[] actualTypeArguments2) Check the assignability of one type to another, taking into account the actual type arguements
static boolean	isAssignableFrom(Class<?> rawType1, Type[] actualTypeArguments1, Type type2)
static boolean	isAssignableFrom(Set<Type> types1, Set<Type> types2) Check the assiginability of a set of flattened types.
static boolean	isAssignableFrom(Set<Type> types1, Type type2) Check the assiginability of a set of flattened types.
static boolean	isAssignableFrom(Type[] types1, Type type2)
static boolean	isAssignableFrom(Type[] actualTypeArguments1, Type[] actualTypeArguments2)
static boolean	isAssignableFrom(Type type1, Set<? extends Type> types2)
static boolean	isAssignableFrom(Type type1, Type type2)
static boolean	isAssignableFrom(Type type1, Type[] types2)
static boolean	isBindings(Annotation binding) Deprecated.
static boolean	isCacheable(Annotation[] annotations)
static boolean	isCacheable(Set<Annotation> annotations)
static boolean	isFinal(Class<?> clazz) Checks if class is final
static boolean	isFinal(Member member) Checks if member is final
static boolean	isPackagePrivate(int mod)
static boolean	isParamerterizedTypeWithWildcard(Class<?> type)
static boolean	isParameterizedType(Class<?> type) Checks if type is parameterized type
static boolean	isPrimitive(Type type)
static boolean	isPrivate(Member member) Checks if member is private
static boolean	isSerializable(Class<?> clazz) Check if a class is serializable.
static boolean	isStatic(Class<?> type) Checks if type is static
static boolean	isStatic(Member member) Checks if member is static
static boolean	isTransient(Member member)
static boolean	isTypeBounded(Type type, Type[] lowerBounds, Type[] upperBounds)
static boolean	isTypeOrAnyMethodFinal(Class<?> type) Checks if type or member is final
static boolean	matches(Class<?> rawType1, Type[] actualTypeArguments1, Class<?> rawType2, Type[] actualTypeArguments2)
static boolean	matches(Class<?> rawType1, Type[] actualTypeArguments1, Type type2)
static boolean	matches(Set<Type> types1, Set<Type> types2) Check whether whether any of the types1 matches a type in types2
static boolean	matches(Type type1, Set<? extends Type> types2)
static boolean	matches(Type type1, Type type2)
static boolean	methodExists(Class<?> clazz, String name) Determine if a method exists in a specified class hierarchy
static <A extends AccessibleObject> A	setAccessible(A member) Set the accessibility flag on the AccessibleObject as described in AccessibleObject.setAccessible(boolean) within the context of a PrivilegedAction.
static void	setFieldValue(boolean setAccessible, Field field, Object instance, Object value) Sets the value of a field on the instance to the specified value.
static void	setFieldValue(Field field, Object instance, Object value) Set the value of a field on the instance to the specified value.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_ANNOTATION_ARRAY

public static final Annotation[] EMPTY_ANNOTATION_ARRAY

An empty array of type Annotation, useful converting lists to arrays.

EMPTY_OBJECT_ARRAY

public static final Object[] EMPTY_OBJECT_ARRAY

An empty array of type Object, useful for converting lists to arrays.

EMPTY_TYPES

public static final Type[] EMPTY_TYPES

EMPTY_CLASSES

public static final Class<?>[] EMPTY_CLASSES

Method Detail

cast

public static <T> T cast(Object obj)

Perform a runtime cast. Similar to Class.cast(Object), but useful when you do not have a Class object for type you wish to cast to.

Class.cast(Object) should be used if possible

Type Parameters:

T - the type to cast to

Parameters:

obj - the object to perform the cast on

Returns:

the casted object

Throws:

ClassCastException - if the type T is not a subtype of the object

See Also:

Class.cast(Object)

getAllDeclaredFields

public static Set<Field> getAllDeclaredFields(Class<?> clazz)

Get all the declared fields on the class hierarchy. This will return overridden fields.

Parameters:

clazz - The class to search

Returns:

the set of all declared fields or an empty set if there are none

findDeclaredField

public static Field findDeclaredField(Class<?> clazz,
                                      String name)

Search the class hierarchy for a field with the given name. Will return the nearest match, starting with the class specified and searching up the hierarchy.

Parameters:

clazz - The class to search

name - The name of the field to search for

Returns:

The field found, or null if no field is found

getField

public static <X> AnnotatedField<? super X> getField(AnnotatedType<X> annotatedType,
                                                     Field field)

Search the annotatedType for the field, returning the AnnotatedField

Parameters:

annotatedType - The annotatedType to search

field - the field to search for

Returns:

The AnnotatedField found, or null if no field is found

getAnnotationsWithMetaAnnotation

public static Set<Annotation> getAnnotationsWithMetaAnnotation(Set<Annotation> annotations,
                                                               Class<? extends Annotation> metaAnnotationType)

Search for annotations with the specified meta annotation type

Parameters:

annotations - The annotation set to search

metaAnnotationType - The type of the meta annotation to search for

Returns:

The set of annotations with the specified meta annotation, or an empty set if none are found

getQualifiers

public static Set<Annotation> getQualifiers(Set<Annotation> annotations,
                                            BeanManager beanManager)

Extract any qualifiers from the set of annotations

Parameters:

annotations - The set of annotations to search

beanManager - The beanManager to use to establish if an annotation is a qualifier

Returns:

The qualifiers present in the set, or an empty set if there are none

methodExists

public static boolean methodExists(Class<?> clazz,
                                   String name)

Determine if a method exists in a specified class hierarchy

Parameters:

clazz - The class to search

name - The name of the method

Returns:

true if a method is found, otherwise false

getAllDeclaredMethods

public static Set<Method> getAllDeclaredMethods(Class<?> clazz)

Get all the declared methods on the class hierarchy. This will return overridden methods.

Parameters:

clazz - The class to search

Returns:

the set of all declared methods or an empty set if there are none

findDeclaredMethod

public static Method findDeclaredMethod(Class<?> clazz,
                                        String name,
                                        Class<?>... args)

Search the class hierarchy for a method with the given name and arguments. Will return the nearest match, starting with the class specified and searching up the hierarchy.

Parameters:

clazz - The class to search

name - The name of the method to search for

args - The arguments of the method to search for

Returns:

The method found, or null if no method is found

findDeclaredConstructor

public static Constructor<?> findDeclaredConstructor(Class<?> clazz,
                                                     Class<?>... args)

Search the class hierarchy for a constructor with the given arguments. Will return the nearest match, starting with the class specified and searching up the hierarchy.

Parameters:

clazz - The class to search

args - The arguments of the constructor to search for

Returns:

The constructor found, or null if no constructor is found

getAllDeclaredConstructors

public static Set<Constructor<?>> getAllDeclaredConstructors(Class<?> clazz)

Get all the declared constructors on the class hierarchy. This will return overridden constructors.

Parameters:

clazz - The class to search

Returns:

the set of all declared constructors or an empty set if there are none

getMemberType

public static Class<?> getMemberType(Member member)

Get the type of the member

Parameters:

member - The member

Returns:

The type of the member

Throws:

UnsupportedOperationException - if the member is not a field, method, or constructor

classForName

public static Class<?> classForName(String name,
                                    ClassLoader... loaders)
                             throws ClassNotFoundException

Loads and initializes a class for the given name.

If the Thread Context Class Loader is available, it will be used, otherwise the classloader used to load Reflections will be used

It is also possible to specify additional classloaders to attempt to load the class with. If the first attempt fails, then these additional loaders are tried in order.

Parameters:

name - the name of the class to load

loaders - additional classloaders to use to attempt to load the class

Returns:

the class object

Throws:

ClassNotFoundException - if the class cannot be found

setAccessible

public static <A extends AccessibleObject> A setAccessible(A member)

Set the accessibility flag on the AccessibleObject as described in AccessibleObject.setAccessible(boolean) within the context of a PrivilegedAction.

Type Parameters:

A - member the accessible object type

Parameters:

member - the accessible object

Returns:

the accessible object after the accessible flag has been altered

invokeMethod

public static Object invokeMethod(Method method,
                                  Object instance,
                                  Object... args)

Invoke the specified method on the provided instance, passing any additional arguments included in this method as arguments to the specified method.

This method provides the same functionality and throws the same exceptions as invokeMethod(boolean, Method, Class, Object, Object...), with the expected return type set to Object and no change to the method's accessibility.

See Also:

invokeMethod(boolean, Method, Class, Object, Object...), Method.invoke(Object, Object...)

invokeMethod

public static Object invokeMethod(boolean setAccessible,
                                  Method method,
                                  Object instance,
                                  Object... args)

Invoke the specified method on the provided instance, passing any additional arguments included in this method as arguments to the specified method.

This method attempts to set the accessible flag of the method in a PrivilegedAction before invoking the method if the first argument is true.

This method provides the same functionality and throws the same exceptions as invokeMethod(boolean, Method, Class, Object, Object...), with the expected return type set to Object.

See Also:

invokeMethod(boolean, Method, Class, Object, Object...), Method.invoke(Object, Object...)

invokeMethod

public static <T> T invokeMethod(Method method,
                                 Class<T> expectedReturnType,
                                 Object instance,
                                 Object... args)

Invoke the specified method on the provided instance, passing any additional arguments included in this method as arguments to the specified method.

This method provides the same functionality and throws the same exceptions as invokeMethod(boolean, Method, Class, Object, Object...), with the expected return type set to Object and honoring the accessibility of the method.

See Also:

invokeMethod(boolean, Method, Class, Object, Object...), Method.invoke(Object, Object...)

invokeMethod

public static <T> T invokeMethod(boolean setAccessible,
                                 Method method,
                                 Class<T> expectedReturnType,
                                 Object instance,
                                 Object... args)

Invoke the method on the instance, with any arguments specified, casting the result of invoking the method to the expected return type.

This method wraps Method.invoke(Object, Object...), converting the checked exceptions that Method.invoke(Object, Object...) specifies to runtime exceptions.

If instructed, this method attempts to set the accessible flag of the method in a PrivilegedAction before invoking the method.

Parameters:

setAccessible - flag indicating whether method should first be set as accessible

method - the method to invoke

instance - the instance to invoke the method

args - the arguments to the method

Returns:

the result of invoking the method, or null if the method's return type is void

Throws:

RuntimeException - if this Method object enforces Java language access control and the underlying method is inaccessible or if the underlying method throws an exception or if the initialization provoked by this method fails.

IllegalArgumentException - if the method is an instance method and the specified instance argument is not an instance of the class or interface declaring the underlying method (or of a subclass or implementor thereof); if the number of actual and formal parameters differ; if an unwrapping conversion for primitive arguments fails; or if, after possible unwrapping, a parameter value cannot be converted to the corresponding formal parameter type by a method invocation conversion.

NullPointerException - if the specified instance is null and the method is an instance method.

ClassCastException - if the result of invoking the method cannot be cast to the expectedReturnType

ExceptionInInitializerError - if the initialization provoked by this method fails.

See Also:

Method.invoke(Object, Object...)

setFieldValue

public static void setFieldValue(Field field,
                                 Object instance,
                                 Object value)

Set the value of a field on the instance to the specified value.

This method provides the same functionality and throws the same exceptions as Reflections#setFieldValue(boolean, Method, Class, Object, Object...), honoring the accessibility of the field.

setFieldValue

public static void setFieldValue(boolean setAccessible,
                                 Field field,
                                 Object instance,
                                 Object value)

Sets the value of a field on the instance to the specified value.

This method wraps Field.set(Object, Object), converting the checked exceptions that Field.set(Object, Object) specifies to runtime exceptions.

If instructed, this method attempts to set the accessible flag of the method in a PrivilegedAction before invoking the method.

Parameters:

field - the field on which to operate, or null if the field is static

instance - the instance on which the field value should be set upon

value - the value to set the field to

Throws:

RuntimeException - if the underlying field is inaccessible.

IllegalArgumentException - if the specified instance is not an instance of the class or interface declaring the underlying field (or a subclass or implementor thereof), or if an unwrapping conversion fails.

NullPointerException - if the specified instance is null and the field is an instance field.

ExceptionInInitializerError - if the initialization provoked by this method fails.

See Also:

Field.set(Object, Object)

getFieldValue

public static Object getFieldValue(Field field,
                                   Object instance)

getFieldValue

public static <T> T getFieldValue(Field field,
                                  Object instance,
                                  Class<T> expectedType)

Get the value of the field, on the specified instance, casting the value of the field to the expected type.

This method wraps Field.get(Object), converting the checked exceptions that Field.get(Object) specifies to runtime exceptions.

Type Parameters:

T - the type of the field's value

Parameters:

field - the field to operate on

instance - the instance from which to retrieve the value

expectedType - the expected type of the field's value

Returns:

the value of the field

Throws:

RuntimeException - if the underlying field is inaccessible.

IllegalArgumentException - if the specified instance is not an instance of the class or interface declaring the underlying field (or a subclass or implementor thereof).

NullPointerException - if the specified instance is null and the field is an instance field.

ExceptionInInitializerError - if the initialization provoked by this method fails.

getRawType

public static <T> Class<T> getRawType(Type type)

Extract the raw type, given a type.

Type Parameters:

T - the type

Parameters:

type - the type to extract the raw type from

Returns:

the raw type, or null if the raw type cannot be determined.

isSerializable

public static boolean isSerializable(Class<?> clazz)

Check if a class is serializable.

Parameters:

clazz - The class to check

Returns:

true if the class implements serializable or is a primitive

buildTypeMap

public static Map<Class<?>,Type> buildTypeMap(Set<Type> types)

isCacheable

public static boolean isCacheable(Set<Annotation> annotations)

isCacheable

public static boolean isCacheable(Annotation[] annotations)

getPropertyName

public static String getPropertyName(Method method)

Gets the property name from a getter method.

We extend JavaBean conventions, allowing the getter method to have parameters

Parameters:

method - The getter method

Returns:

The name of the property. Returns null if method wasn't JavaBean getter-styled

isFinal

public static boolean isFinal(Class<?> clazz)

Checks if class is final

Parameters:

clazz - The class to check

Returns:

True if final, false otherwise

getNesting

public static int getNesting(Class<?> clazz)

isFinal

public static boolean isFinal(Member member)

Checks if member is final

Parameters:

member - The member to check

Returns:

True if final, false otherwise

isPrivate

public static boolean isPrivate(Member member)

Checks if member is private

Parameters:

member - The member to check

Returns:

True if final, false otherwise

isTypeOrAnyMethodFinal

public static boolean isTypeOrAnyMethodFinal(Class<?> type)

Checks if type or member is final

Parameters:

type - Type or member

Returns:

True if final, false otherwise

getNonPrivateFinalMethodOrType

public static Object getNonPrivateFinalMethodOrType(Class<?> type)

isPackagePrivate

public static boolean isPackagePrivate(int mod)

isStatic

public static boolean isStatic(Class<?> type)

Checks if type is static

Parameters:

type - Type to check

Returns:

True if static, false otherwise

isStatic

public static boolean isStatic(Member member)

Checks if member is static

Parameters:

member - Member to check

Returns:

True if static, false otherwise

isTransient

public static boolean isTransient(Member member)

isAbstract

public static boolean isAbstract(Method method)

Checks if a method is abstract

Parameters:

method -

Returns:

getActualTypeArguments

public static Type[] getActualTypeArguments(Class<?> clazz)

Gets the actual type arguments of a class

Parameters:

clazz - The class to examine

Returns:

The type arguments

getActualTypeArguments

public static Type[] getActualTypeArguments(Type type)

Gets the actual type arguments of a Type

Parameters:

type - The type to examine

Returns:

The type arguments

isArrayType

public static boolean isArrayType(Class<?> rawType)

Checks if raw type is array type

Parameters:

rawType - The raw type to check

Returns:

True if array, false otherwise

isParameterizedType

public static boolean isParameterizedType(Class<?> type)

Checks if type is parameterized type

Parameters:

type - The type to check

Returns:

True if parameterized, false otherwise

isParamerterizedTypeWithWildcard

public static boolean isParamerterizedTypeWithWildcard(Class<?> type)

containsWildcards

public static boolean containsWildcards(Type[] types)

isBindings

@Deprecated
public static boolean isBindings(Annotation binding)

Deprecated.

Checks the bindingType to make sure the annotation was declared properly as a binding type (annotated with @BindingType) and that it has a runtime retention policy.

Parameters:

binding - The binding type to check

Returns:

true only if the annotation is really a binding type

isAssignableFrom

public static boolean isAssignableFrom(Class<?> rawType1,
                                       Type[] actualTypeArguments1,
                                       Class<?> rawType2,
                                       Type[] actualTypeArguments2)

Check the assignability of one type to another, taking into account the actual type arguements

Parameters:

rawType1 - the raw type of the class to check

actualTypeArguments1 - the actual type arguements to check, or an empty array if not a parameterized type

rawType2 - the raw type of the class to check

actualTypeArguments2 - the actual type arguements to check, or an empty array if not a parameterized type

Returns:

matches

public static boolean matches(Class<?> rawType1,
                              Type[] actualTypeArguments1,
                              Class<?> rawType2,
                              Type[] actualTypeArguments2)

isAssignableFrom

public static boolean isAssignableFrom(Type[] actualTypeArguments1,
                                       Type[] actualTypeArguments2)

isAssignableFrom

public static boolean isAssignableFrom(Type type1,
                                       Set<? extends Type> types2)

matches

public static boolean matches(Type type1,
                              Set<? extends Type> types2)

isAssignableFrom

public static boolean isAssignableFrom(Type type1,
                                       Type[] types2)

isAssignableFrom

public static boolean isAssignableFrom(Type type1,
                                       Type type2)

matches

public static boolean matches(Type type1,
                              Type type2)

isTypeBounded

public static boolean isTypeBounded(Type type,
                                    Type[] lowerBounds,
                                    Type[] upperBounds)

isAssignableFrom

public static boolean isAssignableFrom(Class<?> rawType1,
                                       Type[] actualTypeArguments1,
                                       Type type2)

matches

public static boolean matches(Class<?> rawType1,
                              Type[] actualTypeArguments1,
                              Type type2)

isAssignableFrom

public static boolean isAssignableFrom(Set<Type> types1,
                                       Set<Type> types2)

Check the assiginability of a set of flattened types. This algorithm will check whether any of the types1 matches a type in types2

Parameters:

types1 -

types2 -

Returns:

matches

public static boolean matches(Set<Type> types1,
                              Set<Type> types2)

Check whether whether any of the types1 matches a type in types2

Parameters:

types1 -

types2 -

Returns:

isAssignableFrom

public static boolean isAssignableFrom(Set<Type> types1,
                                       Type type2)

Check the assiginability of a set of flattened types. This algorithm will check whether any of the types1 matches a type in types2

Parameters:

types1 -

type2 -

Returns:

isAssignableFrom

public static boolean isAssignableFrom(Type[] types1,
                                       Type type2)

isPrimitive

public static boolean isPrimitive(Type type)