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
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.
String Conversion
When variables are part of larger interpolated strings, the variable values, which can be of any type, must be
converted to strings to produce the full result. Each interpolator instance has a configurable
string converter
to perform this conversion. The default implementation of this
function simply uses the value's toString
method in the majority of cases. However, for maximum
consistency with
DefaultConversionHandler
, when a variable
value is a container type (such as a collection or array), then only the first element of the container is converted
to a string instead of the container itself. For example, if the variable x
resolves to the integer array
[1, 2, 3]
, then the string "my value = ${x}"
will by default be interpolated to
"my value = 1"
.
Implementation note: This class is thread-safe. Lookup objects can be added or removed at any time concurrent to interpolation operations.
- Since:
- 1.4
-
Field Summary
Modifier and TypeFieldDescriptionstatic final String
Name of the system property used to determine the lookups added by thegetDefaultPrefixLookups()
method. -
Constructor Summary
ConstructorDescriptionCreates a new instance ofConfigurationInterpolator
. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addDefaultLookup
(Lookup defaultLookup) Adds a defaultLookup
object.void
addDefaultLookups
(Collection<? extends Lookup> lookups) Adds allLookup
objects in the given collection as default lookups.boolean
deregisterLookup
(String prefix) Deregisters theLookup
object for the specified prefix at this instance.protected Lookup
fetchLookupForPrefix
(String prefix) Obtains the lookup object for the specified prefix.static ConfigurationInterpolator
Creates a newConfigurationInterpolator
instance based on the passed in specification object.Gets a collection with the defaultLookup
objects added to thisConfigurationInterpolator
.Gets a map containing the default prefix lookups.Gets a map with the currently registeredLookup
objects and their prefixes.Gets the parentConfigurationInterpolator
.Gets the function used to convert interpolated values to strings.interpolate
(Object value) Performs interpolation of the passed in value.boolean
Sets a flag that variable names can contain other variables.static Lookup
nullSafeLookup
(Lookup lookup) Utility method for obtaining aLookup
object in a safe way.Returns an unmodifiable set with the prefixes, for whichLookup
objects are registered at this instance.void
registerLookup
(String prefix, Lookup lookup) Registers the givenLookup
object for the specified prefix at this instance.void
registerLookups
(Map<String, ? extends Lookup> lookups) Registers allLookup
objects in the given map with their prefixes at thisConfigurationInterpolator
.boolean
removeDefaultLookup
(Lookup lookup) Removes the specifiedLookup
object from the list of defaultLookup
s.Resolves the specified variable.void
setEnableSubstitutionInVariables
(boolean f) Sets the flag whether variable names can contain other variables.void
setParentInterpolator
(ConfigurationInterpolator parentInterpolator) Sets the parentConfigurationInterpolator
.void
setStringConverter
(Function<Object, String> stringConverter) Sets the function used to convert interpolated values to strings.
-
Field Details
-
DEFAULT_PREFIX_LOOKUPS_PROPERTY
Name of the system property used to determine the lookups added by thegetDefaultPrefixLookups()
method. Use of this property is only required in cases where the set of default lookups must be modified.- Since:
- 2.8.0
- See Also:
-
-
Constructor Details
-
ConfigurationInterpolator
public ConfigurationInterpolator()Creates a new instance ofConfigurationInterpolator
.
-
-
Method Details
-
fromSpecification
Creates a newConfigurationInterpolator
instance based on the passed in specification object. If theInterpolatorSpecification
already contains aConfigurationInterpolator
object, it is used directly. Otherwise, a new instance is created and initialized with the properties stored in the specification.- Parameters:
spec
- theInterpolatorSpecification
(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
Gets a map containing the default prefix lookups. Every configuration object derived fromAbstractConfiguration
is by default initialized with aConfigurationInterpolator
containing theseLookup
objects and their prefixes. The map cannot be modified.All of the lookups present in the returned map are from
DefaultLookups
. However, not all of the available lookups are included by default. Specifically, lookups that can execute code (e.g.,SCRIPT
) and those that can result in contact with remote servers (e.g.,URL
andDNS
) are not included. If this behavior must be modified, users can define the "org.apache.commons.configuration2.interpol.ConfigurationInterpolator.defaultPrefixLookups" system property with a comma-separated list ofDefaultLookups
enum names to be included in the set of defaults. For example, setting this system property to"BASE64_ENCODER,ENVIRONMENT"
will only include theBASE64_ENCODER
andENVIRONMENT
lookups. Setting the property to the empty string will cause no defaults to be configured.Default Lookups Prefix Lookup "base64Decoder" BASE64_DECODER
"base64Encoder" BASE64_ENCODER
"const" CONST
"date" DATE
"env" ENVIRONMENT
"file" FILE
"java" JAVA
"localhost" LOCAL_HOST
"properties" PROPERTIES
"resourceBundle" RESOURCE_BUNDLE
"sys" SYSTEM_PROPERTIES
"urlDecoder" URL_DECODER
"urlEncoder" URL_ENCODER
"xml" XML
Additional Lookups (not included by default) Prefix Lookup "dns" DNS
"url" URL
"script" SCRIPT
- Returns:
- a map with the default prefix
Lookup
objects and their prefixes - Since:
- 2.0
-
nullSafeLookup
Utility method for obtaining aLookup
object in a safe way. This method always returns a non-nullLookup
object. If the passed inLookup
is not null, it is directly returned. Otherwise, result is a dummyLookup
which does not provide any values.- Parameters:
lookup
- theLookup
to check- Returns:
- a non-null
Lookup
object - Since:
- 2.0
-
addDefaultLookup
Adds a defaultLookup
object. DefaultLookup
objects are queried (in the order they were added) for all variables without a special prefix. If no defaultLookup
objects are present, such variables won't be processed.- Parameters:
defaultLookup
- the defaultLookup
object to be added (must not be null)- Throws:
IllegalArgumentException
- if theLookup
object is null
-
addDefaultLookups
Adds allLookup
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
- theLookup
objects to be added as default lookups- Throws:
IllegalArgumentException
- if the collection contains a null entry
-
deregisterLookup
Deregisters theLookup
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
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
-
getDefaultLookups
Gets a collection with the defaultLookup
objects added to thisConfigurationInterpolator
. 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
Gets a map with the currently registeredLookup
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
Gets the parentConfigurationInterpolator
.- Returns:
- the parent
ConfigurationInterpolator
(can be null)
-
getStringConverter
Gets the function used to convert interpolated values to strings.- Returns:
- function used to convert interpolated values to strings
-
interpolate
Performs interpolation of the passed in value. If the value is of typeString
, 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. In the special case where the value is a string consisting of a single variable reference, the interpolated variable value is not converted to a string before returning, so that callers can access the raw value. However, if the variable is part of a larger interpolated string, then the variable value is converted to a string using the configuredstring converter
. (See the discussion on string conversion in the class documentation for more details.)Examples
For the following examples, assume that the default string conversion function is in place and that the variable
i
maps to the integer value42
.interpolator.interpolate(1) → 1 // non-string argument returned unchanged interpolator.interpolate("${i}") → 42 // single variable value returned with raw type interpolator.interpolate("answer = ${i}") → "answer = 42" // variable value converted to string
- Parameters:
value
- the value to be interpolated- Returns:
- the interpolated value
-
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
Returns an unmodifiable set with the prefixes, for whichLookup
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
Registers the givenLookup
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
- theLookup
object to be used for this prefix (must not be null)- Throws:
IllegalArgumentException
- if either the prefix or theLookup
object is null
-
registerLookups
Registers allLookup
objects in the given map with their prefixes at thisConfigurationInterpolator
. Using this method multipleLookup
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
Removes the specifiedLookup
object from the list of defaultLookup
s.- Parameters:
lookup
- theLookup
object to be removed- Returns:
- a flag whether this
Lookup
object actually existed and was removed
-
resolve
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 parentConfigurationInterpolator
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
Sets the flag whether variable names can contain other variables. This flag corresponds to theenableSubstitutionInVariables
property of the underlyingStringSubstitutor
object.- Parameters:
f
- the new value of the flag
-
setParentInterpolator
Sets the parentConfigurationInterpolator
. This object is used if theLookup
objects registered at this object cannot resolve a variable.- Parameters:
parentInterpolator
- the parentConfigurationInterpolator
object (can be null)
-
setStringConverter
Sets the function used to convert interpolated values to strings. Passnull
to use the default conversion function.- Parameters:
stringConverter
- function used to convert interpolated values to strings ornull
to use the default conversion function
-