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    */
020    package org.olap4j;
021    
022    import org.olap4j.mdx.SelectNode;
023    
024    import java.sql.SQLException;
025    import 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     */
040    public 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