org.apache.commons.configuration.interpol

Class ConfigurationInterpolator

public class ConfigurationInterpolator extends StrLookup

A class that handles interpolation (variable substitution) for configuration objects.

Each instance of AbstractConfiguration is associated with an object of this class. Each interpolation tasks are delegated to this object.

ConfigurationInterpolator works together with the StrSubstitutor class from Commons Lang. By extending StrLookup it is able to provide values for variables that appear in expressions.

The basic idea of this class is that it can maintain a set of primitive StrLookup objects, each of which are identified by a special prefix. The variables to be processed have the form ${prefix:name}. ConfigurationInterpolator will extract the prefix and determine, which primitive lookup object is registered for it. Then the name of the variable is passed to this object to obtain the actual value. It is also possible to define a default lookup object, which will be used for variables that do not have a prefix.

When a new instance of this class is created it is initialized with a default set of primitive lookup objects. This set can be customized using the static methods registerGlobalLookup() and deregisterGlobalLookup(). Per default it contains the following standard lookup objects:

Prefix Lookup object
sys With this prefix a lookup object is associated that is able to resolve system properties.
const The const prefix indicates that a variable is to be interpreted as a constant member field of a class (i.e. a field with the static final modifiers). The name of the variable must be of the form <full qualified class name>.<field name>, e.g. org.apache.commons.configuration.interpol.ConfigurationInterpolator.PREFIX_CONSTANTS .

After an instance has been created the current set of lookup objects can be modified using the registerLookup() and deregisterLookup() methods. The default lookup object (that is invoked for variables without a prefix) can be set with the setDefaultLookup() method. (If a ConfigurationInterpolator instance is created by a configuration object, this lookup points to the configuration itself, so that variables are resolved using the configuration's properties. This ensures backward compatibility to earlier version of Commons Configuration.)

Implementation node: Instances of this class are not thread-safe related to modifications of their current set of registered lookup objects. It is intended that each instance is associated with a single Configuration object and used for its interpolation tasks.

Since: 1.4

Version: $Id: ConfigurationInterpolator.java 491243 2006-12-30 16:04:03Z oheger $

Author: Commons Configuration team

Field Summary
StrLookupdefaultLookup
Stores the default lookup object.
static MapglobalLookups
A map with the globally registered lookup objects.
MaplocalLookups
A map with the locally registered lookup objects.
static StringPREFIX_CONSTANTS
Constant for the prefix of the standard lookup object for resolving constant values.
static charPREFIX_SEPARATOR
Constant for the prefix separator.
static StringPREFIX_SYSPROPERTIES
Constant for the prefix of the standard lookup object for resolving system properties.
Constructor Summary
ConfigurationInterpolator()
Creates a new instance of ConfigurationInterpolator.
Method Summary
static booleanderegisterGlobalLookup(String prefix)
Deregisters the global lookup object for the specified prefix.
booleanderegisterLookup(String prefix)
Deregisters the lookup object for the specified prefix at this instance.
protected StrLookupfetchLookupForPrefix(String prefix)
Obtains the lookup object for the specified prefix.
protected StrLookupfetchNoPrefixLookup()
Returns the lookup object to be used for variables without a prefix.
StrLookupgetDefaultLookup()
Returns the default lookup object.
Stringlookup(String var)
Resolves the specified variable.
SetprefixSet()
Returns a set with the prefixes, for which lookup objects are registered at this instance.
static voidregisterGlobalLookup(String prefix, StrLookup lookup)
Registers the given lookup object for the specified prefix globally.
voidregisterLookup(String prefix, StrLookup lookup)
Registers the given lookup object for the specified prefix at this instance.
voidsetDefaultLookup(StrLookup defaultLookup)
Sets the default lookup object.

Field Detail

defaultLookup

private StrLookup defaultLookup
Stores the default lookup object.

globalLookups

private static Map globalLookups
A map with the globally registered lookup objects.

localLookups

private Map localLookups
A map with the locally registered lookup objects.

PREFIX_CONSTANTS

public static final String PREFIX_CONSTANTS
Constant for the prefix of the standard lookup object for resolving constant values.

PREFIX_SEPARATOR

private static final char PREFIX_SEPARATOR
Constant for the prefix separator.

PREFIX_SYSPROPERTIES

public static final String PREFIX_SYSPROPERTIES
Constant for the prefix of the standard lookup object for resolving system properties.

Constructor Detail

ConfigurationInterpolator

public ConfigurationInterpolator()
Creates a new instance of ConfigurationInterpolator.

Method Detail

deregisterGlobalLookup

public static boolean deregisterGlobalLookup(String prefix)
Deregisters the global lookup object for the specified prefix. This means that this lookup object won't be available for later created instances any more. For already existing instances this operation does not have any impact.

Parameters: prefix the variable prefix

Returns: a flag whether for this prefix a lookup object had been registered

deregisterLookup

public boolean deregisterLookup(String prefix)
Deregisters the lookup object for the specified prefix at this instance. It will be removed from this instance.

Parameters: prefix the variable prefix

Returns: a flag whether for this prefix a lookup object had been registered

fetchLookupForPrefix

protected StrLookup fetchLookupForPrefix(String prefix)
Obtains the lookup object for the specified prefix. This method is called by the lookup() method. This implementation will check whether a lookup object is registered for the given prefix. If not, a null lookup object will be returned.

Parameters: prefix the prefix

Returns: the lookup object to be used for this prefix

fetchNoPrefixLookup

protected StrLookup fetchNoPrefixLookup()
Returns the lookup object to be used for variables without a prefix. This implementation will check whether a default lookup object was set. If this is the case, it will be returned. Otherwise a null lookup object will be returned.

Returns: the lookup object to be used for variables without a prefix

getDefaultLookup

public StrLookup getDefaultLookup()
Returns the default lookup object.

Returns: the default lookup object

lookup

public String lookup(String var)
Resolves the specified variable. This implementation will try to extract a variable prefix from the given variable name (the first colon (':') is used as prefix separator). It then passes the name of the variable with the prefix stripped to the lookup object registered for this prefix. If no prefix can be found, the default lookup object will be used.

Parameters: var the name of the variable whose value is to be looked up

Returns: the value of this variable or null if it cannot be resolved

prefixSet

public Set prefixSet()
Returns a set with the prefixes, for which lookup objects are registered at this instance. This means that variables with these prefixes can be processed.

Returns: a set with the registered variable prefixes

registerGlobalLookup

public static void registerGlobalLookup(String prefix, StrLookup lookup)
Registers the given lookup object for the specified prefix globally. This means that all instances that are created later will use this lookup object for this prefix. If for this prefix a lookup object is already registered, the new lookup object will replace the old one. Note that the lookup objects registered here will be shared between multiple clients. So they should be thread-safe.

Parameters: prefix the variable prefix (must not be null) lookup the lookup object to be used for this prefix (must not be null)

registerLookup

public void registerLookup(String prefix, StrLookup lookup)
Registers the given lookup object for the specified prefix at this instance. From now on this lookup object will be used for variables that have the specified prefix.

Parameters: prefix the variable prefix (must not be null) lookup the lookup object to be used for this prefix (must not be null)

setDefaultLookup

public void setDefaultLookup(StrLookup defaultLookup)
Sets the default lookup object. This lookup object will be used for all variables without a special prefix. If it is set to null, such variables won't be processed.

Parameters: defaultLookup the new default lookup object