org.minimalcode.beans

Class ObjectWrapper

java.lang.Object

org.minimalcode.beans.ObjectWrapper

public class ObjectWrapper
extends Object

Wrapper for using Java Reflection APIs to facilitate generic property getter and setter operations on Java objects.

This class is highly optimized for preventing internal objects instantiation, and at the same time guarantees near-zero garbage collection. In addition to this, in a not-concurrent context, is perfectly safe to change the wrapped object and the internal options at any time, without side effects.

Various types of public properties are supported:

- Simple properties are any property of any type (both Object than primitive). Methods which supports a string pattern allows to traverse the properties' tree by separating the propety name with a '.' dot notation.

For example "foo.bar.zoo" is parsed to object.getFoo().getBar().getZoo();

- Indexed properties are List, finite Iterable (any Collection), and any type of array. They usually preserve their addition order (although it is not guaranteed for Iterable), and are accessible through an integer index. Methods which supports a string pattern allows to specify the requested integer index by a '[i]' notation.

- For example "myList[1]" is parsed to object.getMyList().get(1);

- For example "myArray[5]" is parsed to object.getMyArray()[5];

- Mapped properties are Map type and are accessible through an object key. Methods which supports the a string pattern allows to specify the requested key by a '[key]' notation. The key string can contains dots.

For example "myMap[my.key]" is parsed to object.getMyMap().get("my.key");

Any pattern combination is allowed, for example "foo.myList[1].bar.myMap[test].myArray[5]" is parsed to object.getFoo().getMyList().get(1).getBar().getMyMap().get("test").getMyArray()[5].

Author:

Fabio Piro

See Also:

Bean, Property

Constructor Summary

Constructors

Constructor and Description
ObjectWrapper(Object obj) Wraps an object.

Method Summary

Modifier and Type	Method and Description
org.minimalcode.reflect.Bean<?>	getBean() Returns the Bean cached instance of the wrapped object.
Object	getIndexedValue(org.minimalcode.reflect.Property property, int index) Returns the value of the specified indexed property from the wrapped object.
Object	getIndexedValue(String propertyName, int index) Returns the value of the specified indexed property from the wrapped object.
Object	getMappedValue(org.minimalcode.reflect.Property property, Object key) Returns the value of the specified mapped property from the wrapped object.
Object	getMappedValue(String propertyName, Object key) Returns the value of the specified mapped property from the wrapped object.
static org.minimalcode.reflect.Property	getProperty(org.minimalcode.reflect.Bean bean, String propertyPattern)
org.minimalcode.reflect.Property	getProperty(String propertyPattern) Returns a single public Property of the wrapped object, if present, else null.
Object	getSimpleValue(org.minimalcode.reflect.Property property) Returns the value of the specified simple property from the wrapped object.
Object	getSimpleValue(String propertyName) Returns the value of the specified simple property from the wrapped object.
Object	getValue(String propertyPattern) Returns the value of the specified simple, indexed or mapped property locate by the given pattern.
void	setAutoGrowing(boolean isAutoGrowing) Changes the status of the Auto-Growing option.
void	setAutoInstancing(boolean isAutoInstancing) Changes the status of the Auto-Instancing option.
void	setIndexedValue(org.minimalcode.reflect.Property property, int index, Object value) Sets the value of the specified indexed property in the wrapped object.
void	setIndexedValue(String propertyName, int index, Object value) Sets the value of the specified indexed property in the wrapped object.
void	setMappedValue(org.minimalcode.reflect.Property property, Object key, Object value) Sets the value of the specified mapped property in the wrapped object.
void	setMappedValue(String propertyName, Object key, Object value) Sets the value of the specified mapped property in the wrapped object.
void	setOutOfBoundsSafety(boolean isOutOfBoundsSafety) Changes the status of the OutOfBounds-Safety option.
void	setSimpleValue(org.minimalcode.reflect.Property property, Object value) Sets the value of the specified property in the wrapped object.
void	setSimpleValue(String propertyName, Object value) Sets the value of the specified property in the wrapped object.
void	setValue(String propertyPattern, Object value) Sets the value of the specified simple, indexed or mapped property locate by the given pattern, in the wrapped object.
void	setWrappedObject(Object obj) Changes, at any time, the wrapped object with a new object.
String	toString() Returns a textual rapresentation of this wrapper.

Methods inherited from class java.lang.Object

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

Constructor Detail

ObjectWrapper

public ObjectWrapper(Object obj)

Wraps an object.

Parameters:

obj - the object to wrap

Throws:

IllegalArgumentException - if the obj parameter is null

Method Detail

setWrappedObject

public void setWrappedObject(Object obj)

Changes, at any time, the wrapped object with a new object.

Parameters:

obj - the new object to wrap

Throws:

IllegalArgumentException - if the obj parameter is null

getBean

public org.minimalcode.reflect.Bean<?> getBean()

Returns the Bean cached instance of the wrapped object.

Returns:

the bean instance of the wrapped object

setAutoGrowing

public void setAutoGrowing(boolean isAutoGrowing)

Changes the status of the Auto-Growing option.

Default: enabled. If enabled, automatically grows-up any unbound List or array to accomodate an element in an index position larger than its capacity.

Affected:

- setValue(String, Object)

- setIndexedValue(String, int, Object)

- setIndexedValue(Property, int, Object)

Parameters:

isAutoGrowing - the new isAutoGrowing flag option value

setAutoInstancing

public void setAutoInstancing(boolean isAutoInstancing)

Changes the status of the Auto-Instancing option.

Default: enabled. If enabled, automatically instances a new object (a no-args constructor is required) or a new List, Map or array, if the nested Property has value null in the wrapped object.

Affected:

- setValue(String, Object)

- setIndexedValue(String, int, Object)

- setIndexedValue(Property, int, Object)

- setMappedValue(String, Object, Object)

- setMappedValue(Property, Object, Object)

Parameters:

isAutoInstancing - the new isAutoInstancing option flag value

setOutOfBoundsSafety

public void setOutOfBoundsSafety(boolean isOutOfBoundsSafety)

Changes the status of the OutOfBounds-Safety option.

Default: enabled. If enabled, always returns a null value instead of throwing an IndexOutOfBoundsException when trying to access to an item in an unbound position of a List, array or any type of finite Iterable, behaving like a Map.get(Object) implementation.

Affected:

- getValue(String)

- getIndexedValue(Property, int)

Parameters:

isOutOfBoundsSafety - the new isOutOfBoundsSafety flag option value

getProperty

public org.minimalcode.reflect.Property getProperty(String propertyPattern)

Returns a single public Property of the wrapped object, if present, else null.

Differently from Bean.getProperty(String), this method supports the nested pattern notation, allowing to statically traverse the properties' tree (ex: "foo.bar.property").

Parameters:

propertyPattern - the nested pattern to traverse, cannot be null

Returns:

the requested property, or null if not found

Throws:

IllegalArgumentException - if the propertyPattern parameter is null

IllegalArgumentException - if the propertyPattern parameter contains an indexed\mapped '[]' notation

getValue

public Object getValue(String propertyPattern)

Returns the value of the specified simple, indexed or mapped property locate by the given pattern.

Parameters:

propertyPattern - the pattern to traverse, cannot be null

Returns:

the simple, indexed or mapped property value

Throws:

org.minimalcode.reflect.ReflectionException - if a reflection error occurs

IllegalArgumentException - if the propertyPattern parameter is null

IllegalArgumentException - if the propertyPattern parameter contains an unclosed indexed\mapped '[]' notation

IllegalArgumentException - if the propertyPattern parameter contains an invalid, not parsable, index integer

NullPointerException - if the propertyPattern parameter contains a nested property with a null value

NullPointerException - if the propertyPattern parameter contains a nested not-existent property

IndexOutOfBoundsException - if the specified index is outside the valid range for the underlying property

getSimpleValue

public Object getSimpleValue(String propertyName)

Returns the value of the specified simple property from the wrapped object.

Parameters:

propertyName - the name of the property whose value is to be extracted, cannot be null

Returns:

the simple property value

Throws:

org.minimalcode.reflect.ReflectionException - if a reflection error occurs

IllegalArgumentException - if the propertyName parameter is null

NullPointerException - if the wrapped object does not have a property with the given name

getSimpleValue

public Object getSimpleValue(org.minimalcode.reflect.Property property)

Returns the value of the specified simple property from the wrapped object.

Parameters:

property - the property whose value is to be extracted, cannot be null

Returns:

the simple property value

Throws:

org.minimalcode.reflect.ReflectionException - if a reflection error occurs

IllegalArgumentException - if the property parameter is null

getIndexedValue

public Object getIndexedValue(String propertyName,
                              int index)

Returns the value of the specified indexed property from the wrapped object.

Parameters:

propertyName - the name of the indexed property whose value is to be extracted, cannot be null

index - the index of the property value to be extracted

Returns:

the indexed property value

Throws:

org.minimalcode.reflect.ReflectionException - if a reflection error occurs

IllegalArgumentException - if the propertyName parameter is null

IllegalArgumentException - if the indexed object in the wrapped object is not a List, Iterable or array

NullPointerException - if the indexed List, Iterable or array is null in the given object

NullPointerException - if the wrapped object does not have a property with the given name

IndexOutOfBoundsException - if the specified index is outside the valid range for the underlying indexed property

getIndexedValue

public Object getIndexedValue(org.minimalcode.reflect.Property property,
                              int index)

Returns the value of the specified indexed property from the wrapped object.

Parameters:

property - the indexed property whose value is to be extracted, cannot be null

index - the index of the property value to be extracted

Returns:

the indexed property value

Throws:

org.minimalcode.reflect.ReflectionException - if a reflection error occurs

IllegalArgumentException - if the property parameter is null

IllegalArgumentException - if the indexed object in the wrapped object is not a List, Iterable or array

NullPointerException - if the indexed List, Iterable or array is null in the wrapped object

IndexOutOfBoundsException - if the specified index is outside the valid range for the underlying indexed property

getMappedValue

public Object getMappedValue(String propertyName,
                             Object key)

Returns the value of the specified mapped property from the wrapped object.

Parameters:

propertyName - the name of the mapped property whose value is to be extracted, cannot be null

key - the key of the property value to be extracted, can be null

Returns:

the mapped property value

Throws:

org.minimalcode.reflect.ReflectionException - if a reflection error occurs

IllegalArgumentException - if the propertyName parameter is null

IllegalArgumentException - if the mapped object in the wrapped object is not a Map type

NullPointerException - if the mapped object in the wrapped object is null

NullPointerException - if the wrapped object does not have a property with the given name

getMappedValue

public Object getMappedValue(org.minimalcode.reflect.Property property,
                             Object key)

Returns the value of the specified mapped property from the wrapped object.

Parameters:

property - the mapped property whose value is to be extracted, cannot be null

key - the key of the property value to be extracted, can be null

Returns:

the mapped property value

Throws:

org.minimalcode.reflect.ReflectionException - if a reflection error occurs

IllegalArgumentException - if the property parameter is null

IllegalArgumentException - if the mapped object in the wrapped object is not a Map type

NullPointerException - if the mapped object in the wrapped object is null

setValue

public void setValue(String propertyPattern,
                     Object value)

Sets the value of the specified simple, indexed or mapped property locate by the given pattern, in the wrapped object.

Parameters:

propertyPattern - the pattern to traverse, cannot be null

value - the value to set, can be null

Throws:

org.minimalcode.reflect.ReflectionException - if a reflection error occurs

IllegalArgumentException - if the propertyPattern parameter is null

IllegalArgumentException - if the propertyPattern parameter contains an unclosed indexed\mapped '[]' notation

IllegalArgumentException - if the propertyPattern parameter contains an invalid, not parsable, index integer

NullPointerException - if the propertyPattern parameter contains a nested property with a null value

NullPointerException - if the propertyPattern parameter contains a nested not-existent property

IndexOutOfBoundsException - if the specified index is outside the valid range for the underlying property

setSimpleValue

public void setSimpleValue(String propertyName,
                           Object value)

Sets the value of the specified property in the wrapped object.

Parameters:

propertyName - the name of the simple property whose value is to be updated, cannot be null

value - the value to set, can be null

Throws:

IllegalArgumentException - if the property parameter is null

NullPointerException - if the wrapped object does not have a property with the given name

setSimpleValue

public void setSimpleValue(org.minimalcode.reflect.Property property,
                           Object value)

Sets the value of the specified property in the wrapped object.

Parameters:

property - the property whose value is to be updated, cannot be null

value - the value to set, can be null

Throws:

IllegalArgumentException - if the property parameter is null

setIndexedValue

public void setIndexedValue(String propertyName,
                            int index,
                            Object value)

Sets the value of the specified indexed property in the wrapped object.

Parameters:

propertyName - the name of the indexed property whose value is to be updated, cannot be null

index - the index position of the property value to be set

value - the indexed value to set, can be null

Throws:

org.minimalcode.reflect.ReflectionException - if a reflection error occurs

IllegalArgumentException - if the propertyName parameter is null

IllegalArgumentException - if the indexed object in the wrapped object is not a List or array type

IndexOutOfBoundsException - if the indexed object in the wrapped object is out of bounds with the given index and autogrowing is disabled

NullPointerException - if the indexed object in the wrapped object is null

NullPointerException - if the indexed object in the wrapped object is out of bounds with the given index, but autogrowing (if enabled) is unable to fill the blank positions with null

NullPointerException - if the wrapped object does not have a property with the given name

setIndexedValue

public void setIndexedValue(org.minimalcode.reflect.Property property,
                            int index,
                            Object value)

Sets the value of the specified indexed property in the wrapped object.

Parameters:

property - the indexed property whose value is to be updated, cannot be null

index - the index position of the property value to be set

value - the indexed value to set, can be null

Throws:

org.minimalcode.reflect.ReflectionException - if a reflection error occurs

IllegalArgumentException - if the property parameter is null

IllegalArgumentException - if the indexed object in the wrapped object is not a List or array type

IndexOutOfBoundsException - if the indexed object in the wrapped object is out of bounds with the given index and autogrowing is disabled

NullPointerException - if the indexed object in the wrapped object is null

NullPointerException - if the indexed object in the wrapped object is out of bounds with the given index, but autogrowing (if enabled) is unable to fill the blank positions with null

setMappedValue

public void setMappedValue(String propertyName,
                           Object key,
                           Object value)

Sets the value of the specified mapped property in the wrapped object.

Parameters:

propertyName - the name of the mapped property whose value is to be extracted, cannot be null

key - the mapped key of the property value to be set

value - the property value to set, can be null

Throws:

org.minimalcode.reflect.ReflectionException - if a reflection error occurs

IllegalArgumentException - if the propertyName parameter is null

IllegalArgumentException - if the mapped object in the wrapped object is not a Map type

NullPointerException - if the mapped object in the wrapped object is null

NullPointerException - if the wrapped object does not have a property with the given name

setMappedValue

public void setMappedValue(org.minimalcode.reflect.Property property,
                           Object key,
                           Object value)

Sets the value of the specified mapped property in the wrapped object.

Parameters:

property - the mapped property whose value is to be updated, cannot be null

key - the mapped key of the property value to be set

value - the property value to set

Throws:

org.minimalcode.reflect.ReflectionException - if a reflection error occurs

IllegalArgumentException - if the property parameter is null

IllegalArgumentException - if the mapped object in the wrapped object is not a Map

NullPointerException - if the mapped object in the wrapped object is null

toString

public String toString()

Returns a textual rapresentation of this wrapper.

Overrides:

toString in class Object

Returns:

a string decribing the wrapped object

getProperty

public static org.minimalcode.reflect.Property getProperty(org.minimalcode.reflect.Bean bean,
                                                           String propertyPattern)