Package org.apache.commons.beanutils

## Class LazyDynaClass

- java.lang.Object
- - org.apache.commons.beanutils.BasicDynaClass
  - - org.apache.commons.beanutils.LazyDynaClass

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

    public class LazyDynaClass
    extends BasicDynaClass
    implements MutableDynaClass

DynaClass which implements the `MutableDynaClass` interface.

A `MutableDynaClass` is a specialized extension to `DynaClass` that allows properties to be added or removed dynamically.

This implementation has one slightly unusual default behaviour - calling the `getDynaProperty(name)` method for a property which doesn't exist returns a `DynaProperty` rather than `null`. The reason for this is that `BeanUtils` calls this method to check if a property exists before trying to set the value. This would defeat the object of the `LazyDynaBean` which automatically adds missing properties when any of its `set()` methods are called. For this reason the `isDynaProperty(name)` method has been added to this implementation in order to determine if a property actually exists. If the more normal behaviour of returning `null` is required, then this can be achieved by calling the `setReturnNull(true)`.

The `add(name, type, readable, writable)` method is not implemented and always throws an `UnsupportedOperationException`. I believe this attributes need to be added to the `DynaProperty` class in order to control read/write facilities.

Version:
  $Id$
See Also:
  `LazyDynaBean`, Serialized Form

### Field Summary

Fields
`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.BasicDynaClass

`constructor, constructorTypes, constructorValues, dynaBeanClass, name, properties, propertiesMap`

### Constructor Summary

Constructors
`LazyDynaClass()` Construct a new LazyDynaClass with default parameters.
`LazyDynaClass​(java.lang.String name)` Construct a new LazyDynaClass with the specified name.
`LazyDynaClass​(java.lang.String name, java.lang.Class<?> dynaBeanClass)` Construct a new LazyDynaClass with the specified name and DynaBean class.
`LazyDynaClass​(java.lang.String name, java.lang.Class<?> dynaBeanClass, DynaProperty[] properties)` Construct a new LazyDynaClass with the specified name, DynaBean class and properties.
`LazyDynaClass​(java.lang.String name, DynaProperty[] properties)` Construct a new LazyDynaClass with the specified name and 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` `getDynaProperty​(java.lang.String name)` Return a property descriptor for the specified property.
`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.
`void` `remove​(java.lang.String name)` Remove the specified dynamic property, and any associated data type, readability, and writeability, from this dynamic class.
`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.BasicDynaClass

`getDynaBeanClass, getDynaProperties, getName, newInstance, setDynaBeanClass, setProperties`

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

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

### Methods inherited from interface org.apache.commons.beanutils.DynaClass

`getDynaProperties, getName, newInstance`

### Field Detail

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

#### LazyDynaClass

    public LazyDynaClass()

Construct a new LazyDynaClass with default parameters.

#### LazyDynaClass

    public LazyDynaClass​(java.lang.String name)

Construct a new LazyDynaClass with the specified name.

Parameters:
  `name` - Name of this DynaBean class

#### LazyDynaClass

    public LazyDynaClass​(java.lang.String name,
                         java.lang.Class<?> dynaBeanClass)

Construct a new LazyDynaClass with the specified name and DynaBean class.

Parameters:
  `name` - Name of this DynaBean class
  `dynaBeanClass` - The implementation class for new instances

#### LazyDynaClass

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

Construct a new LazyDynaClass with the specified name and properties.

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

#### LazyDynaClass

    public LazyDynaClass​(java.lang.String name,
                         java.lang.Class<?> dynaBeanClass,
                         DynaProperty[] properties)

Construct a new LazyDynaClass with the specified name, DynaBean class and properties.

Parameters:
  `name` - Name of this DynaBean class
  `dynaBeanClass` - The implementation class for new instances
  `properties` - Property descriptors for the supported properties

### Method Detail

#### 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 `MutableDynaClass` cannot be changed 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` - `true` if this `MutableDynaClass` cannot be changed otherwise `false`

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

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

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
  `java.lang.IllegalStateException` - if this DynaClass is currently restricted, so no new properties can be added

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

#### 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 Lazy 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`
Overrides:
  `getDynaProperty` in class `BasicDynaClass`
Parameters:
  `name` - Name of the dynamic property for which a descriptor is requested
Returns:
  The dyna property for the specified name
Throws:
  `java.lang.IllegalArgumentException` - if no property name is specified

#### isDynaProperty

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

Parameters:
  `name` - The name of the property to check
Returns:
  `true` if there is a property of the specified name, otherwise `false`
Throws:
  `java.lang.IllegalArgumentException` - if no property name is specified