001package com.randomnoun.common.jexl.eval;
002
003/* (c) 2013 randomnoun. All Rights Reserved. This work is licensed under a
004 * BSD Simplified License. (http://www.randomnoun.com/bsd-simplified.html)
005 */
006
007import java.util.*;
008
009import org.apache.log4j.Logger;
010
011
012/**
013 * This class encapsulates a function, which is intended to be placed in an
014 * EvalContext (using EvalContext.setFunctions()). Any
015 * expression evaluated in that context will then be able to invoke developer-defined
016 * functions.
017 *
018 * <pre>
019    Map&lt;String, EvalFunction&gt; functions = new HashMap();
020    functions.put("length", new LengthFunction());
021    functions.put("like", new LikeFunction());
022    EvalContext evalContext = new EvalContext();
023    evalContext.setFunctions(functions);
024 * </pre>
025 *
026 * Some functions can also generate SQL, see
027 * {@link com.randomnoun.common.jexl.sql.SqlFunction}.
028 *
029 * 
030 * @author knoxg
031 */
032public interface EvalFunction
033{
034        /** Logger for this class */
035        public static Logger logger = Logger.getLogger(EvalFunction.class);
036
037    /**
038     * This is the main entry point for classes that implement this interface.
039     * The evaluate method performs the evaluation of the function that this class
040     * implements (and is supplied the functionName, so that the same class may
041     * evaluate multiple functions). 
042     *
043     * @param functionName The name of the function to be evaluated (can be disregarded
044     *   if this class only performs a single function)
045     * @param context The context in which the function is being executed (could hold
046     *   things like local variable values, current line number, etc...)
047     * @param arguments The arguments passed to this function
048     *
049     * @return The result of the evaluation
050     *
051     * @throws EvalException An exception occurred during evaluation
052     */
053    public Object evaluate(String functionName, EvalContext context, List<Object> arguments)
054        throws EvalException;
055}