Package org.forgerock.config.resolvers

Class SubstitutionService

java.lang.Object
org.forgerock.config.resolvers.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 Details

    • SubstitutionService

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

  • Method Details

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