Class BeanUtilsBean
- java.lang.Object
-
- org.apache.commons.beanutils.BeanUtilsBean
-
- Direct Known Subclasses:
BeanUtilsBean2
,LocaleBeanUtilsBean
public class BeanUtilsBean extends java.lang.Object
JavaBean property population methods.
This class provides implementations for the utility methods in
BeanUtils
. Different instances can be used to isolate caches between classloaders and to vary the value converters registered.- Since:
- 1.7
- Version:
- $Id: BeanUtilsBean.java 1546738 2013-11-30 16:24:19Z oheger $
- See Also:
BeanUtils
-
-
Field Summary
Fields Modifier and Type Field Description private static ContextClassLoaderLocal<BeanUtilsBean>
BEANS_BY_CLASSLOADER
ContainsBeanUtilsBean
instances indexed by context classloader.private ConvertUtilsBean
convertUtilsBean
Used to perform conversions between object types when setting propertiesprivate static java.lang.reflect.Method
INIT_CAUSE_METHOD
A reference to Throwable's initCause method, or null if it's not there in this JVMprivate org.apache.commons.logging.Log
log
Logging for this instanceprivate PropertyUtilsBean
propertyUtilsBean
Used to access properties
-
Constructor Summary
Constructors Constructor Description BeanUtilsBean()
Constructs an instance using new property and conversion instances.BeanUtilsBean(ConvertUtilsBean convertUtilsBean)
Constructs an instance using given conversion instances and newPropertyUtilsBean
instance.BeanUtilsBean(ConvertUtilsBean convertUtilsBean, PropertyUtilsBean propertyUtilsBean)
Constructs an instance using given property and conversion instances.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description java.lang.Object
cloneBean(java.lang.Object bean)
Clone a bean based on the available property getters and setters, even if the bean class itself does not implement Cloneable.protected java.lang.Object
convert(java.lang.Object value, java.lang.Class<?> type)
Convert the value to an object of the specified class (if possible).private java.lang.Object
convertForCopy(java.lang.Object value, java.lang.Class<?> type)
Performs a type conversion of a property value before it is copied to a target bean.void
copyProperties(java.lang.Object dest, java.lang.Object orig)
Copy property values from the origin bean to the destination bean for all cases where the property names are the same.void
copyProperty(java.lang.Object bean, java.lang.String name, java.lang.Object value)
Copy the specified property value to the specified destination bean, performing any type conversion that is required.java.util.Map<java.lang.String,java.lang.String>
describe(java.lang.Object bean)
Return the entire set of properties for which the specified bean provides a read method.private static java.lang.Class<?>
dynaPropertyType(DynaProperty dynaProperty, java.lang.Object value)
Determines the type of aDynaProperty
.java.lang.String[]
getArrayProperty(java.lang.Object bean, java.lang.String name)
Return the value of the specified array property of the specified bean, as a String array.ConvertUtilsBean
getConvertUtils()
Gets theConvertUtilsBean
instance used to perform the conversions.java.lang.String
getIndexedProperty(java.lang.Object bean, java.lang.String name)
Return the value of the specified indexed property of the specified bean, as a String.java.lang.String
getIndexedProperty(java.lang.Object bean, java.lang.String name, int index)
Return the value of the specified indexed property of the specified bean, as a String.private static java.lang.reflect.Method
getInitCauseMethod()
Returns aMethod
allowing access to
Throwable.initCause(Throwable)
method ofThrowable
, ornull
if the method does not exist.static BeanUtilsBean
getInstance()
Gets the instance which provides the functionality forBeanUtils
.java.lang.String
getMappedProperty(java.lang.Object bean, java.lang.String name)
Return the value of the specified indexed property of the specified bean, as a String.java.lang.String
getMappedProperty(java.lang.Object bean, java.lang.String name, java.lang.String key)
Return the value of the specified mapped property of the specified bean, as a String.java.lang.String
getNestedProperty(java.lang.Object bean, java.lang.String name)
Return the value of the (possibly nested) property of the specified name, for the specified bean, as a String.java.lang.String
getProperty(java.lang.Object bean, java.lang.String name)
Return the value of the specified property of the specified bean, no matter which property reference format is used, as a String.PropertyUtilsBean
getPropertyUtils()
Gets thePropertyUtilsBean
instance used to access properties.java.lang.String
getSimpleProperty(java.lang.Object bean, java.lang.String name)
Return the value of the specified simple property of the specified bean, converted to a String.boolean
initCause(java.lang.Throwable throwable, java.lang.Throwable cause)
If we're running on JDK 1.4 or later, initialize the cause for the given throwable.void
populate(java.lang.Object bean, java.util.Map<java.lang.String,? extends java.lang.Object> properties)
Populate the JavaBeans properties of the specified bean, based on the specified name/value pairs.static void
setInstance(BeanUtilsBean newInstance)
Sets the instance which provides the functionality forBeanUtils
.void
setProperty(java.lang.Object bean, java.lang.String name, java.lang.Object value)
Set the specified property value, performing type conversions as required to conform to the type of the destination property.
-
-
-
Field Detail
-
BEANS_BY_CLASSLOADER
private static final ContextClassLoaderLocal<BeanUtilsBean> BEANS_BY_CLASSLOADER
ContainsBeanUtilsBean
instances indexed by context classloader.
-
log
private final org.apache.commons.logging.Log log
Logging for this instance
-
convertUtilsBean
private final ConvertUtilsBean convertUtilsBean
Used to perform conversions between object types when setting properties
-
propertyUtilsBean
private final PropertyUtilsBean propertyUtilsBean
Used to access properties
-
INIT_CAUSE_METHOD
private static final java.lang.reflect.Method INIT_CAUSE_METHOD
A reference to Throwable's initCause method, or null if it's not there in this JVM
-
-
Constructor Detail
-
BeanUtilsBean
public BeanUtilsBean()
Constructs an instance using new property and conversion instances.
-
BeanUtilsBean
public BeanUtilsBean(ConvertUtilsBean convertUtilsBean)
Constructs an instance using given conversion instances and new
PropertyUtilsBean
instance.- Parameters:
convertUtilsBean
- use thisConvertUtilsBean
to perform conversions from one object to another- Since:
- 1.8.0
-
BeanUtilsBean
public BeanUtilsBean(ConvertUtilsBean convertUtilsBean, PropertyUtilsBean propertyUtilsBean)
Constructs an instance using given property and conversion instances.
- Parameters:
convertUtilsBean
- use thisConvertUtilsBean
to perform conversions from one object to anotherpropertyUtilsBean
- use thisPropertyUtilsBean
to access properties
-
-
Method Detail
-
getInstance
public static BeanUtilsBean getInstance()
Gets the instance which provides the functionality forBeanUtils
. This is a pseudo-singleton - an single instance is provided per (thread) context classloader. This mechanism provides isolation for web apps deployed in the same container.- Returns:
- The (pseudo-singleton) BeanUtils bean instance
-
setInstance
public static void setInstance(BeanUtilsBean newInstance)
Sets the instance which provides the functionality forBeanUtils
. This is a pseudo-singleton - an single instance is provided per (thread) context classloader. This mechanism provides isolation for web apps deployed in the same container.- Parameters:
newInstance
- The (pseudo-singleton) BeanUtils bean instance
-
cloneBean
public java.lang.Object cloneBean(java.lang.Object bean) throws java.lang.IllegalAccessException, java.lang.InstantiationException, java.lang.reflect.InvocationTargetException, java.lang.NoSuchMethodException
Clone a bean based on the available property getters and setters, even if the bean class itself does not implement Cloneable.
Note: this method creates a shallow clone. In other words, any objects referred to by the bean are shared with the clone rather than being cloned in turn.
- Parameters:
bean
- Bean to be cloned- Returns:
- the cloned bean
- Throws:
java.lang.IllegalAccessException
- if the caller does not have access to the property accessor methodjava.lang.InstantiationException
- if a new instance of the bean's class cannot be instantiatedjava.lang.reflect.InvocationTargetException
- if the property accessor method throws an exceptionjava.lang.NoSuchMethodException
- if an accessor method for this property cannot be found
-
copyProperties
public void copyProperties(java.lang.Object dest, java.lang.Object orig) throws java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException
Copy property values from the origin bean to the destination bean for all cases where the property names are the same. For each property, a conversion is attempted as necessary. All combinations of standard JavaBeans and DynaBeans as origin and destination are supported. Properties that exist in the origin bean, but do not exist in the destination bean (or are read-only in the destination bean) are silently ignored.
If the origin "bean" is actually a
Map
, it is assumed to contain String-valued simple property names as the keys, pointing at the corresponding property values that will be converted (if necessary) and set in the destination bean. Note that this method is intended to perform a "shallow copy" of the properties and so complex properties (for example, nested ones) will not be copied.This method differs from
populate()
, which was primarily designed for populating JavaBeans from the map of request parameters retrieved on an HTTP request, is that no scalar->indexed or indexed->scalar manipulations are performed. If the origin property is indexed, the destination property must be also.If you know that no type conversions are required, the
copyProperties()
method inPropertyUtils
will execute faster than this method.FIXME - Indexed and mapped properties that do not have getter and setter methods for the underlying array or Map are not copied by this method.
- Parameters:
dest
- Destination bean whose properties are modifiedorig
- Origin bean whose properties are retrieved- Throws:
java.lang.IllegalAccessException
- if the caller does not have access to the property accessor methodjava.lang.IllegalArgumentException
- if thedest
ororig
argument is null or if thedest
property type is different from the source type and the relevant converter has not been registered.java.lang.reflect.InvocationTargetException
- if the property accessor method throws an exception
-
copyProperty
public void copyProperty(java.lang.Object bean, java.lang.String name, java.lang.Object value) throws java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException
Copy the specified property value to the specified destination bean, performing any type conversion that is required. If the specified bean does not have a property of the specified name, or the property is read only on the destination bean, return without doing anything. If you have custom destination property types, register
Converter
s for them by calling theregister()
method ofConvertUtils
.IMPLEMENTATION RESTRICTIONS:
- Does not support destination properties that are indexed, but only an indexed setter (as opposed to an array setter) is available.
- Does not support destination properties that are mapped, but only a keyed setter (as opposed to a Map setter) is available.
- The desired property type of a mapped setter cannot be determined (since Maps support any data type), so no conversion will be performed.
- Parameters:
bean
- Bean on which setting is to be performedname
- Property name (can be nested/indexed/mapped/combo)value
- Value to be set- Throws:
java.lang.IllegalAccessException
- if the caller does not have access to the property accessor methodjava.lang.reflect.InvocationTargetException
- if the property accessor method throws an exception
-
describe
public java.util.Map<java.lang.String,java.lang.String> describe(java.lang.Object bean) throws java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.NoSuchMethodException
Return the entire set of properties for which the specified bean provides a read method. This map contains the to
String
converted property values for all properties for which a read method is provided (i.e. where the getReadMethod() returns non-null).This map can be fed back to a call to
BeanUtils.populate()
to reconsitute the same set of properties, modulo differences for read-only and write-only properties, but only if there are no indexed properties.Warning: if any of the bean property implementations contain (directly or indirectly) a call to this method then a stack overflow may result. For example:
will result in an infinite regression whenclass MyBean { public Map getParameterMap() { BeanUtils.describe(this); } }
getParametersMap
is called. It is recommended that such methods are given alternative names (for example,parametersMap
).- Parameters:
bean
- Bean whose properties are to be extracted- Returns:
- Map of property descriptors
- Throws:
java.lang.IllegalAccessException
- if the caller does not have access to the property accessor methodjava.lang.reflect.InvocationTargetException
- if the property accessor method throws an exceptionjava.lang.NoSuchMethodException
- if an accessor method for this property cannot be found
-
getArrayProperty
public java.lang.String[] getArrayProperty(java.lang.Object bean, java.lang.String name) throws java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.NoSuchMethodException
Return the value of the specified array property of the specified bean, as a String array.- Parameters:
bean
- Bean whose property is to be extractedname
- Name of the property to be extracted- Returns:
- The array property value
- Throws:
java.lang.IllegalAccessException
- if the caller does not have access to the property accessor methodjava.lang.reflect.InvocationTargetException
- if the property accessor method throws an exceptionjava.lang.NoSuchMethodException
- if an accessor method for this property cannot be found
-
getIndexedProperty
public java.lang.String getIndexedProperty(java.lang.Object bean, java.lang.String name) throws java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.NoSuchMethodException
Return the value of the specified indexed property of the specified bean, as a String. The zero-relative index of the required value must be included (in square brackets) as a suffix to the property name, orIllegalArgumentException
will be thrown.- Parameters:
bean
- Bean whose property is to be extractedname
-propertyname[index]
of the property value to be extracted- Returns:
- The indexed property's value, converted to a String
- Throws:
java.lang.IllegalAccessException
- if the caller does not have access to the property accessor methodjava.lang.reflect.InvocationTargetException
- if the property accessor method throws an exceptionjava.lang.NoSuchMethodException
- if an accessor method for this property cannot be found
-
getIndexedProperty
public java.lang.String getIndexedProperty(java.lang.Object bean, java.lang.String name, int index) throws java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.NoSuchMethodException
Return the value of the specified indexed property of the specified bean, as a String. The index is specified as a method parameter and must *not* be included in the property name expression- Parameters:
bean
- Bean whose property is to be extractedname
- Simple property name of the property value to be extractedindex
- Index of the property value to be extracted- Returns:
- The indexed property's value, converted to a String
- Throws:
java.lang.IllegalAccessException
- if the caller does not have access to the property accessor methodjava.lang.reflect.InvocationTargetException
- if the property accessor method throws an exceptionjava.lang.NoSuchMethodException
- if an accessor method for this property cannot be found
-
getMappedProperty
public java.lang.String getMappedProperty(java.lang.Object bean, java.lang.String name) throws java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.NoSuchMethodException
Return the value of the specified indexed property of the specified bean, as a String. The String-valued key of the required value must be included (in parentheses) as a suffix to the property name, orIllegalArgumentException
will be thrown.- Parameters:
bean
- Bean whose property is to be extractedname
-propertyname(index)
of the property value to be extracted- Returns:
- The mapped property's value, converted to a String
- Throws:
java.lang.IllegalAccessException
- if the caller does not have access to the property accessor methodjava.lang.reflect.InvocationTargetException
- if the property accessor method throws an exceptionjava.lang.NoSuchMethodException
- if an accessor method for this property cannot be found
-
getMappedProperty
public java.lang.String getMappedProperty(java.lang.Object bean, java.lang.String name, java.lang.String key) throws java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.NoSuchMethodException
Return the value of the specified mapped property of the specified bean, as a String. The key is specified as a method parameter and must *not* be included in the property name expression- Parameters:
bean
- Bean whose property is to be extractedname
- Simple property name of the property value to be extractedkey
- Lookup key of the property value to be extracted- Returns:
- The mapped property's value, converted to a String
- Throws:
java.lang.IllegalAccessException
- if the caller does not have access to the property accessor methodjava.lang.reflect.InvocationTargetException
- if the property accessor method throws an exceptionjava.lang.NoSuchMethodException
- if an accessor method for this property cannot be found
-
getNestedProperty
public java.lang.String getNestedProperty(java.lang.Object bean, java.lang.String name) throws java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.NoSuchMethodException
Return the value of the (possibly nested) property of the specified name, for the specified bean, as a String.- Parameters:
bean
- Bean whose property is to be extractedname
- Possibly nested name of the property to be extracted- Returns:
- The nested property's value, converted to a String
- Throws:
java.lang.IllegalAccessException
- if the caller does not have access to the property accessor methodjava.lang.IllegalArgumentException
- if a nested reference to a property returns nulljava.lang.reflect.InvocationTargetException
- if the property accessor method throws an exceptionjava.lang.NoSuchMethodException
- if an accessor method for this property cannot be found
-
getProperty
public java.lang.String getProperty(java.lang.Object bean, java.lang.String name) throws java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.NoSuchMethodException
Return the value of the specified property of the specified bean, no matter which property reference format is used, as a String.- Parameters:
bean
- Bean whose property is to be extractedname
- Possibly indexed and/or nested name of the property to be extracted- Returns:
- The property's value, converted to a String
- Throws:
java.lang.IllegalAccessException
- if the caller does not have access to the property accessor methodjava.lang.reflect.InvocationTargetException
- if the property accessor method throws an exceptionjava.lang.NoSuchMethodException
- if an accessor method for this property cannot be found
-
getSimpleProperty
public java.lang.String getSimpleProperty(java.lang.Object bean, java.lang.String name) throws java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException, java.lang.NoSuchMethodException
Return the value of the specified simple property of the specified bean, converted to a String.- Parameters:
bean
- Bean whose property is to be extractedname
- Name of the property to be extracted- Returns:
- The property's value, converted to a String
- Throws:
java.lang.IllegalAccessException
- if the caller does not have access to the property accessor methodjava.lang.reflect.InvocationTargetException
- if the property accessor method throws an exceptionjava.lang.NoSuchMethodException
- if an accessor method for this property cannot be found
-
populate
public void populate(java.lang.Object bean, java.util.Map<java.lang.String,? extends java.lang.Object> properties) throws java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException
Populate the JavaBeans properties of the specified bean, based on the specified name/value pairs. This method uses Java reflection APIs to identify corresponding "property setter" method names, and deals with setter arguments of type
String
,boolean
,int
,long
,float
, anddouble
. In addition, array setters for these types (or the corresponding primitive types) can also be identified.The particular setter method to be called for each property is determined using the usual JavaBeans introspection mechanisms. Thus, you may identify custom setter methods using a BeanInfo class that is associated with the class of the bean itself. If no such BeanInfo class is available, the standard method name conversion ("set" plus the capitalized name of the property in question) is used.
NOTE: It is contrary to the JavaBeans Specification to have more than one setter method (with different argument signatures) for the same property.
WARNING - The logic of this method is customized for extracting String-based request parameters from an HTTP request. It is probably not what you want for general property copying with type conversion. For that purpose, check out the
copyProperties()
method instead.- Parameters:
bean
- JavaBean whose properties are being populatedproperties
- Map keyed by property name, with the corresponding (String or String[]) value(s) to be set- Throws:
java.lang.IllegalAccessException
- if the caller does not have access to the property accessor methodjava.lang.reflect.InvocationTargetException
- if the property accessor method throws an exception
-
setProperty
public void setProperty(java.lang.Object bean, java.lang.String name, java.lang.Object value) throws java.lang.IllegalAccessException, java.lang.reflect.InvocationTargetException
Set the specified property value, performing type conversions as required to conform to the type of the destination property.
If the property is read only then the method returns without throwing an exception.
If
null
is passed into a property expecting a primitive value, then this will be converted as if it were anull
string.WARNING - The logic of this method is customized to meet the needs of
populate()
, and is probably not what you want for general property copying with type conversion. For that purpose, check out thecopyProperty()
method instead.WARNING - PLEASE do not modify the behavior of this method without consulting with the Struts developer community. There are some subtleties to its functionality that are not documented in the Javadoc description above, yet are vital to the way that Struts utilizes this method.
- Parameters:
bean
- Bean on which setting is to be performedname
- Property name (can be nested/indexed/mapped/combo)value
- Value to be set- Throws:
java.lang.IllegalAccessException
- if the caller does not have access to the property accessor methodjava.lang.reflect.InvocationTargetException
- if the property accessor method throws an exception
-
getConvertUtils
public ConvertUtilsBean getConvertUtils()
Gets theConvertUtilsBean
instance used to perform the conversions.- Returns:
- The ConvertUtils bean instance
-
getPropertyUtils
public PropertyUtilsBean getPropertyUtils()
Gets thePropertyUtilsBean
instance used to access properties.- Returns:
- The ConvertUtils bean instance
-
initCause
public boolean initCause(java.lang.Throwable throwable, java.lang.Throwable cause)
If we're running on JDK 1.4 or later, initialize the cause for the given throwable.- Parameters:
throwable
- The throwable.cause
- The cause of the throwable.- Returns:
- true if the cause was initialized, otherwise false.
- Since:
- 1.8.0
-
convert
protected java.lang.Object convert(java.lang.Object value, java.lang.Class<?> type)
Convert the value to an object of the specified class (if possible).
- Parameters:
value
- Value to be converted (may be null)type
- Class of the value to be converted to- Returns:
- The converted value
- Throws:
ConversionException
- if thrown by an underlying Converter- Since:
- 1.8.0
-
convertForCopy
private java.lang.Object convertForCopy(java.lang.Object value, java.lang.Class<?> type)
Performs a type conversion of a property value before it is copied to a target bean. This method delegates toconvert(Object, Class)
, but null values are not converted. This causes null values to be copied verbatim.- Parameters:
value
- the value to be converted and copiedtype
- the target type of the conversion- Returns:
- the converted value
-
getInitCauseMethod
private static java.lang.reflect.Method getInitCauseMethod()
Returns aMethod
allowing access to
Throwable.initCause(Throwable)
method ofThrowable
, ornull
if the method does not exist.- Returns:
- A
Method
for
Throwable.initCause
, ornull
if unavailable.
-
dynaPropertyType
private static java.lang.Class<?> dynaPropertyType(DynaProperty dynaProperty, java.lang.Object value)
Determines the type of aDynaProperty
. Here a special treatment is needed for mapped properties.- Parameters:
dynaProperty
- the property descriptorvalue
- the value object to be set for this property- Returns:
- the type of this property
-
-