org.apache.logging.log4j.core.lookup
Class StrSubstitutor

This class takes a piece of text and substitutes all the variables within it.
The default definition of a variable is ${variableName}.
The prefix and suffix can be changed via constructors and set methods.

Variable values are typically resolved from a map, but could also be resolved
from system properties, or by supplying a custom variable resolver.

The simplest example is to use this class to replace Java System properties. For example:

Typical usage of this class follows the following pattern: First an instance is created
and initialized with the map that contains the values for the available variables.
If a prefix and/or suffix for variables should be used other than the default ones,
the appropriate settings can be performed. After that the replace()
method can be called passing in the source text for interpolation. In the returned
text all variable references (as long as their values are known) will be resolved.
The following example demonstrates this:

Also, this class allows to set a default value for unresolved variables.
The default value for a variable can be appended to the variable name after the variable
default value delimiter. The default value of the variable default value delimiter is ':-',
as in bash and other *nix shells, as those are arguably where the default ${} delimiter set originated.
The variable default value delimiter can be manually set by calling setValueDelimiterMatcher(StrMatcher),
setValueDelimiter(char) or setValueDelimiter(String).
The following shows an example with variable default value settings:

In addition to this usage pattern there are some static convenience methods that
cover the most common use cases. These methods can be used without the need of
manually creating an instance. However if multiple replace operations are to be
performed, creating and reusing an instance of this class will be more efficient.

Variable replacement works in a recursive way. Thus, if a variable value contains
a variable then that variable will also be replaced. Cyclic replacements are
detected and will cause an exception to be thrown.

Sometimes the interpolation's result must contain a variable prefix. As an example
take the following source text:

The variable ${${name}} must be used.

Here only the variable's name referred to in the text should be replaced resulting
in the text (assuming that the value of the name variable is x):

The variable ${x} must be used.

To achieve this effect there are two possibilities: Either set a different prefix
and suffix for variables which do not conflict with the result text you want to
produce. The other possibility is to use the escape character, by default '$'.
If this character is placed before a variable reference, this reference is ignored
and won't be replaced. For example:

The variable $${${name}} must be used.

In some complex scenarios you might even want to perform substitution in the
names of variables, for instance

${jre-${java.specification.version}}

StrSubstitutor supports this recursive substitution in variable
names, but it has to be enabled explicitly by setting the
enableSubstitutionInVariables
property to true.

replace(LogEvent event,
StringBuilder source,
int offset,
int length)
Replaces all the occurrences of variables with their matching values
from the resolver using the given source builder as a template.

resolveVariable

Most users of this class do not need to call this method. This method is
called automatically by the substitution process.

Writers of subclasses can override this method if they need to alter
how each substitution occurs. The method is passed the variable's name
and must return the corresponding value. This implementation uses the
getVariableResolver() with the variable's name as the key.

Parameters:

event - The LogEvent, if there is one.

variableName - the name of the variable, not null

buf - the buffer where the substitution is occurring, not null

startPos - the start position of the variable including the prefix, valid

getValueDelimiterMatcher

The variable default value delimiter is the character or characters that delimit the
variable name and the variable default value. This delimiter is expressed in terms of a matcher
allowing advanced variable default value delimiter matches.

If it returns null, then the variable default value resolution is disabled.

Returns:

the variable default value delimiter matcher in use, may be null

setValueDelimiterMatcher

The variable default value delimiter is the character or characters that delimit the
variable name and the variable default value. This delimiter is expressed in terms of a matcher
allowing advanced variable default value delimiter matches.

If the valueDelimiterMatcher is null, then the variable default value resolution
becomes disabled.

setValueDelimiter

The variable default value delimiter is the character or characters that delimit the
variable name and the variable default value. This method allows a single character
variable default value delimiter to be easily set.

Parameters:

valueDelimiter - the variable default value delimiter character to use

Returns:

this, to enable chaining

setValueDelimiter

The variable default value delimiter is the character or characters that delimit the
variable name and the variable default value. This method allows a string
variable default value delimiter to be easily set.

If the valueDelimiter is null or empty string, then the variable default
value resolution becomes disabled.

Parameters:

valueDelimiter - the variable default value delimiter string to use, may be null or empty

setEnableSubstitutionInVariables

Sets a flag whether substitution is done in variable names. If set to
true, the names of variables can contain other variables which are
processed first before the original variable is evaluated, e.g.
${jre-${java.version}}. The default value is false.