Package org.apache.commons.configuration2.interpol

## Class ConfigurationInterpolator

- 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.

  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

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static String` | `DEFAULT_PREFIX_LOOKUPS_PROPERTY` | Name of the system property used to determine the lookups added by the `getDefaultPrefixLookups()` method.

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | 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()` | Gets a collection with the default `Lookup` objects added to this `ConfigurationInterpolator`.
    `static Map<String,​Lookup>` | `getDefaultPrefixLookups()` | Gets a map containing the default prefix lookups.
    `Map<String,​Lookup>` | `getLookups()` | Gets a map with the currently registered `Lookup` objects and their prefixes.
    `ConfigurationInterpolator` | `getParentInterpolator()` | Gets 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.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_PREFIX_LOOKUPS_PROPERTY

          public static final String DEFAULT_PREFIX_LOOKUPS_PROPERTY

      Name of the system property used to determine the lookups added by the `getDefaultPrefixLookups()` 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:
        Constant Field Values

  - ### 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()

      Gets 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.

      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.

      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

          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()

      Gets 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()

      Gets 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()

      Gets 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. 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

      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

    - #### getStringConverter

          public Function<Object,​String> getStringConverter()

      Get the function used to convert interpolated values to strings.
      Returns:
        function used to convert interpolated values to strings

    - #### setStringConverter

          public void setStringConverter​(Function<Object,​String> stringConverter)

      Set the function used to convert interpolated values to strings. Pass `null` to use the default conversion function.
      Parameters:
        `stringConverter` - function used to convert interpolated values to strings or `null` to use the default conversion function

    - #### 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 `Lookup`s.
      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)