ConfigurationInterpolator (Apache Commons Configuration 2.7 API)

java.lang.Object
- org.apache.commons.configuration2.interpol.ConfigurationInterpolator

```
public class ConfigurationInterpolator
extends Object
```
A class that handles interpolation (variable substitution) for configuration objects.

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

ConfigurationInterpolator internally uses the StringSubstitutor class from Commons Text. Thus it supports the same syntax of variable expressions.

The basic idea of this class is that it can maintain a set of primitive Lookup objects, each of which is 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 an arbitrary number of default lookup objects, which are used for variables that do not have a prefix or that cannot be resolved by their associated lookup object. When adding default lookup objects their order matters; they are queried in this order, and the first non-null variable value is used.

After an instance has been created it does not contain any Lookup objects. The current set of lookup objects can be modified using the registerLookup() and deregisterLookup() methods. Default lookup objects (that are invoked for variables without a prefix) can be added or removed with the addDefaultLookup() and removeDefaultLookup() methods respectively. (When a ConfigurationInterpolator instance is created by a configuration object, a default lookup object is added pointing to the configuration itself, so that variables are resolved using the configuration's properties.)

The default usage scenario is that on a fully initialized instance the interpolate() method is called. It is passed an object value which may contain variables. All these variables are substituted if they can be resolved. The result is the passed in value with variables replaced. Alternatively, the resolve() method can be called to obtain the values of specific variables without performing interpolation.

Implementation node: This class is thread-safe. Lookup objects can be added or removed at any time concurrent to interpolation operations.

Since:

1.4

Constructor Summary

Constructors
Constructor and Description

ConfigurationInterpolator()
Creates a new instance of ConfigurationInterpolator.

Constructors
Constructor and Description
`ConfigurationInterpolator()` Creates a new instance of `ConfigurationInterpolator`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addDefaultLookup(Lookup defaultLookup)` Adds a default `Lookup` object.
`void`	`addDefaultLookups(Collection<? extends Lookup> lookups)` Adds all `Lookup` objects in the given collection as default lookups.
`boolean`	`deregisterLookup(String prefix)` Deregisters the `Lookup` object for the specified prefix at this instance.
`protected Lookup`	`fetchLookupForPrefix(String prefix)` Obtains the lookup object for the specified prefix.
`static ConfigurationInterpolator`	`fromSpecification(InterpolatorSpecification spec)` Creates a new `ConfigurationInterpolator` instance based on the passed in specification object.
`List<Lookup>`	`getDefaultLookups()` Returns a collection with the default `Lookup` objects added to this `ConfigurationInterpolator`.
`static Map<String,Lookup>`	`getDefaultPrefixLookups()` Returns a map containing the default prefix lookups.
`Map<String,Lookup>`	`getLookups()` Returns a map with the currently registered `Lookup` objects and their prefixes.
`ConfigurationInterpolator`	`getParentInterpolator()` Returns the parent `ConfigurationInterpolator`.
`Object`	`interpolate(Object value)` Performs interpolation of the passed in value.
`boolean`	`isEnableSubstitutionInVariables()` Sets a flag that variable names can contain other variables.
`static Lookup`	`nullSafeLookup(Lookup lookup)` Utility method for obtaining a `Lookup` object in a safe way.
`Set<String>`	`prefixSet()` Returns an unmodifiable set with the prefixes, for which `Lookup` objects are registered at this instance.
`void`	`registerLookup(String prefix, Lookup lookup)` Registers the given `Lookup` object for the specified prefix at this instance.
`void`	`registerLookups(Map<String,? extends Lookup> lookups)` Registers all `Lookup` objects in the given map with their prefixes at this `ConfigurationInterpolator`.
`boolean`	`removeDefaultLookup(Lookup lookup)` Removes the specified `Lookup` object from the list of default `Lookup`s.
`Object`	`resolve(String var)` Resolves the specified variable.
`void`	`setEnableSubstitutionInVariables(boolean f)` Sets the flag whether variable names can contain other variables.
`void`	`setParentInterpolator(ConfigurationInterpolator parentInterpolator)` Sets the parent `ConfigurationInterpolator`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - ConfigurationInterpolator
```
public ConfigurationInterpolator()
```
    Creates a new instance of ConfigurationInterpolator.
- Method Detail
  - fromSpecification
```
public static ConfigurationInterpolator fromSpecification(InterpolatorSpecification spec)
```
    Creates a new ConfigurationInterpolator instance based on the passed in specification object. If the InterpolatorSpecification already contains a ConfigurationInterpolator object, it is used directly. Otherwise, a new instance is created and initialized with the properties stored in the specification.
    
    Parameters:
    
    spec - the InterpolatorSpecification (must not be null)
    
    Returns:
    
    the ConfigurationInterpolator obtained or created based on the given specification
    
    Throws:
    
    IllegalArgumentException - if the specification is null
    
    Since:
    
    2.0
  - getDefaultPrefixLookups
```
public static Map<String,Lookup> getDefaultPrefixLookups()
```
    Returns a map containing the default prefix lookups. Every configuration object derived from AbstractConfiguration is by default initialized with a ConfigurationInterpolator containing these Lookup objects and their prefixes. The map cannot be modified
    
    Returns:
    
    a map with the default prefix Lookup objects and their prefixes
    
    Since:
    
    2.0
  - nullSafeLookup
```
public static Lookup nullSafeLookup(Lookup lookup)
```
    Utility method for obtaining a Lookup object in a safe way. This method always returns a non-null Lookup object. If the passed in Lookup is not null, it is directly returned. Otherwise, result is a dummy Lookup which does not provide any values.
    
    Parameters:
    
    lookup - the Lookup to check
    
    Returns:
    
    a non-null Lookup object
    
    Since:
    
    2.0
  - addDefaultLookup
```
public void addDefaultLookup(Lookup defaultLookup)
```
    Adds a default Lookup object. Default Lookup objects are queried (in the order they were added) for all variables without a special prefix. If no default Lookup objects are present, such variables won't be processed.
    
    Parameters:
    
    defaultLookup - the default Lookup object to be added (must not be null)
    
    Throws:
    
    IllegalArgumentException - if the Lookup object is null
  - addDefaultLookups
```
public void addDefaultLookups(Collection<? extends Lookup> lookups)
```
    Adds all Lookup objects in the given collection as default lookups. The collection can be null, then this method has no effect. It must not contain null entries.
    
    Parameters:
    
    lookups - the Lookup objects to be added as default lookups
    
    Throws:
    
    IllegalArgumentException - if the collection contains a null entry
  - 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 Lookup 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 (never null).
    
    Parameters:
    
    prefix - the prefix
    
    Returns:
    
    the lookup object to be used for this prefix
  - getDefaultLookups
```
public List<Lookup> getDefaultLookups()
```
    Returns a collection with the default Lookup objects added to this ConfigurationInterpolator. These objects are not associated with a variable prefix. The returned list is a snapshot copy of the internal collection of default lookups; so manipulating it does not affect this instance.
    
    Returns:
    
    the default lookup objects
  - getLookups
```
public Map<String,Lookup> getLookups()
```
    Returns a map with the currently registered Lookup objects and their prefixes. This is a snapshot copy of the internally used map. So modifications of this map do not effect this instance.
    
    Returns:
    
    a copy of the map with the currently registered Lookup objects
  - getParentInterpolator
```
public ConfigurationInterpolator getParentInterpolator()
```
    Returns the parent ConfigurationInterpolator.
    
    Returns:
    
    the parent ConfigurationInterpolator (can be null)
  - interpolate
```
public Object interpolate(Object value)
```
    Performs interpolation of the passed in value. If the value is of type String, this method checks whether it contains variables. If so, all variables are replaced by their current values (if possible). For non string arguments, the value is returned without changes.
    
    Parameters:
    
    value - the value to be interpolated
    
    Returns:
    
    the interpolated value
  - isEnableSubstitutionInVariables
```
public boolean isEnableSubstitutionInVariables()
```
    Sets a flag that variable names can contain other variables. If enabled, variable substitution is also done in variable names.
    
    Returns:
    
    the substitution in variables flag
  - prefixSet
```
public Set<String> prefixSet()
```
    Returns an unmodifiable 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
  - registerLookup
```
public void registerLookup(String prefix,
                           Lookup 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)
    
    Throws:
    
    IllegalArgumentException - if either the prefix or the Lookup object is null
  - registerLookups
```
public void registerLookups(Map<String,? extends Lookup> lookups)
```
    Registers all Lookup objects in the given map with their prefixes at this ConfigurationInterpolator. Using this method multiple Lookup objects can be registered at once. If the passed in map is null, this method does not have any effect.
    
    Parameters:
    
    lookups - the map with lookups to register (may be null)
    
    Throws:
    
    IllegalArgumentException - if the map contains entries
  - removeDefaultLookup
```
public boolean removeDefaultLookup(Lookup lookup)
```
    Removes the specified Lookup object from the list of default Lookups.
    
    Parameters:
    
    lookup - the Lookup object to be removed
    
    Returns:
    
    a flag whether this Lookup object actually existed and was removed
  - resolve
```
public Object resolve(String var)
```
    Resolves the specified variable. This implementation tries 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 or if the associated lookup object cannot resolve this variable, the default lookup objects are used. If this is not successful either and a parent ConfigurationInterpolator is available, this object is asked to resolve the variable.
    
    Parameters:
    
    var - the name of the variable whose value is to be looked up which may contain a prefix.
    
    Returns:
    
    the value of this variable or null if it cannot be resolved
  - setEnableSubstitutionInVariables
```
public void setEnableSubstitutionInVariables(boolean f)
```
    Sets the flag whether variable names can contain other variables. This flag corresponds to the enableSubstitutionInVariables property of the underlying StringSubstitutor object.
    
    Parameters:
    
    f - the new value of the flag
  - setParentInterpolator
```
public void setParentInterpolator(ConfigurationInterpolator parentInterpolator)
```
    Sets the parent ConfigurationInterpolator. This object is used if the Lookup objects registered at this object cannot resolve a variable.
    
    Parameters:
    
    parentInterpolator - the parent ConfigurationInterpolator object (can be null)

Class ConfigurationInterpolator

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ConfigurationInterpolator

Method Detail

fromSpecification

getDefaultPrefixLookups

nullSafeLookup

addDefaultLookup

addDefaultLookups

deregisterLookup

fetchLookupForPrefix

getDefaultLookups

getLookups

getParentInterpolator

interpolate

isEnableSubstitutionInVariables

prefixSet

registerLookup

registerLookups

removeDefaultLookup

resolve

setEnableSubstitutionInVariables

setParentInterpolator