Module org.omnifaces

Package org.omnifaces.util

Class Reflection

java.lang.Object

org.omnifaces.util.Reflection

@Typed
public final class Reflection
extends Object

Collection of utility methods for working with reflection.

This class is not listed in showcase! Should I use it?

This class is indeed intented for internal usage only. We won't add methods here on user request. We only add methods here once we encounter non-DRY code in OmniFaces codebase. The methods may be renamed/changed without notice.

We don't stop you from using it if you found it in the Javadoc and you think you find it useful, but you have to accept the risk that the method signatures can be changed without notice. This utility class exists because OmniFaces intends to be free of 3rd party dependencies.

Since:

2.0

Author:

Arjan Tijms, Bauke Scholtz, Andre Wachsmuth

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Reflection.PropertyPath	This class represents a property path.

Method Summary

Modifier and Type	Method	Description
static <C,T> T	accessField(C instance, Class<? extends C> classType, Class<T> fieldType)	Returns the value of the field of the given class type on the given field type from the given instance.
static <T> T	accessField(Object instance, Class<T> fieldType)	Returns the value of the field of the given instance on the given field type.
static <T> T	accessField(Object instance, String fieldName)	Returns the value of the field of the given instance on the given field name.
static <T> Constructor<T>	findConstructor(Class<T> clazz, Class<?>... parameterTypes)	Finds a constructor based on the given parameter types and returns null is none is found.
static Method	findMethod(Object base, String methodName, Object... params)	Finds a method based on the method name, amount of parameters and limited typing and returns null is none is found.
static <A extends Annotation> List<Method>	findMethods(Object base, Class<A> annotation)	Finds methods having the given annotation.
static Map<Object,Reflection.PropertyPath>	getBaseBeanPropertyPaths(Object bean)	Recursively collect all base bean property paths from the given bean which resolve to non-null bases.
static Map<Object,Reflection.PropertyPath>	getBaseBeanPropertyPaths(Object bean, Predicate<Method> recursableGetter)	Recursively collect all base bean property paths from the given bean which resolve to non-null bases and are recursable.
static Object	getBeanProperty(Object bean, String property)	Obtain given property from given bean.
static <T> T	instance(Class<T> clazz)	Returns a new instance of the given class object using the default constructor.
static <T> T	instance(String className)	Returns a new instance of the given class name using the default constructor.
static <T> T	invokeMethod(Object instance, Method method, Object... parameters)	Invoke given method of the given instance with the given parameters and return the result.
static <T> T	invokeMethod(Object instance, String methodName, Object... parameters)	Invoke a method of the given instance on the given method name with the given parameters and return the result.
static <A extends Annotation> void	invokeMethods(Object instance, Class<A> annotation)	Invoke methods of the given instance having the given annotation.
static boolean	isAssignable(Object source, Class<?> targetType)	Returns true if given source is assignable to target type, taking into account autoboxing.
static <T> T	modifyField(Object instance, Field field, T value)	Modifies the value of the given field of the given instance with the given value.
static <T> T	modifyField(Object instance, String fieldName, T value)	Modifies the value of the field of the given instance on the given field name with the given value.
static void	setBeanProperties(Object bean, Map<Reflection.PropertyPath,Object> properties)	Recursively set given properties on given bean.
static void	setProperties(Object bean, Map<String,Object> propertiesToSet)	Sets a collection of properties of a given bean to the values associated with those properties.
static void	setPropertiesWithCoercion(Object bean, Map<String,Object> propertiesToSet)	Sets a collection of properties of a given bean to the (optionally coerced) values associated with those properties.
static <T> Class<T>	toClass(String className)	Returns the class object associated with the given class name, using the context class loader and if that fails the defining class loader of the current class.
static <T> Class<T>	toClassOrNull(String className)	Returns the class object associated with the given class name, using the context class loader and if that fails the defining class loader of the current class.

Methods inherited from class java.lang.Object

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

Method Detail

setProperties

public static void setProperties(Object bean,
                                 Map<String,Object> propertiesToSet)

Sets a collection of properties of a given bean to the values associated with those properties.

In the map that represents these properties, each key represents the name of the property, with the value associated with that key being the value that is set for the property.

E.g. map entry key = foo, value = "bar", which "bar" an instance of String, will conceptually result in the following call: bean.setFoo("string");

NOTE: This particular method assumes that there's a write method for each property in the map with the right type. No specific checking is done whether this is indeed the case.

If you need to set nested properties recursively as well, use setBeanProperties(Object, Map) instead.

Parameters:

bean - the bean on which properties will be set

propertiesToSet - the map containing properties and their values to be set on the bean

setPropertiesWithCoercion

public static void setPropertiesWithCoercion(Object bean,
                                             Map<String,Object> propertiesToSet)

Sets a collection of properties of a given bean to the (optionally coerced) values associated with those properties.

In the map that represents these properties, each key represents the name of the property, with the value associated with that key being the value that is set for the property.

E.g. map entry key = foo, value = "bar", which "bar" an instance of String, will conceptually result in the following call: bean.setFoo("string");

NOTE 1: In case the value is a String, and the target type is not String, the standard property editor mechanism will be used to attempt a conversion.

Note 2: This method operates somewhat as the reverse of setProperties(Object, Map). Here only the available writable properties of the bean are matched against the map with properties to set. Properties in the map for which there isn't a corresponding writable property on the bean are ignored.

Following the above two notes, use this method when attempting to set properties on an bean in a lenient best effort basis. Use setProperties(Object, Map) when all properties need to be set with the exact type as the value appears in the map.

Parameters:

bean - the bean on which properties will be set

propertiesToSet - the map containing properties and their values to be set on the object

setBeanProperties

public static void setBeanProperties(Object bean,
                                     Map<Reflection.PropertyPath,Object> properties)

Recursively set given properties on given bean. It will automatically prepopulate nested lists, maps, arrays and beans where necessary.

Parameters:

bean - Bean to recursively set properties on.

properties - Properties to recursively set on bean. The map key represents the property path and the map value represents the property value.

Since:

3.8

getBeanProperty

public static Object getBeanProperty(Object bean,
                                     String property)

Obtain given property from given bean.

Parameters:

bean - Bean to obtain property from.

property - Property name.

Returns:

Value of given property of given bean.

Since:

3.8

getBaseBeanPropertyPaths

public static Map<Object,Reflection.PropertyPath> getBaseBeanPropertyPaths(Object bean)

Recursively collect all base bean property paths from the given bean which resolve to non-null bases. A "base" is represented by the bean itself and all of its nested lists, maps, arrays and beans. This does not include the non-nested properties of any base. E.g. "person.address.street" will return a map with actual instances of "person" and "person.address" as keys. Note that the "street" is not included as it does not represent a base.

Parameters:

bean - The given bean.

Returns:

All base bean property paths which resolve to non-null values, mapped by the base.

Since:

3.8

getBaseBeanPropertyPaths

public static Map<Object,Reflection.PropertyPath> getBaseBeanPropertyPaths(Object bean,
                                                                                 Predicate<Method> recursableGetter)

Recursively collect all base bean property paths from the given bean which resolve to non-null bases and are recursable. A "base" is represented by the bean itself and all of its nested lists, maps, arrays and beans. This does not include the non-nested properties of any base. E.g. "person.address.street" will return a map with actual instances of "person" and "person.address" as keys. Note that the "street" is not included as it does not represent a base.

Parameters:

bean - The given bean.

recursableGetter - Whether the given getter method is recursable.

Returns:

All base bean property paths which resolve to non-null values, mapped by the base.

Since:

3.9

findMethod

public static Method findMethod(Object base,
                                String methodName,
                                Object... params)

Finds a method based on the method name, amount of parameters and limited typing and returns null is none is found.

Note that this supports overloading, but a limited one. Given an actual parameter of type Long, this will select a method accepting Number when the choice is between Number and a non-compatible type like String. However, it will NOT select the best match if the choice is between Number and Long.

Parameters:

base - the object in which the method is to be found

methodName - name of the method to be found

params - the method parameters

Returns:

a method if one is found, null otherwise

findMethods

public static <A extends Annotation> List<Method> findMethods(Object base,
                                                              Class<A> annotation)

Finds methods having the given annotation.

Parameters:

base - The object in which the methods are to be found.

annotation - Annotation of the method to be found.

Returns:

List of matching methods.

Since:

3.6

isAssignable

public static boolean isAssignable(Object source,
                                   Class<?> targetType)

Returns true if given source is assignable to target type, taking into account autoboxing. Java returns namely false on int.class.isAssignableFrom(Integer.class).

Parameters:

source - The source to be checked.

targetType - The target type to be checked.

Returns:

True if the given source is assignable to the given target type.

Since:

2.7.2

toClass

public static <T> Class<T> toClass(String className)

Returns the class object associated with the given class name, using the context class loader and if that fails the defining class loader of the current class.

Type Parameters:

T - The expected class type.

Parameters:

className - Fully qualified class name of the class for which a class object needs to be created.

Returns:

The class object associated with the given class name.

Throws:

IllegalStateException - If the class cannot be loaded.

ClassCastException - When T is of wrong type.

toClassOrNull

public static <T> Class<T> toClassOrNull(String className)

Returns the class object associated with the given class name, using the context class loader and if that fails the defining class loader of the current class. If the class cannot be loaded, then return null instead of throwing illegal state exception.

Type Parameters:

T - The expected class type.

Parameters:

className - Fully qualified class name of the class for which a class object needs to be created.

Returns:

The class object associated with the given class name.

Throws:

ClassCastException - When T is of wrong type.

Since:

2.5

findConstructor

public static <T> Constructor<T> findConstructor(Class<T> clazz,
                                                 Class<?>... parameterTypes)

Finds a constructor based on the given parameter types and returns null is none is found.

Parameters:

clazz - The class object for which the constructor is to be found.

parameterTypes - The desired method parameter types.

Returns:

A constructor if one is found, null otherwise.

Since:

2.6

instance

public static <T> T instance(String className)

Returns a new instance of the given class name using the default constructor.

Type Parameters:

T - The expected return type.

Parameters:

className - Fully qualified class name of the class for which an instance needs to be created.

Returns:

A new instance of the given class name using the default constructor.

Throws:

IllegalStateException - If the class cannot be loaded.

ClassCastException - When T is of wrong type.

instance

public static <T> T instance(Class<T> clazz)

Returns a new instance of the given class object using the default constructor.

Type Parameters:

T - The generic object type.

Parameters:

clazz - The class object for which an instance needs to be created.

Returns:

A new instance of the given class object using the default constructor.

Throws:

IllegalStateException - If the class cannot be found, or cannot be instantiated, or when a security manager prevents this operation.

accessField

public static <T> T accessField(Object instance,
                                String fieldName)

Returns the value of the field of the given instance on the given field name.

Type Parameters:

T - The expected return type.

Parameters:

instance - The instance to access the given field on.

fieldName - The name of the field to be accessed on the given instance.

Returns:

The value of the field of the given instance on the given field name.

Throws:

ClassCastException - When T is of wrong type.

IllegalStateException - If the field cannot be accessed.

Since:

2.5

accessField

public static <T> T accessField(Object instance,
                                Class<T> fieldType)

Returns the value of the field of the given instance on the given field type. Note that this returns only the first encountered field of the given type and thus the result is undetermined when there are multiple fields of the given type.

Type Parameters:

T - The expected return type.

Parameters:

instance - The instance to access the given field on.

fieldType - The type of the field to be accessed on the given instance.

Returns:

The value of the field of the given instance on the given field type, or null when there is no such field.

Throws:

ClassCastException - When T is of wrong type.

IllegalStateException - If the field cannot be accessed.

Since:

4.3

accessField

public static <C,T> T accessField(C instance,
                                        Class<? extends C> classType,
                                        Class<T> fieldType)

Returns the value of the field of the given class type on the given field type from the given instance. Note that this returns only the first encountered field of the given type and thus the result is undetermined when there are multiple fields of the given type. The difference with accessField(Object, Class) is that any subclass of the given class type are not searched in might the given instance being such one subclass with its own field.

Type Parameters:

T - The expected return type.

Parameters:

instance - The instance to access the given field on.

classType - The type of the class to find the given field in.

fieldType - The type of the field to be accessed on the given instance.

Returns:

The value of the field of the given class type on the given field type from the given instance, or null when there is no such field.

Throws:

ClassCastException - When T is of wrong type.

IllegalStateException - If the field cannot be accessed.

Since:

4.3

modifyField

public static <T> T modifyField(Object instance,
                                String fieldName,
                                T value)

Modifies the value of the field of the given instance on the given field name with the given value.

Type Parameters:

T - The field type.

Parameters:

instance - The instance to access the given field on.

fieldName - The name of the field to be accessed on the given instance.

value - The new value of the field of the given instance on the given field name.

Returns:

The old value of the field of the given instance on the given field name.

Throws:

ClassCastException - When T is of wrong type.

IllegalStateException - If the field cannot be modified.

Since:

3.8

modifyField

public static <T> T modifyField(Object instance,
                                Field field,
                                T value)

Modifies the value of the given field of the given instance with the given value.

Type Parameters:

T - The field type.

Parameters:

instance - The instance to access the given field on.

field - The field to be accessed on the given instance.

value - The new value of the given field of the given instance.

Returns:

The old value of the given field of the given instance.

Throws:

ClassCastException - When T is of wrong type.

IllegalStateException - If the field cannot be modified.

Since:

3.6

invokeMethod

public static <T> T invokeMethod(Object instance,
                                 String methodName,
                                 Object... parameters)

Invoke a method of the given instance on the given method name with the given parameters and return the result.

Note: the current implementation assumes for simplicity that no one of the given parameters is null. If one of them is still null, a NullPointerException will be thrown.

Type Parameters:

T - The expected return type.

Parameters:

instance - The instance to invoke the given method on.

methodName - The name of the method to be invoked on the given instance.

parameters - The method parameters, if any.

Returns:

The result of the method invocation, if any.

Throws:

NullPointerException - When one of the given parameters is null.

IllegalStateException - If the method cannot be invoked.

ClassCastException - When T is of wrong type.

Since:

2.5

invokeMethod

public static <T> T invokeMethod(Object instance,
                                 Method method,
                                 Object... parameters)

Invoke given method of the given instance with the given parameters and return the result.

Type Parameters:

T - The expected return type.

Parameters:

instance - The instance to invoke the given method on.

method - The method to be invoked on the given instance.

parameters - The method parameters, if any.

Returns:

The result of the method invocation, if any.

Throws:

IllegalStateException - If the method cannot be invoked.

ClassCastException - When T is of wrong type.

Since:

3.6

invokeMethods

public static <A extends Annotation> void invokeMethods(Object instance,
                                                        Class<A> annotation)

Invoke methods of the given instance having the given annotation.

Parameters:

instance - The instance to invoke the methods having the given annotation on.

annotation - Annotation of the methods to be invoked.

Throws:

IllegalStateException - If the method cannot be invoked.

Since:

3.6