org.apache.commons.lang.text
Class StrSubstitutor

java.lang.Object
  org.apache.commons.lang.text.StrSubstitutor

public class StrSubstitutor

extends java.lang.Object

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 = 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 refered 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.
 

Since:

2.2

Version:

$Id: StrSubstitutor.java 592077 2007-11-05 16:47:10Z mbenson $

Author:

Oliver Heger, Stephen Colebourne

Field Summary

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 Summary

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.

Method Summary

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.
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.
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.
protected java.lang.String	resolveVariable(java.lang.String variableName, StrBuilder buf, int startPos, int endPos) Internal method that resolves the value of a variable.
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.
protected boolean	substitute(StrBuilder buf, int offset, int length) Internal method that substitutes the variables.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, 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.

Constructor Detail

StrSubstitutor

public StrSubstitutor()

Creates a new instance with defaults for variable prefix and suffix and the escaping character.

StrSubstitutor

public StrSubstitutor(java.util.Map 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(java.util.Map valueMap,
                      java.lang.String prefix,
                      java.lang.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:

java.lang.IllegalArgumentException - if the prefix or suffix is null

StrSubstitutor

public StrSubstitutor(java.util.Map valueMap,
                      java.lang.String prefix,
                      java.lang.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:

java.lang.IllegalArgumentException - if the prefix or suffix is 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,
                      java.lang.String prefix,
                      java.lang.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:

java.lang.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:

java.lang.IllegalArgumentException - if the prefix or suffix is null

Method Detail

replace

public 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.

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 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. This method allows to specifiy 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:

java.lang.IllegalArgumentException - if the prefix or suffix is null

replaceSystemProperties

public 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.

Parameters:

source - the source text containing the variables to substitute, null returns null

Returns:

the result of the replace operation

replace

public 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.

Parameters:

source - the string to replace in, null returns null

Returns:

the result of the replace operation

replace

public 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.

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 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. 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 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. 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 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. 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 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. 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 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. 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 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. 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 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. 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

replaceIn

public boolean replaceIn(java.lang.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(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. 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(StrBuilder 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(StrBuilder 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

substitute

protected boolean substitute(StrBuilder 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:

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 java.lang.String resolveVariable(java.lang.String variableName,
                                           StrBuilder 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:

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 characer 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 characer 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:

java.lang.IllegalArgumentException - if the prefix matcher is null

setVariablePrefix

public StrSubstitutor setVariablePrefix(char prefix)

Sets the variable prefix to use.

The variable prefix is the characer 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(java.lang.String prefix)

Sets the variable prefix to use.

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.

Parameters:

prefix - the prefix for variables, not null

Returns:

this, to enable chaining

Throws:

java.lang.IllegalArgumentException - if the prefix is null

getVariableSuffixMatcher

public StrMatcher getVariableSuffixMatcher()

Gets the variable suffix matcher currently in use.

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.

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 characer 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:

java.lang.IllegalArgumentException - if the suffix matcher is null

setVariableSuffix

public StrSubstitutor setVariableSuffix(char suffix)

Sets the variable suffix to use.

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.

Parameters:

suffix - the suffix character to use

Returns:

this, to enable chaining

setVariableSuffix

public StrSubstitutor setVariableSuffix(java.lang.String suffix)

Sets the variable suffix to use.

The variable suffix is the characer 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:

java.lang.IllegalArgumentException - if the suffix is null

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