001/*
002// $Id: MdxParser.java 482 2012-01-05 23:27:27Z jhyde $
003//
004// Licensed to Julian Hyde under one or more contributor license
005// agreements. See the NOTICE file distributed with this work for
006// additional information regarding copyright ownership.
007//
008// Julian Hyde licenses this file to you under the Apache License,
009// Version 2.0 (the "License"); you may not use this file except in
010// compliance with the License. You may obtain a copy of the License at:
011//
012// http://www.apache.org/licenses/LICENSE-2.0
013//
014// Unless required by applicable law or agreed to in writing, software
015// distributed under the License is distributed on an "AS IS" BASIS,
016// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017// See the License for the specific language governing permissions and
018// limitations under the License.
019*/
020package org.olap4j.mdx.parser;
021
022import org.olap4j.mdx.ParseTreeNode;
023import org.olap4j.mdx.SelectNode;
024
025/**
026 * Parser for the MDX query language.
027 *
028 * <p>A parser is reusable but not reentrant: you can call {@link #parseSelect}
029 * and {@link #parseExpression} several times, but not at the same time
030 * from different threads.
031 *
032 * @see MdxParserFactory
033 *
034 * @author jhyde
035 * @version $Id: MdxParser.java 482 2012-01-05 23:27:27Z jhyde $
036 * @since Aug 22, 2006
037 */
038public interface MdxParser {
039    /**
040     * Parses an MDX Select statement and returns the {@link SelectNode} at the
041     * root of the parse tree.
042     *
043     * <p>In order to be parsed successfully, the expression must be
044     * syntactically correct but does not need to be valid. (Syntactic
045     * correctness and validity are described further in the description of
046     * {@link #parseExpression(String)}.)
047     *
048     * @param mdx MDX query string
049     * @return Parse tree
050     */
051    SelectNode parseSelect(String mdx);
052
053    /**
054     * Parses an MDX expression and returns a parse tree.
055     *
056     * <p>An expression is a combination of operators and operands, which can
057     * occur in many places inside an MDX query, such as the definition of a
058     * calculated member or an axis.
059     *
060     * <p>In order to be parsed successfully, the expression must be
061     * syntactically correct but does not need to be valid.
062     * For example,
063     *
064     * <blockquote><code>(1 + (2 + 3)</code></blockquote>
065     *
066     * is syntactically incorrect,
067     * because there are more open parentheses "(" than close parentheses ")",
068     * and the parser will give an error. Conversely,
069     *
070     * <blockquote><code>(1 + [Measures].[Bad Measure])</code></blockquote>
071     *
072     * is syntactically correct, and the parser
073     * will successfully create a parse tree, even if
074     * <code>[Measures].[Bad Measure]</code> does not exist.
075     *
076     * @param mdx MDX expression
077     * @return Parse tree
078     */
079    ParseTreeNode parseExpression(String mdx);
080}
081
082// End MdxParser.java