org.apache.commons.collections
Class BeanMap

java.lang.Object
  extended by java.util.AbstractMap<String,Object>
      extended by org.apache.commons.collections.BeanMap
All Implemented Interfaces:
Cloneable, Map<String,Object>

public class BeanMap
extends AbstractMap<String,Object>
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

Since:
Commons Collections 1.0
Version:
$Revision: 1.1.1.1 $ $Date: 2005/05/23 04:32:37 $
Author:
James Strachan, Matt Hall, John Watkinson, Stephen Colebourne

Nested Class Summary
protected static class BeanMap.MyMapEntry
          Map entry used by BeanMap.
 
Nested classes/interfaces inherited from interface java.util.Map
Map.Entry<K,V>
 
Field Summary
static HashMap defaultTransformers
          Maps primitive Class types to transformers.
static Object[] NULL_ARGUMENTS
          An empty array.
 
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(String 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<Map.Entry<String,Object>> entryIterator()
          Convenience method for getting an iterator over the entries.
 Set<Map.Entry<String,Object>> entrySet()
          Gets a Set of MapEntry objects that are the mappings for this BeanMap.
protected  void firePropertyChange(String key, Object oldValue, Object newValue)
          Called during a successful AbstractMap.put(Object,Object) operation.
 Object get(String name)
          Returns the value of the bean's property with the given name.
 Object getBean()
          Returns the bean currently being operated on.
 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.
 Method getWriteMethod(String name)
          Returns the mutator for the property with the given name.
 Iterator<String> keyIterator()
          Convenience method for getting an iterator over the keys.
 Set<String> 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(String 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<Object> valueIterator()
          Convenience method for getting an iterator over the values.
 Collection<Object> values()
          Returns the values for the BeanMap.
 
Methods inherited from class java.util.AbstractMap
containsKey, equals, get, hashCode, isEmpty, putAll, remove
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

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 Detail

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 Detail

toString

public String toString()
Overrides:
toString in class AbstractMap<String,Object>

clone

public Object clone()
             throws CloneNotSupportedException
Clone this bean map using the following process:


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

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).

Specified by:
clear in interface Map<String,Object>
Overrides:
clear in class AbstractMap<String,Object>

containsKey

public boolean containsKey(String 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.

Specified by:
containsValue in interface Map<String,Object>
Overrides:
containsValue in class AbstractMap<String,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

get

public Object get(String 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

put

public Object put(String name,
                  Object value)
           throws IllegalArgumentException,
                  ClassCastException
Sets the bean property with the given name to the given value.

Specified by:
put in interface Map<String,Object>
Overrides:
put in class AbstractMap<String,Object>
Parameters:
name - the name of the property to set
value - the value to set that property to
Returns:
the previous value of that property
Throws:
IllegalArgumentException - if the given name is null; if the given name is not a String; if the bean doesn't define a property with that name; or if the bean property with that name is read-only
ClassCastException

size

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

Specified by:
size in interface Map<String,Object>
Overrides:
size in class AbstractMap<String,Object>
Returns:
the number of properties defined by the bean

keySet

public Set<String> 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.

Specified by:
keySet in interface Map<String,Object>
Overrides:
keySet in class AbstractMap<String,Object>
Returns:
BeanMap keys. The Set returned by this method is not modifiable.

entrySet

public Set<Map.Entry<String,Object>> entrySet()
Gets a Set of MapEntry objects that are the mappings for this BeanMap.

Each MapEntry can be set but not removed.

Specified by:
entrySet in interface Map<String,Object>
Specified by:
entrySet in class AbstractMap<String,Object>
Returns:
the unmodifiable set of mappings

values

public Collection<Object> values()
Returns the values for the BeanMap.

Specified by:
values in interface Map<String,Object>
Overrides:
values in class AbstractMap<String,Object>
Returns:
values for the BeanMap. The returned collection is not modifiable.

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

keyIterator

public Iterator<String> 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

valueIterator

public Iterator<Object> valueIterator()
Convenience method for getting an iterator over the values.

Returns:
an iterator over the values

entryIterator

public Iterator<Map.Entry<String,Object>> entryIterator()
Convenience method for getting an iterator over the entries.

Returns:
an iterator over the entries

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

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

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

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

reinitialise

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


firePropertyChange

protected void firePropertyChange(String key,
                                  Object oldValue,
                                  Object newValue)
Called during a successful AbstractMap.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

createWriteMethodArguments

protected Object[] createWriteMethodArguments(Method method,
                                              Object value)
                                       throws IllegalAccessException,
                                              ClassCastException
Creates an array of parameters to pass to the given mutator method. If the given object is not the right type to pass to the method directly, it will be converted using convertType(Class,Object).

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
Throws:
IllegalAccessException - if convertType(Class,Object) raises it
IllegalArgumentException - if any other exception is raised by convertType(Class,Object)
ClassCastException

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
Throws:
NumberFormatException - if newType is a primitive type, and the string representation of the given value cannot be converted to that type
InstantiationException - if the constructor found with reflection raises it
InvocationTargetException - if the constructor found with reflection raises it
IllegalAccessException - never
IllegalArgumentException - never

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

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


Copyright © 2005-2005 Apache Software Foundation, Matt Hall, John Watkinson. All Rights Reserved.