org.apache.commons.collections

Class BeanMap

Implemented Interfaces:
Cloneable

public class BeanMap
extends AbstractMap
implements Cloneable

An implementation of Map for JavaBeans which uses introspection to get and put properties in the bean.

If an exception occurs during attempts to get or set a property then the property is considered non existent in the Map

Version:
$Revision: 1.29 $ $Date: 2004/02/18 01:15:42 $
Authors:
James Strachan
Stephen Colebourne
Since:
Commons Collections 1.0

Nested Class Summary

protected static class
BeanMap.MyMapEntry
Map entry used by BeanMap.

Field Summary

static Object[]
NULL_ARGUMENTS
An empty array.
static HashMap
defaultTransformers
Maps primitive Class types to transformers.

Constructor Summary

BeanMap()
Constructs a new empty BeanMap.
BeanMap(Object bean)
Constructs a new BeanMap that operates on the specified bean.

Method Summary

void
clear()
This method reinitializes the bean map to have default values for the bean's properties.
Object
clone()
Clone this bean map using the following process:
  • If there is no underlying bean, return a cloned BeanMap without a bean.
boolean
containsKey(Object name)
Returns true if the bean defines a property with the given name.
boolean
containsValue(Object value)
Returns true if the bean defines a property whose current value is the given object.
protected Object
convertType(Class newType, Object value)
Converts the given value to the given type.
protected Object[]
createWriteMethodArguments(Method method, Object value)
Creates an array of parameters to pass to the given mutator method.
Iterator
entryIterator()
Convenience method for getting an iterator over the entries.
Set
entrySet()
Gets a Set of MapEntry objects that are the mappings for this BeanMap.
protected void
firePropertyChange(Object key, Object oldValue, Object newValue)
Called during a successful put(Object,Object) operation.
Object
get(Object name)
Returns the value of the bean's property with the given name.
Object
getBean()
Returns the bean currently being operated on.
protected Method
getReadMethod(Object name)
Returns the accessor for the property with the given name.
Method
getReadMethod(String name)
Returns the accessor for the property with the given name.
Class
getType(String name)
Returns the type of the property with the given name.
protected Transformer
getTypeTransformer(Class aType)
Returns a transformer for the given primitive type.
protected Method
getWriteMethod(Object name)
Returns the mutator for the property with the given name.
Method
getWriteMethod(String name)
Returns the mutator for the property with the given name.
Iterator
keyIterator()
Convenience method for getting an iterator over the keys.
Set
keySet()
Get the keys for this BeanMap.
protected void
logInfo(Exception ex)
Logs the given exception to System.out.
protected void
logWarn(Exception ex)
Logs the given exception to System.err.
Object
put(Object name, Object value)
Sets the bean property with the given name to the given value.
void
putAllWriteable(BeanMap map)
Puts all of the writable properties from the given BeanMap into this BeanMap.
protected void
reinitialise()
Reinitializes this bean.
void
setBean(Object newBean)
Sets the bean to be operated on by this map.
int
size()
Returns the number of properties defined by the bean.
String
toString()
Iterator
valueIterator()
Convenience method for getting an iterator over the values.
Collection
values()
Returns the values for the BeanMap.

Field Details

NULL_ARGUMENTS

public static final Object[] NULL_ARGUMENTS
An empty array. Used to invoke accessors via reflection.

defaultTransformers

public static HashMap defaultTransformers
Maps primitive Class types to transformers. The transformer transform strings into the appropriate primitive wrapper.

Constructor Details

BeanMap

public BeanMap()
Constructs a new empty BeanMap.

BeanMap

public BeanMap(Object bean)
Constructs a new BeanMap that operates on the specified bean. If the given bean is null, then this map will be empty.
Parameters:
bean - the bean for this map to operate on

Method Details

clear

public void clear()
This method reinitializes the bean map to have default values for the bean's properties. This is accomplished by constructing a new instance of the bean which the map uses as its underlying data source. This behavior for clear() differs from the Map contract in that the mappings are not actually removed from the map (the mappings for a BeanMap are fixed).

clone

public Object clone()
            throws CloneNotSupportedException
Clone this bean map using the following process:
  • If there is no underlying bean, return a cloned BeanMap without a bean.
  • Since there is an underlying bean, try to instantiate a new bean of the same type using Class.newInstance().
  • If the instantiation fails, throw a CloneNotSupportedException
  • Clone the bean map and set the newly instantiated bean as the underlying bean for the bean map.
  • Copy each property that is both readable and writable from the existing object to a cloned bean map.
  • If anything fails along the way, throw a CloneNotSupportedException.

    containsKey

    public boolean containsKey(Object name)
    Returns true if the bean defines a property with the given name.

    The given name must be a String; if not, this method returns false. This method will also return false if the bean does not define a property with that name.

    Write-only properties will not be matched as the test operates against property read methods.

    Parameters:
    name - the name of the property to check
    Returns:
    false if the given name is null or is not a String; false if the bean does not define a property with that name; or true if the bean does define a property with that name

    containsValue

    public boolean containsValue(Object value)
    Returns true if the bean defines a property whose current value is the given object.
    Parameters:
    value - the value to check
    Returns:
    false true if the bean has at least one property whose current value is that object, false otherwise

    convertType

    protected Object convertType(Class newType,
                                 Object value)
                throws InstantiationException,
                       IllegalAccessException,
                       IllegalArgumentException,
                       InvocationTargetException
    Converts the given value to the given type. First, reflection is is used to find a public constructor declared by the given class that takes one argument, which must be the precise type of the given value. If such a constructor is found, a new object is created by passing the given value to that constructor, and the newly constructed object is returned.

    If no such constructor exists, and the given type is a primitive type, then the given value is converted to a string using its toString() method, and that string is parsed into the correct primitive type using, for instance, Integer.valueOf(String) to convert the string into an int.

    If no special constructor exists and the given type is not a primitive type, this method returns the original value.

    Parameters:
    newType - the type to convert the value to
    value - the value to convert
    Returns:
    the converted value

    createWriteMethodArguments

    protected Object[] createWriteMethodArguments(Method method,
                                                  Object value)
                throws IllegalAccessException,
                       ClassCastException
    Parameters:
    method - the mutator method
    value - the value to pass to the mutator method
    Returns:
    an array containing one object that is either the given value or a transformed value

    entryIterator

    public Iterator entryIterator()
    Convenience method for getting an iterator over the entries.
    Returns:
    an iterator over the entries

    entrySet

    public Set entrySet()
    Gets a Set of MapEntry objects that are the mappings for this BeanMap.

    Each MapEntry can be set but not removed.

    Returns:
    the unmodifiable set of mappings

    firePropertyChange

    protected void firePropertyChange(Object key,
                                      Object oldValue,
                                      Object newValue)
    Called during a successful put(Object,Object) operation. Default implementation does nothing. Override to be notified of property changes in the bean caused by this map.
    Parameters:
    key - the name of the property that changed
    oldValue - the old value for that property
    newValue - the new value for that property

    get

    public Object get(Object name)
    Returns the value of the bean's property with the given name.

    The given name must be a String and must not be null; otherwise, this method returns null. If the bean defines a property with the given name, the value of that property is returned. Otherwise, null is returned.

    Write-only properties will not be matched as the test operates against property read methods.

    Parameters:
    name - the name of the property whose value to return
    Returns:
    the value of the property with that name

    getBean

    public Object getBean()
    Returns the bean currently being operated on. The return value may be null if this map is empty.
    Returns:
    the bean being operated on by this map

    getReadMethod

    protected Method getReadMethod(Object name)
    Returns the accessor for the property with the given name.
    Parameters:
    name - the name of the property
    Returns:
    null if the name is null; null if the name is not a String; null if no such property exists; or the accessor method for that property

    getReadMethod

    public Method getReadMethod(String name)
    Returns the accessor for the property with the given name.
    Parameters:
    name - the name of the property
    Returns:
    the accessor method for the property, or null

    getType

    public Class getType(String name)
    Returns the type of the property with the given name.
    Parameters:
    name - the name of the property
    Returns:
    the type of the property, or null if no such property exists

    getTypeTransformer

    protected Transformer getTypeTransformer(Class aType)
    Returns a transformer for the given primitive type.
    Parameters:
    aType - the primitive type whose transformer to return
    Returns:
    a transformer that will convert strings into that type, or null if the given type is not a primitive type

    getWriteMethod

    protected Method getWriteMethod(Object name)
    Returns the mutator for the property with the given name.
    Parameters:
    name - the name of the
    Returns:
    null if the name is null; null if the name is not a String; null if no such property exists; null if the property is read-only; or the mutator method for that property

    getWriteMethod

    public Method getWriteMethod(String name)
    Returns the mutator for the property with the given name.
    Parameters:
    name - the name of the property
    Returns:
    the mutator method for the property, or null

    keyIterator

    public Iterator keyIterator()
    Convenience method for getting an iterator over the keys.

    Write-only properties will not be returned in the iterator.

    Returns:
    an iterator over the keys

    keySet

    public Set keySet()
    Get the keys for this BeanMap.

    Write-only properties are not included in the returned set of property names, although it is possible to set their value and to get their type.

    Returns:
    BeanMap keys. The Set returned by this method is not modifiable.

    logInfo

    protected void logInfo(Exception ex)
    Logs the given exception to System.out. Used to display warnings while accessing/mutating the bean.
    Parameters:
    ex - the exception to log

    logWarn

    protected void logWarn(Exception ex)
    Logs the given exception to System.err. Used to display errors while accessing/mutating the bean.
    Parameters:
    ex - the exception to log

    put

    public Object put(Object name,
                      Object value)
                throws IllegalArgumentException,
                       ClassCastException
    Sets the bean property with the given name to the given value.
    Parameters:
    name - the name of the property to set
    value - the value to set that property to
    Returns:
    the previous value of that property

    putAllWriteable

    public void putAllWriteable(BeanMap map)
    Puts all of the writable properties from the given BeanMap into this BeanMap. Read-only and Write-only properties will be ignored.
    Parameters:
    map - the BeanMap whose properties to put

    reinitialise

    protected void reinitialise()
    Reinitializes this bean. Called during setBean(Object). Does introspection to find properties.

    setBean

    public void setBean(Object newBean)
    Sets the bean to be operated on by this map. The given value may be null, in which case this map will be empty.
    Parameters:
    newBean - the new bean to operate on

    size

    public int size()
    Returns the number of properties defined by the bean.
    Returns:
    the number of properties defined by the bean

    toString

    public String toString()

    valueIterator

    public Iterator valueIterator()
    Convenience method for getting an iterator over the values.
    Returns:
    an iterator over the values

    values

    public Collection values()
    Returns the values for the BeanMap.
    Returns:
    values for the BeanMap. The returned collection is not modifiable.

    Copyright © 2001-2006 Apache Software Foundation. All Rights Reserved.