public class StrSubstitutor
extends java.lang.Object
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 = 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.
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.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.
|
Constructor and Description |
---|
StrSubstitutor()
Creates a new instance with defaults for variable prefix and suffix
and the escaping character.
|
StrSubstitutor(java.util.Map valueMap)
Creates a new instance and initializes it.
|
StrSubstitutor(java.util.Map valueMap,
java.lang.String prefix,
java.lang.String suffix)
Creates a new instance and initializes it.
|
StrSubstitutor(java.util.Map valueMap,
java.lang.String prefix,
java.lang.String suffix,
char escape)
Creates a new instance and initializes it.
|
StrSubstitutor(StrLookup variableResolver)
Creates a new instance and initializes it.
|
StrSubstitutor(StrLookup variableResolver,
java.lang.String prefix,
java.lang.String suffix,
char escape)
Creates a new instance and initializes it.
|
StrSubstitutor(StrLookup variableResolver,
StrMatcher prefixMatcher,
StrMatcher suffixMatcher,
char escape)
Creates a new instance and initializes it.
|
Modifier and Type | Method and Description |
---|---|
char |
getEscapeChar()
Returns the escape character.
|
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.
|
java.lang.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.
|
java.lang.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.
|
java.lang.String |
replace(java.lang.Object source)
Replaces all the occurrences of variables in the given source object with
their matching values from the resolver.
|
static java.lang.String |
replace(java.lang.Object source,
java.util.Map valueMap)
Replaces all the occurrences of variables in the given source object with
their matching values from the map.
|
static java.lang.String |
replace(java.lang.Object source,
java.util.Map valueMap,
java.lang.String prefix,
java.lang.String suffix)
Replaces all the occurrences of variables in the given source object with
their matching values from the map.
|
static java.lang.String |
replace(java.lang.Object source,
java.util.Properties valueProperties)
Replaces all the occurrences of variables in the given source object with their matching
values from the properties.
|
java.lang.String |
replace(StrBuilder source)
Replaces all the occurrences of variables with their matching values
from the resolver using the given source builder as a template.
|
java.lang.String |
replace(StrBuilder 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.
|
java.lang.String |
replace(java.lang.String source)
Replaces all the occurrences of variables with their matching values
from the resolver using the given source string as a template.
|
java.lang.String |
replace(java.lang.StringBuffer source)
Replaces all the occurrences of variables with their matching values
from the resolver using the given source buffer as a template.
|
java.lang.String |
replace(java.lang.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.
|
java.lang.String |
replace(java.lang.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(StrBuilder source)
Replaces all the occurrences of variables within the given source
builder with their matching values from the resolver.
|
boolean |
replaceIn(StrBuilder 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(java.lang.StringBuffer source)
Replaces all the occurrences of variables within the given source buffer
with their matching values from the resolver.
|
boolean |
replaceIn(java.lang.StringBuffer source,
int offset,
int length)
Replaces all the occurrences of variables within the given source buffer
with their matching values from the resolver.
|
static java.lang.String |
replaceSystemProperties(java.lang.Object source)
Replaces all the occurrences of variables in the given source object with
their matching values from the system properties.
|
void |
setEnableSubstitutionInVariables(boolean enableSubstitutionInVariables)
Sets a flag whether substitution is done in variable names.
|
void |
setEscapeChar(char escapeCharacter)
Sets the escape character.
|
StrSubstitutor |
setVariablePrefix(char prefix)
Sets the variable prefix to use.
|
StrSubstitutor |
setVariablePrefix(java.lang.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(java.lang.String suffix)
Sets the variable suffix to use.
|
StrSubstitutor |
setVariableSuffixMatcher(StrMatcher suffixMatcher)
Sets the variable suffix matcher currently in use.
|
public static final char DEFAULT_ESCAPE
public static final StrMatcher DEFAULT_PREFIX
public static final StrMatcher DEFAULT_SUFFIX
public StrSubstitutor()
public StrSubstitutor(java.util.Map valueMap)
valueMap
- the map with the variables' values, may be nullpublic StrSubstitutor(java.util.Map valueMap, java.lang.String prefix, java.lang.String suffix)
valueMap
- the map with the variables' values, may be nullprefix
- the prefix for variables, not nullsuffix
- the suffix for variables, not nulljava.lang.IllegalArgumentException
- if the prefix or suffix is nullpublic StrSubstitutor(java.util.Map valueMap, java.lang.String prefix, java.lang.String suffix, char escape)
valueMap
- the map with the variables' values, may be nullprefix
- the prefix for variables, not nullsuffix
- the suffix for variables, not nullescape
- the escape characterjava.lang.IllegalArgumentException
- if the prefix or suffix is nullpublic StrSubstitutor(StrLookup variableResolver)
variableResolver
- the variable resolver, may be nullpublic StrSubstitutor(StrLookup variableResolver, java.lang.String prefix, java.lang.String suffix, char escape)
variableResolver
- the variable resolver, may be nullprefix
- the prefix for variables, not nullsuffix
- the suffix for variables, not nullescape
- the escape characterjava.lang.IllegalArgumentException
- if the prefix or suffix is nullpublic StrSubstitutor(StrLookup variableResolver, StrMatcher prefixMatcher, StrMatcher suffixMatcher, char escape)
variableResolver
- the variable resolver, may be nullprefixMatcher
- the prefix for variables, not nullsuffixMatcher
- the suffix for variables, not nullescape
- the escape characterjava.lang.IllegalArgumentException
- if the prefix or suffix is nullpublic static java.lang.String replace(java.lang.Object source, java.util.Map valueMap)
source
- the source text containing the variables to substitute, null returns nullvalueMap
- the map with the values, may be nullpublic static java.lang.String replace(java.lang.Object source, java.util.Map valueMap, java.lang.String prefix, java.lang.String suffix)
source
- the source text containing the variables to substitute, null returns nullvalueMap
- the map with the values, may be nullprefix
- the prefix of variables, not nullsuffix
- the suffix of variables, not nulljava.lang.IllegalArgumentException
- if the prefix or suffix is nullpublic static java.lang.String replace(java.lang.Object source, java.util.Properties valueProperties)
source
- the source text containing the variables to substitute, null returns nullvalueProperties
- the properties with values, may be nullpublic static java.lang.String replaceSystemProperties(java.lang.Object source)
source
- the source text containing the variables to substitute, null returns nullpublic java.lang.String replace(java.lang.String source)
source
- the string to replace in, null returns nullpublic java.lang.String replace(java.lang.String source, int offset, int length)
Only the specified portion of the string will be processed. The rest of the string is not processed, and is not returned.
source
- the string to replace in, null returns nulloffset
- the start offset within the array, must be validlength
- the length within the array to be processed, must be validpublic java.lang.String replace(char[] source)
source
- the character array to replace in, not altered, null returns nullpublic java.lang.String replace(char[] source, int offset, int length)
Only the specified portion of the array will be processed. The rest of the array is not processed, and is not returned.
source
- the character array to replace in, not altered, null returns nulloffset
- the start offset within the array, must be validlength
- the length within the array to be processed, must be validpublic java.lang.String replace(java.lang.StringBuffer source)
source
- the buffer to use as a template, not changed, null returns nullpublic java.lang.String replace(java.lang.StringBuffer source, int offset, int length)
Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, and is not returned.
source
- the buffer to use as a template, not changed, null returns nulloffset
- the start offset within the array, must be validlength
- the length within the array to be processed, must be validpublic java.lang.String replace(StrBuilder source)
source
- the builder to use as a template, not changed, null returns nullpublic java.lang.String replace(StrBuilder source, int offset, int length)
Only the specified portion of the builder will be processed. The rest of the builder is not processed, and is not returned.
source
- the builder to use as a template, not changed, null returns nulloffset
- the start offset within the array, must be validlength
- the length within the array to be processed, must be validpublic java.lang.String replace(java.lang.Object source)
toString
and is not altered.source
- the source to replace in, null returns nullpublic boolean replaceIn(java.lang.StringBuffer source)
source
- the buffer to replace in, updated, null returns zeropublic boolean replaceIn(java.lang.StringBuffer source, int offset, int length)
Only the specified portion of the buffer will be processed. The rest of the buffer is not processed, but it is not deleted.
source
- the buffer to replace in, updated, null returns zerooffset
- the start offset within the array, must be validlength
- the length within the buffer to be processed, must be validpublic boolean replaceIn(StrBuilder source)
source
- the builder to replace in, updated, null returns zeropublic boolean replaceIn(StrBuilder source, int offset, int length)
Only the specified portion of the builder will be processed. The rest of the builder is not processed, but it is not deleted.
source
- the builder to replace in, null returns zerooffset
- the start offset within the array, must be validlength
- the length within the builder to be processed, must be validpublic char getEscapeChar()
public void setEscapeChar(char escapeCharacter)
escapeCharacter
- the escape character (0 for disabling escaping)public StrMatcher getVariablePrefixMatcher()
The variable prefix is the characer or characters that identify the start of a variable. This prefix is expressed in terms of a matcher allowing advanced prefix matches.
public StrSubstitutor setVariablePrefixMatcher(StrMatcher prefixMatcher)
The variable prefix is the characer or characters that identify the start of a variable. This prefix is expressed in terms of a matcher allowing advanced prefix matches.
prefixMatcher
- the prefix matcher to use, null ignoredjava.lang.IllegalArgumentException
- if the prefix matcher is nullpublic StrSubstitutor setVariablePrefix(char prefix)
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.
prefix
- the prefix character to usepublic StrSubstitutor setVariablePrefix(java.lang.String prefix)
The variable prefix is the characer or characters that identify the start of a variable. This method allows a string prefix to be easily set.
prefix
- the prefix for variables, not nulljava.lang.IllegalArgumentException
- if the prefix is nullpublic StrMatcher getVariableSuffixMatcher()
The variable suffix is the characer or characters that identify the end of a variable. This suffix is expressed in terms of a matcher allowing advanced suffix matches.
public StrSubstitutor setVariableSuffixMatcher(StrMatcher suffixMatcher)
The variable suffix is the characer or characters that identify the end of a variable. This suffix is expressed in terms of a matcher allowing advanced suffix matches.
suffixMatcher
- the suffix matcher to use, null ignoredjava.lang.IllegalArgumentException
- if the suffix matcher is nullpublic StrSubstitutor setVariableSuffix(char suffix)
The variable suffix is the characer or characters that identify the end of a variable. This method allows a single character suffix to be easily set.
suffix
- the suffix character to usepublic StrSubstitutor setVariableSuffix(java.lang.String suffix)
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.
suffix
- the suffix for variables, not nulljava.lang.IllegalArgumentException
- if the suffix is nullpublic StrLookup getVariableResolver()
public void setVariableResolver(StrLookup variableResolver)
variableResolver
- the VariableResolverpublic boolean isEnableSubstitutionInVariables()
public void setEnableSubstitutionInVariables(boolean enableSubstitutionInVariables)
${jre-${java.version}}
. The default value is false.enableSubstitutionInVariables
- the new value of the flagCopyright © 2010 - 2020 Adobe. All Rights Reserved