net.christopherschultz.evaluator
Class StandardFunction

java.lang.Object
  extended by net.christopherschultz.evaluator.StandardFunction
All Implemented Interfaces:
Function
Direct Known Subclasses:
ContainsAllFunction, ContainsAnyFunction, CountMatchesFunction, DistributeFunction, IJWInvocation, IsNullFunction, LengthFunction, MathFunction, MathFunction.max, MathFunction.min, MathFunction.pow, MathFunction.random, MemoryFunction, NewObjectFunction, VariablesFunction

public abstract class StandardFunction
extends Object
implements Function

Implements a Function with standard arugment evaluation semantics.

In most programming languages and expression evaluators, all arguments are evaluated before the call is actually made to the function in question. In FunctionCallExpression, the expressions themselves are passed to the function, leaving those semantics up to the implementing function.

Given that most functions will want their argument expressions evaluated prior to function invocation, this class has been written to provide that service, free of charge.

Simply implement the call(EvaluationContext,String,Object[]) method and register your function with FunctionCallExpression, and you won't have to worry about evaluating your own argument expressions.

If this all seems very silly, you are probably right. However, I have decided to implement mathematical operators as functions, including the logical operators. In order to implement short-circuit boolean evaluation as a function, the ability for a function to evaluate its own arguments allows a function to short-circuit its own argument evaluation.

Version:
$Revision: 1.5 $ $Date: 2008-06-20 22:58:48 $
Author:
Chris Schultz
See Also:
FunctionCallExpression

Constructor Summary
protected StandardFunction()
          Creates a new StandardFunction.
 
Method Summary
 Object call(EvaluationContext ec, String functionName, List argumentExpressions)
           Invokes the function with the specified argument expressions in the specified evaluation context.
abstract  Object call(EvaluationContext ec, String functionName, Object[] arguments)
          Calls this function with standard argument evaluation semantics.
static Object getExpressionValue(EvaluationContext ec, Object expression)
          Gets the value of an expression.
static Object[] getExpressionValueArray(EvaluationContext ec, List expressions)
          Evaluates the specified list of expressions and returns the results in an array.
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

StandardFunction

protected StandardFunction()
Creates a new StandardFunction.

Method Detail

call

public final Object call(EvaluationContext ec,
                         String functionName,
                         List argumentExpressions)
                  throws EvaluationException

Invokes the function with the specified argument expressions in the specified evaluation context.

This function implementation evaluates all argument expressions and then invokes the call(EvaluationContext,String,Object[]) method.

Specified by:
call in interface Function
Parameters:
ec - The EvaluationContext in which this function is being called.
functionName - The name of the function being invoked.
argumentExpressions - The expressions which, when evaluated, result in the arguments to the function.
Returns:
The result of the function.
Throws:
EvaluationException - If there is a problem evaluating any of the arguments' expressions, or if there is an error during function execution.

call

public abstract Object call(EvaluationContext ec,
                            String functionName,
                            Object[] arguments)
                     throws EvaluationException
Calls this function with standard argument evaluation semantics.

Parameters:
ec - The EvaluationContext in which this function is being called.
functionName - The name of the function being invoked.
arguments - The argument values to pass to this function.
Returns:
The result of the function.
Throws:
EvaluationException - If there is an error during function execution.

getExpressionValueArray

public static Object[] getExpressionValueArray(EvaluationContext ec,
                                               List expressions)
                                        throws EvaluationException
Evaluates the specified list of expressions and returns the results in an array. Note that non-expression elements in the list will silently be passed-through to the array.

Parameters:
ec - The context in which the expressions should be evaluated.
expressions - A List of Expressions which should be evaluated.
Returns:
An array of values representing the return values of each expression in expressions, or null if there are no expressions in the expressions list.
Throws:
EvaluationException - If there is a problem evaluating any of the expressions.

getExpressionValue

public static Object getExpressionValue(EvaluationContext ec,
                                        Object expression)
                                 throws EvaluationException
Gets the value of an expression. If the argument expression is not an instance of Expression, then the value is returned unchanged. If the argument is an Expression, then it will be evaluated using the current context and the resulting value will be returned.

Throws:
EvaluationException

toString

public String toString()
Overrides:
toString in class Object