org.apache.commons.collections
Class BeanMap

java.lang.Object
  |
  +--java.util.AbstractMap
        |
        +--org.apache.commons.collections.BeanMap

All Implemented Interfaces:

java.lang.Cloneable, java.util.Map

public class BeanMap

extends java.util.AbstractMap

implements java.lang.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:

1.0

Author:

James Strachan

Field Summary

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

Constructor Summary

BeanMap()
Constructs a new empty BeanMap.

BeanMap(java.lang.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.
java.lang.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(java.lang.Object name) Returns true if the bean defines a property with the given name.
boolean	containsValue(java.lang.Object value) Returns true if the bean defines a property whose current value is the given object.
java.util.Iterator	entryIterator() Convenience method for getting an iterator over the entries.
java.util.Set	entrySet() Get the mappings for this BeanMap
java.lang.Object	get(java.lang.Object name) Returns the value of the bean's property with the given name.
java.lang.Object	getBean() Returns the bean currently being operated on.
java.lang.Class	getType(java.lang.String name) Returns the type of the property with the given name.
java.util.Iterator	keyIterator() Convenience method for getting an iterator over the keys.
java.util.Set	keySet() Get the keys for this BeanMap.
java.lang.Object	put(java.lang.Object name, java.lang.Object value) Sets the bean property with the given name to the given value.
void	putAllWriteable(BeanMap map) Puts all of the writeable properties from the given BeanMap into this BeanMap.
void	setBean(java.lang.Object newBean) Sets the bean to be operated on by this map.
int	size() Returns the number of properties defined by the bean.
java.util.Iterator	valueIterator() Convenience method for getting an iterator over the values.
java.util.Collection	values() Returns the values for the BeanMap.

Methods inherited from class java.util.AbstractMap

equals, hashCode, isEmpty, putAll, remove, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

NULL_ARGUMENTS

public static final java.lang.Object[] NULL_ARGUMENTS

An empty array. Used to invoke accessors via reflection.

defaultTransformers

public static java.util.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(java.lang.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

clone

public java.lang.Object clone()
                       throws java.lang.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 underyling 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.

  Overrides:

  clone in class java.util.AbstractMap

  java.lang.CloneNotSupportedException

putAllWriteable

public void putAllWriteable(BeanMap map)

Puts all of the writeable properties from the given BeanMap into this BeanMap. Read-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 java.util.Map

Overrides:

clear in class java.util.AbstractMap

containsKey

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

Specified by:

containsKey in interface java.util.Map

Overrides:

containsKey in class java.util.AbstractMap

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(java.lang.Object value)

Returns true if the bean defines a property whose current value is the given object.

Specified by:

containsValue in interface java.util.Map

Overrides:

containsValue in class java.util.AbstractMap

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 java.lang.Object get(java.lang.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.

Specified by:

get in interface java.util.Map

Overrides:

get in class java.util.AbstractMap

Parameters:

name - the name of the property whose value to return

Returns:

the value of the property with that name

put

public java.lang.Object put(java.lang.Object name,
                            java.lang.Object value)
                     throws java.lang.IllegalArgumentException,
                            java.lang.ClassCastException

Sets the bean property with the given name to the given value.

Specified by:

put in interface java.util.Map

Overrides:

put in class java.util.AbstractMap

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:

java.lang.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

java.lang.ClassCastException

size

public int size()

Returns the number of properties defined by the bean.

Specified by:

size in interface java.util.Map

Overrides:

size in class java.util.AbstractMap

Returns:

the number of properties defined by the bean

keySet

public java.util.Set keySet()

Get the keys for this BeanMap.

Specified by:

keySet in interface java.util.Map

Overrides:

keySet in class java.util.AbstractMap

Returns:

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

entrySet

public java.util.Set entrySet()

Get the mappings for this BeanMap

Specified by:

entrySet in interface java.util.Map

Specified by:

entrySet in class java.util.AbstractMap

Returns:

BeanMap mappings. The Set returned by this method is not modifiable.

values

public java.util.Collection values()

Returns the values for the BeanMap.

Specified by:

values in interface java.util.Map

Overrides:

values in class java.util.AbstractMap

Returns:

values for the BeanMap. The returned collection is not modifiable.

getType

public java.lang.Class getType(java.lang.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 java.util.Iterator keyIterator()

Convenience method for getting an iterator over the keys.

Returns:

an iterator over the keys

valueIterator

public java.util.Iterator valueIterator()

Convenience method for getting an iterator over the values.

Returns:

an iterator over the values

entryIterator

public java.util.Iterator entryIterator()

Convenience method for getting an iterator over the entries.

Returns:

an iterator over the entries

getBean

public java.lang.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(java.lang.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