Java Doc for StrSubstitutor.java in  » Library » Apache-common-lang » org » apache » commons » lang » text » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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);
 

 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.
 

 The variable ${x} must be used.
 

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

The variable prefix is the characer or characters that identify the start of a variable.

The variable suffix is the characer or characters that identify the end of a variable.

Most users of this class do not need to call this method.

The variable prefix is the characer or characters that identify the start of a variable.

The variable prefix is the characer or characters that identify the start of a variable.

The variable prefix is the characer or characters that identify the start of a variable.

The variable suffix is the characer or characters that identify the end of a variable.

The variable suffix is the characer or characters that identify the end of a variable.

The variable suffix is the characer or characters that identify the end of a variable.

Most users of this class do not need to call this method.

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. the prefix matcher 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. the suffix matcher in use

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
Parameters:
  offset - the start offset within the array, must be valid
Parameters:
  length - the length within the array to be processed, must be valid the result of the replace operation

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
Parameters:
  offset - the start offset within the array, must be valid
Parameters:
  length - the length within the array to be processed, must be valid the result of the replace operation

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
Parameters:
  offset - the start offset within the array, must be valid
Parameters:
  length - the length within the array to be processed, must be valid the result of the replace operation

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
Parameters:
  offset - the start offset within the array, must be valid
Parameters:
  length - the length within the array to be processed, must be valid the result of the replace operation

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
Parameters:
  offset - the start offset within the array, must be valid
Parameters:
  length - the length within the buffer to be processed, must be valid true if altered

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
Parameters:
  offset - the start offset within the array, must be valid
Parameters:
  length - the length within the builder to be processed, must be valid true if altered

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 StrSubstitutor.getVariableResolver() with the variable's name as the key.
Parameters:
  variableName - the name of the variable, not null
Parameters:
  buf - the buffer where the substitution is occurring, not null
Parameters:
  startPos - the start position of the variable including the prefix, valid
Parameters:
  endPos - the end position of the variable including the suffix, valid the variable's value or null if the variable is unknown

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 this, to enable chaining

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 this, to enable chaining
throws:
  IllegalArgumentException - if the prefix is null

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 this, to enable chaining
throws:
  IllegalArgumentException - if the prefix matcher is null

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 this, to enable chaining

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 this, to enable chaining
throws:
  IllegalArgumentException - if the suffix is null

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 this, to enable chaining
throws:
  IllegalArgumentException - if the suffix matcher is null

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
Parameters:
  offset - the start offset within the builder, must be valid
Parameters:
  length - the length within the builder to be processed, must be valid true if altered