001    /*
002    // $Id: //open/mondrian/src/main/mondrian/spi/UserDefinedFunction.java#8 $
003    // This software is subject to the terms of the Common Public License
004    // Agreement, available at the following URL:
005    // http://www.opensource.org/licenses/cpl.html.
006    // Copyright (C) 2005-2008 Julian Hyde
007    // All Rights Reserved.
008    // You must accept the terms of that agreement to use this software.
009    */
010    package mondrian.spi;
011    
012    import mondrian.olap.*;
013    import mondrian.olap.type.Type;
014    
015    import org.apache.log4j.*;
016    import org.apache.log4j.Category;
017    
018    /**
019     * Definition of a user-defined function.
020     *
021     * <p>The class must have a public, zero-arguments constructor, be on
022     * Mondrian's runtime class-path, and be referenced from the schema file:
023     *
024     * <blockquote><code>
025     * &lt;Schema&gt;<br/>
026     * &nbsp;&nbsp;&nbsp;&nbsp;....<br/>
027     * &nbsp;&nbsp;&nbsp;&nbsp;&lt;UserDefinedFunction name="MyFun" class="com.acme.MyFun"&gt;<br/>
028     * &lt;/Schema&gt;</code></blockquote>
029     *
030     * @author jhyde
031     * @version $Id: //open/mondrian/src/main/mondrian/spi/UserDefinedFunction.java#8 $
032     */
033    public interface UserDefinedFunction {
034        /**
035         * Returns the name with which the user-defined function will be used
036         * from within MDX expressions.
037         */
038        public String getName();
039    
040        /**
041         * Returns a description of the user-defined function.
042         */
043        public String getDescription();
044    
045        /**
046         * Returns the syntactic type of the user-defined function.
047         * Usually {@link Syntax#Function}.
048         */
049        public Syntax getSyntax();
050    
051        /**
052         * Returns an array of the types of the parameters of this function.
053         */
054        public Type[] getParameterTypes();
055    
056        /**
057         * Returns the return-type of this function.
058         * @param parameterTypes
059         */
060        public Type getReturnType(Type[] parameterTypes);
061    
062        /**
063         * Applies this function to a set of arguments, and returns a result.
064         *
065         * @param evaluator Evaluator containts the runtime context, in particular
066         *   the current member of each dimension.
067         * @param arguments Expressions which yield the arguments of this function.
068         *   Most user-defined functions will evaluate all arguments before using
069         *   them. Functions such as <code>IIf</code> do not evaluate all
070         *   arguments; this technique is called <dfn>lazy evaluation</dfn>.
071         * @return The result value.
072         */
073        public Object execute(Evaluator evaluator, Argument[] arguments);
074    
075        /**
076         * Returns a list of reserved words used by this function.
077         * May return an empty array or null if this function does not require
078         * any reserved words.
079         */
080        public String[] getReservedWords();
081    
082        interface Argument {
083    
084            Object evaluateScalar(Evaluator evaluator);
085    
086            Object evaluate(Evaluator evaluator);
087    
088            Type getType();
089        }
090    }
091    
092    // End UserDefinedFunction.java