Package org.apache.commons.beanutils

Class BeanMap

  • All Implemented Interfaces:
    java.lang.Cloneable, java.util.Map<java.lang.Object,​java.lang.Object>
    public class BeanMap
extends java.util.AbstractMap<java.lang.Object,​java.lang.Object>
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

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      protected static class  BeanMap.Entry
      Map entry used by BeanMap.

      • Nested classes/interfaces inherited from class java.util.AbstractMap

        java.util.AbstractMap.SimpleEntry<K extends java.lang.Object,​V extends java.lang.Object>, java.util.AbstractMap.SimpleImmutableEntry<K extends java.lang.Object,​V extends java.lang.Object>

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.lang.Object bean  
      static java.util.HashMap defaultTransformers
      Deprecated.
      Use getTypeTransformer(Class) method
      static java.lang.Object[] NULL_ARGUMENTS
      An empty array.
      private java.util.HashMap<java.lang.String,​java.lang.reflect.Method> readMethods  
      private java.util.HashMap<java.lang.String,​java.lang.Class<? extends java.lang.Object>> types  
      private static java.util.Map<java.lang.Class<? extends java.lang.Object>,​org.apache.commons.collections.Transformer> typeTransformers
      Maps primitive Class types to transformers.
      private java.util.HashMap<java.lang.String,​java.lang.reflect.Method> writeMethods  

    • Constructor Summary

      Constructors 
      Constructor Description
      BeanMap()
      Constructs a new empty BeanMap.
      BeanMap​(java.lang.Object bean)
      Constructs a new BeanMap that operates on the specified bean.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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. 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.
      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.
      private static java.util.Map<java.lang.Class<? extends java.lang.Object>,​org.apache.commons.collections.Transformer> createTypeTransformers()  
      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<java.util.Map.Entry<java.lang.Object,​java.lang.Object>> entryIterator()
      Convenience method for getting an iterator over the entries.
      java.util.Set<java.util.Map.Entry<java.lang.Object,​java.lang.Object>> 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.
      private void initialise()  
      java.util.Iterator<java.lang.String> keyIterator()
      Convenience method for getting an iterator over the keys.
      java.util.Set<java.lang.Object> 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<java.lang.Object> valueIterator()
      Convenience method for getting an iterator over the values.
      java.util.Collection<java.lang.Object> 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

      • Methods inherited from interface java.util.Map

        compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll

    • Field Detail

      • NULL_ARGUMENTS

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

      • typeTransformers

        private static final java.util.Map<java.lang.Class<? extends java.lang.Object>,​org.apache.commons.collections.Transformer> typeTransformers
        Maps primitive Class types to transformers. The transformer transform strings into the appropriate primitive wrapper. Private & unmodifiable replacement for the (public & static) defaultTransformers instance.

      • defaultTransformers

        @Deprecated
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:
        "http://issues.apache.org/jira/browse/BEANUTILS-112"

      • bean

        private transient java.lang.Object bean

      • readMethods

        private transient java.util.HashMap<java.lang.String,​java.lang.reflect.Method> readMethods

      • writeMethods

        private transient java.util.HashMap<java.lang.String,​java.lang.reflect.Method> writeMethods

      • types

        private transient java.util.HashMap<java.lang.String,​java.lang.Class<? extends java.lang.Object>> types

    • 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

      • createTypeTransformers

        private static java.util.Map<java.lang.Class<? extends java.lang.Object>,​org.apache.commons.collections.Transformer> createTypeTransformers()

      • 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<java.lang.Object,​java.lang.Object>
        Overrides:
        clear in class java.util.AbstractMap<java.lang.Object,​java.lang.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.util.AbstractMap<java.lang.Object,​java.lang.Object>
        Returns:
        a cloned instance of this bean map
        Throws:
        java.lang.CloneNotSupportedException - if the underlying bean cannot be cloned

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

        Specified by:
        containsKey in interface java.util.Map<java.lang.Object,​java.lang.Object>
        Overrides:
        containsKey in class java.util.AbstractMap<java.lang.Object,​java.lang.Object>
        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<java.lang.Object,​java.lang.Object>
        Overrides:
        containsValue in class java.util.AbstractMap<java.lang.Object,​java.lang.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 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

      • 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

      • entryIterator

        public java.util.Iterator<java.util.Map.Entry<java.lang.Object,​java.lang.Object>> entryIterator()
        Convenience method for getting an iterator over the entries.
        Returns:
        an iterator over the entries

      • entrySet

        public java.util.Set<java.util.Map.Entry<java.lang.Object,​java.lang.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 java.util.Map<java.lang.Object,​java.lang.Object>
        Specified by:
        entrySet in class java.util.AbstractMap<java.lang.Object,​java.lang.Object>
        Returns:
        the unmodifiable set of mappings

      • 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

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

        Specified by:
        get in interface java.util.Map<java.lang.Object,​java.lang.Object>
        Overrides:
        get in class java.util.AbstractMap<java.lang.Object,​java.lang.Object>
        Parameters:
        name - the name of the property whose value to return
        Returns:
        the value of the property with that name

      • 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

      • 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

      • 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

      • 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

      • 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

      • 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

      • 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

      • initialise

        private void initialise()

      • keyIterator

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

      • keySet

        public java.util.Set<java.lang.Object> 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 java.util.Map<java.lang.Object,​java.lang.Object>
        Overrides:
        keySet in class java.util.AbstractMap<java.lang.Object,​java.lang.Object>
        Returns:
        BeanMap keys. The Set returned by this method is not modifiable.

      • 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

      • 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<java.lang.Object,​java.lang.Object>
        Overrides:
        put in class java.util.AbstractMap<java.lang.Object,​java.lang.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:
        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

      • 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​(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

      • size

        public int size()
        Returns the number of properties defined by the bean.
        Specified by:
        size in interface java.util.Map<java.lang.Object,​java.lang.Object>
        Overrides:
        size in class java.util.AbstractMap<java.lang.Object,​java.lang.Object>
        Returns:
        the number of properties defined by the bean

      • toString

        public java.lang.String toString()
        Renders a string representation of this object.
        Overrides:
        toString in class java.util.AbstractMap<java.lang.Object,​java.lang.Object>
        Returns:
        a String representation of this object

      • valueIterator

        public java.util.Iterator<java.lang.Object> valueIterator()
        Convenience method for getting an iterator over the values.
        Returns:
        an iterator over the values

      • values

        public java.util.Collection<java.lang.Object> values()
        Returns the values for the BeanMap.
        Specified by:
        values in interface java.util.Map<java.lang.Object,​java.lang.Object>
        Overrides:
        values in class java.util.AbstractMap<java.lang.Object,​java.lang.Object>
        Returns:
        values for the BeanMap. The returned collection is not modifiable.