com.uwyn.rife.ioc
Class HierarchicalProperties

java.lang.Object
  com.uwyn.rife.ioc.HierarchicalProperties

public class HierarchicalProperties
extends Object

This class allows the creation of a hierarchical tree of named PropertyValue instances.

When a property is looked up in a child HierarchicalProperties instance, the lookup will be propagated to its parent when it couldn't be found in the child. A single hierarchical line is thus considered to be one collection that groups all involved HierarchicalProperties instances. Retrieving the names and the size will recursively take all the properties of the parents into account and return the consolidated result. To offer these features, intelligent caching has been implemented to ensure optimal performance.

Since:

1.1

Version:

$Revision: 3643 $

Author:

Geert Bevin (gbevin[remove] at uwyn dot com)

Constructor Summary

HierarchicalProperties()

Method Summary

boolean	contains(String name) Checks the HierarchicalProperties hierarchy for the presence of the specified name.
HierarchicalProperties	createShadow(HierarchicalProperties limit) Creates a copy of this HierarchicalProperties hierarchy until a certain instance is reached.
PropertyValue	get(String name) Retrieves the PropertyValue for a specific name from the HierarchicalProperties hierarchy.
Collection<String>	getInjectableNames() Retrieves a Set with the unique names that are present in the HierarchicalProperties hierarchy and that conform to the Java rules for valid identifiers.
Map<String,PropertyValue>	getLocalMap() Retrieves the Map with only the properties that are locally present in this HierarchicalProperties instance.
Collection<String>	getNames() Retrieves a Set with the unique names that are present in the HierarchicalProperties hierarchy.
HierarchicalProperties	getParent() Retrieves the parent of this HierarchicalProperties instance.
HierarchicalProperties	getRoot() Retrieves the first parent of this HierarchicalProperties hierarchy.
Object	getValue(String name) Retrieves the value of PropertyValue for a specific name from the HierarchicalProperties hierarchy.
Object	getValue(String name, Object defaultValue) Retrieves the value of PropertyValue for a specific name from the HierarchicalProperties hierarchy.
String	getValueString(String name) Retrieves the string value of PropertyValue for a specific name from the HierarchicalProperties hierarchy.
String	getValueString(String name, String defaultValue) Retrieves the string value of PropertyValue for a specific name from the HierarchicalProperties hierarchy.
<T> T	getValueTyped(String name, Class<T> type) Retrieves the typed value of PropertyValue for a specific name from the HierarchicalProperties hierarchy.
<T> T	getValueTyped(String name, Class<T> type, T defaultValue) Retrieves the typed value of PropertyValue for a specific name from the HierarchicalProperties hierarchy.
HierarchicalProperties	parent(HierarchicalProperties parent) Sets the parent of this HierarchicalProperties instance.
HierarchicalProperties	put(String name, Object value) Associates the specified fixed object value with the specified name in this HierarchicalProperties instance.
HierarchicalProperties	put(String name, PropertyValue value) Associates the specified value with the specified name in this HierarchicalProperties instance.
HierarchicalProperties	putAll(HierarchicalProperties source) Copies all of the named properties from the specified HierarchicalProperties instance to this HierarchicalProperties instance.
HierarchicalProperties	putAll(Map source) Copies all of the entries for a Map instance to this HierarchicalProperties instance.
PropertyValue	remove(String name) Removes the mapping for this name from this HierarchicalProperties instance, if it is present.
void	setParent(HierarchicalProperties parent) Sets the parent of this HierarchicalProperties instance.
int	size() Retrieves the number of unique names in the HierarchicalProperties hierarchy.

Methods inherited from class java.lang.Object

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

Constructor Detail

HierarchicalProperties

public HierarchicalProperties()

Method Detail

createShadow

public HierarchicalProperties createShadow(HierarchicalProperties limit)

Creates a copy of this HierarchicalProperties hierarchy until a certain instance is reached.

Each copied instance will shared the datastructure in which the properties are stored with the original. Creating a shadow is this for changing the hierarchical structure but maintaining a centralized management of the properties.

Parameters:

limit - the HierarchicalProperties instance that will not be part of the shadow copy and interrupt the copying process; or null if the entire hierachy should be copied.

Returns:

the shadow copy of this HierarchicalProperties hierarchy hierarchy

Since:

1.1

getRoot

public HierarchicalProperties getRoot()

Retrieves the first parent of this HierarchicalProperties hierarchy.

Returns:

the root of this HierarchicalProperties hierarchy

Since:

1.1

getLocalMap

public Map<String,PropertyValue> getLocalMap()

Retrieves the Map with only the properties that are locally present in this HierarchicalProperties instance.

Returns:

the local Map of this HierarchicalProperties instance

Since:

1.1

setParent

public void setParent(HierarchicalProperties parent)

Sets the parent of this HierarchicalProperties instance.

Parameters:

parent - the parent of this instance; or null if this instance should be isolated

Since:

1.1

See Also:

getParent()

parent

public HierarchicalProperties parent(HierarchicalProperties parent)

Sets the parent of this HierarchicalProperties instance.

Parameters:

parent - the parent of this instance; or null if this instance should be isolated

Returns:

this HierarchicalProperties instance

Since:

1.1

See Also:

getParent()

getParent

public HierarchicalProperties getParent()

Retrieves the parent of this HierarchicalProperties instance.

Returns:

the parent of this HierarchicalProperties instance; or

null if this instance is isolated

Since:

1.1

See Also:

parent(com.uwyn.rife.ioc.HierarchicalProperties)

put

public HierarchicalProperties put(String name,
                                  PropertyValue value)

Associates the specified value with the specified name in this HierarchicalProperties instance. If it previously contained a mapping for this name, the old value is replaced by the specified value.

Parameters:

name - the name that will be associated with the property

value - the property value that will be associated with the specified name

Returns:

this HierarchicalProperties instance

Since:

1.1

See Also:

put(String, Object), putAll(com.uwyn.rife.ioc.HierarchicalProperties)

put

public HierarchicalProperties put(String name,
                                  Object value)

Associates the specified fixed object value with the specified name in this HierarchicalProperties instance. If it previously contained a mapping for this name, the old value is replaced by the specified value.

Parameters:

name - the name that will be associated with the property

value - the property value that will be associated with the specified name, note that this method will create a PropertyValueObject instance that will contain the value in a fixed manner

Returns:

this HierarchicalProperties instance

Since:

1.6

See Also:

put(String, PropertyValue), putAll(com.uwyn.rife.ioc.HierarchicalProperties)

remove

public PropertyValue remove(String name)

Removes the mapping for this name from this HierarchicalProperties instance, if it is present.

Parameters:

name - the name that will be removed

Returns:

the previously associated value; or

null if the name wasn't found in this HierarchicalProperties instance

Since:

1.1

putAll

public HierarchicalProperties putAll(HierarchicalProperties source)

Copies all of the named properties from the specified HierarchicalProperties instance to this HierarchicalProperties instance. The effect of this call is equivalent to that of calling put(java.lang.String, com.uwyn.rife.ioc.PropertyValue) on this HierarchicalProperties once for each mapping from the specified HierarchicalProperties instance.

Parameters:

source - the properties that will be stored in this HierarchicalProperties instance

Returns:

this HierarchicalProperties instance

Since:

1.1

See Also:

put(java.lang.String, com.uwyn.rife.ioc.PropertyValue)

putAll

public HierarchicalProperties putAll(Map source)

Copies all of the entries for a Map instance to this HierarchicalProperties instance.

Parameters:

source - the map entries that will be stored in this HierarchicalProperties instance

Returns:

this HierarchicalProperties instance

Since:

1.5

contains

public boolean contains(String name)

Checks the HierarchicalProperties hierarchy for the presence of the specified name.

Parameters:

name - the name whose presence will be checked

Returns:

true if the name was found; or

false otherwise

Since:

1.1

See Also:

get(java.lang.String)

get

public PropertyValue get(String name)

Retrieves the PropertyValue for a specific name from the HierarchicalProperties hierarchy.

Parameters:

name - the name whose associated value will be returned

Returns:

the associated PropertyValue; or

null if the name could not be found

Since:

1.1

See Also:

contains(java.lang.String)

getValue

public Object getValue(String name)
                throws PropertyValueException

Retrieves the value of PropertyValue for a specific name from the HierarchicalProperties hierarchy.

Parameters:

name - the name whose associated value will be returned

Returns:

the associated PropertyValue; or

null if the name could not be found

Throws:

PropertyValueException - when an error occurred while retrieving the property value

Since:

1.1

See Also:

get(java.lang.String), getValue(String, Object)

getValue

public Object getValue(String name,
                       Object defaultValue)
                throws PropertyValueException

Retrieves the value of PropertyValue for a specific name from the HierarchicalProperties hierarchy. If the property couldn't be found or if the value was null, the default value will be returned.

Parameters:

name - the name whose associated value will be returned

defaultValue - the value that should be used as a fallback

Returns:

the associated PropertyValue; or

the defaultValue if the property couldn't be found or if the value was null

Throws:

PropertyValueException - when an error occurred while retrieving the property value

Since:

1.1

See Also:

get(java.lang.String), getValue(String)

getValueString

public String getValueString(String name)
                      throws PropertyValueException

Retrieves the string value of PropertyValue for a specific name from the HierarchicalProperties hierarchy.

Parameters:

name - the name whose associated value will be returned

Returns:

the string value of the retrieved PropertyValue; or

null if the name could not be found

Throws:

PropertyValueException - when an error occurred while retrieving the property value

Since:

1.1

See Also:

get(java.lang.String), getValueString(String, String), getValueTyped(java.lang.String, java.lang.Class)

getValueString

public String getValueString(String name,
                             String defaultValue)
                      throws PropertyValueException

Retrieves the string value of PropertyValue for a specific name from the HierarchicalProperties hierarchy. If the property couldn't be found, if the value was null or if the value was empty, the default value will be returned.

Parameters:

name - the name whose associated value will be returned

defaultValue - the value that should be used as a fallback

Returns:

the string value of the retrieved PropertyValue; or

the defaultValue if the property couldn't be found or if the value was null or an empty string

Throws:

PropertyValueException - when an error occurred while retrieving the property value

Since:

1.1

See Also:

get(java.lang.String), getValueString(String), getValueTyped(java.lang.String, java.lang.Class)

getValueTyped

public <T> T getValueTyped(String name,
                           Class<T> type)
                throws PropertyValueException

Retrieves the typed value of PropertyValue for a specific name from the HierarchicalProperties hierarchy.

Note that no conversion will occurr, the value is simple verified to be assignable to the requested type and then casted to it.

Parameters:

name - the name whose associated value will be returned

type - the class that the value has to be retrieved as

Returns:

the associated PropertyValue as an instance of the provided type; or

null if the name could not be found

Throws:

IncompatiblePropertyValueTypeException - when the type of the property value wasn't compatible with the requested type

PropertyValueException - when an error occurred while retrieving the property value

Since:

1.6

See Also:

get(java.lang.String), getValueString(java.lang.String), getValueTyped(String, Class)

getValueTyped

public <T> T getValueTyped(String name,
                           Class<T> type,
                           T defaultValue)
                throws PropertyValueException

Retrieves the typed value of PropertyValue for a specific name from the HierarchicalProperties hierarchy.

Note that no conversion will occurr, the value is simple verified to be assignable to the requested type and then casted to it.

Parameters:

name - the name whose associated value will be returned

type - the class that the value has to be retrieved as

defaultValue - the value that should be used as a fallback

Returns:

the associated PropertyValue as an instance of the provided type; or

the defaultValue if the property couldn't be found or if the value was null

Throws:

IncompatiblePropertyValueTypeException - when the type of the property value wasn't compatible with the requested type

PropertyValueException - when an error occurred while retrieving the property value

Since:

1.6

See Also:

get(java.lang.String), getValueString(java.lang.String), getValueTyped(String, Class)

size

public int size()

Retrieves the number of unique names in the HierarchicalProperties hierarchy.

Returns:

the amount of unique names

Since:

1.1

getNames

public Collection<String> getNames()

Retrieves a Set with the unique names that are present in the HierarchicalProperties hierarchy.

Returns:

a collection with the unique names

Since:

1.1

See Also:

getInjectableNames()

getInjectableNames

public Collection<String> getInjectableNames()

Retrieves a Set with the unique names that are present in the HierarchicalProperties hierarchy and that conform to the Java rules for valid identifiers. The names in this set are thus usable for injection through bean setters.

Returns:

a Set with the unique injectable names

Since:

1.1

See Also:

getNames()