Class ConfigurationInterpolator
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
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 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 a default lookup object, which
will be used for variables that do not have a prefix or that cannot be
resolved by their associated lookup object.
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 1295276 2012-02-29 21:11:35Z oheger $
- Author:
- Commons Configuration team
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
Constant for the prefix of the standard lookup object for resolving constant values.static final String
Constant for the prefix of the standard lookup object for resolving environment properties.static final String
Constant for the prefix of the standard lookup object for resolving system properties. -
Constructor Summary
ConstructorsConstructorDescriptionCreates a new instance ofConfigurationInterpolator
. -
Method Summary
Modifier and TypeMethodDescriptionstatic boolean
deregisterGlobalLookup
(String prefix) Deregisters the global lookup object for the specified prefix.boolean
deregisterLookup
(String prefix) Deregisters the lookup object for the specified prefix at this instance.protected org.apache.commons.lang.text.StrLookup
fetchLookupForPrefix
(String prefix) Obtains the lookup object for the specified prefix.protected org.apache.commons.lang.text.StrLookup
Returns the lookup object to be used for variables without a prefix.org.apache.commons.lang.text.StrLookup
Returns the default lookup object.Requests the parent interpolator.Resolves the specified variable.Returns a set with the prefixes, for which lookup objects are registered at this instance.static void
registerGlobalLookup
(String prefix, org.apache.commons.lang.text.StrLookup lookup) Registers the given lookup object for the specified prefix globally.void
registerLocalLookups
(ConfigurationInterpolator interpolator) Registers the local lookup instances for the given interpolator.void
registerLookup
(String prefix, org.apache.commons.lang.text.StrLookup lookup) Registers the given lookup object for the specified prefix at this instance.void
setDefaultLookup
(org.apache.commons.lang.text.StrLookup defaultLookup) Sets the default lookup object.void
setParentInterpolator
(ConfigurationInterpolator parentInterpolator) Sets the parent interpolator.Methods inherited from class org.apache.commons.lang.text.StrLookup
mapLookup, noneLookup, systemPropertiesLookup
-
Field Details
-
PREFIX_SYSPROPERTIES
Constant for the prefix of the standard lookup object for resolving system properties.- See Also:
-
PREFIX_CONSTANTS
Constant for the prefix of the standard lookup object for resolving constant values.- See Also:
-
PREFIX_ENVIRONMENT
Constant for the prefix of the standard lookup object for resolving environment properties.- Since:
- 1.7
- See Also:
-
-
Constructor Details
-
ConfigurationInterpolator
public ConfigurationInterpolator()Creates a new instance ofConfigurationInterpolator
.
-
-
Method Details
-
registerGlobalLookup
public static void registerGlobalLookup(String prefix, org.apache.commons.lang.text.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)
-
deregisterGlobalLookup
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
-
registerLookup
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)
-
deregisterLookup
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
-
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
-
getDefaultLookup
Returns the default lookup object.- Returns:
- the default lookup object
-
setDefaultLookup
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
-
lookup
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 or if the associated lookup object cannot resolve this variable, the default lookup object will be used.- Specified by:
lookup
in classorg.apache.commons.lang.text.StrLookup
- 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
-
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 (never null).- Returns:
- the lookup object to be used for variables without a prefix
-
fetchLookupForPrefix
Obtains the lookup object for the specified prefix. This method is called by thelookup()
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
-
registerLocalLookups
Registers the local lookup instances for the given interpolator.- Parameters:
interpolator
- the instance receiving the local lookups- Since:
- upcoming
-
setParentInterpolator
Sets the parent interpolator. This object is used if the interpolation is nested hierarchically and the current interpolation object cannot resolve a variable.- Parameters:
parentInterpolator
- the parent interpolator object or null- Since:
- upcoming
-
getParentInterpolator
Requests the parent interpolator. This object is used if the interpolation is nested hierarchically and the current interpolation- Returns:
- the parent interpolator or null
- Since:
- upcoming
-