com.jgoodies.binding.beans
Class BeanUtils

java.lang.Object
  com.jgoodies.binding.beans.BeanUtils

public final class BeanUtils
extends java.lang.Object

Consists exclusively of static methods that provide convenience behavior for working with Java Bean properties.

Version:

$Revision: 1.12 $

Author:

Karsten Lentzsch

See Also:

Introspector, BeanInfo, PropertyDescriptor

Method Summary

static void	addPropertyChangeListener(java.lang.Object bean, java.lang.Class<?> beanClass, java.beans.PropertyChangeListener listener) Adds a property change listener to the given bean.
static void	addPropertyChangeListener(java.lang.Object bean, java.lang.Class<?> beanClass, java.lang.String propertyName, java.beans.PropertyChangeListener listener) Adds a named property change listener to the given bean.
static void	addPropertyChangeListener(java.lang.Object bean, java.beans.PropertyChangeListener listener) Adds a property change listener to the given bean.
static void	addPropertyChangeListener(java.lang.Object bean, java.lang.String propertyName, java.beans.PropertyChangeListener listener) Adds a named property change listener to the given bean.
static java.lang.reflect.Method	getNamedPCLAdder(java.lang.Class<?> clazz) Looks up and returns the method that adds a PropertyChangeListener for a specified property name to instances of the given class.
static java.lang.reflect.Method	getNamedPCLRemover(java.lang.Class<?> clazz) Looks up and returns the method that removes a PropertyChangeListener for a specified property name from instances of the given class.
static java.lang.reflect.Method	getPCLAdder(java.lang.Class<?> clazz) Looks up and returns the method that adds a multicast PropertyChangeListener to instances of the given class.
static java.lang.reflect.Method	getPCLRemover(java.lang.Class<?> clazz) Looks up and returns the method that removes a multicast PropertyChangeListener from instances of the given class.
static java.beans.PropertyDescriptor	getPropertyDescriptor(java.lang.Class<?> beanClass, java.lang.String propertyName) Looks up and returns a PropertyDescriptor for the given Java Bean class and property name using the standard Java Bean introspection behavior.
static java.beans.PropertyDescriptor	getPropertyDescriptor(java.lang.Class<?> beanClass, java.lang.String propertyName, java.lang.String getterName, java.lang.String setterName) Looks up and returns a PropertyDescriptor for the given Java Bean class and property name.
static java.lang.Object	getValue(java.lang.Object bean, java.beans.PropertyDescriptor propertyDescriptor) Returns the value of the specified property of the given non-null bean.
static void	removePropertyChangeListener(java.lang.Object bean, java.lang.Class<?> beanClass, java.beans.PropertyChangeListener listener) Removes a property change listener from the given bean.
static void	removePropertyChangeListener(java.lang.Object bean, java.lang.Class<?> beanClass, java.lang.String propertyName, java.beans.PropertyChangeListener listener) Removes a named property change listener from the given bean.
static void	removePropertyChangeListener(java.lang.Object bean, java.beans.PropertyChangeListener listener) Removes a property change listener from the given bean.
static void	removePropertyChangeListener(java.lang.Object bean, java.lang.String propertyName, java.beans.PropertyChangeListener listener) Removes a named property change listener from the given bean.
static void	setValue(java.lang.Object bean, java.beans.PropertyDescriptor propertyDescriptor, java.lang.Object newValue) Sets the given object as new value of the specified property of the given non-null bean.
static boolean	supportsBoundProperties(java.lang.Class<?> clazz) Checks and answers whether the given class supports bound properties, i.e. it provides a pair of multicast event listener registration methods for PropertyChangeListeners: public void addPropertyChangeListener(PropertyChangeListener x); public void removePropertyChangeListener(PropertyChangeListener x);

Methods inherited from class java.lang.Object

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

Method Detail

supportsBoundProperties

public static boolean supportsBoundProperties(java.lang.Class<?> clazz)

Checks and answers whether the given class supports bound properties, i.e. it provides a pair of multicast event listener registration methods for PropertyChangeListeners:

 public void addPropertyChangeListener(PropertyChangeListener x);
 public void removePropertyChangeListener(PropertyChangeListener x);
 

Parameters:

clazz - the class to test

Returns:

true if the class supports bound properties, false otherwise

getPropertyDescriptor

public static java.beans.PropertyDescriptor getPropertyDescriptor(java.lang.Class<?> beanClass,
                                                                  java.lang.String propertyName)
                                                           throws java.beans.IntrospectionException

Looks up and returns a PropertyDescriptor for the given Java Bean class and property name using the standard Java Bean introspection behavior.

Parameters:

beanClass - the type of the bean that holds the property

propertyName - the name of the Bean property

Returns:

the PropertyDescriptor associated with the given bean and property name as returned by the Bean introspection

Throws:

java.beans.IntrospectionException - if an exception occurs during introspection.

java.lang.NullPointerException - if the beanClass or propertyName is null

Since:

1.1.1

getPropertyDescriptor

public static java.beans.PropertyDescriptor getPropertyDescriptor(java.lang.Class<?> beanClass,
                                                                  java.lang.String propertyName,
                                                                  java.lang.String getterName,
                                                                  java.lang.String setterName)

Looks up and returns a PropertyDescriptor for the given Java Bean class and property name. If a getter name or setter name is available, these are used to create a PropertyDescriptor. Otherwise, the standard Java Bean introspection is used to determine the property descriptor.

Parameters:

beanClass - the class of the bean that holds the property

propertyName - the name of the property to be accessed

getterName - the optional name of the property's getter

setterName - the optional name of the property's setter

Returns:

the PropertyDescriptor associated with the given bean and property name

Throws:

PropertyNotFoundException - if the property could not be found

Since:

1.1.1

getPCLAdder

public static java.lang.reflect.Method getPCLAdder(java.lang.Class<?> clazz)

Looks up and returns the method that adds a multicast PropertyChangeListener to instances of the given class.

Parameters:

clazz - the class that provides the adder method

Returns:

the method that adds multicast PropertyChangeListeners

getPCLRemover

public static java.lang.reflect.Method getPCLRemover(java.lang.Class<?> clazz)

Looks up and returns the method that removes a multicast PropertyChangeListener from instances of the given class.

Parameters:

clazz - the class that provides the remover method

Returns:

the method that removes multicast PropertyChangeListeners

getNamedPCLAdder

public static java.lang.reflect.Method getNamedPCLAdder(java.lang.Class<?> clazz)

Looks up and returns the method that adds a PropertyChangeListener for a specified property name to instances of the given class.

Parameters:

clazz - the class that provides the adder method

Returns:

the method that adds the PropertyChangeListeners

getNamedPCLRemover

public static java.lang.reflect.Method getNamedPCLRemover(java.lang.Class<?> clazz)

Looks up and returns the method that removes a PropertyChangeListener for a specified property name from instances of the given class.

Parameters:

clazz - the class that provides the remover method

Returns:

the method that removes the PropertyChangeListeners

addPropertyChangeListener

public static void addPropertyChangeListener(java.lang.Object bean,
                                             java.lang.Class<?> beanClass,
                                             java.beans.PropertyChangeListener listener)

Adds a property change listener to the given bean. First checks whether the bean supports bound properties, i.e. it provides a pair of methods to register multicast property change event listeners; see section 7.4.1 of the Java Beans specification for details.

Parameters:

bean - the bean to add the property change listener to

beanClass - the Bean class used to lookup methods from

listener - the listener to add

Throws:

java.lang.NullPointerException - if the bean or listener is null

java.lang.IllegalArgumentException - if the bean is not an instance of the bean class

PropertyUnboundException - if the bean does not support bound properties

PropertyNotBindableException - if the property change handler cannot be added successfully

Since:

1.1.1

addPropertyChangeListener

public static void addPropertyChangeListener(java.lang.Object bean,
                                             java.lang.Class<?> beanClass,
                                             java.lang.String propertyName,
                                             java.beans.PropertyChangeListener listener)

Adds a named property change listener to the given bean. The bean must provide the optional support for listening on named properties as described in section 7.4.5 of the Java Bean Specification. The bean class must provide the method:

 public void addPropertyChangeListener(String name, PropertyChangeListener l);
 

Parameters:

bean - the bean to add a property change handler

beanClass - the Bean class used to lookup methods from

propertyName - the name of the property to be observed

listener - the listener to add

Throws:

java.lang.NullPointerException - if the bean, propertyName or listener is null

java.lang.IllegalArgumentException - if the bean is not an instance of the bean class

PropertyNotBindableException - if the property change handler cannot be added successfully

addPropertyChangeListener

public static void addPropertyChangeListener(java.lang.Object bean,
                                             java.beans.PropertyChangeListener listener)

Adds a property change listener to the given bean. First checks whether the bean supports bound properties, i.e. it provides a pair of methods to register multicast property change event listeners; see section 7.4.1 of the Java Beans specification for details.

Parameters:

bean - the bean to add the property change listener to

listener - the listener to add

Throws:

java.lang.NullPointerException - if the bean or listener is null

PropertyUnboundException - if the bean does not support bound properties

PropertyNotBindableException - if the property change handler cannot be added successfully

addPropertyChangeListener

public static void addPropertyChangeListener(java.lang.Object bean,
                                             java.lang.String propertyName,
                                             java.beans.PropertyChangeListener listener)

Adds a named property change listener to the given bean. The bean must provide the optional support for listening on named properties as described in section 7.4.5 of the Java Bean Specification. The bean class must provide the method:

 public void addPropertyChangeListener(String name, PropertyChangeListener l);
 

Parameters:

bean - the bean to add a property change handler

propertyName - the name of the property to be observed

listener - the listener to add

Throws:

java.lang.NullPointerException - if the bean, propertyName or listener is null

PropertyNotBindableException - if the property change handler cannot be added successfully

removePropertyChangeListener

public static void removePropertyChangeListener(java.lang.Object bean,
                                                java.lang.Class<?> beanClass,
                                                java.beans.PropertyChangeListener listener)

Removes a property change listener from the given bean.

Parameters:

bean - the bean to remove the property change listener from

beanClass - the Java Bean class used to lookup methods from

listener - the listener to remove

Throws:

java.lang.NullPointerException - if the bean or listener is null

java.lang.IllegalArgumentException - if the bean is not an instance of the bean class

PropertyUnboundException - if the bean does not support bound properties

PropertyNotBindableException - if the property change handler cannot be removed successfully

Since:

1.1.1

removePropertyChangeListener

public static void removePropertyChangeListener(java.lang.Object bean,
                                                java.lang.Class<?> beanClass,
                                                java.lang.String propertyName,
                                                java.beans.PropertyChangeListener listener)

Removes a named property change listener from the given bean. The bean must provide the optional support for listening on named properties as described in section 7.4.5 of the Java Bean Specification. The bean class must provide the method:

 public void removePropertyChangeHandler(String name, PropertyChangeListener l);
 

Parameters:

bean - the bean to remove the property change listener from

beanClass - the Java Bean class used to lookup methods from

propertyName - the name of the observed property

listener - the listener to remove

Throws:

java.lang.NullPointerException - if the bean, propertyName, or listener is null

java.lang.IllegalArgumentException - if the bean is not an instance of the bean class

PropertyNotBindableException - if the property change handler cannot be removed successfully

Since:

1.1.1

removePropertyChangeListener

public static void removePropertyChangeListener(java.lang.Object bean,
                                                java.beans.PropertyChangeListener listener)

Removes a property change listener from the given bean.

Parameters:

bean - the bean to remove the property change listener from

listener - the listener to remove

Throws:

java.lang.NullPointerException - if the bean or listener is null

PropertyUnboundException - if the bean does not support bound properties

PropertyNotBindableException - if the property change handler cannot be removed successfully

removePropertyChangeListener

public static void removePropertyChangeListener(java.lang.Object bean,
                                                java.lang.String propertyName,
                                                java.beans.PropertyChangeListener listener)

Removes a named property change listener from the given bean. The bean must provide the optional support for listening on named properties as described in section 7.4.5 of the Java Bean Specification. The bean class must provide the method:

 public void removePropertyChangeHandler(String name, PropertyChangeListener l);
 

Parameters:

bean - the bean to remove the property change listener from

propertyName - the name of the observed property

listener - the listener to remove

Throws:

java.lang.NullPointerException - if the bean, propertyName, or listener is null

PropertyNotBindableException - if the property change handler cannot be removed successfully

getValue

public static java.lang.Object getValue(java.lang.Object bean,
                                        java.beans.PropertyDescriptor propertyDescriptor)

Returns the value of the specified property of the given non-null bean. This operation is unsupported if the bean property is read-only.

If the read access fails, a PropertyAccessException is thrown that provides the Throwable that caused the failure.

Parameters:

bean - the bean to read the value from

propertyDescriptor - describes the property to be read

Returns:

the bean's property value

Throws:

java.lang.NullPointerException - if the bean is null

java.lang.UnsupportedOperationException - if the bean property is write-only

PropertyAccessException - if the new value could not be read

setValue

public static void setValue(java.lang.Object bean,
                            java.beans.PropertyDescriptor propertyDescriptor,
                            java.lang.Object newValue)
                     throws java.beans.PropertyVetoException

Sets the given object as new value of the specified property of the given non-null bean. This is unsupported if the bean property is read-only.

If the write access fails, a PropertyAccessException is thrown that provides the Throwable that caused the failure. If the bean property is constrained and a VetoableChangeListener has vetoed against the value change, the PropertyAccessException wraps the PropertyVetoException thrown by the setter.

Parameters:

bean - the bean that holds the adapted property

propertyDescriptor - describes the property to be set

newValue - the property value to be set

Throws:

java.lang.NullPointerException - if the bean is null

java.lang.UnsupportedOperationException - if the bean property is read-only

PropertyAccessException - if the new value could not be set

java.beans.PropertyVetoException - if the bean setter throws this exception