com.uwyn.rife.ioc
Class HierarchicalProperties

java.lang.Object
  extended by 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()


Copyright © 2001-2007 Uwyn sprl/bvba. All Rights Reserved.