org.clapper.util.text

Class AbstractVariableSubstituter

java.lang.Object

org.clapper.util.text.AbstractVariableSubstituter

All Implemented Interfaces:

VariableNameChecker, VariableSubstituter

Direct Known Subclasses:

UnixShellVariableSubstituter, WindowsCmdVariableSubstituter

public abstract class AbstractVariableSubstituter
extends java.lang.Object
implements VariableSubstituter, VariableNameChecker

Abstract base class for VariableSubstituter classes, containing various useful utility methods.

Method Summary

Modifier and Type	Method and Description
boolean	getAbortOnSyntaxError() Get the value of the flag that controls whether the substitute() methods will abort when they encounter a syntax error.
boolean	getAbortOnUndefinedVariable() Get the value of the flag that controls whether the substitute() methods will abort when they encounter an undefined variable.
boolean	legalVariableCharacter(char c) Determine whether a character is a legal variable identifier character.
void	setAbortOnSyntaxError(boolean enable) Set or clear the flag that controls whether the substitute() methods will abort when they encounter a syntax error.
void	setAbortOnUndefinedVariable(boolean enable) Set or clear the flag that controls whether the substitute() methods will abort when they encounter an undefined variable.
java.lang.String	substitute(java.lang.String s, VariableDereferencer deref) Substitute all variable references in the supplied string, using a Unix Bourne Shell-style variable syntax.
java.lang.String	substitute(java.lang.String s, VariableDereferencer deref, java.lang.Object context) Substitute all variable references in the supplied string, using a Unix Bourne Shell-style variable syntax.
abstract java.lang.String	substitute(java.lang.String s, VariableDereferencer deref, VariableNameChecker nameChecker, java.lang.Object context) Substitute all variable references in the supplied string, using a Unix Bourne Shell-style variable syntax.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

legalVariableCharacter

public boolean legalVariableCharacter(char c)

Determine whether a character is a legal variable identifier character. This default implementation permits alphanumerics, underscores and periods ("."). Subclasses can override this method.

Specified by:

legalVariableCharacter in interface VariableNameChecker

Parameters:

c - The character

Returns:

true if the character is legal, false otherwise.

See Also:

VariableSubstituter.substitute(java.lang.String, org.clapper.util.text.VariableDereferencer, java.lang.Object)

substitute

public java.lang.String substitute(java.lang.String s,
                                   VariableDereferencer deref)
                            throws VariableSyntaxException,
                                   UndefinedVariableException,
                                   VariableSubstitutionException

Substitute all variable references in the supplied string, using a Unix Bourne Shell-style variable syntax. This method uses a supplied VariableDereferencer object to resolve variable values. Note that this method throws no exceptions. Syntax errors in the variable references are silently ignored. Variables that have no value are substituted as the empty string. This method assumes that variable names may consist solely of alphanumeric characters, underscores and periods. This syntax is sufficient to substitute variables from System.properties, for instance. If you want more control over the legal characters, use the one of the other substitute methods.

Calling this method is equivalent to:

substitute(s, deref, null)

Parameters:

s - the string containing possible variable references

deref - the VariableDereferencer object to use to resolve the variables' values.

Returns:

The (possibly) expanded string.

Throws:

UndefinedVariableException - undefined variable, and getAbortOnUndefinedVariable() returns true

VariableSyntaxException - syntax error, and getAbortOnSyntaxError() returns true

VariableSubstitutionException - substitution error

See Also:

substitute(String,VariableDereferencer,VariableNameChecker,Object), VariableDereferencer.getVariableValue(String,Object)

substitute

public java.lang.String substitute(java.lang.String s,
                                   VariableDereferencer deref,
                                   java.lang.Object context)
                            throws VariableSyntaxException,
                                   UndefinedVariableException,
                                   VariableSubstitutionException

Substitute all variable references in the supplied string, using a Unix Bourne Shell-style variable syntax. This method uses a supplied VariableDereferencer object to resolve variable values. Note that this method throws no exceptions. Syntax errors in the variable references are silently ignored. Variables that have no value are substituted as the empty string. This method assumes that variable names may consist solely of alphanumeric characters, underscores and periods. This syntax is sufficient to substitute variables from System.properties, for instance. If you want more control over the legal characters, use the one of the other substitute methods.

Specified by:

substitute in interface VariableSubstituter

Parameters:

s - the string containing possible variable references

deref - the VariableDereferencer object to use to resolve the variables' values.

context - an optional context object, passed through unmodified to the deref object's VariableDereferencer.getVariableValue(java.lang.String, java.lang.Object) method. This object can be anything at all (and, in fact, may be null if you don't care.) It's primarily useful for passing context information from the caller to the (custom) VariableDereferencer.

Returns:

The (possibly) expanded string.

Throws:

UndefinedVariableException - undefined variable, and getAbortOnUndefinedVariable() returns true

VariableSyntaxException - syntax error, and getAbortOnSyntaxError() returns true

VariableSubstitutionException - substitution error

See Also:

substitute(String,VariableDereferencer,VariableNameChecker,Object), VariableDereferencer.getVariableValue(String,Object)

substitute

public abstract java.lang.String substitute(java.lang.String s,
                                            VariableDereferencer deref,
                                            VariableNameChecker nameChecker,
                                            java.lang.Object context)
                                     throws VariableSyntaxException,
                                            UndefinedVariableException,
                                            VariableSubstitutionException

Substitute all variable references in the supplied string, using a Unix Bourne Shell-style variable syntax. This method uses a supplied VariableDereferencer object to resolve variable values. Note that this method throws no exceptions. Syntax errors in the variable references are silently ignored. Variables that have no value are substituted as the empty string. If the nameChecker parameter is not null, this method calls its VariableNameChecker.legalVariableCharacter(char) method to determine whether a given character is a legal part of a variable name. If nameChecker is null, then this method assumes that variable names may consist solely of alphanumeric characters, underscores and periods. This syntax is sufficient to substitute variables from System.properties, for instance.

Specified by:

substitute in interface VariableSubstituter

Parameters:

s - the string containing possible variable references

deref - the VariableDereferencer object to use to resolve the variables' values.

nameChecker - the VariableNameChecker object to be used to check for legal variable name characters, or null

context - an optional context object, passed through unmodified to the deref object's VariableDereferencer.getVariableValue(java.lang.String, java.lang.Object) method. This object can be anything at all (and, in fact, may be null if you don't care.) It's primarily useful for passing context information from the caller to the VariableDereferencer.

Returns:

The (possibly) expanded string.

Throws:

UndefinedVariableException - undefined variable, and getAbortOnUndefinedVariable() returns true

VariableSyntaxException - syntax error, and getAbortOnSyntaxError() returns true

VariableSubstitutionException - substitution error

See Also:

substitute(String,VariableDereferencer,Object), VariableDereferencer.getVariableValue(String,Object)

getAbortOnSyntaxError

public boolean getAbortOnSyntaxError()

Get the value of the flag that controls whether the substitute() methods will abort when they encounter a syntax error. If this flag is clear, then this object will recover from a syntax error (usually by leaving the syntactically bad variable reference untouched in the resulting string). If this flag is set, then a syntax error results in a VariableSyntaxException.

Specified by:

getAbortOnSyntaxError in interface VariableSubstituter

Returns:

true if the "abort on syntax error" capability is enabled, false if it is disabled.

See Also:

setAbortOnUndefinedVariable(boolean)

getAbortOnUndefinedVariable

public boolean getAbortOnUndefinedVariable()

Get the value of the flag that controls whether the substitute() methods will abort when they encounter an undefined variable. If this flag is clear, then an undefined variable is expanded to an empty string. If this flag is set, then an undefined value results in an UndefinedVariableException.

Specified by:

getAbortOnUndefinedVariable in interface VariableSubstituter

Returns:

true if the "abort on undefined variable" capability is enabled, false if it is disabled.

See Also:

setAbortOnUndefinedVariable(boolean)

setAbortOnSyntaxError

public void setAbortOnSyntaxError(boolean enable)

Set or clear the flag that controls whether the substitute() methods will abort when they encounter a syntax error. If this flag is clear, then this object will recover from a syntax error (usually by leaving the syntactically bad variable reference untouched in the resulting string). If this flag is set, then a syntax error results in a VariableSyntaxException. The flag defaults to false.

Specified by:

setAbortOnSyntaxError in interface VariableSubstituter

Parameters:

enable - true to enable the "abort on syntax error" flag, false to disable it.

See Also:

getAbortOnUndefinedVariable()

setAbortOnUndefinedVariable

public void setAbortOnUndefinedVariable(boolean enable)

Set or clear the flag that controls whether the substitute() methods will abort when they encounter an undefined variable. If this flag is clear, then an undefined variable is expanded to an empty string. If this flag is set, then an undefined value results in an UndefinedVariableException. The flag defaults to false.

Specified by:

setAbortOnUndefinedVariable in interface VariableSubstituter

Parameters:

enable - true to enable the "abort on undefined variable" flag, false to disable it.

See Also:

getAbortOnUndefinedVariable()