Package 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 accommodate 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 accommodate the index being set.

    DynaBean myBean = new LazyDynaBean();
         MutableDynaClass myClass = (MutableDynaClass)myBean.getDynaClass();
         myClass.add("myIndexedProperty", int[].class);
         myBean.set("myIndexedProperty", 0, Integer.valueOf(10));
         myBean.set("myIndexedProperty", 1, Integer.valueOf(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.

See Also:
  - `LazyDynaClass`
  - Serialized Form

- ## Field Summary

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

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `LazyDynaBean()`
  Construct a new `LazyDynaBean` with a `LazyDynaClass` instance.
  `LazyDynaBean(String name)`
  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.

- ## Method Summary

  Modifier and Type
  Method
  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 Details

  - ### 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 Details

  - ### LazyDynaBean

    public LazyDynaBean()
    Construct a new `LazyDynaBean` with a `LazyDynaClass` instance.

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

  - ### LazyDynaBean

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

- ## Method Details

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

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

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

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

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

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

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

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

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

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

  - ### 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`

  - ### 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`

  - ### newMap

    protected Map<String,Object> newMap()

    Creates a new instance of the `Map`.

    Returns:
      a new Map instance

  - ### 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, 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, 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, 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

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