Package rife.ioc

Class HierarchicalProperties

java.lang.Object
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.0

  • Field Details

    • SYSTEM_PROPERTY_FILE_NAME

      public static final String SYSTEM_PROPERTY_FILE_NAME
      Providing a RIFE2_PROPERTIES_FILE environment variable, describes the path of a file that will be automatically read and parsed for additional properties. These properties will be inserted into the hierarchical properties hierarchy after the system environment variables and before the system properties.
      Since:
      1.5
      See Also:

  • Constructor Details

    • HierarchicalProperties

      public HierarchicalProperties()

  • Method Details

    • createSystemInstance

      public static HierarchicalProperties createSystemInstance()
      Creates a new instance that's populated with the system environment variables and JVM properties.
      Returns:
      a pre-populated new instance with system data
      Since:
      1.4.1

    • createShadow

      public HierarchicalProperties createShadow(HierarchicalProperties limit)
      Creates a copy of this HierarchicalProperties hierarchy until a certain instance is reached.

      Each copied instance will share the datastructure in which the properties are stored with the original. Creating a shadow is 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
      Since:
      1.0

    • getRoot

      public HierarchicalProperties getRoot()
      Retrieves the first parent of this HierarchicalProperties hierarchy.
      Returns:
      the root of this HierarchicalProperties hierarchy
      Since:
      1.0

    • 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.0

    • 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.0
      See Also:

    • 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.0
      See Also:

    • 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.0
      See Also:

    • 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.0
      See Also:

    • 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.0
      See Also:

    • 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.0

    • putAll

      public HierarchicalProperties putAll(HierarchicalProperties source)
      Copies all 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, 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.0
      See Also:

    • putAllWithoutReplacing

      public HierarchicalProperties putAllWithoutReplacing(HierarchicalProperties source)
      Copies all the named properties from the specified HierarchicalProperties instance to this HierarchicalProperties instance, without replacing existing properties. The effect of this call is equivalent to that of calling put(java.lang.String, rife.ioc.PropertyValue) on this HierarchicalProperties once for each mapping from the specified HierarchicalProperties instance that doesn't have a key in this instance yet.
      Parameters:
      source - the properties that will be stored in this HierarchicalProperties instance
      Returns:
      this HierarchicalProperties instance
      Since:
      1.0
      See Also:

    • putAll

      public HierarchicalProperties putAll(Map source)
      Copies all 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.0

    • 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.0
      See Also:

    • 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.0
      See Also:

    • 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.0
      See Also:

    • 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.0
      See Also:

    • 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.0
      See Also:

    • 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.0
      See Also:

    • 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 cast 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.0
      See Also:

    • 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 occur, the value is simple verified to be assignable to the requested type and then cast 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.0
      See Also:

    • size

      public int size()
      Retrieves the number of unique names in the HierarchicalProperties hierarchy.
      Returns:
      the amount of unique names
      Since:
      1.0

    • 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.0
      See Also:

    • 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.0
      See Also: