org.apache.commons.beanutils

## Class LazyDynaBean

- java.lang.Object
- - org.apache.commons.beanutils.LazyDynaBean

- All Implemented Interfaces:
    Serializable, DynaBean
  Direct Known Subclasses:
    LazyDynaMap

      public class LazyDynaBean
      extends Object
      implements DynaBean, Serializable

  DynaBean which automatically adds properties to the `DynaClass` and provides Lazy List and Lazy Map features.

  DynaBeans deal with three types of properties - simple, indexed and mapped and have the following `get()` and `set()` methods for each of these types:

  - Simple property methods - `get(name)` and `set(name, value)`
  - Indexed property methods - `get(name, index)` and `set(name, index, value)`
  - Mapped property methods - `get(name, key)` and `set(name, key, value)`

  Getting Property Values

  Calling any of the `get()` methods, for a property which doesn't exist, returns `null` in this implementation.

  Setting Simple Properties

  The `LazyDynaBean` will automatically add a property to the `DynaClass` if it doesn't exist when the `set(name, value)` method is called.

  `DynaBean myBean = new LazyDynaBean();` `myBean.set("myProperty", "myValue");`

  Setting Indexed Properties

  If the property doesn't exist, the `LazyDynaBean` will automatically add a property with an `ArrayList` type to the `DynaClass` when the `set(name, index, value)` method is called. It will also instantiate a new `ArrayList` and automatically grow the `List` so that it is big enough to accomodate the index being set. `ArrayList` is the default indexed property that LazyDynaBean uses but this can be easily changed by overriding the `defaultIndexedProperty(name)` method.

  `DynaBean myBean = new LazyDynaBean();` `myBean.set("myIndexedProperty", 0, "myValue1");` `myBean.set("myIndexedProperty", 1, "myValue2");`

  If the indexed property does exist in the `DynaClass` but is set to `null` in the `LazyDynaBean`, then it will instantiate a new `List` or `Array` as specified by the property's type in the `DynaClass` and automatically grow the `List` or `Array` so that it is big enough to accomodate the index being set.

  `DynaBean myBean = new LazyDynaBean();` `MutableDynaClass myClass = (MutableDynaClass)myBean.getDynaClass();` `myClass.add("myIndexedProperty", int[].class);` `myBean.set("myIndexedProperty", 0, new Integer(10));` `myBean.set("myIndexedProperty", 1, new Integer(20));`

  Setting Mapped Properties

  If the property doesn't exist, the `LazyDynaBean` will automatically add a property with a `HashMap` type to the `DynaClass` and instantiate a new `HashMap` in the DynaBean when the `set(name, key, value)` method is called. `HashMap` is the default mapped property that LazyDynaBean uses but this can be easily changed by overriding the `defaultMappedProperty(name)` method.

  `DynaBean myBean = new LazyDynaBean();` `myBean.set("myMappedProperty", "myKey", "myValue");`

  If the mapped property does exist in the `DynaClass` but is set to `null` in the `LazyDynaBean`, then it will instantiate a new `Map` as specified by the property's type in the `DynaClass`.

  `DynaBean myBean = new LazyDynaBean();` `MutableDynaClass myClass = (MutableDynaClass)myBean.getDynaClass();` `myClass.add("myMappedProperty", TreeMap.class);` `myBean.set("myMappedProperty", "myKey", "myValue");`

  Restricted DynaClass

  `MutableDynaClass` have a facility to restrict the `DynaClass` so that its properties cannot be modified. If the `MutableDynaClass` is restricted then calling any of the `set()` methods for a property which doesn't exist will result in a `IllegalArgumentException` being thrown.

  Version:
    $Id: LazyDynaBean.java 1540504 2013-11-10 18:22:57Z niallp $
  See Also:
    `LazyDynaClass`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static BigDecimal` | `BigDecimal_ZERO` BigDecimal Zero
    `protected static BigInteger` | `BigInteger_ZERO` BigInteger Zero
    `protected static Byte` | `Byte_ZERO` Byte Zero
    `protected static Character` | `Character_SPACE` Character Space
    `protected static Double` | `Double_ZERO` Double Zero
    `protected MutableDynaClass` | `dynaClass` The `MutableDynaClass` "base class" that this DynaBean is associated with.
    `protected static Float` | `Float_ZERO` Float Zero
    `protected static Integer` | `Integer_ZERO` Integer Zero
    `protected static Long` | `Long_ZERO` Long Zero
    `protected static Short` | `Short_ZERO` Short Zero
    `protected Map<String,Object>` | `values` The `MutableDynaClass` "base class" that this DynaBean is associated with.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LazyDynaBean()` Construct a new `LazyDynaBean` with a `LazyDynaClass` instance.
    `LazyDynaBean(DynaClass dynaClass)` Construct a new `DynaBean` associated with the specified `DynaClass` instance - if its not a `MutableDynaClass` then a new `LazyDynaClass` is created and the properties copied.
    `LazyDynaBean(String name)` Construct a new `LazyDynaBean` with a `LazyDynaClass` instance.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `contains(String name, String key)` Does the specified mapped property contain a value for the specified key value?
    `protected Object` | `createDynaBeanProperty(String name, Class<?> type)` Create a new Instance of a 'DynaBean' Property.
    `protected Object` | `createIndexedProperty(String name, Class<?> type)` Create a new Instance of an 'Indexed' Property
    `protected Object` | `createMappedProperty(String name, Class<?> type)` Create a new Instance of a 'Mapped' Property
    `protected Object` | `createNumberProperty(String name, Class<?> type)` Create a new Instance of a `java.lang.Number` Property.
    `protected Object` | `createOtherProperty(String name, Class<?> type)` Create a new Instance of other Property types
    `protected Object` | `createPrimitiveProperty(String name, Class<?> type)` Create a new Instance of a 'Primitive' Property.
    `protected Object` | `createProperty(String name, Class<?> type)` Create a new Instance of a Property
    `protected Object` | `defaultIndexedProperty(String name)` Creates a new `ArrayList` for an 'indexed' property which doesn't exist.
    `protected Map<String,Object>` | `defaultMappedProperty(String name)` Creates a new `HashMap` for a 'mapped' property which doesn't exist.
    `Object` | `get(String name)` Return the value of a simple property with the specified name.
    `Object` | `get(String name, int index)` Return the value of an indexed property with the specified name.
    `Object` | `get(String name, String key)` Return the value of a mapped property with the specified name.
    `DynaClass` | `getDynaClass()` Return the `DynaClass` instance that describes the set of properties available for this DynaBean.
    `Map<String,Object>` | `getMap()` Return a Map representation of this DynaBean.
    `protected Object` | `growIndexedProperty(String name, Object indexedProperty, int index)` Grow the size of an indexed property
    `protected boolean` | `isAssignable(Class<?> dest, Class<?> source)` Is an object of the source class assignable to the destination class?
    `protected boolean` | `isDynaProperty(String name)` Indicates if there is a property with the specified name.
    `protected Map<String,Object>` | `newMap()` Creates a new instance of the `Map`.
    `void` | `remove(String name, String key)` Remove any existing value for the specified key on the specified mapped property.
    `void` | `set(String name, int index, Object value)` Set the value of an indexed property with the specified name.
    `void` | `set(String name, Object value)` Set the value of a simple property with the specified name.
    `void` | `set(String name, String key, Object value)` Set the value of a mapped property with the specified name.
    `int` | `size(String name)` Return the size of an indexed or mapped property.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### BigInteger_ZERO

          protected static final BigInteger BigInteger_ZERO

      BigInteger Zero

    - #### BigDecimal_ZERO

          protected static final BigDecimal BigDecimal_ZERO

      BigDecimal Zero

    - #### Character_SPACE

          protected static final Character Character_SPACE

      Character Space

    - #### Byte_ZERO

          protected static final Byte Byte_ZERO

      Byte Zero

    - #### Short_ZERO

          protected static final Short Short_ZERO

      Short Zero

    - #### Integer_ZERO

          protected static final Integer Integer_ZERO

      Integer Zero

    - #### Long_ZERO

          protected static final Long Long_ZERO

      Long Zero

    - #### Float_ZERO

          protected static final Float Float_ZERO

      Float Zero

    - #### Double_ZERO

          protected static final Double Double_ZERO

      Double Zero

    - #### values

          protected Map<String,Object> values

      The `MutableDynaClass` "base class" that this DynaBean is associated with.

    - #### dynaClass

          protected MutableDynaClass dynaClass

      The `MutableDynaClass` "base class" that this DynaBean is associated with.

  - ### Constructor Detail

    - #### LazyDynaBean

          public LazyDynaBean()

      Construct a new `LazyDynaBean` with a `LazyDynaClass` instance.

    - #### LazyDynaBean

          public LazyDynaBean(String name)

      Construct a new `LazyDynaBean` with a `LazyDynaClass` instance.
      Parameters:
        `name` - Name of this DynaBean class

    - #### LazyDynaBean

          public LazyDynaBean(DynaClass dynaClass)

      Construct a new `DynaBean` associated with the specified `DynaClass` instance - if its not a `MutableDynaClass` then a new `LazyDynaClass` is created and the properties copied.
      Parameters:
        `dynaClass` - The DynaClass we are associated with

  - ### Method Detail

    - #### getMap

          public Map<String,Object> getMap()

      Return a Map representation of this DynaBean. This, for example, could be used in JSTL in the following way to access a DynaBean's `fooProperty`:
      - `${myDynaBean.map.fooProperty}`
      Returns:
        a Map representation of this DynaBean

    - #### size

          public int size(String name)

      Return the size of an indexed or mapped property.

      Parameters:
        `name` - Name of the property
      Returns:
        The indexed or mapped property size
      Throws:
        `IllegalArgumentException` - if no property name is specified

    - #### contains

          public boolean contains(String name,
                         String key)

      Does the specified mapped property contain a value for the specified key value?
      Specified by:
        `contains` in interface `DynaBean`
      Parameters:
        `name` - Name of the property to check
        `key` - Name of the key to check
      Returns:
        `true` if the mapped property contains a value for the specified key, otherwise `false`
      Throws:
        `IllegalArgumentException` - if no property name is specified

    - #### get

          public Object get(String name)

      Return the value of a simple property with the specified name.

      N.B. Returns `null` if there is no property of the specified name.

      Specified by:
        `get` in interface `DynaBean`
      Parameters:
        `name` - Name of the property whose value is to be retrieved.
      Returns:
        The property's value
      Throws:
        `IllegalArgumentException` - if no property name is specified

    - #### get

          public Object get(String name,
                   int index)

      Return the value of an indexed property with the specified name.

      N.B. Returns `null` if there is no 'indexed' property of the specified name.

      Specified by:
        `get` in interface `DynaBean`
      Parameters:
        `name` - Name of the property whose value is to be retrieved
        `index` - Index of the value to be retrieved
      Returns:
        The indexed property's value
      Throws:
        `IllegalArgumentException` - if the specified property exists, but is not indexed
        `IndexOutOfBoundsException` - if the specified index is outside the range of the underlying property

    - #### get

          public Object get(String name,
                   String key)

      Return the value of a mapped property with the specified name.

      N.B. Returns `null` if there is no 'mapped' property of the specified name.

      Specified by:
        `get` in interface `DynaBean`
      Parameters:
        `name` - Name of the property whose value is to be retrieved
        `key` - Key of the value to be retrieved
      Returns:
        The mapped property's value
      Throws:
        `IllegalArgumentException` - if the specified property exists, but is not mapped

    - #### getDynaClass

          public DynaClass getDynaClass()

      Return the `DynaClass` instance that describes the set of properties available for this DynaBean.
      Specified by:
        `getDynaClass` in interface `DynaBean`
      Returns:
        The associated DynaClass

    - #### remove

          public void remove(String name,
                    String key)

      Remove any existing value for the specified key on the specified mapped property.
      Specified by:
        `remove` in interface `DynaBean`
      Parameters:
        `name` - Name of the property for which a value is to be removed
        `key` - Key of the value to be removed
      Throws:
        `IllegalArgumentException` - if there is no property of the specified name

    - #### set

          public void set(String name,
                 Object value)

      Set the value of a simple property with the specified name.
      Specified by:
        `set` in interface `DynaBean`
      Parameters:
        `name` - Name of the property whose value is to be set
        `value` - Value to which this property is to be set
      Throws:
        `IllegalArgumentException` - if this is not an existing property name for our DynaClass and the MutableDynaClass is restricted
        `ConversionException` - if the specified value cannot be converted to the type required for this property
        `NullPointerException` - if an attempt is made to set a primitive property to null

    - #### set

          public void set(String name,
                 int index,
                 Object value)

      Set the value of an indexed property with the specified name.
      Specified by:
        `set` in interface `DynaBean`
      Parameters:
        `name` - Name of the property whose value is to be set
        `index` - Index of the property to be set
        `value` - Value to which this property is to be set
      Throws:
        `ConversionException` - if the specified value cannot be converted to the type required for this property
        `IllegalArgumentException` - if there is no property of the specified name
        `IllegalArgumentException` - if the specified property exists, but is not indexed
        `IndexOutOfBoundsException` - if the specified index is outside the range of the underlying property

    - #### set

          public void set(String name,
                 String key,
                 Object value)

      Set the value of a mapped property with the specified name.
      Specified by:
        `set` in interface `DynaBean`
      Parameters:
        `name` - Name of the property whose value is to be set
        `key` - Key of the property to be set
        `value` - Value to which this property is to be set
      Throws:
        `ConversionException` - if the specified value cannot be converted to the type required for this property
        `IllegalArgumentException` - if there is no property of the specified name
        `IllegalArgumentException` - if the specified property exists, but is not mapped

    - #### growIndexedProperty

          protected Object growIndexedProperty(String name,
                                   Object indexedProperty,
                                   int index)

      Grow the size of an indexed property
      Parameters:
        `name` - The name of the property
        `indexedProperty` - The current property value
        `index` - The indexed value to grow the property to (i.e. one less than the required size)
      Returns:
        The new property value (grown to the appropriate size)

    - #### createProperty

          protected Object createProperty(String name,
                              Class<?> type)

      Create a new Instance of a Property
      Parameters:
        `name` - The name of the property
        `type` - The class of the property
      Returns:
        The new value

    - #### createIndexedProperty

          protected Object createIndexedProperty(String name,
                                     Class<?> type)

      Create a new Instance of an 'Indexed' Property
      Parameters:
        `name` - The name of the property
        `type` - The class of the property
      Returns:
        The new value

    - #### createMappedProperty

          protected Object createMappedProperty(String name,
                                    Class<?> type)

      Create a new Instance of a 'Mapped' Property
      Parameters:
        `name` - The name of the property
        `type` - The class of the property
      Returns:
        The new value

    - #### createDynaBeanProperty

          protected Object createDynaBeanProperty(String name,
                                      Class<?> type)

      Create a new Instance of a 'DynaBean' Property.
      Parameters:
        `name` - The name of the property
        `type` - The class of the property
      Returns:
        The new value

    - #### createPrimitiveProperty

          protected Object createPrimitiveProperty(String name,
                                       Class<?> type)

      Create a new Instance of a 'Primitive' Property.
      Parameters:
        `name` - The name of the property
        `type` - The class of the property
      Returns:
        The new value

    - #### createNumberProperty

          protected Object createNumberProperty(String name,
                                    Class<?> type)

      Create a new Instance of a `java.lang.Number` Property.
      Parameters:
        `name` - The name of the property
        `type` - The class of the property
      Returns:
        The new value

    - #### createOtherProperty

          protected Object createOtherProperty(String name,
                                   Class<?> type)

      Create a new Instance of other Property types
      Parameters:
        `name` - The name of the property
        `type` - The class of the property
      Returns:
        The new value

    - #### defaultIndexedProperty

          protected Object defaultIndexedProperty(String name)

      Creates a new `ArrayList` for an 'indexed' property which doesn't exist.

      This method should be overridden if an alternative `List` or `Array` implementation is required for 'indexed' properties.

      Parameters:
        `name` - Name of the 'indexed property.
      Returns:
        The default value for an indexed property (java.util.ArrayList)

    - #### defaultMappedProperty

          protected Map<String,Object> defaultMappedProperty(String name)

      Creates a new `HashMap` for a 'mapped' property which doesn't exist.

      This method can be overridden if an alternative `Map` implementation is required for 'mapped' properties.

      Parameters:
        `name` - Name of the 'mapped property.
      Returns:
        The default value for a mapped property (java.util.HashMap)

    - #### isDynaProperty

          protected boolean isDynaProperty(String name)

      Indicates if there is a property with the specified name.
      Parameters:
        `name` - The name of the property to check
      Returns:
        `true` if there is a property of the specified name, otherwise `false`

    - #### isAssignable

          protected boolean isAssignable(Class<?> dest,
                             Class<?> source)

      Is an object of the source class assignable to the destination class?
      Parameters:
        `dest` - Destination class
        `source` - Source class
      Returns:
        `true` if the source class is assignable to the destination class, otherwise `false`

    - #### newMap

          protected Map<String,Object> newMap()

      Creates a new instance of the `Map`.

      Returns:
        a new Map instance

Copyright © 2000–2014 The Apache Software Foundation. All rights reserved.