Package org.apache.commons.beanutils2

Class LazyDynaMap

java.lang.Object

org.apache.commons.beanutils2.LazyDynaBean

org.apache.commons.beanutils2.LazyDynaMap

All Implemented Interfaces:

DynaBean, DynaClass, MutableDynaClass

public class LazyDynaMap
extends LazyDynaBean
implements MutableDynaClass

Provides a light weight DynaBean</code> facade to a <code>Map with lazy map/list processing.

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

As well providing rhe standard DynaBean</code> access to the <code>Map's properties this class also provides the usual Lazy behavior:

• Properties don't need to be pre-defined in a DynaClass
• Indexed properties (Lists</code> or <code>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</code> have a facility to <em>restrict</em> the <code>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.

Field Summary

Fields

Modifier and Type	Field	Description
protected String	name	The name of this DynaClass (analogous to the getName()</code> method of <code>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.beanutils2.LazyDynaBean

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

Constructor Summary

Constructors

Constructor	Description
LazyDynaMap()	Constructs a new instance.
LazyDynaMap(String name)	Constructs a new LazyDynaMap with the specified name.
LazyDynaMap(String name, Map<String,Object> values)	Constructs a new LazyDynaMap</code> with the specified name and <code>Map.
LazyDynaMap(String name, DynaProperty[] properties)	Constructs a new LazyDynaMap with the specified name and properties.
LazyDynaMap(Map<String,Object> values)	Constructs a new LazyDynaMap</code> with the specified <code>Map.
LazyDynaMap(DynaClass dynaClass)	Constructs a new LazyDynaMap based on an exisiting DynaClass
LazyDynaMap(DynaProperty[] properties)	Constructs a new LazyDynaMap with the specified properties.

Method Summary

Modifier and Type	Method	Description
void	add(String name)	Add a new dynamic property with no restrictions on data type, readability, or writeability.
void	add(String name, Class<?> type)	Add a new dynamic property with the specified data type, but with no restrictions on readability or writeability.
void	add(String name, Class<?> type, boolean readable, boolean writable)	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 PropertyDescriptor for the properties currently defined in this DynaClass.
DynaProperty	getDynaProperty(String name)	Return a property descriptor for the specified property.
Map<String,Object>	getMap()	Gets the underlying Map backing this DynaBean
String	getName()	Gets the name of this DynaClass (analogous to the getName()</code> method of <code>java.lang.Class)
protected boolean	isDynaProperty(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(String name)	Remove the specified dynamic property, and any associated data type, readability, and writeability, from this dynamic class.
void	set(String name, Object value)	Sets the value of a simple property with the specified name.
void	setMap(Map<String,Object> values)	Sets the Map backing this DynaBean
void	setRestricted(boolean restricted)	Set whether this DynaClass is currently restricted.
void	setReturnNull(boolean returnNull)	Sets 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.beanutils2.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 Details

name

protected String name

The name of this DynaClass (analogous to the getName()</code> method of <code>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 Details

LazyDynaMap

public LazyDynaMap()

Constructs a new instance.

LazyDynaMap

public LazyDynaMap(DynaClass dynaClass)

Constructs a new LazyDynaMap based on an exisiting DynaClass

Parameters:

dynaClass - DynaClass to copy the name and properties from

LazyDynaMap

public LazyDynaMap(DynaProperty[] properties)

Constructs a new LazyDynaMap with the specified properties.

Parameters:

properties - Property descriptors for the supported properties

LazyDynaMap

public LazyDynaMap(Map<String,Object> values)

Constructs a new LazyDynaMap</code> with the specified <code>Map.

Parameters:

values - The Map backing this LazyDynaMap

LazyDynaMap

public LazyDynaMap(String name)

Constructs a new LazyDynaMap with the specified name.

Parameters:

name - Name of this DynaBean class

LazyDynaMap

public LazyDynaMap(String name,
 DynaProperty[] properties)

Constructs 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(String name,
 Map<String,Object> values)

Constructs a new LazyDynaMap</code> with the specified name and <code>Map.

Parameters:

name - Name of this DynaBean class

values - The Map backing this LazyDynaMap

Method Details

add

protected void add(DynaProperty property)

Add a new dynamic property.

Parameters:

property - Property the new dynamic property to add.

Throws:

IllegalArgumentException - if name is null

add

public void add(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:

IllegalArgumentException - if name is null

add

public void add(String name,
 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:

IllegalArgumentException - if name is null

IllegalStateException - if this DynaClass is currently restricted, so no new properties can be added

add

public void add(String name,
 Class<?> type,
 boolean readable,
 boolean writable)

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

N.B.Support for readable/writable 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

writable - Set to true if this property value should be writable

Throws:

UnsupportedOperationException - anytime this method is called

getDynaProperties

public DynaProperty[] getDynaProperties()

Return an array of PropertyDescriptor 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

getDynaProperty

public DynaProperty getDynaProperty(String name)

Return a property descriptor for the specified property.

If the property is not found and the returnNull indicator is true</code>, this method always returns <code>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 behavior.

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:

IllegalArgumentException - if no property name is specified

getMap

public Map<String,Object> getMap()

Gets the underlying Map backing this DynaBean

Overrides:

getMap in class LazyDynaBean

Returns:

the underlying Map

Since:

1.8.0

getName

public String getName()

Gets the name of this DynaClass (analogous to the getName()</code> method of <code>java.lang.Class)

Specified by:

getName in interface DynaClass

Returns:

the name of the DynaClass

isDynaProperty

protected boolean isDynaProperty(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:

IllegalArgumentException - if no property name is specified

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

isReturnNull

public boolean isReturnNull()

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

Returns:

true</code> if a <code>null DynaProperty should be returned if the property doesn't exist, otherwise false if a new DynaProperty should be created.

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

remove

public void remove(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:

IllegalArgumentException - if name is null

IllegalStateException - if this DynaClass is currently restricted, so no properties can be removed

set

public void set(String name,
 Object value)

Sets 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

setMap

public void setMap(Map<String,Object> values)

Sets the Map backing this DynaBean

Parameters:

values - The new Map of values

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

setReturnNull

public void setReturnNull(boolean returnNull)

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

Parameters:

returnNull - true</code> if a <code>null DynaProperty should be returned if the property doesn't exist, otherwise false if a new DynaProperty should be created.