Package org.forgerock.config.resolvers

Class SubstitutionService

  • public class SubstitutionService
extends Object
    Substitute tokens in the source String with their resolved value.

    Expected token format: &{key[|default]}.

    The substitution algorithm works with a stack:

    • a new entry is pushed on top when starting a new property
    • when end of property is found, variable is popped out of the stack, resolved and value is appended to the new item on top

    It supports recursion: resolved values are also substituted before being appended to the result.

    Escaping is also supported.

    • Constructor Detail

      • SubstitutionService

        public SubstitutionService​(PropertyResolver resolver)
        Creates a new substitution service that will resolve variables using the given resolver.
        Parameters:
        resolver - resolver to use

    • Method Detail

      • substitute

        public String substitute​(String source)
                  throws SubstitutionException
        Perform variable substitution on the source String.

        Any unresolved variable is returned unmodified.

        Escape the source value.

        Parameters:
        source - value potentially containing tokens
        Returns:
        substituted value
        Throws:
        SubstitutionException - when substitution is interrupted because of an error (unresolved var or cycle)

      • substitute

        public String substitute​(String source,
                         boolean escape)
                  throws SubstitutionException
        Perform variable substitution on the source String.

        Any unresolved variable is returned unmodified.

        Escape the source value if escape is set to true.

        Parameters:
        source - value potentially containing tokens
        escape - Enable/disable escaping mode
        Returns:
        substituted value
        Throws:
        SubstitutionException - when substitution is interrupted because of an error (unresolved var or cycle)

      • substitute

        public String substitute​(String source,
                         SubstitutionContext context)
                  throws SubstitutionException
        Perform variable substitution on the source String.

        Any unresolved variable is returned unmodified.

        When escaping mode is enabled (SubstitutionContext.isEscaping()} set to true), the substitution service will honor '\' (backslash) characters, treating them as a protection for the next character. Protected characters are the '|' (pipe), '&' (ampersand), and } (closing braces). In other words, with escape mode enabled, it's possible to prevent "&{key}" to be substituted by protecting the '&' with a '\', resulting in "\&{key}" to be returned unmodified. Escaping makes it also possible to use the pipe character in a property name, (e.g. &{key\|suffix|default-value}), or have the '}' (closing braces) in a property's default value (e.g. &{key|default\}value}).

        When escaping mode is disabled (SubstitutionContext.isEscaping() set to false), then all '\' characters found in the source string are kept as-is, and no protection of '&' char is possible, meaning that even "\&{key}" will be substituted to "\<value>".

        Escaping examples:

        • "\&{foo}" is not substituted (escaped & char) and returns "&{foo}"
        • "&{foo\}" is not substituted (malformed token because of the escaped '}' char) and returns "&{foo}"
        • "&{fo\|o}" is substituted with value from fo|o (escaped | char) and returns "<resolved-value>" if key can be resolved
        • "Tom \& Jerry" returns "Tom & Jerry"
        Parameters:
        source - value potentially containing tokens
        context - Hold substitution configuration values (escaping, notifications, ...)
        Returns:
        substituted value
        Throws:
        SubstitutionException - when substitution is interrupted because of an error (unresolved var or cycle)