001/*
002// This software is subject to the terms of the Eclipse Public License v1.0
003// Agreement, available at the following URL:
004// http://www.eclipse.org/legal/epl-v10.html.
005// You must accept the terms of that agreement to use this software.
006//
007// Copyright (C) 2002-2005 Julian Hyde
008// Copyright (C) 2005-2009 Pentaho and others
009// All Rights Reserved.
010*/
011package mondrian.olap.fun;
012
013import mondrian.olap.*;
014
015import java.util.List;
016
017/**
018 * A <code>Resolver</code> converts a function name, invocation type, and set
019 * of arguments into a {@link FunDef}.
020 *
021 * @author jhyde
022 * @since 3 March, 2002
023 */
024public interface Resolver {
025    /**
026     * Returns the name of the function or operator.
027     */
028    String getName();
029
030    /**
031     * Returns the description of the function or operator.
032     */
033    String getDescription();
034
035    /**
036     * Returns the syntax with which the function or operator was invoked.
037     */
038    Syntax getSyntax();
039
040    /**
041     * Given a particular set of arguments the function is applied to, returns
042     * the correct overloaded form of the function.
043     *
044     * <p>The method adds an item to <code>conversions</code> every
045     * time it performs an implicit type-conversion. If there are several
046     * candidate functions with the same signature, the validator will choose
047     * the one which used the fewest implicit conversions.</p>
048     *
049     * @param args Expressions which this function call is applied to.
050     * @param validator Validator
051     * @param conversions List of implicit conversions performed (out)
052     *
053     * @return The function definition which matches these arguments, or null
054     *   if no function definition that this resolver knows about matches.
055     */
056    FunDef resolve(
057        Exp[] args,
058        Validator validator,
059        List<Conversion> conversions);
060
061    /**
062     * Returns whether a particular argument must be a scalar expression.
063     * Returns <code>false</code> if any of the variants of this resolver
064     * allows a set as its <code>k</code>th argument; true otherwise.
065     */
066    boolean requiresExpression(int k);
067
068    /**
069     * Returns an array of symbolic constants which can appear as arguments
070     * to this function.
071     *
072     * <p>For example, the <code>DrilldownMember</code> may take the symbol
073     * <code>RECURSIVE</code> as an argument. Most functions do not define
074     * any symbolic constants.
075     *
076     * @return An array of the names of the symbolic constants
077     */
078    String[] getReservedWords();
079
080    /**
081     * Returns a string describing the syntax of this function, for example
082     * <pre><code>StrToSet(<String Expression>)</code></pre>
083     */
084    String getSignature();
085
086    /**
087     * Returns a representative example of the function which this Resolver
088     * can produce, for purposes of describing the function set. May return
089     * null if there is no representative function, or if the Resolver has
090     * a way to describe itself in more detail.
091     */
092    FunDef getFunDef();
093
094    /**
095     * Description of an implicit conversion that occurred while resolving an
096     * operator call.
097     */
098    public interface Conversion {
099        /**
100         * Returns the cost of the conversion. If there are several matching
101         * overloads, the one with the lowest overall cost will be preferred.
102         *
103         * @return Cost of conversion
104         */
105        int getCost();
106
107        /**
108         * Checks the viability of implicit conversions. Converting from a
109         * dimension to a hierarchy is valid if is only one hierarchy.
110         */
111        void checkValid();
112
113        /**
114         * Applies this conversion to its argument, modifying the argument list
115         * in place.
116         *
117         * @param validator Validator
118         * @param args Argument list
119         */
120        void apply(Validator validator, List<Exp> args);
121    }
122}
123
124// End Resolver.java