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