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.
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.
Modifier and Type | Field and Description |
---|---|
static String |
DEFAULT_PREFIX_LOOKUPS_PROPERTY
Name of the system property used to determine the lookups added by the
getDefaultPrefixLookups() method. |
Constructor and Description |
---|
ConfigurationInterpolator()
Creates a new instance of
ConfigurationInterpolator . |
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 . |
Function<Object,String> |
getStringConverter()
Get the function used to convert interpolated values to strings.
|
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 . |
void |
setStringConverter(Function<Object,String> stringConverter)
Set the function used to convert interpolated values to strings.
|
public static final String DEFAULT_PREFIX_LOOKUPS_PROPERTY
getDefaultPrefixLookups()
method. Use of this property is only required
in cases where the set of default lookups must be modified.public ConfigurationInterpolator()
ConfigurationInterpolator
.public static ConfigurationInterpolator fromSpecification(InterpolatorSpecification spec)
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.spec
- the InterpolatorSpecification
(must not be null)ConfigurationInterpolator
obtained or created based on the given specificationIllegalArgumentException
- if the specification is nullpublic static Map<String,Lookup> getDefaultPrefixLookups()
AbstractConfiguration
is by default initialized with a ConfigurationInterpolator
containing
these Lookup
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
and DNS
) 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 of DefaultLookups
enum names to be included in the set of defaults.
For example, setting this system property to "BASE64_ENCODER,ENVIRONMENT"
will only include the
BASE64_ENCODER
and
ENVIRONMENT
lookups. Setting the property to the empty string will
cause no defaults to be configured.
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 |
Prefix | Lookup |
---|---|
"dns" | DNS |
"url" | URL |
"script" | SCRIPT |
Lookup
objects and their prefixespublic static Lookup nullSafeLookup(Lookup lookup)
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.lookup
- the Lookup
to checkLookup
objectpublic void addDefaultLookup(Lookup defaultLookup)
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.defaultLookup
- the default Lookup
object to be added (must not be null)IllegalArgumentException
- if the Lookup
object is nullpublic void addDefaultLookups(Collection<? extends Lookup> lookups)
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.lookups
- the Lookup
objects to be added as default lookupsIllegalArgumentException
- if the collection contains a null entrypublic boolean deregisterLookup(String prefix)
Lookup
object for the specified prefix at this instance. It will be removed from this
instance.prefix
- the variable prefixprotected Lookup fetchLookupForPrefix(String prefix)
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).prefix
- the prefixpublic List<Lookup> getDefaultLookups()
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.public Map<String,Lookup> getLookups()
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.Lookup
objectspublic ConfigurationInterpolator getParentInterpolator()
ConfigurationInterpolator
.ConfigurationInterpolator
(can be null)public Object interpolate(Object value)
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. 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 configured
string 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 value 42
.
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
value
- the value to be interpolatedpublic boolean isEnableSubstitutionInVariables()
public Function<Object,String> getStringConverter()
public void setStringConverter(Function<Object,String> stringConverter)
null
to use the default conversion function.stringConverter
- function used to convert interpolated values to strings
or null
to use the default conversion functionpublic Set<String> prefixSet()
Lookup
objects are registered at this instance. This
means that variables with these prefixes can be processed.public void registerLookup(String prefix, Lookup lookup)
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.prefix
- the variable prefix (must not be null)lookup
- the Lookup
object to be used for this prefix (must not be null)IllegalArgumentException
- if either the prefix or the Lookup
object is nullpublic void registerLookups(Map<String,? extends Lookup> lookups)
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.lookups
- the map with lookups to register (may be null)IllegalArgumentException
- if the map contains entriespublic boolean removeDefaultLookup(Lookup lookup)
Lookup
object from the list of default Lookup
s.lookup
- the Lookup
object to be removedLookup
object actually existed and was removedpublic Object resolve(String var)
ConfigurationInterpolator
is available, this object is asked to resolve the variable.var
- the name of the variable whose value is to be looked up which may contain a prefix.public void setEnableSubstitutionInVariables(boolean f)
enableSubstitutionInVariables
property of the underlying StringSubstitutor
object.f
- the new value of the flagpublic void setParentInterpolator(ConfigurationInterpolator parentInterpolator)
ConfigurationInterpolator
. This object is used if the Lookup
objects registered at
this object cannot resolve a variable.parentInterpolator
- the parent ConfigurationInterpolator
object (can be null)Copyright © 2001–2022 The Apache Software Foundation. All rights reserved.