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 Summary

Constructors

Constructor and Description
SubstitutionService(PropertyResolver resolver) Creates a new substitution service that will resolve variables using the given resolver.

Method Summary

Modifier and Type	Method and Description
String	substitute(String source) Perform variable substitution on the source String.
String	substitute(String source, boolean escape) Perform variable substitution on the source String.
String	substitute(String source, SubstitutionContext context) Perform variable substitution on the source String.

Methods inherited from class java.lang.Object

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

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.escaping set to true), the substitution service will honor '\' (backslash) characters, treating them as a protection for the next character. 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.

When escaping mode is disabled (SubstitutionContext.escaping 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)