Package org.apache.commons.beanutils

## Class LazyDynaMap

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

All Implemented Interfaces:
  `java.io.Serializable`, `DynaBean`, `DynaClass`, `MutableDynaClass`

    public class LazyDynaMap
    extends LazyDynaBean
    implements MutableDynaClass

Provides a light weight `DynaBean` facade to a `Map` with lazy map/list processing.

Its a light weight `DynaBean` implementation because there is no actual `DynaClass` associated with this `DynaBean` - in fact it implements the `DynaClass` interface itself providing pseudo DynaClass behaviour from the actual values stored in the `Map`.

As well providing rhe standard `DynaBean` access to the `Map`'s properties this class also provides the usual Lazy behaviour:

- Properties don't need to be pre-defined in a `DynaClass`
- Indexed properties (`Lists` or `Arrays`) are automatically instantiated and grown so that they are large enough to cater for the index being set.
- Mapped properties are automatically instantiated.

Restricted DynaClass

This class implements the `MutableDynaClass` interface. `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$
See Also:
  Serialized Form

### Field Summary

Fields
`protected java.lang.String` `name` The name of this DynaClass (analogous to the `getName()` method of `java.lang.Class`).
`protected boolean` `restricted` Controls whether changes to this DynaClass's properties are allowed.
`protected boolean` `returnNull` Controls whether the `getDynaProperty()` method returns null if a property doesn't exist - or creates a new one.

### Fields inherited from class org.apache.commons.beanutils.LazyDynaBean

`BigDecimal_ZERO, BigInteger_ZERO, Byte_ZERO, Character_SPACE, Double_ZERO, dynaClass, Float_ZERO, Integer_ZERO, Long_ZERO, Short_ZERO, values`

### Constructor Summary

Constructors
`LazyDynaMap()` Default Constructor.
`LazyDynaMap​(java.lang.String name)` Construct a new `LazyDynaMap` with the specified name.
`LazyDynaMap​(java.lang.String name, java.util.Map<java.lang.String,​java.lang.Object> values)` Construct a new `LazyDynaMap` with the specified name and `Map`.
`LazyDynaMap​(java.lang.String name, DynaProperty[] properties)` Construct a new `LazyDynaMap` with the specified name and properties.
`LazyDynaMap​(java.util.Map<java.lang.String,​java.lang.Object> values)` Construct a new `LazyDynaMap` with the specified `Map`.
`LazyDynaMap​(DynaClass dynaClass)` Construct a new `LazyDynaMap` based on an exisiting DynaClass
`LazyDynaMap​(DynaProperty[] properties)` Construct a new `LazyDynaMap` with the specified properties.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `add​(java.lang.String name)` Add a new dynamic property with no restrictions on data type, readability, or writeability.
`void` `add​(java.lang.String name, java.lang.Class<?> type)` Add a new dynamic property with the specified data type, but with no restrictions on readability or writeability.
`void` `add​(java.lang.String name, java.lang.Class<?> type, boolean readable, boolean writeable)` Add a new dynamic property with the specified data type, readability, and writeability.
`protected void` `add​(DynaProperty property)` Add a new dynamic property.
`DynaProperty[]` `getDynaProperties()` Return an array of `ProperyDescriptors` for the properties currently defined in this DynaClass.
`DynaProperty` `getDynaProperty​(java.lang.String name)` Return a property descriptor for the specified property.
`java.util.Map<java.lang.String,​java.lang.Object>` `getMap()` Return the underlying Map backing this `DynaBean`
`java.lang.String` `getName()` Return the name of this DynaClass (analogous to the `getName()` method of `java.lang.Class`)
`protected boolean` `isDynaProperty​(java.lang.String name)` Indicate whether a property actually exists.
`boolean` `isRestricted()` Is this DynaClass currently restricted.
`boolean` `isReturnNull()` Should this DynaClass return a `null` from the `getDynaProperty(name)` method if the property doesn't exist.
`DynaBean` `newInstance()` Instantiate and return a new DynaBean instance, associated with this DynaClass.
`void` `remove​(java.lang.String name)` Remove the specified dynamic property, and any associated data type, readability, and writeability, from this dynamic class.
`void` `set​(java.lang.String name, java.lang.Object value)` Set the value of a simple property with the specified name.
`void` `setMap​(java.util.Map<java.lang.String,​java.lang.Object> values)` Set the Map backing this `DynaBean`
`void` `setRestricted​(boolean restricted)` Set whether this DynaClass is currently restricted.
`void` `setReturnNull​(boolean returnNull)` Set whether this DynaClass should return a `null` from the `getDynaProperty(name)` method if the property doesn't exist.

### Methods inherited from class org.apache.commons.beanutils.LazyDynaBean

`contains, createDynaBeanProperty, createIndexedProperty, createMappedProperty, createNumberProperty, createOtherProperty, createPrimitiveProperty, createProperty, defaultIndexedProperty, defaultMappedProperty, get, get, get, getDynaClass, growIndexedProperty, isAssignable, newMap, remove, set, set, size`

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

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

### Field Detail

#### name

    protected java.lang.String name

The name of this DynaClass (analogous to the `getName()` method of `java.lang.Class`).

#### restricted

    protected boolean restricted

Controls whether changes to this DynaClass's properties are allowed.

#### returnNull

    protected boolean returnNull

Controls whether the `getDynaProperty()` method returns null if a property doesn't exist - or creates a new one.

Default is `false`.

### Constructor Detail

#### LazyDynaMap

    public LazyDynaMap()

Default Constructor.

#### LazyDynaMap

    public LazyDynaMap​(java.lang.String name)

Construct a new `LazyDynaMap` with the specified name.

Parameters:
  `name` - Name of this DynaBean class

#### LazyDynaMap

    public LazyDynaMap​(java.util.Map<java.lang.String,​java.lang.Object> values)

Construct a new `LazyDynaMap` with the specified `Map`.

Parameters:
  `values` - The Map backing this `LazyDynaMap`

#### LazyDynaMap

    public LazyDynaMap​(java.lang.String name,
                       java.util.Map<java.lang.String,​java.lang.Object> values)

Construct a new `LazyDynaMap` with the specified name and `Map`.

Parameters:
  `name` - Name of this DynaBean class
  `values` - The Map backing this `LazyDynaMap`

#### LazyDynaMap

    public LazyDynaMap​(DynaProperty[] properties)

Construct a new `LazyDynaMap` with the specified properties.

Parameters:
  `properties` - Property descriptors for the supported properties

#### LazyDynaMap

    public LazyDynaMap​(java.lang.String name,
                       DynaProperty[] properties)

Construct a new `LazyDynaMap` with the specified name and properties.

Parameters:
  `name` - Name of this DynaBean class
  `properties` - Property descriptors for the supported properties

#### LazyDynaMap

    public LazyDynaMap​(DynaClass dynaClass)

Construct a new `LazyDynaMap` based on an exisiting DynaClass

Parameters:
  `dynaClass` - DynaClass to copy the name and properties from

### Method Detail

#### setMap

    public void setMap​(java.util.Map<java.lang.String,​java.lang.Object> values)

Set the Map backing this `DynaBean`

Parameters:
  `values` - The new Map of values

#### getMap

    public java.util.Map<java.lang.String,​java.lang.Object> getMap()

Return the underlying Map backing this `DynaBean`

Overrides:
  `getMap` in class `LazyDynaBean`
Returns:
  the underlying Map
Since:
  1.8.0

#### set

    public void set​(java.lang.String name,
                    java.lang.Object value)

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

Specified by:
  `set` in interface `DynaBean`
Overrides:
  `set` in class `LazyDynaBean`
Parameters:
  `name` - Name of the property whose value is to be set
  `value` - Value to which this property is to be set

#### getName

    public java.lang.String getName()

Return the name of this DynaClass (analogous to the `getName()` method of `java.lang.Class`)

Specified by:
  `getName` in interface `DynaClass`
Returns:
  the name of the DynaClass

#### getDynaProperty

    public DynaProperty getDynaProperty​(java.lang.String name)

Return a property descriptor for the specified property.

If the property is not found and the `returnNull` indicator is `true`, this method always returns `null`.

If the property is not found and the `returnNull` indicator is `false` a new property descriptor is created and returned (although its not actually added to the DynaClass's properties). This is the default beahviour.

The reason for not returning a `null` property descriptor is that `BeanUtils` uses this method to check if a property exists before trying to set it - since these Map implementations automatically add any new properties when they are set, returning `null` from this method would defeat their purpose.

Specified by:
  `getDynaProperty` in interface `DynaClass`
Parameters:
  `name` - Name of the dynamic property for which a descriptor is requested
Returns:
  The descriptor for the specified property
Throws:
  `java.lang.IllegalArgumentException` - if no property name is specified

#### getDynaProperties

    public DynaProperty[] getDynaProperties()

Return an array of `ProperyDescriptors` for the properties currently defined in this DynaClass. If no properties are defined, a zero-length array will be returned.

FIXME - Should we really be implementing `getBeanInfo()` instead, which returns property descriptors and a bunch of other stuff?

Specified by:
  `getDynaProperties` in interface `DynaClass`
Returns:
  the set of properties for this DynaClass

#### newInstance

    public DynaBean newInstance()

Instantiate and return a new DynaBean instance, associated with this DynaClass.

Specified by:
  `newInstance` in interface `DynaClass`
Returns:
  A new `DynaBean` instance

#### isRestricted

    public boolean isRestricted()

Is this DynaClass currently restricted.

If restricted, no changes to the existing registration of property names, data types, readability, or writeability are allowed.

Specified by:
  `isRestricted` in interface `MutableDynaClass`
Returns:
  `true` if this Mutable `DynaClass` is restricted, otherwise `false`

#### setRestricted

    public void setRestricted​(boolean restricted)

Set whether this DynaClass is currently restricted.

If restricted, no changes to the existing registration of property names, data types, readability, or writeability are allowed.

Specified by:
  `setRestricted` in interface `MutableDynaClass`
Parameters:
  `restricted` - The new restricted state

#### add

    public void add​(java.lang.String name)

Add a new dynamic property with no restrictions on data type, readability, or writeability.

Specified by:
  `add` in interface `MutableDynaClass`
Parameters:
  `name` - Name of the new dynamic property
Throws:
  `java.lang.IllegalArgumentException` - if name is null

#### add

    public void add​(java.lang.String name,
                    java.lang.Class<?> type)

Add a new dynamic property with the specified data type, but with no restrictions on readability or writeability.

Specified by:
  `add` in interface `MutableDynaClass`
Parameters:
  `name` - Name of the new dynamic property
  `type` - Data type of the new dynamic property (null for no restrictions)
Throws:
  `java.lang.IllegalArgumentException` - if name is null
  `java.lang.IllegalStateException` - if this DynaClass is currently restricted, so no new properties can be added

#### add

    public void add​(java.lang.String name,
                    java.lang.Class<?> type,
                    boolean readable,
                    boolean writeable)

Add a new dynamic property with the specified data type, readability, and writeability.

N.B.Support for readable/writeable properties has not been implemented and this method always throws a `UnsupportedOperationException`.

I'm not sure the intention of the original authors for this method, but it seems to me that readable/writable should be attributes of the `DynaProperty` class (which they are not) and is the reason this method has not been implemented.

Specified by:
  `add` in interface `MutableDynaClass`
Parameters:
  `name` - Name of the new dynamic property
  `type` - Data type of the new dynamic property (null for no restrictions)
  `readable` - Set to `true` if this property value should be readable
  `writeable` - Set to `true` if this property value should be writeable
Throws:
  `java.lang.UnsupportedOperationException` - anytime this method is called

#### add

    protected void add​(DynaProperty property)

Add a new dynamic property.

Parameters:
  `property` - Property the new dynamic property to add.
Throws:
  `java.lang.IllegalArgumentException` - if name is null

#### remove

    public void remove​(java.lang.String name)

Remove the specified dynamic property, and any associated data type, readability, and writeability, from this dynamic class. NOTE - This does NOT cause any corresponding property values to be removed from DynaBean instances associated with this DynaClass.

Specified by:
  `remove` in interface `MutableDynaClass`
Parameters:
  `name` - Name of the dynamic property to remove
Throws:
  `java.lang.IllegalArgumentException` - if name is null
  `java.lang.IllegalStateException` - if this DynaClass is currently restricted, so no properties can be removed

#### isReturnNull

    public boolean isReturnNull()

Should this DynaClass return a `null` from the `getDynaProperty(name)` method if the property doesn't exist.

Returns:
  `true` if a `null` `DynaProperty` should be returned if the property doesn't exist, otherwise `false` if a new `DynaProperty` should be created.

#### setReturnNull

    public void setReturnNull​(boolean returnNull)

Set whether this DynaClass should return a `null` from the `getDynaProperty(name)` method if the property doesn't exist.

Parameters:
  `returnNull` - `true` if a `null` `DynaProperty` should be returned if the property doesn't exist, otherwise `false` if a new `DynaProperty` should be created.

#### isDynaProperty

    protected boolean isDynaProperty​(java.lang.String name)

Indicate whether a property actually exists.

N.B. Using `getDynaProperty(name) == null` doesn't work in this implementation because that method might return a DynaProperty if it doesn't exist (depending on the `returnNull` indicator).

Overrides:
  `isDynaProperty` in class `LazyDynaBean`
Parameters:
  `name` - Name of the dynamic property
Returns:
  `true` if the property exists, otherwise `false`
Throws:
  `java.lang.IllegalArgumentException` - if no property name is specified