001 /*
002 // $Id: OlapStatement.java 367 2010-11-16 18:54:39Z jhyde $
003 // This software is subject to the terms of the Eclipse Public License v1.0
004 // Agreement, available at the following URL:
005 // http://www.eclipse.org/legal/epl-v10.html.
006 // Copyright (C) 2006-2010 Julian Hyde
007 // All Rights Reserved.
008 // You must accept the terms of that agreement to use this software.
009 */
010 package org.olap4j;
011
012 import java.sql.SQLException;
013 import java.sql.Statement;
014
015 import org.olap4j.mdx.SelectNode;
016
017 /**
018 * Object used for statically executing an MDX statement and returning a
019 * {@link CellSet}.
020 *
021 * <p>An <code>OlapStatement</code> is generally created using
022 * {@link OlapConnection#createStatement()}.</p>
023 *
024 * @see PreparedOlapStatement
025 *
026 * @author jhyde
027 * @version $Id: OlapStatement.java 367 2010-11-16 18:54:39Z jhyde $
028 * @since Aug 22, 2006
029 */
030 public interface OlapStatement extends Statement, OlapWrapper {
031
032 /**
033 * Retrieves the <code>OlapConnection</code> object
034 * that produced this <code>OlapStatement</code> object.
035 */
036 OlapConnection getConnection() throws SQLException;
037
038 /**
039 * Executes an OLAP statement.
040 *
041 * @param mdx MDX <code>SELECT</code> statement
042 *
043 * @return Cell set
044 *
045 * @throws OlapException if a database access error occurs,
046 * this method is called on a closed <code>OlapStatement</code>,
047 * the query times out (see {@link #setQueryTimeout(int)})
048 * or another thread cancels the statement (see {@link #cancel()})
049 */
050 CellSet executeOlapQuery(String mdx) throws OlapException;
051
052 /**
053 * Executes an OLAP statement expressed as a parse tree.
054 *
055 * <p>Validates the parse tree before executing it.
056 *
057 * @param selectNode Parse tree of MDX <code>SELECT</code> statement
058 *
059 * @return Cell set
060 *
061 * @throws OlapException if a database access error occurs,
062 * this method is called on a closed <code>OlapStatement</code>,
063 * the query times out (see {@link #setQueryTimeout(int)})
064 * or another thread cancels the statement (see {@link #cancel()})
065 */
066 CellSet executeOlapQuery(SelectNode selectNode) throws OlapException;
067
068 /**
069 * Adds a listener to be notified of events to {@link CellSet}s created by
070 * this statement.
071 *
072 * <p>NOTE: You may wonder why this method belongs to the
073 * {@link OlapStatement} class and not {@code CellSet}. If the method
074 * belonged to {@code CellSet} there would be a window between creation and
075 * registering a listener during which events might be lost, whereas
076 * registering the listener with the statement ensures that the listener is
077 * attached immediately that the cell set is opened. It follows that
078 * registering a listener does not affect the cell set <em>currently
079 * open</em> (if any), and that no events will be received if the statement
080 * has no open cell sets.
081 *
082 * @param granularity Granularity of cell set events to listen for
083 *
084 * @param listener Listener to be notified of changes
085 *
086 * @throws OlapException if granularity is not one supported by this server,
087 * per the
088 * {@link OlapDatabaseMetaData#getSupportedCellSetListenerGranularities()}
089 * method
090 */
091 void addListener(
092 CellSetListener.Granularity granularity,
093 CellSetListener listener)
094 throws OlapException;
095 }
096
097 // End OlapStatement.java