StrSubstitutor (Apache Log4j Core 2.20.0 API)

java.lang.Object
- org.apache.logging.log4j.core.lookup.StrSubstitutor

All Implemented Interfaces:

ConfigurationAware

Direct Known Subclasses:

ConfigurationStrSubstitutor, RuntimeStrSubstitutor
```
public class StrSubstitutor
extends Object
implements ConfigurationAware
```
Substitutes variables within a string by values.
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:
```
 StrSubstitutor.replaceSystemProperties(
      "You are running with java.version = ${java.version} and os.name = ${os.name}.");
 
```
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:
```
 Map valuesMap = new HashMap<>();
 valuesMap.put("animal", "quick brown fox");
 valuesMap.put("target", "lazy dog");
 String templateString = "The ${animal} jumped over the ${target}.";
 StrSubstitutor sub = new StrSubstitutor(valuesMap);
 String resolvedString = sub.replace(templateString);
 
```
yielding:
```
      The quick brown fox jumped over the lazy dog.
 
```
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:
```
 Map valuesMap = new HashMap<>();
 valuesMap.put("animal", "quick brown fox");
 valuesMap.put("target", "lazy dog");
 String templateString = "The ${animal} jumped over the ${target}. ${undefined.number:-1234567890}.";
 StrSubstitutor sub = new StrSubstitutor(valuesMap);
 String resolvedString = sub.replace(templateString);
 
```
yielding:
```
      The quick brown fox jumped over the lazy dog. 1234567890.
 
```
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.

Field Summary

Fields
Modifier and Type	Field and Description
`static char`	`DEFAULT_ESCAPE` Constant for the default escape character.
`static StrMatcher`	`DEFAULT_PREFIX` Constant for the default variable prefix.
`static StrMatcher`	`DEFAULT_SUFFIX` Constant for the default variable suffix.
`static StrMatcher`	`DEFAULT_VALUE_DELIMITER`
`static String`	`DEFAULT_VALUE_DELIMITER_STRING` Constant for the default value delimiter of a variable.
`static StrMatcher`	`DEFAULT_VALUE_ESCAPE_DELIMITER`
`static String`	`ESCAPE_DELIMITER_STRING`

Constructor Summary

Constructors
Constructor and Description
`StrSubstitutor()` Creates a new instance with defaults for variable prefix and suffix and the escaping character.
`StrSubstitutor(Map<String,String> valueMap)` Creates a new instance and initializes it.
`StrSubstitutor(Map<String,String> valueMap, String prefix, String suffix)` Creates a new instance and initializes it.
`StrSubstitutor(Map<String,String> valueMap, String prefix, String suffix, char escape)` Creates a new instance and initializes it.
`StrSubstitutor(Map<String,String> valueMap, String prefix, String suffix, char escape, String valueDelimiter)` Creates a new instance and initializes it.
`StrSubstitutor(Properties properties)` Creates a new instance and initializes it.
`StrSubstitutor(StrLookup variableResolver)` Creates a new instance and initializes it.
`StrSubstitutor(StrLookup variableResolver, String prefix, String suffix, char escape)` Creates a new instance and initializes it.
`StrSubstitutor(StrLookup variableResolver, String prefix, String suffix, char escape, String valueDelimiter)` Creates a new instance and initializes it.
`StrSubstitutor(StrLookup variableResolver, StrMatcher prefixMatcher, StrMatcher suffixMatcher, char escape)` Creates a new instance and initializes it.
`StrSubstitutor(StrLookup variableResolver, StrMatcher prefixMatcher, StrMatcher suffixMatcher, char escape, StrMatcher valueDelimiterMatcher)` Creates a new instance and initializes it.
`StrSubstitutor(StrLookup variableResolver, StrMatcher prefixMatcher, StrMatcher suffixMatcher, char escape, StrMatcher valueDelimiterMatcher, StrMatcher valueEscapeMatcher)` Creates a new instance and initializes it.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`appendWithSeparators(StringBuilder sb, Iterable<?> iterable, String separator)` Appends a iterable placing separators between each value, but not before the first or after the last.
`char`	`getEscapeChar()` Returns the escape character.
`StrMatcher`	`getValueDelimiterMatcher()` Gets the variable default value delimiter matcher currently in use.
`StrMatcher`	`getVariablePrefixMatcher()` Gets the variable prefix matcher currently in use.
`StrLookup`	`getVariableResolver()` Gets the VariableResolver that is used to lookup variables.
`StrMatcher`	`getVariableSuffixMatcher()` Gets the variable suffix matcher currently in use.
`boolean`	`isEnableSubstitutionInVariables()` Returns a flag whether substitution is done in variable names.
`String`	`replace(char[] source)` Replaces all the occurrences of variables with their matching values from the resolver using the given source array as a template.
`String`	`replace(char[] source, int offset, int length)` Replaces all the occurrences of variables with their matching values from the resolver using the given source array as a template.
`String`	`replace(LogEvent event, char[] source)` Replaces all the occurrences of variables with their matching values from the resolver using the given source array as a template.
`String`	`replace(LogEvent event, char[] source, int offset, int length)` Replaces all the occurrences of variables with their matching values from the resolver using the given source array as a template.
`String`	`replace(LogEvent event, Object source)` Replaces all the occurrences of variables in the given source object with their matching values from the resolver.
`String`	`replace(LogEvent event, String source)` Replaces all the occurrences of variables with their matching values from the resolver using the given source string as a template.
`String`	`replace(LogEvent event, StringBuffer source)` Replaces all the occurrences of variables with their matching values from the resolver using the given source buffer as a template.
`String`	`replace(LogEvent event, StringBuffer source, int offset, int length)` Replaces all the occurrences of variables with their matching values from the resolver using the given source buffer as a template.
`String`	`replace(LogEvent event, StringBuilder source)` Replaces all the occurrences of variables with their matching values from the resolver using the given source builder as a template.
`String`	`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.
`String`	`replace(LogEvent event, String source, int offset, int length)` Replaces all the occurrences of variables with their matching values from the resolver using the given source string as a template.
`String`	`replace(Object source)` Replaces all the occurrences of variables in the given source object with their matching values from the resolver.
`static String`	`replace(Object source, Map<String,String> valueMap)` Replaces all the occurrences of variables in the given source object with their matching values from the map.
`static String`	`replace(Object source, Map<String,String> valueMap, String prefix, String suffix)` Replaces all the occurrences of variables in the given source object with their matching values from the map.
`static String`	`replace(Object source, Properties valueProperties)` Replaces all the occurrences of variables in the given source object with their matching values from the properties.
`String`	`replace(String source)` Replaces all the occurrences of variables with their matching values from the resolver using the given source string as a template.
`String`	`replace(StringBuffer source)` Replaces all the occurrences of variables with their matching values from the resolver using the given source buffer as a template.
`String`	`replace(StringBuffer source, int offset, int length)` Replaces all the occurrences of variables with their matching values from the resolver using the given source buffer as a template.
`String`	`replace(StringBuilder source)` Replaces all the occurrences of variables with their matching values from the resolver using the given source builder as a template.
`String`	`replace(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.
`String`	`replace(String source, int offset, int length)` Replaces all the occurrences of variables with their matching values from the resolver using the given source string as a template.
`boolean`	`replaceIn(LogEvent event, StringBuffer source, int offset, int length)` Replaces all the occurrences of variables within the given source buffer with their matching values from the resolver.
`boolean`	`replaceIn(LogEvent event, StringBuilder source)` Replaces all the occurrences of variables within the given source builder with their matching values from the resolver.
`boolean`	`replaceIn(LogEvent event, StringBuilder source, int offset, int length)` Replaces all the occurrences of variables within the given source builder with their matching values from the resolver.
`boolean`	`replaceIn(StringBuffer source)` Replaces all the occurrences of variables within the given source buffer with their matching values from the resolver.
`boolean`	`replaceIn(StringBuffer source, int offset, int length)` Replaces all the occurrences of variables within the given source buffer with their matching values from the resolver.
`boolean`	`replaceIn(StringBuilder source)` Replaces all the occurrences of variables within the given source builder with their matching values from the resolver.
`boolean`	`replaceIn(StringBuilder source, int offset, int length)` Replaces all the occurrences of variables within the given source builder with their matching values from the resolver.
`protected LookupResult`	`resolveVariable(LogEvent event, String variableName, StringBuilder buf, int startPos, int endPos)` Internal method that resolves the value of a variable.
`void`	`setConfiguration(Configuration configuration)` Injects the current Configuration into this object.
`void`	`setEnableSubstitutionInVariables(boolean enableSubstitutionInVariables)` Sets a flag whether substitution is done in variable names.
`void`	`setEscapeChar(char escapeCharacter)` Sets the escape character.
`StrSubstitutor`	`setValueDelimiter(char valueDelimiter)` Sets the variable default value delimiter to use.
`StrSubstitutor`	`setValueDelimiter(String valueDelimiter)` Sets the variable default value delimiter to use.
`StrSubstitutor`	`setValueDelimiterMatcher(StrMatcher valueDelimiterMatcher)` Sets the variable default value delimiter matcher to use.
`StrSubstitutor`	`setVariablePrefix(char prefix)` Sets the variable prefix to use.
`StrSubstitutor`	`setVariablePrefix(String prefix)` Sets the variable prefix to use.
`StrSubstitutor`	`setVariablePrefixMatcher(StrMatcher prefixMatcher)` Sets the variable prefix matcher currently in use.
`void`	`setVariableResolver(StrLookup variableResolver)` Sets the VariableResolver that is used to lookup variables.
`StrSubstitutor`	`setVariableSuffix(char suffix)` Sets the variable suffix to use.
`StrSubstitutor`	`setVariableSuffix(String suffix)` Sets the variable suffix to use.
`StrSubstitutor`	`setVariableSuffixMatcher(StrMatcher suffixMatcher)` Sets the variable suffix matcher currently in use.
`protected boolean`	`substitute(LogEvent event, StringBuilder buf, int offset, int length)` Internal method that substitutes the variables.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - DEFAULT_ESCAPE
```
public static final char DEFAULT_ESCAPE
```
    Constant for the default escape character.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_PREFIX
```
public static final StrMatcher DEFAULT_PREFIX
```
    Constant for the default variable prefix.
  - DEFAULT_SUFFIX
```
public static final StrMatcher DEFAULT_SUFFIX
```
    Constant for the default variable suffix.
  - DEFAULT_VALUE_DELIMITER_STRING
```
public static final String DEFAULT_VALUE_DELIMITER_STRING
```
    Constant for the default value delimiter of a variable.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_VALUE_DELIMITER
```
public static final StrMatcher DEFAULT_VALUE_DELIMITER
```
  - ESCAPE_DELIMITER_STRING
```
public static final String ESCAPE_DELIMITER_STRING
```
    See Also:
    
    Constant Field Values
  - DEFAULT_VALUE_ESCAPE_DELIMITER
```
public static final StrMatcher DEFAULT_VALUE_ESCAPE_DELIMITER
```
- Constructor Detail
  - StrSubstitutor
```
public StrSubstitutor()
```
    Creates a new instance with defaults for variable prefix and suffix and the escaping character.
  - StrSubstitutor
```
public StrSubstitutor(Map<String,String> valueMap)
```
    Creates a new instance and initializes it. Uses defaults for variable prefix and suffix and the escaping character.
    
    Parameters:
    
    valueMap - the map with the variables' values, may be null
  - StrSubstitutor
```
public StrSubstitutor(Map<String,String> valueMap,
                      String prefix,
                      String suffix)
```
    Creates a new instance and initializes it. Uses a default escaping character.
    
    Parameters:
    
    valueMap - the map with the variables' values, may be null
    
    prefix - the prefix for variables, not null
    
    suffix - the suffix for variables, not null
    
    Throws:
    
    IllegalArgumentException - if the prefix or suffix is null
  - StrSubstitutor
```
public StrSubstitutor(Map<String,String> valueMap,
                      String prefix,
                      String suffix,
                      char escape)
```
    Creates a new instance and initializes it.
    
    Parameters:
    
    valueMap - the map with the variables' values, may be null
    
    prefix - the prefix for variables, not null
    
    suffix - the suffix for variables, not null
    
    escape - the escape character
    
    Throws:
    
    IllegalArgumentException - if the prefix or suffix is null
  - StrSubstitutor
```
public StrSubstitutor(Map<String,String> valueMap,
                      String prefix,
                      String suffix,
                      char escape,
                      String valueDelimiter)
```
    Creates a new instance and initializes it.
    
    Parameters:
    
    valueMap - the map with the variables' values, may be null
    
    prefix - the prefix for variables, not null
    
    suffix - the suffix for variables, not null
    
    escape - the escape character
    
    valueDelimiter - the variable default value delimiter, may be null
    
    Throws:
    
    IllegalArgumentException - if the prefix or suffix is null
  - StrSubstitutor
```
public StrSubstitutor(Properties properties)
```
    Creates a new instance and initializes it. Uses defaults for variable prefix and suffix and the escaping character.
    
    Parameters:
    
    properties - the map with the variables' values, may be null
  - StrSubstitutor
```
public StrSubstitutor(StrLookup variableResolver)
```
    Creates a new instance and initializes it.
    
    Parameters:
    
    variableResolver - the variable resolver, may be null
  - StrSubstitutor
```
public StrSubstitutor(StrLookup variableResolver,
                      String prefix,
                      String suffix,
                      char escape)
```
    Creates a new instance and initializes it.
    
    Parameters:
    
    variableResolver - the variable resolver, may be null
    
    prefix - the prefix for variables, not null
    
    suffix - the suffix for variables, not null
    
    escape - the escape character
    
    Throws:
    
    IllegalArgumentException - if the prefix or suffix is null
  - StrSubstitutor
```
public StrSubstitutor(StrLookup variableResolver,
                      String prefix,
                      String suffix,
                      char escape,
                      String valueDelimiter)
```
    Creates a new instance and initializes it.
    
    Parameters:
    
    variableResolver - the variable resolver, may be null
    
    prefix - the prefix for variables, not null
    
    suffix - the suffix for variables, not null
    
    escape - the escape character
    
    valueDelimiter - the variable default value delimiter string, may be null
    
    Throws:
    
    IllegalArgumentException - if the prefix or suffix is null
  - StrSubstitutor
```
public StrSubstitutor(StrLookup variableResolver,
                      StrMatcher prefixMatcher,
                      StrMatcher suffixMatcher,
                      char escape)
```
    Creates a new instance and initializes it.
    
    Parameters:
    
    variableResolver - the variable resolver, may be null
    
    prefixMatcher - the prefix for variables, not null
    
    suffixMatcher - the suffix for variables, not null
    
    escape - the escape character
    
    Throws:
    
    IllegalArgumentException - if the prefix or suffix is null
  - StrSubstitutor
```
public StrSubstitutor(StrLookup variableResolver,
                      StrMatcher prefixMatcher,
                      StrMatcher suffixMatcher,
                      char escape,
                      StrMatcher valueDelimiterMatcher)
```
    Creates a new instance and initializes it.
    
    Parameters:
    
    variableResolver - the variable resolver, may be null
    
    prefixMatcher - the prefix for variables, not null
    
    suffixMatcher - the suffix for variables, not null
    
    escape - the escape character
    
    valueDelimiterMatcher - the variable default value delimiter matcher, may be null
    
    Throws:
    
    IllegalArgumentException - if the prefix or suffix is null
  - StrSubstitutor
```
public StrSubstitutor(StrLookup variableResolver,
                      StrMatcher prefixMatcher,
                      StrMatcher suffixMatcher,
                      char escape,
                      StrMatcher valueDelimiterMatcher,
                      StrMatcher valueEscapeMatcher)
```
    Creates a new instance and initializes it.
    
    Parameters:
    
    variableResolver - the variable resolver, may be null
    
    prefixMatcher - the prefix for variables, not null
    
    suffixMatcher - the suffix for variables, not null
    
    escape - the escape character
    
    valueDelimiterMatcher - the variable default value delimiter matcher, may be null
    
    valueEscapeMatcher - the matcher to escape defaulting, may be null.
    
    Throws:
    
    IllegalArgumentException - if the prefix or suffix is null
- Method Detail
  - replace
```
public static String replace(Object source,
                             Map<String,String> valueMap)
```
    Replaces all the occurrences of variables in the given source object with their matching values from the map.
    
    Parameters:
    
    source - the source text containing the variables to substitute, null returns null
    
    valueMap - the map with the values, may be null
    
    Returns:
    
    the result of the replace operation
  - replace
```
public static String replace(Object source,
                             Map<String,String> valueMap,
                             String prefix,
                             String suffix)
```
    Replaces all the occurrences of variables in the given source object with their matching values from the map. This method allows to specify a custom variable prefix and suffix
    
    Parameters:
    
    source - the source text containing the variables to substitute, null returns null
    
    valueMap - the map with the values, may be null
    
    prefix - the prefix of variables, not null
    
    suffix - the suffix of variables, not null
    
    Returns:
    
    the result of the replace operation
    
    Throws:
    
    IllegalArgumentException - if the prefix or suffix is null
  - replace
```
public static String replace(Object source,
                             Properties valueProperties)
```
    Replaces all the occurrences of variables in the given source object with their matching values from the properties.
    
    Parameters:
    
    source - the source text containing the variables to substitute, null returns null
    
    valueProperties - the properties with values, may be null
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String replace(String source)
```
    Replaces all the occurrences of variables with their matching values from the resolver using the given source string as a template.
    
    Parameters:
    
    source - the string to replace in, null returns null
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String replace(LogEvent event,
                      String source)
```
    Replaces all the occurrences of variables with their matching values from the resolver using the given source string as a template.
    
    Parameters:
    
    event - The current LogEvent if there is one.
    
    source - the string to replace in, null returns null
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String replace(String source,
                      int offset,
                      int length)
```
    Replaces all the occurrences of variables with their matching values from the resolver using the given source string as a template.
    Only the specified portion of the string will be processed. The rest of the string is not processed, and is not returned.
    
    Parameters:
    
    source - the string to replace in, null returns null
    
    offset - the start offset within the array, must be valid
    
    length - the length within the array to be processed, must be valid
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String replace(LogEvent event,
                      String source,
                      int offset,
                      int length)
```
    Replaces all the occurrences of variables with their matching values from the resolver using the given source string as a template.
    Only the specified portion of the string will be processed. The rest of the string is not processed, and is not returned.
    
    Parameters:
    
    event - the current LogEvent, if one exists.
    
    source - the string to replace in, null returns null
    
    offset - the start offset within the array, must be valid
    
    length - the length within the array to be processed, must be valid
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String replace(char[] source)
```
    Replaces all the occurrences of variables with their matching values from the resolver using the given source array as a template. The array is not altered by this method.
    
    Parameters:
    
    source - the character array to replace in, not altered, null returns null
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String replace(LogEvent event,
                      char[] source)
```
    Replaces all the occurrences of variables with their matching values from the resolver using the given source array as a template. The array is not altered by this method.
    
    Parameters:
    
    event - the current LogEvent, if one exists.
    
    source - the character array to replace in, not altered, null returns null
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String replace(char[] source,
                      int offset,
                      int length)
```
    Replaces all the occurrences of variables with their matching values from the resolver using the given source array as a template. The array is not altered by this method.
    Only the specified portion of the array will be processed. The rest of the array is not processed, and is not returned.
    
    Parameters:
    
    source - the character array to replace in, not altered, null returns null
    
    offset - the start offset within the array, must be valid
    
    length - the length within the array to be processed, must be valid
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String replace(LogEvent event,
                      char[] source,
                      int offset,
                      int length)
```
    Replaces all the occurrences of variables with their matching values from the resolver using the given source array as a template. The array is not altered by this method.
    Only the specified portion of the array will be processed. The rest of the array is not processed, and is not returned.
    
    Parameters:
    
    event - the current LogEvent, if one exists.
    
    source - the character array to replace in, not altered, null returns null
    
    offset - the start offset within the array, must be valid
    
    length - the length within the array to be processed, must be valid
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String replace(StringBuffer source)
```
    Replaces all the occurrences of variables with their matching values from the resolver using the given source buffer as a template. The buffer is not altered by this method.
    
    Parameters:
    
    source - the buffer to use as a template, not changed, null returns null
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String replace(LogEvent event,
                      StringBuffer source)
```
    Replaces all the occurrences of variables with their matching values from the resolver using the given source buffer as a template. The buffer is not altered by this method.
    
    Parameters:
    
    event - the current LogEvent, if one exists.
    
    source - the buffer to use as a template, not changed, null returns null
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String replace(StringBuffer source,
                      int offset,
                      int length)
```
    Replaces all the occurrences of variables with their matching values from the resolver using the given source buffer as a template. The buffer is not altered by this method.
    Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, and is not returned.
    
    Parameters:
    
    source - the buffer to use as a template, not changed, null returns null
    
    offset - the start offset within the array, must be valid
    
    length - the length within the array to be processed, must be valid
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String replace(LogEvent event,
                      StringBuffer source,
                      int offset,
                      int length)
```
    Replaces all the occurrences of variables with their matching values from the resolver using the given source buffer as a template. The buffer is not altered by this method.
    Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, and is not returned.
    
    Parameters:
    
    event - the current LogEvent, if one exists.
    
    source - the buffer to use as a template, not changed, null returns null
    
    offset - the start offset within the array, must be valid
    
    length - the length within the array to be processed, must be valid
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String replace(StringBuilder source)
```
    Replaces all the occurrences of variables with their matching values from the resolver using the given source builder as a template. The builder is not altered by this method.
    
    Parameters:
    
    source - the builder to use as a template, not changed, null returns null
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String replace(LogEvent event,
                      StringBuilder source)
```
    Replaces all the occurrences of variables with their matching values from the resolver using the given source builder as a template. The builder is not altered by this method.
    
    Parameters:
    
    event - The LogEvent.
    
    source - the builder to use as a template, not changed, null returns null.
    
    Returns:
    
    the result of the replace operation.
  - replace
```
public String replace(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. The builder is not altered by this method.
    Only the specified portion of the builder will be processed. The rest of the builder is not processed, and is not returned.
    
    Parameters:
    
    source - the builder to use as a template, not changed, null returns null
    
    offset - the start offset within the array, must be valid
    
    length - the length within the array to be processed, must be valid
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String 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. The builder is not altered by this method.
    Only the specified portion of the builder will be processed. The rest of the builder is not processed, and is not returned.
    
    Parameters:
    
    event - the current LogEvent, if one exists.
    
    source - the builder to use as a template, not changed, null returns null
    
    offset - the start offset within the array, must be valid
    
    length - the length within the array to be processed, must be valid
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String replace(Object source)
```
    Replaces all the occurrences of variables in the given source object with their matching values from the resolver. The input source object is converted to a string using toString and is not altered.
    
    Parameters:
    
    source - the source to replace in, null returns null
    
    Returns:
    
    the result of the replace operation
  - replace
```
public String replace(LogEvent event,
                      Object source)
```
    Replaces all the occurrences of variables in the given source object with their matching values from the resolver. The input source object is converted to a string using toString and is not altered.
    
    Parameters:
    
    event - the current LogEvent, if one exists.
    
    source - the source to replace in, null returns null
    
    Returns:
    
    the result of the replace operation
  - replaceIn
```
public boolean replaceIn(StringBuffer source)
```
    Replaces all the occurrences of variables within the given source buffer with their matching values from the resolver. The buffer is updated with the result.
    
    Parameters:
    
    source - the buffer to replace in, updated, null returns zero
    
    Returns:
    
    true if altered
  - replaceIn
```
public boolean replaceIn(StringBuffer source,
                         int offset,
                         int length)
```
    Replaces all the occurrences of variables within the given source buffer with their matching values from the resolver. The buffer is updated with the result.
    Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, but it is not deleted.
    
    Parameters:
    
    source - the buffer to replace in, updated, null returns zero
    
    offset - the start offset within the array, must be valid
    
    length - the length within the buffer to be processed, must be valid
    
    Returns:
    
    true if altered
  - replaceIn
```
public boolean replaceIn(LogEvent event,
                         StringBuffer source,
                         int offset,
                         int length)
```
    Replaces all the occurrences of variables within the given source buffer with their matching values from the resolver. The buffer is updated with the result.
    Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, but it is not deleted.
    
    Parameters:
    
    event - the current LogEvent, if one exists.
    
    source - the buffer to replace in, updated, null returns zero
    
    offset - the start offset within the array, must be valid
    
    length - the length within the buffer to be processed, must be valid
    
    Returns:
    
    true if altered
  - replaceIn
```
public boolean replaceIn(StringBuilder source)
```
    Replaces all the occurrences of variables within the given source builder with their matching values from the resolver.
    
    Parameters:
    
    source - the builder to replace in, updated, null returns zero
    
    Returns:
    
    true if altered
  - replaceIn
```
public boolean replaceIn(LogEvent event,
                         StringBuilder source)
```
    Replaces all the occurrences of variables within the given source builder with their matching values from the resolver.
    
    Parameters:
    
    event - the current LogEvent, if one exists.
    
    source - the builder to replace in, updated, null returns zero
    
    Returns:
    
    true if altered
  - replaceIn
```
public boolean replaceIn(StringBuilder source,
                         int offset,
                         int length)
```
    Replaces all the occurrences of variables within the given source builder with their matching values from the resolver.
    Only the specified portion of the builder will be processed. The rest of the builder is not processed, but it is not deleted.
    
    Parameters:
    
    source - the builder to replace in, null returns zero
    
    offset - the start offset within the array, must be valid
    
    length - the length within the builder to be processed, must be valid
    
    Returns:
    
    true if altered
  - replaceIn
```
public boolean replaceIn(LogEvent event,
                         StringBuilder source,
                         int offset,
                         int length)
```
    Replaces all the occurrences of variables within the given source builder with their matching values from the resolver.
    Only the specified portion of the builder will be processed. The rest of the builder is not processed, but it is not deleted.
    
    Parameters:
    
    event - the current LogEvent, if one is present.
    
    source - the builder to replace in, null returns zero
    
    offset - the start offset within the array, must be valid
    
    length - the length within the builder to be processed, must be valid
    
    Returns:
    
    true if altered
  - substitute
```
protected boolean substitute(LogEvent event,
                             StringBuilder buf,
                             int offset,
                             int length)
```
    Internal method that substitutes the variables.
    Most users of this class do not need to call this method. This method will be called automatically by another (public) method.
    
    Writers of subclasses can override this method if they need access to the substitution process at the start or end.
    
    Parameters:
    
    event - The current LogEvent, if there is one.
    
    buf - the string builder to substitute into, not null
    
    offset - the start offset within the builder, must be valid
    
    length - the length within the builder to be processed, must be valid
    
    Returns:
    
    true if altered
  - resolveVariable
```
protected LookupResult resolveVariable(LogEvent event,
                                       String variableName,
                                       StringBuilder buf,
                                       int startPos,
                                       int endPos)
```
    Internal method that resolves the value of a variable.
    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
    
    endPos - the end position of the variable including the suffix, valid
    
    Returns:
    
    the variable's value or null if the variable is unknown
  - getEscapeChar
```
public char getEscapeChar()
```
    Returns the escape character.
    
    Returns:
    
    the character used for escaping variable references
  - setEscapeChar
```
public void setEscapeChar(char escapeCharacter)
```
    Sets the escape character. If this character is placed before a variable reference in the source text, this variable will be ignored.
    
    Parameters:
    
    escapeCharacter - the escape character (0 for disabling escaping)
  - getVariablePrefixMatcher
```
public StrMatcher getVariablePrefixMatcher()
```
    Gets the variable prefix matcher currently in use.
    The variable prefix is the character or characters that identify the start of a variable. This prefix is expressed in terms of a matcher allowing advanced prefix matches.
    
    Returns:
    
    the prefix matcher in use
  - setVariablePrefixMatcher
```
public StrSubstitutor setVariablePrefixMatcher(StrMatcher prefixMatcher)
```
    Sets the variable prefix matcher currently in use.
    The variable prefix is the character or characters that identify the start of a variable. This prefix is expressed in terms of a matcher allowing advanced prefix matches.
    
    Parameters:
    
    prefixMatcher - the prefix matcher to use, null ignored
    
    Returns:
    
    this, to enable chaining
    
    Throws:
    
    IllegalArgumentException - if the prefix matcher is null
  - setVariablePrefix
```
public StrSubstitutor setVariablePrefix(char prefix)
```
    Sets the variable prefix to use.
    The variable prefix is the character or characters that identify the start of a variable. This method allows a single character prefix to be easily set.
    
    Parameters:
    
    prefix - the prefix character to use
    
    Returns:
    
    this, to enable chaining
  - setVariablePrefix
```
public StrSubstitutor setVariablePrefix(String prefix)
```
    Sets the variable prefix to use.
    The variable prefix is the character or characters that identify the start of a variable. This method allows a string prefix to be easily set.
    
    Parameters:
    
    prefix - the prefix for variables, not null
    
    Returns:
    
    this, to enable chaining
    
    Throws:
    
    IllegalArgumentException - if the prefix is null
  - getVariableSuffixMatcher
```
public StrMatcher getVariableSuffixMatcher()
```
    Gets the variable suffix matcher currently in use.
    The variable suffix is the character or characters that identify the end of a variable. This suffix is expressed in terms of a matcher allowing advanced suffix matches.
    
    Returns:
    
    the suffix matcher in use
  - setVariableSuffixMatcher
```
public StrSubstitutor setVariableSuffixMatcher(StrMatcher suffixMatcher)
```
    Sets the variable suffix matcher currently in use.
    The variable suffix is the character or characters that identify the end of a variable. This suffix is expressed in terms of a matcher allowing advanced suffix matches.
    
    Parameters:
    
    suffixMatcher - the suffix matcher to use, null ignored
    
    Returns:
    
    this, to enable chaining
    
    Throws:
    
    IllegalArgumentException - if the suffix matcher is null
  - setVariableSuffix
```
public StrSubstitutor setVariableSuffix(char suffix)
```
    Sets the variable suffix to use.
    The variable suffix is the character or characters that identify the end of a variable. This method allows a single character suffix to be easily set.
    
    Parameters:
    
    suffix - the suffix character to use
    
    Returns:
    
    this, to enable chaining
  - setVariableSuffix
```
public StrSubstitutor setVariableSuffix(String suffix)
```
    Sets the variable suffix to use.
    The variable suffix is the character or characters that identify the end of a variable. This method allows a string suffix to be easily set.
    
    Parameters:
    
    suffix - the suffix for variables, not null
    
    Returns:
    
    this, to enable chaining
    
    Throws:
    
    IllegalArgumentException - if the suffix is null
  - getValueDelimiterMatcher
```
public StrMatcher getValueDelimiterMatcher()
```
    Gets the variable default value delimiter matcher currently in use.
    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
```
public StrSubstitutor setValueDelimiterMatcher(StrMatcher valueDelimiterMatcher)
```
    Sets the variable default value delimiter matcher to use.
    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.
    
    Parameters:
    
    valueDelimiterMatcher - variable default value delimiter matcher to use, may be null
    
    Returns:
    
    this, to enable chaining
  - setValueDelimiter
```
public StrSubstitutor setValueDelimiter(char valueDelimiter)
```
    Sets the variable default value delimiter to use.
    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
```
public StrSubstitutor setValueDelimiter(String valueDelimiter)
```
    Sets the variable default value delimiter to use.
    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
    
    Returns:
    
    this, to enable chaining
  - getVariableResolver
```
public StrLookup getVariableResolver()
```
    Gets the VariableResolver that is used to lookup variables.
    
    Returns:
    
    the VariableResolver
  - setVariableResolver
```
public void setVariableResolver(StrLookup variableResolver)
```
    Sets the VariableResolver that is used to lookup variables.
    
    Parameters:
    
    variableResolver - the VariableResolver
  - isEnableSubstitutionInVariables
```
public boolean isEnableSubstitutionInVariables()
```
    Returns a flag whether substitution is done in variable names.
    
    Returns:
    
    the substitution in variable names flag
  - setEnableSubstitutionInVariables
```
public void setEnableSubstitutionInVariables(boolean enableSubstitutionInVariables)
```
    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 true.
    
    Parameters:
    
    enableSubstitutionInVariables - the new value of the flag
  - appendWithSeparators
```
public void appendWithSeparators(StringBuilder sb,
                                 Iterable<?> iterable,
                                 String separator)
```
    Appends a iterable placing separators between each value, but not before the first or after the last. Appending a null iterable will have no effect..
    
    Parameters:
    
    sb - StringBuilder that contains the String being constructed.
    
    iterable - the iterable to append
    
    separator - the separator to use, null means no separator
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - setConfiguration
```
public void setConfiguration(Configuration configuration)
```
    Description copied from interface: ConfigurationAware
    
    Injects the current Configuration into this object.
    
    Specified by:
    
    setConfiguration in interface ConfigurationAware
    
    Parameters:
    
    configuration - the current Configuration

Copyright © 1999-2023 The Apache Software Foundation. All Rights Reserved.
Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, the Apache Logging project logo, and the Apache Log4j logo are trademarks of The Apache Software Foundation.

Class StrSubstitutor

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_ESCAPE

DEFAULT_PREFIX

DEFAULT_SUFFIX

DEFAULT_VALUE_DELIMITER_STRING

DEFAULT_VALUE_DELIMITER

ESCAPE_DELIMITER_STRING

DEFAULT_VALUE_ESCAPE_DELIMITER

Constructor Detail

StrSubstitutor

StrSubstitutor

StrSubstitutor

StrSubstitutor

StrSubstitutor

StrSubstitutor

StrSubstitutor

StrSubstitutor

StrSubstitutor

StrSubstitutor

StrSubstitutor

StrSubstitutor

Method Detail

replace

replace

replace

replace

replace

replace

replace

replace

replace

replace

replace

replace

replace

replace

replace

replace

replace

replace

replace

replace

replace

replaceIn

replaceIn

replaceIn

replaceIn

replaceIn

replaceIn

replaceIn

substitute

resolveVariable

getEscapeChar

setEscapeChar

getVariablePrefixMatcher

setVariablePrefixMatcher

setVariablePrefix

setVariablePrefix

getVariableSuffixMatcher

setVariableSuffixMatcher

setVariableSuffix

setVariableSuffix

getValueDelimiterMatcher

setValueDelimiterMatcher

setValueDelimiter

setValueDelimiter

getVariableResolver

setVariableResolver

isEnableSubstitutionInVariables

setEnableSubstitutionInVariables

appendWithSeparators

toString

setConfiguration