Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.beanutils
Class BeanMap

    java.lang.Object
      |
      +--java.util.AbstractMap
            |
            +--org.apache.commons.beanutils.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

Version:
  $Revision: 557796 $ $Date: 2007-07-19 23:28:49 +0100 (Thu, 19 Jul 2007) $
Author:
  James Strachan, Stephen Colebourne

Inner Class Summary
`protected static class` | `BeanMap.Entry` Map entry used by `BeanMap`.

Inner classes inherited from class java.util.Map
`java.util.Map.Entry`

Field Summary
`static java.util.HashMap` | `defaultTransformers` Deprecated. Use `getTypeTransformer(Class)` method
`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.
`protected java.lang.Object` | `convertType(java.lang.Class newType, java.lang.Object value)` Converts the given value to the given type.
`protected java.lang.Object[]` | `createWriteMethodArguments(java.lang.reflect.Method method, java.lang.Object value)` Creates an array of parameters to pass to the given mutator method.
`java.util.Iterator` | `entryIterator()` Convenience method for getting an iterator over the entries.
`java.util.Set` | `entrySet()` Gets a Set of MapEntry objects that are the mappings for this BeanMap.
`protected void` | `firePropertyChange(java.lang.Object key, java.lang.Object oldValue, java.lang.Object newValue)` Called during a successful `put(Object,Object)` operation.
`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.
`protected java.lang.reflect.Method` | `getReadMethod(java.lang.Object name)` Returns the accessor for the property with the given name.
`java.lang.reflect.Method` | `getReadMethod(java.lang.String name)` Returns the accessor for the property with the given name.
`java.lang.Class` | `getType(java.lang.String name)` Returns the type of the property with the given name.
`protected org.apache.commons.collections.Transformer` | `getTypeTransformer(java.lang.Class aType)` Returns a transformer for the given primitive type.
`protected java.lang.reflect.Method` | `getWriteMethod(java.lang.Object name)` Returns the mutator for the property with the given name.
`java.lang.reflect.Method` | `getWriteMethod(java.lang.String name)` Returns the mutator for 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.
`protected void` | `logInfo(java.lang.Exception ex)` Logs the given exception to `System.out`.
`protected void` | `logWarn(java.lang.Exception ex)` Logs the given exception to `System.err`.
`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 writable properties from the given BeanMap into this BeanMap.
`protected void` | `reinitialise()` Reinitializes this bean.
`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.lang.String` | `toString()` Renders a string representation of this object.
`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`

Methods inherited from class java.lang.Object
`finalize, 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

  Deprecated. Use `getTypeTransformer(Class)` method

  This HashMap has been made unmodifiable to prevent issues when loaded in a shared ClassLoader enviroment.
  See Also:

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

### toString

    public java.lang.String toString()

  Renders a string representation of this object.
  Overrides:
    `toString` in class `java.util.AbstractMap`
  Returns:
    a `String` representation of this object

### 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 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.
  Overrides:
    `clone` in class `java.lang.Object`
  Returns:
    a cloned instance of this bean map
  Throws:
    `java.lang.CloneNotSupportedException` - if the underlying bean cannot be cloned

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

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

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

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

  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.
  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` - if an error occurs creating the method args

### size

    public int size()

  Returns the number of properties defined by the bean.
  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.

  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.

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

  Gets a Set of MapEntry objects that are the mappings for this BeanMap.

  Each MapEntry can be set but not removed.

  Overrides:
    `entrySet` in class `java.util.AbstractMap`
  Returns:
    the unmodifiable set of mappings

### values

    public java.util.Collection values()

  Returns the values for the BeanMap.
  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.

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

  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

### getReadMethod

    public java.lang.reflect.Method getReadMethod(java.lang.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 java.lang.reflect.Method getWriteMethod(java.lang.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

### getReadMethod

    protected java.lang.reflect.Method getReadMethod(java.lang.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

### getWriteMethod

    protected java.lang.reflect.Method getWriteMethod(java.lang.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

### reinitialise

    protected void reinitialise()

  Reinitializes this bean. Called during `setBean(Object)`. Does introspection to find properties.

### firePropertyChange

    protected void firePropertyChange(java.lang.Object key,
                                      java.lang.Object oldValue,
                                      java.lang.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

### createWriteMethodArguments

    protected java.lang.Object[] createWriteMethodArguments(java.lang.reflect.Method method,
                                                            java.lang.Object value)
                                                     throws java.lang.IllegalAccessException,
                                                            java.lang.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:
    `java.lang.IllegalAccessException` - if `convertType(Class,Object)` raises it
    `java.lang.IllegalArgumentException` - if any other exception is raised by `convertType(Class,Object)`
    `java.lang.ClassCastException` - if an error occurs creating the method args

### convertType

    protected java.lang.Object convertType(java.lang.Class newType,
                                           java.lang.Object value)
                                    throws java.lang.InstantiationException,
                                           java.lang.IllegalAccessException,
                                           java.lang.IllegalArgumentException,
                                           java.lang.reflect.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:
    `java.lang.NumberFormatException` - if newType is a primitive type, and the string representation of the given value cannot be converted to that type
    `java.lang.InstantiationException` - if the constructor found with reflection raises it
    `java.lang.reflect.InvocationTargetException` - if the constructor found with reflection raises it
    `java.lang.IllegalAccessException` - never
    `java.lang.IllegalArgumentException` - never

### getTypeTransformer

    protected org.apache.commons.collections.Transformer getTypeTransformer(java.lang.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(java.lang.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(java.lang.Exception ex)

  Logs the given exception to `System.err`. Used to display errors while accessing/mutating the bean.
  Parameters:
    `ex` - the exception to log

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000-2007 The Apache Software Foundation. All Rights Reserved.