org.apache.struts.util
Class PropertyUtils

java.lang.Object
  |
  +--org.apache.struts.util.PropertyUtils

Deprecated. At some point after Struts 1.0 final, will be replaced by an equivalent class in the Jakarta Commons Beanutils package.

public class PropertyUtils

extends java.lang.Object

Utility methods for using Java Reflection APIs to facilitate generic property getter and setter operations on Java objects. Much of this code was originally included in BeanUtils, but has been separated because of the volume of code involved.

In general, the objects that are examined and modified using these methods are expected to conform to the property getter and setter method naming conventions described in the JavaBeans Specification (Version 1.0.1). No data type conversions are performed, and there are no usage of any PropertyEditor classes that have been registered, although a convenient way to access the registered classes themselves is included.

For the purposes of this class, three formats for referencing a particular property value of a bean are defined, with the layout of an identifying String in parentheses:

• Simple (name) - The specified name identifies an individual property of a particular JavaBean. The name of the actual getter or setter method to be used is determined using standard JavaBeans instrospection, so that (unless overridden by a BeanInfo class, a property named "xyz" will have a getter method named getXyz() or (for boolean properties only) isXyz(), and a setter method named setXyz().
• Nested (name1.name2.name3) The first name element is used to select a property getter, as for simple references above. The object returned for this property is then consulted, using the same approach, for a property getter for a property named name2, and so on. The property value that is ultimately retrieved or modified is the one identified by the last name element.
• Indexed (name[index]) - The underlying property value is assumed to be an array, or this JavaBean is assumed to have indexed property getter and setter methods. The appropriate (zero-relative) entry in the array is selected.
• Combined (name1.name2[index].name3 - Various forms combining nested and indexed references are also supported.

Version:

$Revision: 1.1 $ $Date$

Author:

Craig R. McClanahan, Ralph Schaer, Chris Audley

Field Summary

private static int	debug Deprecated. The debugging detail level for this component.
private static FastHashMap	descriptorsCache Deprecated. The cache of PropertyDescriptor arrays for beans we have already introspected, keyed by the fully qualified class name of this object.
static char	INDEXED_DELIM Deprecated. The delimiter that preceeds the zero-relative subscript for an indexed reference.
static char	INDEXED_DELIM2 Deprecated. The delimiter that follows the zero-relative subscript for an indexed reference.
static char	NESTED_DELIM Deprecated. The delimiter that separates the components of a nested reference.

Constructor Summary

PropertyUtils()
Deprecated.

Method Summary

(package private) static void	() Deprecated.
static void	copyProperties(java.lang.Object dest, java.lang.Object orig) Deprecated. Copy property values from the "origin" bean to the "destination" bean for all cases where the property names are the same (even though the actual getter and setter methods might have been customized via BeanInfo classes).
static java.util.Map	describe(java.lang.Object bean) Deprecated. Return the entire set of properties for which the specified bean provides a read method.
private static java.lang.reflect.Method	getAccessibleMethod(java.lang.reflect.Method method) Deprecated. Return an accessible method (that is, one that can be invoked via reflection) that implements the specified Method.
private static java.lang.reflect.Method	getAccessibleMethodFromInterfaceNest(java.lang.Class clazz, java.lang.String methodName, java.lang.Class[] parameterTypes) Deprecated. Return an accessible method (that is, one that can be invoked via reflection) that implements the specified method, by scanning through all implemented interfaces and subinterfaces.
static int	getDebug() Deprecated.
static java.lang.Object	getIndexedProperty(java.lang.Object bean, java.lang.String name) Deprecated. Return the value of the specified indexed property of the specified bean, with no type conversions.
static java.lang.Object	getIndexedProperty(java.lang.Object bean, java.lang.String name, int index) Deprecated. Return the value of the specified indexed property of the specified bean, with no type conversions.
static java.lang.Object	getNestedProperty(java.lang.Object bean, java.lang.String name) Deprecated. Return the value of the (possibly nested) property of the specified name, for the specified bean, with no type conversions.
static java.lang.Object	getProperty(java.lang.Object bean, java.lang.String name) Deprecated. Return the value of the specified property of the specified bean, no matter which property reference format is used, with no type conversions.
static java.beans.PropertyDescriptor	getPropertyDescriptor(java.lang.Object bean, java.lang.String name) Deprecated. Retrieve the property descriptor for the specified property of the specified bean, or return null if there is no such descriptor.
static java.beans.PropertyDescriptor[]	getPropertyDescriptors(java.lang.Object bean) Deprecated. Retrieve the property descriptors for the specified bean, introspecting and caching them the first time a particular bean class is encountered.
static java.lang.Class	getPropertyEditorClass(java.lang.Object bean, java.lang.String name) Deprecated. Return the Java Class repesenting the property editor class that has been registered for this property (if any).
static java.lang.Class	getPropertyType(java.lang.Object bean, java.lang.String name) Deprecated. Return the Java Class representing the property type of the specified property, or null if there is no such property for the specified bean.
static java.lang.reflect.Method	getReadMethod(java.beans.PropertyDescriptor descriptor) Deprecated. Return an accessible property getter method for this property, if there is one; otherwise return null.
static java.lang.Object	getSimpleProperty(java.lang.Object bean, java.lang.String name) Deprecated. Return the value of the specified simple property of the specified bean, with no type conversions.
static java.lang.reflect.Method	getWriteMethod(java.beans.PropertyDescriptor descriptor) Deprecated. Return an accessible property setter method for this property, if there is one; otherwise return null.
static void	setDebug(int newDebug) Deprecated.
static void	setIndexedProperty(java.lang.Object bean, java.lang.String name, int index, java.lang.Object value) Deprecated. Set the value of the specified indexed property of the specified bean, with no type conversions.
static void	setIndexedProperty(java.lang.Object bean, java.lang.String name, java.lang.Object value) Deprecated. Set the value of the specified indexed property of the specified bean, with no type conversions.
static void	setNestedProperty(java.lang.Object bean, java.lang.String name, java.lang.Object value) Deprecated. Set the value of the (possibly nested) property of the specified name, for the specified bean, with no type conversions.
static void	setProperty(java.lang.Object bean, java.lang.String name, java.lang.Object value) Deprecated. Set the value of the specified property of the specified bean, no matter which property reference format is used, with no type conversions.
static void	setSimpleProperty(java.lang.Object bean, java.lang.String name, java.lang.Object value) Deprecated. Set the value of the specified simple property of the specified bean, with no type conversions.

Methods inherited from class java.lang.Object

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

Field Detail

INDEXED_DELIM

public static final char INDEXED_DELIM

Deprecated.

The delimiter that preceeds the zero-relative subscript for an indexed reference.

INDEXED_DELIM2

public static final char INDEXED_DELIM2

Deprecated.

The delimiter that follows the zero-relative subscript for an indexed reference.

NESTED_DELIM

public static final char NESTED_DELIM

Deprecated.

The delimiter that separates the components of a nested reference.

debug

private static int debug

Deprecated.

The debugging detail level for this component.

descriptorsCache

private static FastHashMap descriptorsCache

Deprecated.

The cache of PropertyDescriptor arrays for beans we have already introspected, keyed by the fully qualified class name of this object.

Constructor Detail

PropertyUtils

public PropertyUtils()

Deprecated.

Method Detail

getDebug

public static int getDebug()

Deprecated.

setDebug

public static void setDebug(int newDebug)

Deprecated.

static void ()

Deprecated.

copyProperties

public static void copyProperties(java.lang.Object dest,
                                  java.lang.Object orig)
                           throws java.lang.IllegalAccessException,
                                  java.lang.reflect.InvocationTargetException,
                                  java.lang.NoSuchMethodException

Deprecated.

Copy property values from the "origin" bean to the "destination" bean for all cases where the property names are the same (even though the actual getter and setter methods might have been customized via BeanInfo classes). No conversions are performed on the actual property values -- it is assumed that the values retrieved from the origin bean are assignment-compatible with the types expected by the destination bean.

Parameters:

dest - Destination bean whose properties are modified

orig - Origin bean whose properties are retrieved

Throws:

java.lang.IllegalAccessException - if the caller does not have access to the property accessor method

java.lang.IllegalArgumentException - if the dest or orig argument is null

java.lang.reflect.InvocationTargetException - if the property accessor method throws an exception

java.lang.NoSuchMethodException - if an accessor method for this propety cannot be found

describe

public static java.util.Map describe(java.lang.Object bean)
                              throws java.lang.IllegalAccessException,
                                     java.lang.reflect.InvocationTargetException,
                                     java.lang.NoSuchMethodException

Deprecated.

Return the entire set of properties for which the specified bean provides a read method. This map contains the unconverted property values for all properties for which a read method is provided (i.e. where the getReadMethod() returns non-null).

Parameters:

bean - Bean whose properties are to be extracted

Throws:

java.lang.IllegalAccessException - if the caller does not have access to the property accessor method

java.lang.IllegalArgumentException - if bean is null

java.lang.reflect.InvocationTargetException - if the property accessor method throws an exception

java.lang.NoSuchMethodException - if an accessor method for this propety cannot be found

getIndexedProperty

public static java.lang.Object getIndexedProperty(java.lang.Object bean,
                                                  java.lang.String name)
                                           throws java.lang.IllegalAccessException,
                                                  java.lang.reflect.InvocationTargetException,
                                                  java.lang.NoSuchMethodException

Deprecated.

Return the value of the specified indexed property of the specified bean, with no type conversions. The zero-relative index of the required value must be included (in square brackets) as a suffix to the property name, or IllegalArgumentException will be thrown.

Parameters:

bean - Bean whose property is to be extracted

name - propertyname[index] of the property value to be extracted

Throws:

java.lang.IllegalAccessException - if the caller does not have access to the property accessor method

java.lang.IllegalArgumentException - if bean or name is null

java.lang.reflect.InvocationTargetException - if the property accessor method throws an exception

java.lang.NoSuchMethodException - if an accessor method for this propety cannot be found

getIndexedProperty

public static java.lang.Object getIndexedProperty(java.lang.Object bean,
                                                  java.lang.String name,
                                                  int index)
                                           throws java.lang.IllegalAccessException,
                                                  java.lang.reflect.InvocationTargetException,
                                                  java.lang.NoSuchMethodException

Deprecated.

Return the value of the specified indexed property of the specified bean, with no type conversions.

Parameters:

bean - Bean whose property is to be extracted

name - Simple property name of the property value to be extracted

index - Index of the property value to be extracted

Throws:

java.lang.IllegalAccessException - if the caller does not have access to the property accessor method

java.lang.IllegalArgumentException - if bean or name is null

java.lang.reflect.InvocationTargetException - if the property accessor method throws an exception

java.lang.NoSuchMethodException - if an accessor method for this propety cannot be found

getNestedProperty

public static java.lang.Object getNestedProperty(java.lang.Object bean,
                                                 java.lang.String name)
                                          throws java.lang.IllegalAccessException,
                                                 java.lang.reflect.InvocationTargetException,
                                                 java.lang.NoSuchMethodException

Deprecated.

Return the value of the (possibly nested) property of the specified name, for the specified bean, with no type conversions.

Parameters:

bean - Bean whose property is to be extracted

name - Possibly nested name of the property to be extracted

Throws:

java.lang.IllegalAccessException - if the caller does not have access to the property accessor method

java.lang.IllegalArgumentException - if bean or name is null

java.lang.IllegalArgumentException - if a nested reference to a property returns null

java.lang.reflect.InvocationTargetException - if the property accessor method throws an exception

java.lang.NoSuchMethodException - if an accessor method for this propety cannot be found

getProperty

public static java.lang.Object getProperty(java.lang.Object bean,
                                           java.lang.String name)
                                    throws java.lang.IllegalAccessException,
                                           java.lang.reflect.InvocationTargetException,
                                           java.lang.NoSuchMethodException

Deprecated.

Return the value of the specified property of the specified bean, no matter which property reference format is used, with no type conversions.

Parameters:

bean - Bean whose property is to be extracted

name - Possibly indexed and/or nested name of the property to be extracted

Throws:

java.lang.IllegalAccessException - if the caller does not have access to the property accessor method

java.lang.IllegalArgumentException - if bean or name is null

java.lang.reflect.InvocationTargetException - if the property accessor method throws an exception

java.lang.NoSuchMethodException - if an accessor method for this propety cannot be found

getPropertyDescriptor

public static java.beans.PropertyDescriptor getPropertyDescriptor(java.lang.Object bean,
                                                                  java.lang.String name)
                                                           throws java.lang.IllegalAccessException,
                                                                  java.lang.reflect.InvocationTargetException,
                                                                  java.lang.NoSuchMethodException

Deprecated.

Retrieve the property descriptor for the specified property of the specified bean, or return null if there is no such descriptor. This method resolves indexed and nested property references in the same manner as other methods in this class, except that if the last (or only) name element is indexed, the descriptor for the last resolved property itself is returned.

Parameters:

bean - Bean for which a property descriptor is requested

name - Possibly indexed and/or nested name of the property for which a property descriptor is requested

Throws:

java.lang.IllegalAccessException - if the caller does not have access to the property accessor method

java.lang.IllegalArgumentException - if bean or name is null

java.lang.IllegalArgumentException - if a nested reference to a property returns null

java.lang.reflect.InvocationTargetException - if the property accessor method throws an exception

java.lang.NoSuchMethodException - if an accessor method for this propety cannot be found

getPropertyDescriptors

public static java.beans.PropertyDescriptor[] getPropertyDescriptors(java.lang.Object bean)

Deprecated.

Retrieve the property descriptors for the specified bean, introspecting and caching them the first time a particular bean class is encountered.

Parameters:

bean - Bean for which property descriptors are requested

Throws:

java.lang.IllegalArgumentException - if bean is null

getPropertyEditorClass

public static java.lang.Class getPropertyEditorClass(java.lang.Object bean,
                                                     java.lang.String name)
                                              throws java.lang.IllegalAccessException,
                                                     java.lang.reflect.InvocationTargetException,
                                                     java.lang.NoSuchMethodException

Deprecated.

Return the Java Class repesenting the property editor class that has been registered for this property (if any). This method follows the same name resolution rules used by getPropertyDescriptor(), so if the last element of a name reference is indexed, the property editor for the underlying property's class is returned.

Note that null will be returned if there is no property, or if there is no registered property editor class. Because this return value is ambiguous, you should determine the existence of the property itself by other means.

Parameters:

bean - Bean for which a property descriptor is requested

name - Possibly indexed and/or nested name of the property for which a property descriptor is requested

Throws:

java.lang.IllegalAccessException - if the caller does not have access to the property accessor method

java.lang.IllegalArgumentException - if bean or name is null

java.lang.IllegalArgumentException - if a nested reference to a property returns null

java.lang.reflect.InvocationTargetException - if the property accessor method throws an exception

java.lang.NoSuchMethodException - if an accessor method for this propety cannot be found

getPropertyType

public static java.lang.Class getPropertyType(java.lang.Object bean,
                                              java.lang.String name)
                                       throws java.lang.IllegalAccessException,
                                              java.lang.reflect.InvocationTargetException,
                                              java.lang.NoSuchMethodException

Deprecated.

Return the Java Class representing the property type of the specified property, or null if there is no such property for the specified bean. This method follows the same name resolution rules used by getPropertyDescriptor(), so if the last element of a name reference is indexed, the type of the property itself will be returned. If the last (or only) element has no property with the specified name, null is returned.

Parameters:

bean - Bean for which a property descriptor is requested

name - Possibly indexed and/or nested name of the property for which a property descriptor is requested

Throws:

java.lang.IllegalAccessException - if the caller does not have access to the property accessor method

java.lang.IllegalArgumentException - if bean or name is null

java.lang.IllegalArgumentException - if a nested reference to a property returns null

java.lang.reflect.InvocationTargetException - if the property accessor method throws an exception

java.lang.NoSuchMethodException - if an accessor method for this propety cannot be found

getReadMethod

public static java.lang.reflect.Method getReadMethod(java.beans.PropertyDescriptor descriptor)

Deprecated.

Return an accessible property getter method for this property, if there is one; otherwise return null.

Parameters:

descriptor - Property descriptor to return a getter for

getSimpleProperty

public static java.lang.Object getSimpleProperty(java.lang.Object bean,
                                                 java.lang.String name)
                                          throws java.lang.IllegalAccessException,
                                                 java.lang.reflect.InvocationTargetException,
                                                 java.lang.NoSuchMethodException

Deprecated.

Return the value of the specified simple property of the specified bean, with no type conversions.

Parameters:

bean - Bean whose property is to be extracted

name - Name of the property to be extracted

Throws:

java.lang.IllegalAccessException - if the caller does not have access to the property accessor method

java.lang.IllegalArgumentException - if bean or name is null

java.lang.IllegalArgumentException - if the property name is nested or indexed

java.lang.reflect.InvocationTargetException - if the property accessor method throws an exception

java.lang.NoSuchMethodException - if an accessor method for this propety cannot be found

getWriteMethod

public static java.lang.reflect.Method getWriteMethod(java.beans.PropertyDescriptor descriptor)

Deprecated.

Return an accessible property setter method for this property, if there is one; otherwise return null.

Parameters:

descriptor - Property descriptor to return a setter for

setIndexedProperty

public static void setIndexedProperty(java.lang.Object bean,
                                      java.lang.String name,
                                      java.lang.Object value)
                               throws java.lang.IllegalAccessException,
                                      java.lang.reflect.InvocationTargetException,
                                      java.lang.NoSuchMethodException

Deprecated.

Set the value of the specified indexed property of the specified bean, with no type conversions. The zero-relative index of the required value must be included (in square brackets) as a suffix to the property name, or IllegalArgumentException will be thrown.

Parameters:

bean - Bean whose property is to be modified

name - propertyname[index] of the property value to be modified

value - Value to which the specified property element should be set

Throws:

java.lang.IllegalAccessException - if the caller does not have access to the property accessor method

java.lang.IllegalArgumentException - if bean or name is null

java.lang.reflect.InvocationTargetException - if the property accessor method throws an exception

java.lang.NoSuchMethodException - if an accessor method for this propety cannot be found

setIndexedProperty

public static void setIndexedProperty(java.lang.Object bean,
                                      java.lang.String name,
                                      int index,
                                      java.lang.Object value)
                               throws java.lang.IllegalAccessException,
                                      java.lang.reflect.InvocationTargetException,
                                      java.lang.NoSuchMethodException

Deprecated.

Set the value of the specified indexed property of the specified bean, with no type conversions.

Parameters:

bean - Bean whose property is to be set

name - Simple property name of the property value to be set

index - Index of the property value to be set

value - Value to which the indexed property element is to be set

Throws:

java.lang.IllegalAccessException - if the caller does not have access to the property accessor method

java.lang.IllegalArgumentException - if bean or name is null

java.lang.reflect.InvocationTargetException - if the property accessor method throws an exception

java.lang.NoSuchMethodException - if an accessor method for this propety cannot be found

setNestedProperty

public static void setNestedProperty(java.lang.Object bean,
                                     java.lang.String name,
                                     java.lang.Object value)
                              throws java.lang.IllegalAccessException,
                                     java.lang.reflect.InvocationTargetException,
                                     java.lang.NoSuchMethodException

Deprecated.

Set the value of the (possibly nested) property of the specified name, for the specified bean, with no type conversions.

Parameters:

bean - Bean whose property is to be modified

name - Possibly nested name of the property to be modified

value - Value to which the property is to be set

Throws:

java.lang.IllegalAccessException - if the caller does not have access to the property accessor method

java.lang.IllegalArgumentException - if bean or name is null

java.lang.IllegalArgumentException - if a nested reference to a property returns null

java.lang.reflect.InvocationTargetException - if the property accessor method throws an exception

java.lang.NoSuchMethodException - if an accessor method for this propety cannot be found

setProperty

public static void setProperty(java.lang.Object bean,
                               java.lang.String name,
                               java.lang.Object value)
                        throws java.lang.IllegalAccessException,
                               java.lang.reflect.InvocationTargetException,
                               java.lang.NoSuchMethodException

Deprecated.

Set the value of the specified property of the specified bean, no matter which property reference format is used, with no type conversions.

Parameters:

bean - Bean whose property is to be modified

name - Possibly indexed and/or nested name of the property to be modified

value - Value to which this property is to be set

Throws:

java.lang.IllegalAccessException - if the caller does not have access to the property accessor method

java.lang.IllegalArgumentException - if bean or name is null

java.lang.reflect.InvocationTargetException - if the property accessor method throws an exception

java.lang.NoSuchMethodException - if an accessor method for this propety cannot be found

setSimpleProperty

public static void setSimpleProperty(java.lang.Object bean,
                                     java.lang.String name,
                                     java.lang.Object value)
                              throws java.lang.IllegalAccessException,
                                     java.lang.reflect.InvocationTargetException,
                                     java.lang.NoSuchMethodException

Deprecated.

Set the value of the specified simple property of the specified bean, with no type conversions.

Parameters:

bean - Bean whose property is to be modified

name - Name of the property to be modified

value - Value to which the property should be set

Throws:

java.lang.IllegalAccessException - if the caller does not have access to the property accessor method

java.lang.IllegalArgumentException - if bean or name is null

java.lang.IllegalArgumentException - if the property name is nested or indexed

java.lang.reflect.InvocationTargetException - if the property accessor method throws an exception

java.lang.NoSuchMethodException - if an accessor method for this propety cannot be found

getAccessibleMethod

private static java.lang.reflect.Method getAccessibleMethod(java.lang.reflect.Method method)

Deprecated.

Return an accessible method (that is, one that can be invoked via reflection) that implements the specified Method. If no such method can be found, return null.

Parameters:

method - The method that we wish to call

getAccessibleMethodFromInterfaceNest

private static java.lang.reflect.Method getAccessibleMethodFromInterfaceNest(java.lang.Class clazz,
                                                                             java.lang.String methodName,
                                                                             java.lang.Class[] parameterTypes)

Deprecated.

Return an accessible method (that is, one that can be invoked via reflection) that implements the specified method, by scanning through all implemented interfaces and subinterfaces. If no such Method can be found, return null.

Parameters:

clazz - Parent class for the interfaces to be checked

methodName - Method name of the method we wish to call

parameterTypes - The parameter type signatures