001/*
002// $Id: OlapStatement.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;
021
022import org.olap4j.mdx.SelectNode;
023
024import java.sql.SQLException;
025import java.sql.Statement;
026
027/**
028 * Object used for statically executing an MDX statement and returning a
029 * {@link CellSet}.
030 *
031 * <p>An <code>OlapStatement</code> is generally created using
032 * {@link OlapConnection#createStatement()}.</p>
033 *
034 * @see PreparedOlapStatement
035 *
036 * @author jhyde
037 * @version $Id: OlapStatement.java 482 2012-01-05 23:27:27Z jhyde $
038 * @since Aug 22, 2006
039 */
040public interface OlapStatement extends Statement, OlapWrapper {
041
042    /**
043     * Retrieves the <code>OlapConnection</code> object
044     * that produced this <code>OlapStatement</code> object.
045     */
046    OlapConnection getConnection() throws SQLException;
047
048    /**
049     * Executes an OLAP statement.
050     *
051     * @param mdx MDX <code>SELECT</code> statement
052     *
053     * @return Cell set
054     *
055     * @throws OlapException if a database access error occurs,
056     * this method is called on a closed <code>OlapStatement</code>,
057     * the query times out (see {@link #setQueryTimeout(int)})
058     * or another thread cancels the statement (see {@link #cancel()})
059     */
060    CellSet executeOlapQuery(String mdx) throws OlapException;
061
062    /**
063     * Executes an OLAP statement expressed as a parse tree.
064     *
065     * <p>Validates the parse tree before executing it.
066     *
067     * @param selectNode Parse tree of MDX <code>SELECT</code> statement
068     *
069     * @return Cell set
070     *
071     * @throws OlapException if a database access error occurs,
072     * this method is called on a closed <code>OlapStatement</code>,
073     * the query times out (see {@link #setQueryTimeout(int)})
074     * or another thread cancels the statement (see {@link #cancel()})
075     */
076    CellSet executeOlapQuery(SelectNode selectNode) throws OlapException;
077
078    /**
079     * Adds a listener to be notified of events to {@link CellSet}s created by
080     * this statement.
081     *
082     * <p>NOTE: You may wonder why this method belongs to the
083     * {@link OlapStatement} class and not {@code CellSet}. If the method
084     * belonged to {@code CellSet} there would be a window between creation and
085     * registering a listener during which events might be lost, whereas
086     * registering the listener with the statement ensures that the listener is
087     * attached immediately that the cell set is opened. It follows that
088     * registering a listener does not affect the cell set <em>currently
089     * open</em> (if any), and that no events will be received if the statement
090     * has no open cell sets.
091     *
092     * @param granularity Granularity of cell set events to listen for
093     *
094     * @param listener Listener to be notified of changes
095     *
096     * @throws OlapException if granularity is not one supported by this server,
097     *   per the
098     *   {@link OlapDatabaseMetaData#getSupportedCellSetListenerGranularities()}
099     *   method
100     */
101    void addListener(
102        CellSetListener.Granularity granularity,
103        CellSetListener listener)
104        throws OlapException;
105}
106
107// End OlapStatement.java