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