net.sourceforge.jeval
Class Evaluator

java.lang.Object
  net.sourceforge.jeval.Evaluator

public class Evaluator
extends java.lang.Object

This class is used to evaluate mathematical, string, Boolean and functional expressions. It is the main entry point into the JEval API.

The following types of expressions are supported:

• mathematical Expression involving numbers. Numbers are treated as doubles, so resulting numbers will contain at least one decimal place.
• string String can also be added together, compared, etc...
• Boolean Expression that evaluate to true (1.0) and false (0.0).
• functional Custom functions can be created or there are many Math and String functions that JEval supplies with this class.

The following operators are supported:

• ( open parentheses
• ) closed parentheses
• + addition (for numbers and strings)
• - subtration
• * mutliplication
• / division
• % modulus
• + unary plus
• - unary minus
• = equal (for numbers and strings)
• != not equal (for numbers and strings)
• < less than (for numbers and strings)
• <= less than or equal (for numbers and strings)
• > greater than (for numbers and strings)
• >= greater than or equal (for numbers and strings)
• && boolean and
• || boolean or
• ! boolean not

Allows for prebuilt and custom functions.

• JEval already comes with many functions which represent most of the methods in the Math and String classes in the standard JDK.
• Thirty-nine math and string functions come built in. See the net.sourceforge.jeval.functions.math and net.sourceforge.jeval.functions.string packages for details on these ready to use functions. You can choose to not load these functions if we you want to gain a small improvement in performance.
• Functions must be followed by an open parentheses and a closed parentheses which contain any required parameters.
• For more details on functions, see the Function class and the test classes.

Allows for variables.

• Variable must be enclosed by a pound sign and open brace #{ and a closed brace }. i.e. expression = "#{a} + #{b}"
• Two math variables come built in. The E and PI variables represent the same value as the Math.E and Math.PI constants in the standard Java SDK. You can choose not to load these variables.
-

Notes on expression parsing:

• Spaces are ignored when parsing expressions.
• The order of precedence used by this class is as follows from highest to lowest.
• The expression is evaluated as one or more subexpressions. Subexpressions within open parentheses and closed parentheses are evaluated before other parts of the expression.
• Inner most subexpression are evaluated first working outward.
• Subexpressions at the same level are evaluated from left to right.
• When evaluating expressions and subexpressions, operators are evaluated with the following precedence listed below.
• Operators with with the same precedence are evaluated from left to right.
• Once the expression is parsed, variable are replaced with their values and/or functions are executed and replaced with their results. At this time variables are also replaced within function calls at the time they are executed.

Operator precedence:

• + unary plus, - unary minus, ! boolean not
• * multiplication, / division, % modulus
• + addition, - subtraction
• < less than, <= less than or equal, > greater than, >= greater than or equal
• = equal, != not equal
• && boolean and
• || boolean or

Function and variable names can not break any of the following rules:

• can not start with a number
• can not contain an operator (see the above list of operators)/li>
• can not contain a quote character - single or double/li>
• can not contain a brace character - open or closed/li>
• can not contain one of the following special characters: #, ~ , ^ !

Other Notes:

• This class is not thread safe.
• Allows for the quote character (single or double) to be specified at run time. Quote characters are required for specifying string values.
• Expressions can contain different types of expressions within the same expression. However, Numeric and string types can not be mixed in a left / right oeprand pair.
• An expression can be parsed before being evaluated by calling the parse method. Also, if an expression does not change, it will not be parsed each time the expression is evaluated. Therefore, variables values can change and the expression can be evaluataed again without having to re-parse the expression.
• Nested or recursive function calls are not supported,
• The string used to start variables, "#{", can not appear in an expression.
• See the evaluate methods in this class, JUnit tests and samples for more details.

Field Summary

static java.lang.Double	BOOLEAN_FALSE_DOUBLE_VALUE
static java.lang.String	BOOLEAN_FALSE_STR
static java.lang.Double	BOOLEAN_TRUE_DOUBLE_VALUE
static java.lang.String	BOOLEAN_TRUE_STR

Constructor Summary

Evaluator()
The default constructor.

Evaluator(char quoteCharacter, boolean loadMathVariables, boolean loadMathFunctions, boolean loadStringFunctions)
The main constructor for Evaluator.

Method Summary

void	clearFunctions() Removes all of the functions at one time.
void	clearVariables() Removes all of the variables at one time.
java.lang.String	evaluate() This method evaluates mathematical, boolean or functional expressions.
java.lang.String	evaluate(boolean keepQuotes, boolean wrapStringFunctionResults) This method evaluates mathematical, boolean or functional expressions.
java.lang.String	evaluate(java.lang.String expression) This method evaluates mathematical, boolean or functional expressions.
java.lang.String	evaluate(java.lang.String expression, boolean keepQuotes, boolean wrapStringFunctionResults) This method evaluates mathematical, boolean or functional expressions.
boolean	getBooleanResult(java.lang.String expression) This method is a simple wrapper around the evaluate(String) method.
net.sourceforge.jeval.function.Function	getFunction(java.lang.String functionName) Returns a funtion from the list of functions.
double	getNumberResult(java.lang.String expression) This method is a simple wrapper around the evaluate(String) method.
char	getQuoteCharacter() Returns the current quote character in use.
java.lang.String	getVariable(java.lang.String variableName) Returns the value for a variable in the list of variables.
protected boolean	isExpressionBoolean(java.lang.String expressionString) Determines if the string represents a valid boolean value.
protected boolean	isExpressionString(java.lang.String expressionString) Determines if the string represents a valid expression string or not.
void	isValidName(java.lang.String name) This method verifies if a function or variable name is valid or not.
void	parse(java.lang.String expression) This method parses a mathematical, boolean or functional expressions.
void	putFunction(net.sourceforge.jeval.function.Function function) Adds a function to the list of functions to use when evaluating expressions.
void	putVariable(java.lang.String variableName, java.lang.String variableValue) Adds or replaces a variable to the list of variables to use when evaluating expressions.
void	removeFunction(java.lang.String functionName) Removes the function from the list of functions to use when evaluating expressions.
void	removeVaraible(java.lang.String variableName) Removes the variable from the list of variables to use when evaluating expressions.
java.lang.String	replaceVariables(java.lang.String expression) Replaces the variables in the expression with the values of the variables for this instance of the evaluator.
void	setQuoteCharacter(char quoteCharacter) Sets the quote character to use when evaluating expressions.

Methods inherited from class java.lang.Object

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

Field Detail

BOOLEAN_TRUE_STR

public static final java.lang.String BOOLEAN_TRUE_STR

See Also:

Constant Field Values

BOOLEAN_FALSE_STR

public static final java.lang.String BOOLEAN_FALSE_STR

See Also:

Constant Field Values

BOOLEAN_TRUE_DOUBLE_VALUE

public static final java.lang.Double BOOLEAN_TRUE_DOUBLE_VALUE

BOOLEAN_FALSE_DOUBLE_VALUE

public static final java.lang.Double BOOLEAN_FALSE_DOUBLE_VALUE

Constructor Detail

Evaluator

public Evaluator()

The default constructor. This constructor calls the four parameter Evaluator constructor and passes in the following default values: SINGLE_QUOTE, true, true and true.

Evaluator

public Evaluator(char quoteCharacter,
                 boolean loadMathVariables,
                 boolean loadMathFunctions,
                 boolean loadStringFunctions)

The main constructor for Evaluator.

Parameters:

quoteCharacter - The quote character to use when evaluating expression.

loadMathVariables - Indicates if the standard Math variables should be loaded or not.

loadMathFunctions - Indicates if the standard Math functions should be loaded or not.

loadStringFunctions - Indicates if the standard String functions should be loaded or not.

Throws:

java.lang.IllegalArgumentException - Thrown when the quote character is not a valid quote character.

Method Detail

getQuoteCharacter

public char getQuoteCharacter()

Returns the current quote character in use.

Returns:

The quote character in use.

setQuoteCharacter

public void setQuoteCharacter(char quoteCharacter)

Sets the quote character to use when evaluating expressions.

Parameters:

quoteCharacter - The quote character to use when evaluating expressions.

Throws:

java.lang.IllegalArgumentException - Thrown when the quote character is not a valid quote character.

putFunction

public void putFunction(net.sourceforge.jeval.function.Function function)

Adds a function to the list of functions to use when evaluating expressions.

Parameters:

function - The function being added.

Throws:

java.lang.IllegalArgumentException - Thrown when the function name is not valid or the function name is already in use.

getFunction

public net.sourceforge.jeval.function.Function getFunction(java.lang.String functionName)

Returns a funtion from the list of functions. If the function can not be found in the list of functions, then null will be returned.

Parameters:

functionName - The name of the function to retrieve the value for.

Returns:

The value for a function in the list of function.

removeFunction

public void removeFunction(java.lang.String functionName)

Removes the function from the list of functions to use when evaluating expressions.

Parameters:

functionName - The name of the function to remove.

clearFunctions

public void clearFunctions()

Removes all of the functions at one time.

putVariable

public void putVariable(java.lang.String variableName,
                        java.lang.String variableValue)

Adds or replaces a variable to the list of variables to use when evaluating expressions. If the variable already exists, then its value will be overlaid.

Parameters:

variableName - The name of the variable being set.

variableValue - The value for the variable being set.

getVariable

public java.lang.String getVariable(java.lang.String variableName)

Returns the value for a variable in the list of variables. If the variable can not be found in the list of variables, then null will be returned.

Parameters:

variableName - The name of the variable to retrieve the value for.

Returns:

The value for a variable in the list of variables.

removeVaraible

public void removeVaraible(java.lang.String variableName)

Removes the variable from the list of variables to use when evaluating expressions.

Parameters:

variableName - The name of the variable to remove.

clearVariables

public void clearVariables()

Removes all of the variables at one time.

evaluate

public java.lang.String evaluate(java.lang.String expression)
                          throws EvaluationException

This method evaluates mathematical, boolean or functional expressions. See the class description and test classes for more information on how to write an expression. If quotes exist around a string expression, then they will be left in the result string. Function will also have their results wrapped with the appripriate quote characters.

Parameters:

expression - The expression to evaluate.

Returns:

The result of the evaluated. expression. Numbers are treated as doubles, so resulting numbers will contain at least one decimal place.

Throws:

EvaluateException - Thrown when an error is found while evaluating the expression.

EvaluationException

evaluate

public java.lang.String evaluate()
                          throws EvaluationException

This method evaluates mathematical, boolean or functional expressions. See the class description and test classes for more information on how to write an expression. The expression used will be the one previously specified when using the parse method. If the parse method has not been called before calling this method, then an exception will be thrown. If quotes exist around a string expression, then they will be left in the result string. Function will also have their results wrapped with the appripriate quote characters.

Returns:

The result of the evaluated. expression. Numbers are treated as doubles, so resulting numbers will contain at least one decimal place.

Throws:

EvaluateException - Thrown when an error is found while evaluating the expression.

EvaluationException

evaluate

public java.lang.String evaluate(java.lang.String expression,
                                 boolean keepQuotes,
                                 boolean wrapStringFunctionResults)
                          throws EvaluationException

This method evaluates mathematical, boolean or functional expressions. See the class description and test classes for more information on how to write an expression.

Parameters:

expression - The expression to evaluate.

keepQuotes - Indicates if the the quotes should be kept in the result or not. This is only for string expression that are enclosed in quotes prior to being evaluated.

wrapStringFunctionResults - Indicates if the results from functions that return strings should be wrapped in quotes. The quote character used will be whatever is the current quote character for this object.

Returns:

The result of the evaluated expression. Numbers are treated as doubles, so resulting numbers will contain at least one decimal place.

Throws:

EvaluateException - Thrown when an error is found while evaluating the expression.

EvaluationException

evaluate

public java.lang.String evaluate(boolean keepQuotes,
                                 boolean wrapStringFunctionResults)
                          throws EvaluationException

This method evaluates mathematical, boolean or functional expressions. The expression used will be the one previously specified when using the parse method. If the parse method has not been called before calling this method, then an exception will be thrown. See the class description and test classes for more information on how to write an expression.

Parameters:

keepQuotes - Indicates if the the quotes should be kept in the result or not. This is only for string expressions that are enclosed in quotes prior to being evaluated.

wrapStringFunctionResults - Indicates if the results from functions that return strings should be wrapped in quotes. The quote character used will be whatever is the current quote character for this object.

Returns:

The result of the evaluated expression. Numbers are treated as doubles, so resulting numbers will contain at least one decimal place.

Throws:

EvaluateException - Thrown when an error is found while evaluating the expression.

EvaluationException

getBooleanResult

public boolean getBooleanResult(java.lang.String expression)
                         throws EvaluationException

This method is a simple wrapper around the evaluate(String) method. Its purpose is to return a more friendly boolean return value instead of the string "1.0" (for true) and "0.0" (for false) that is normally returned.

Parameters:

expression - The expression to evaluate.

Returns:

A boolean value that represents the result of the evaluated expression.

Throws:

EvaluateException - Thrown when an error is found while evaluating the expression. It is also thrown if the result is not able to be converted to a boolean value.

EvaluationException

getNumberResult

public double getNumberResult(java.lang.String expression)
                       throws EvaluationException

This method is a simple wrapper around the evaluate(String) method. Its purpose is to return a more friendly double return value instead of the string number that is normally returned.

Parameters:

expression - The expression to evaluate.

Returns:

A double value that represents the result of the evaluated expression.

Throws:

EvaluateException - Thrown when an error is found while evaluating the expression. It is also thrown if the result is not able to be converted to a double value.

EvaluationException

parse

public void parse(java.lang.String expression)
           throws EvaluationException

This method parses a mathematical, boolean or functional expressions. When the expression is eventually evaluated, as long as the expression has not changed, it will not have to be reparsed. See the class description and test classes for more information on how to write an expression.

Parameters:

expression - The expression to evaluate.

Throws:

EvaluateException - Thrown when an error is found while evaluating the expression.

EvaluationException

isExpressionString

protected boolean isExpressionString(java.lang.String expressionString)
                              throws EvaluationException

Determines if the string represents a valid expression string or not. Valid expression strings must start and end with a quote character.

Parameters:

expressionString - The string being evaluated.

Returns:

True if the string is a valid string and false if not.

Throws:

EvaluationException

isExpressionBoolean

protected boolean isExpressionBoolean(java.lang.String expressionString)

Determines if the string represents a valid boolean value.

Parameters:

expressionString - The string being evaluated.

Returns:

True if the string is a valid boolean value and false if not.

isValidName

public void isValidName(java.lang.String name)
                 throws java.lang.IllegalArgumentException

This method verifies if a function or variable name is valid or not. Function and variable names must follow these rules... can not start with a number can not contain an operator (see the above list of operators) can not contain a quote character - single or double can not contain a brace character - open or closed can not contain one of the following special characters: ~ , ^ !

Parameters:

name - The function or variable name being validated.

Throws:

java.lang.IllegalArgumentException - Thrown if the name is invalid.

replaceVariables

public java.lang.String replaceVariables(java.lang.String expression)
                                  throws EvaluationException

Replaces the variables in the expression with the values of the variables for this instance of the evaluator.

Parameters:

expression - The expression being processed.

Returns:

A new expression with the variables replaced with their values.

Throws:

EvaluateException - Thrown is an error is encoutnered while processing the expression.

EvaluationException