org.apache.qpid.junit.extensions.util
Class ContextualProperties

java.lang.Object
  extended by java.util.Dictionary<K,V>
      extended by java.util.Hashtable<Object,Object>
          extended by java.util.Properties
              extended by org.apache.qpid.junit.extensions.util.ParsedProperties
                  extended by org.apache.qpid.junit.extensions.util.ContextualProperties
All Implemented Interfaces:
Serializable, Cloneable, Map<Object,Object>

public class ContextualProperties
extends ParsedProperties

ContextualProperties is an extension of Properties that automatically selects properties based on an environment parameter (defined by the system property ENV_SYS_PROPERTY), the name of a class, plus a modifier (which can be used to name a method of a class) and a property key. It also supports the definition of arrays of property values using indexes. The properties are searched in the following order until a match is found:

  1. environment + class name with package name + modifier + key
  2. environment + class name with package name + key
  3. environment + key
  4. class name with package name + modifier + key
  5. class name with package name + key
  6. key

To create arrays of property values add index numbers onto the end of the property keys. An array of string values will be created with the elements of the array set to the value of the property at the matching index. Ideally the index values will be contiguous, starting at 0. This does not need to be the case however. If an array definition begins at index n, and ends at index m, Then an array big enough to hold m + 1 elements will be created and populated with values from n to m. Values before n and any missing values between n and m will be null in the array.

To give an example, suppose you have two different environments 'DEVELOPMENT' and 'PRODUCTION' and they each need the same properties but set to different values for each environment and some properties the same in both, you could create a properties file like:

# Project configuration properties file.

# These properties are environment specific.
DEVELOPMENT.debug=true
PRODUCTION.debug=false

# Always debug MyClass in all environments but not the myMethod method.
MyClass.debug=true
MyClass.myMethod.debug=false

# Set up an array of my ten favourite animals. Leave elements 3 to 8 as null as I haven't decided on them yet.
animals.0=cat
animals.1=dog
animals.2=elephant
animals.9=lion

# This is a default value that will be used when the environment is not known.
debug=false

The most specific definition of a property is searched for first moving out to the most general. This allows general property defaults to be set and then overiden for specific uses by some classes and modifiers.

A ContextualProperties object can be loaded in the same way as a java.utils.Properties. A recommended way to do this that does not assume that the properties file is a file (it could be in a jar) is to load the properties from the url for the resource lookup up on the classpath:

Properties configProperties = new ContextualProperties();
configProperties.load(this.getClass().getClassLoader().getResourceAsStream("config.properties"));

EnvironmentProperties will load the 'DEVELOPMENT.debug' property or 'PROUCTION.debug' property based on the setting of the system environment property. If a matching property for the environment cannot be found then the simple property name without the environment pre-pended onto it will be used instead. This 'use of default environments' behaviour is turned on initially but it can be disabled by calling the useDefaultEnvironments(boolean) method.

When a property matching a key cannot be found then the property accessor methods will always return null. If a default value for a property exists but the 'use of default environments' behavious prevents it being used then the accessor methods will return null.

CRC Card
Responsibilities Collaborations
Automatically select properties dependant on environment, class name and modifier as well as property key.
Convert indexed properties into arrays.

See Also:
Serialized Form

Field Summary
protected  Map arrayProperties
          Used to hold all the array properties.
static String ENV_SYS_PROPERTY
          The name of the system property that is used to define the environment.
 
Fields inherited from class java.util.Properties
defaults
 
Constructor Summary
ContextualProperties()
          Default constructor that builds a ContextualProperties that uses environment defaults.
ContextualProperties(Properties props)
          Creates a ContextualProperties that uses environment defaults and is initialized with the specified properties.
 
Method Summary
protected  void createArrayProperties()
          Scans all the properties in the parent Properties object and creates arrays for any array property definitions.
protected  Iterator getKeyIterator(String base, String modifier, String key)
          For a given environment, base, modifier and key and setting of the use of default environments feature this generates an iterator that walks over the order in which to try and access properties.
 String[] getProperties(Object base, String modifier, String key)
          Looks up an array property value relative to the environment, base class and modifier.
 String[] getProperties(String key)
          Looks up an array property value relative to the environment, callers class and method.
 String[] getProperties(String base, String modifier, String key)
          Looks up an array property value relative to the environment, base class and modifier.
 String getProperty(Object base, String modifier, String key)
          Looks up a property value relative to the environment, base class and modifier.
 String getProperty(String key)
          Looks up a property value relative to the environment, callers class and method.
 String getProperty(String base, String modifier, String key)
          Looks up a property value relative to the environment, base class and modifier.
 void load(InputStream inStream)
          Parses an input stream as properties.
 void useDefaultEnvironments(boolean flag)
          Tells this environment aware properties object whether it should use default environment properties without a pre-pended environment when a property for the current environment cannot be found.
 
Methods inherited from class org.apache.qpid.junit.extensions.util.ParsedProperties
getPropertyAsBoolean, getPropertyAsInteger, getPropertyAsLong, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty, setPropertyIfNull, setPropertyIfNull, setPropertyIfNull, setPropertyIfNull, setPropertyIfNull, setPropertyIfNull, setPropertyIfNull, setSysPropertyIfNull, setSysPropertyIfNull, setSysPropertyIfNull, setSysPropertyIfNull, setSysPropertyIfNull, setSysPropertyIfNull, setSysPropertyIfNull
 
Methods inherited from class java.util.Properties
getProperty, list, list, load, loadFromXML, propertyNames, save, setProperty, store, store, storeToXML, storeToXML, stringPropertyNames
 
Methods inherited from class java.util.Hashtable
clear, clone, contains, containsKey, containsValue, elements, entrySet, equals, get, hashCode, isEmpty, keys, keySet, put, putAll, rehash, remove, size, toString, values
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

ENV_SYS_PROPERTY

public static final String ENV_SYS_PROPERTY
The name of the system property that is used to define the environment.

See Also:
Constant Field Values

arrayProperties

protected Map arrayProperties
Used to hold all the array properties. This is a mapping from property names to ArrayLists of Strings.

Constructor Detail

ContextualProperties

public ContextualProperties()
Default constructor that builds a ContextualProperties that uses environment defaults.


ContextualProperties

public ContextualProperties(Properties props)
Creates a ContextualProperties that uses environment defaults and is initialized with the specified properties.

Parameters:
props - The properties to initialize this with.
Method Detail

load

public void load(InputStream inStream)
          throws IOException
Parses an input stream as properties.

Overrides:
load in class Properties
Parameters:
inStream - The input stream to read the properties from.
Throws:
IOException - If there is an IO error during reading from the input stream.

useDefaultEnvironments

public void useDefaultEnvironments(boolean flag)
Tells this environment aware properties object whether it should use default environment properties without a pre-pended environment when a property for the current environment cannot be found.

Parameters:
flag - True to use defaults, false to not use defaults.

getProperty

public String getProperty(String key)
Looks up a property value relative to the environment, callers class and method. The default environment will be checked for a matching property if defaults are being used. In order to work out the callers class and method this method throws an exception and then searches one level up its stack frames.

Overrides:
getProperty in class Properties
Parameters:
key - The property key.
Returns:
The value of this property searching from the most specific definition (environment, class, method, key) to the most general (key only), unless use of default environments is turned off in which case the most general proeprty searched is (environment, key).

getProperty

public String getProperty(Object base,
                          String modifier,
                          String key)
Looks up a property value relative to the environment, base class and modifier. The default environment will be checked for a matching property if defaults are being used.

Parameters:
base - An object of the class to retrieve properties relative to.
modifier - The modifier (which may stand for a method of the class).
key - The property key.
Returns:
The value of this property searching from the most specific definition (environment, class, modifier, key) to the most general (key only), unless use of default environments is turned off in which case the most general property searched is (environment, key).

getProperty

public String getProperty(String base,
                          String modifier,
                          String key)
Looks up a property value relative to the environment, base class and modifier. The default environment will be checked for a matching property if defaults are being used.

Parameters:
base - The name of the class to retrieve properties relative to.
modifier - The modifier (which may stand for a method of the class).
key - The property key.
Returns:
The value of this property searching from the most specific definition (environment, class, modifier, key) to the most general (key only), unless use of default environments is turned off in which case the most general property searched is (environment, key).

getProperties

public String[] getProperties(String key)
Looks up an array property value relative to the environment, callers class and method. The default environment will be checked for a matching array property if defaults are being used. In order to work out the callers class and method this method throws an exception and then searches one level up its stack frames.

Parameters:
key - The property key.
Returns:
The array value of this indexed property searching from the most specific definition (environment, class, method, key) to the most general (key only), unless use of default environments is turned off in which case the most general proeprty searched is (environment, key).

getProperties

public String[] getProperties(Object base,
                              String modifier,
                              String key)
Looks up an array property value relative to the environment, base class and modifier. The default environment will be checked for a matching array property if defaults are being used.

Parameters:
base - An object of the class to retrieve properties relative to.
modifier - The modifier (which may stand for a method of the class).
key - The property key.
Returns:
The array value of this indexed property searching from the most specific definition (environment, class, modifier, key) to the most general (key only), unless use of default environments is turned off in which case the most general proeprty searched is (environment, key).

getProperties

public String[] getProperties(String base,
                              String modifier,
                              String key)
Looks up an array property value relative to the environment, base class and modifier. The default environment will be checked for a matching array property if defaults are being used.

Parameters:
base - The name of the class to retrieve properties relative to.
modifier - The modifier (which may stand for a method of the class).
key - The property key.
Returns:
The array value of this indexed property searching from the most specific definition (environment, class, modifier, key) to the most general (key only), unless use of default environments is turned off in which case the most general property searched is (environment, key).

getKeyIterator

protected Iterator getKeyIterator(String base,
                                  String modifier,
                                  String key)
For a given environment, base, modifier and key and setting of the use of default environments feature this generates an iterator that walks over the order in which to try and access properties.

See the ORDER constant for an explanation of how the key ordering is generated.

Parameters:
base - The name of the class to retrieve properties relative to.
modifier - The modifier (which may stand for a method of the class).
key - The property key.
Returns:
An Iterator over String keys defining the order in which properties should be accessed.

createArrayProperties

protected void createArrayProperties()
Scans all the properties in the parent Properties object and creates arrays for any array property definitions.

Array properties are defined with indexes. For example:

property.1=one
property.2=two
property.3=three

Note that these properties will be stored as the 'empty string' or "" property array.

.1=one
2=two



Licensed to the Apache Software Foundation