com.izforge.izpack.util
Class VariableSubstitutor

java.lang.Object
  extended by com.izforge.izpack.util.VariableSubstitutor
All Implemented Interfaces:
java.io.Serializable

public class VariableSubstitutor
extends java.lang.Object
implements java.io.Serializable

Substitutes variables occurring in an input stream or a string. This implementation supports a generic variable value mapping and escapes the possible special characters occurring in the substituted values. The file types specifically supported are plain text files (no escaping), Java properties files, and XML files. A valid variable name matches the regular expression [a-zA-Z][a-zA-Z0-9_]* and names are case sensitive. Variables are referenced either by $NAME or ${NAME} (the latter syntax being useful in situations like ${NAME}NOTPARTOFNAME). If a referenced variable is undefined then it is not substituted but the corresponding part of the stream is copied as is.

Author:
Johannes Lehtinen
See Also:
Serialized Form

Field Summary
protected  boolean bracesRequired
          Whether braces are required for substitution.
static java.lang.String PLAIN
          PLAIN = "plain"
private static long serialVersionUID
           
protected static int TYPE_ANT
          A constant for file type.
protected static int TYPE_AT
          A constant for file type.
protected static int TYPE_JAVA
          A constant for file type.
protected static int TYPE_JAVA_PROPERTIES
          A constant for file type.
protected static int TYPE_PLAIN
          A constant for file type.
protected static int TYPE_SHELL
          A constant for file type.
protected static int TYPE_XML
          A constant for file type.
protected static java.util.Map<java.lang.String,java.lang.Integer> typeNameToConstantMap
          A mapping of file type names to corresponding integer constants.
protected  java.util.Properties variables
          The variable value mappings
 
Constructor Summary
VariableSubstitutor(java.util.Properties variables)
          Constructs a new substitutor using the specified variable value mappings.
 
Method Summary
 boolean areBracesRequired()
          Get whether this substitutor requires braces.
protected  java.lang.String escapeSpecialChars(java.lang.String str, int type)
          Escapes the special characters in the specified string using file type specific rules.
protected  int getTypeConstant(java.lang.String type)
          Returns the internal constant for the specified file type.
 void setBracesRequired(boolean braces)
          Specify whether this substitutor requires braces.
 int substitute(java.io.InputStream in, java.io.OutputStream out, java.lang.String type, java.lang.String encoding)
          Substitutes the variables found in the specified input stream.
 java.lang.String substitute(java.io.InputStream in, java.lang.String type)
          Substitute method Variant that gets An Input Stream and returns A String
 int substitute(java.io.Reader reader, java.io.Writer writer, java.lang.String type)
          Substitutes the variables found in the data read from the specified reader.
 java.lang.String substitute(java.lang.String str, java.lang.String type)
          Substitutes the variables found in the specified string.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

serialVersionUID

private static final long serialVersionUID
See Also:
Constant Field Values

variables

protected transient java.util.Properties variables
The variable value mappings


bracesRequired

protected boolean bracesRequired
Whether braces are required for substitution.


TYPE_PLAIN

protected static final int TYPE_PLAIN
A constant for file type. Plain file.

See Also:
Constant Field Values

TYPE_JAVA_PROPERTIES

protected static final int TYPE_JAVA_PROPERTIES
A constant for file type. Java properties file.

See Also:
Constant Field Values

TYPE_XML

protected static final int TYPE_XML
A constant for file type. XML file.

See Also:
Constant Field Values

TYPE_SHELL

protected static final int TYPE_SHELL
A constant for file type. Shell file.

See Also:
Constant Field Values

TYPE_AT

protected static final int TYPE_AT
A constant for file type. Plain file with '@' start char.

See Also:
Constant Field Values

TYPE_JAVA

protected static final int TYPE_JAVA
A constant for file type. Java file, where \ have to be escaped.

See Also:
Constant Field Values

TYPE_ANT

protected static final int TYPE_ANT
A constant for file type. Plain file with ANT-like variable markers, ie @param@

See Also:
Constant Field Values

PLAIN

public static final java.lang.String PLAIN
PLAIN = "plain"

See Also:
Constant Field Values

typeNameToConstantMap

protected static final java.util.Map<java.lang.String,java.lang.Integer> typeNameToConstantMap
A mapping of file type names to corresponding integer constants.

Constructor Detail

VariableSubstitutor

public VariableSubstitutor(java.util.Properties variables)
Constructs a new substitutor using the specified variable value mappings. The environment hashtable is copied by reference. Braces are not required by default

Parameters:
variables - the map with variable value mappings
Method Detail

areBracesRequired

public boolean areBracesRequired()
Get whether this substitutor requires braces.


setBracesRequired

public void setBracesRequired(boolean braces)
Specify whether this substitutor requires braces.


substitute

public java.lang.String substitute(java.lang.String str,
                                   java.lang.String type)
                            throws java.lang.IllegalArgumentException
Substitutes the variables found in the specified string. Escapes special characters using file type specific escaping if necessary.

Parameters:
str - the string to check for variables
type - the escaping type or null for plain
Returns:
the string with substituted variables
Throws:
java.lang.IllegalArgumentException - if unknown escaping type specified

substitute

public int substitute(java.io.InputStream in,
                      java.io.OutputStream out,
                      java.lang.String type,
                      java.lang.String encoding)
               throws java.lang.IllegalArgumentException,
                      java.io.UnsupportedEncodingException,
                      java.io.IOException
Substitutes the variables found in the specified input stream. Escapes special characters using file type specific escaping if necessary.

Parameters:
in - the input stream to read
out - the output stream to write
type - the file type or null for plain
encoding - the character encoding or null for default
Returns:
the number of substitutions made
Throws:
java.lang.IllegalArgumentException - if unknown file type specified
java.io.UnsupportedEncodingException - if encoding not supported
java.io.IOException - if an I/O error occurs

substitute

public java.lang.String substitute(java.io.InputStream in,
                                   java.lang.String type)
                            throws java.lang.IllegalArgumentException,
                                   java.io.UnsupportedEncodingException,
                                   java.io.IOException
Substitute method Variant that gets An Input Stream and returns A String

Parameters:
in - The Input Stream, with Placeholders
type - The used FormatType
Returns:
the substituted result as string
Throws:
java.lang.IllegalArgumentException - If a wrong input was given.
java.io.UnsupportedEncodingException - If the file comes with a wrong Encoding
java.io.IOException - If an I/O Error occurs.

substitute

public int substitute(java.io.Reader reader,
                      java.io.Writer writer,
                      java.lang.String type)
               throws java.lang.IllegalArgumentException,
                      java.io.IOException
Substitutes the variables found in the data read from the specified reader. Escapes special characters using file type specific escaping if necessary.

Parameters:
reader - the reader to read
writer - the writer used to write data out
type - the file type or null for plain
Returns:
the number of substitutions made
Throws:
java.lang.IllegalArgumentException - if unknown file type specified
java.io.IOException - if an I/O error occurs

getTypeConstant

protected int getTypeConstant(java.lang.String type)
Returns the internal constant for the specified file type.

Parameters:
type - the type name or null for plain
Returns:
the file type constant

escapeSpecialChars

protected java.lang.String escapeSpecialChars(java.lang.String str,
                                              int type)
Escapes the special characters in the specified string using file type specific rules.

Parameters:
str - the string to check for special characters
type - the target file type (one of TYPE_xxx)
Returns:
the string with the special characters properly escaped