net.sourceforge.jeval
Class Evaluator

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

The following operators are supported:
Allows for prebuilt and custom functions.
Allows for variables.
Notes on expression parsing: Operator precedence: Function and variable names can not break any of the following rules:
Other Notes:


Constructor Summary
Evaluator()
          The default constructor.
Evaluator(char quoteCharacter, boolean loadMathVariables, boolean loadMathFunctions, boolean loadStringFunctions, boolean processNestedFunctions)
          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.
 Function getFunction(java.lang.String functionName)
          Returns a funtion from the list of functions.
 java.util.Map getFunctions()
          Rturns the map of functions currently set on this object.
 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.
 VariableResolver getVariableResolver()
          Returns the variable resolver.
 java.util.Map getVariables()
          Rturns the map of variables currently set on this object.
 java.lang.String getVariableValue(java.lang.String variableName)
          Returns the value for a variable in the list of variables.
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(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 setFunctions(java.util.Map functions)
          Sets the map of functions for this object.
 void setQuoteCharacter(char quoteCharacter)
          Sets the quote character to use when evaluating expressions.
 void setVariableResolver(VariableResolver variableResolver)
          Sets the variable resolver for this class.
 void setVariables(java.util.Map variables)
          Sets the map of variables for this object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Evaluator

public Evaluator()
The default constructor. This constructor calls the five parameter Evaluator constructor and passes in the following default values: SINGLE_QUOTE, true, true, true and true.


Evaluator

public Evaluator(char quoteCharacter,
                 boolean loadMathVariables,
                 boolean loadMathFunctions,
                 boolean loadStringFunctions,
                 boolean processNestedFunctions)
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.
processNestedFunctions - Indicates if nested function calls should be processed 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(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 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.


getFunctions

public java.util.Map getFunctions()
Rturns the map of functions currently set on this object.

Returns:
the map of functions currently set on this object.

setFunctions

public void setFunctions(java.util.Map functions)
Sets the map of functions for this object.

Parameters:
The - map of functions for this object.

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.

getVariableValue

public java.lang.String getVariableValue(java.lang.String variableName)
                                  throws EvaluationException
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.
Throws:
Throws - an EvaluatorException if the variable name can not be resolved.
EvaluationException

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.


getVariables

public java.util.Map getVariables()
Rturns the map of variables currently set on this object.

Returns:
the map of variables currently set on this object.

setVariables

public void setVariables(java.util.Map variables)
Sets the map of variables for this object.

Parameters:
variables - The map of variables for this object.

getVariableResolver

public VariableResolver getVariableResolver()
Returns the variable resolver. The variable resolver can be used by the user to resolve their own variables. Variables in the variable resolver override any variables that are in this classes internal variable map.

Returns:
The variable resolver.

setVariableResolver

public void setVariableResolver(VariableResolver variableResolver)
Sets the variable resolver for this class. Varaibles resolved by the variable resolver will override any variables in this class's internal variable map.

Parameters:
variableResolver - The variable resolver for this class.

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

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

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


Copyright (C) 2002-2007 Robert Breidecker.