001 /* 002 // $Id: PreparedOlapStatement.java 229 2009-05-08 19:11:29Z 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-2008 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 org.olap4j.metadata.Cube; 013 014 import java.sql.PreparedStatement; 015 import java.sql.SQLException; 016 017 /** 018 * An object that represents a precompiled OLAP statement. 019 * 020 * <p>An OLAP statement is precompiled and stored in a 021 * <code>PreparedOlapStatement</code> object. This object can then be used to 022 * efficiently execute this statement multiple times.</p> 023 * 024 * <p>A <code>PreparedOlapStatement</code> is generally created using 025 * {@link OlapConnection#prepareOlapStatement(String)}.</p> 026 * 027 * <p><B>Note:</B> The setter methods (<code>setShort</code>, 028 * <code>setString</code>, and so on) for setting IN parameter values 029 * must specify types that are compatible with the defined type of 030 * the input parameter. For instance, if the IN parameter has type 031 * <code>INTEGER</code>, then the method <code>setInt</code> should be used.</p> 032 * 033 * <p>If a parameter has Member type, use the {@link #setObject(int, Object)} 034 * method to set it. A {@link OlapException} will be thrown if the object is not 035 * an instance of {@link org.olap4j.metadata.Member} or does not belong to the 036 * correct {@link org.olap4j.metadata.Hierarchy}.</p> 037 * 038 * <p>The method {@link #getParameterMetaData()} returns a description of the 039 * parameters, as in JDBC. The result is an {@link OlapParameterMetaData}. 040 * 041 * <p>Unlike JDBC, it is not necessary to assign a value to every parameter. 042 * This is because OLAP parameters have a default value. Parameters have their 043 * default value until they are set, and then retain their new values for each 044 * subsequent execution of this <code>PreparedOlapStatement</code>. 045 * 046 * @see OlapConnection#prepareOlapStatement(String) 047 * @see CellSet 048 * 049 * @author jhyde 050 * @version $Id: PreparedOlapStatement.java 229 2009-05-08 19:11:29Z jhyde $ 051 * @since Aug 22, 2006 052 */ 053 public interface PreparedOlapStatement 054 extends PreparedStatement, OlapStatement 055 { 056 /** 057 * Executes the MDX query in this <code>PreparedOlapStatement</code> object 058 * and returns the <code>CellSet</code> object generated by the query. 059 * 060 * @return an <code>CellSet</code> object that contains the data produced 061 * by the query; never <code>null</code> 062 * @exception OlapException if a database access error occurs 063 */ 064 CellSet executeQuery() throws OlapException; 065 066 /** 067 * Retrieves the number, types and properties of this 068 * <code>PreparedOlapStatement</code> object's parameters. 069 * 070 * @return an <code>OlapParameterMetaData</code> object that contains 071 * information about the number, types and properties of this 072 * <code>PreparedOlapStatement</code> object's parameters 073 * @exception OlapException if a database access error occurs 074 * @see OlapParameterMetaData 075 */ 076 OlapParameterMetaData getParameterMetaData() throws OlapException; 077 078 /** 079 * Retrieves a <code>CellSetMetaData</code> object that contains 080 * information about the axes and cells of the <code>CellSet</code> object 081 * that will be returned when this <code>PreparedOlapStatement</code> object 082 * is executed. 083 * 084 * @return the description of this <code>CellSet</code>'s axes 085 * and cells 086 * @exception OlapException if a database access error occurs 087 */ 088 CellSetMetaData getMetaData() throws SQLException; 089 090 /** 091 * Returns the cube (or virtual cube) which this statement is based upon. 092 * 093 * @return cube this statement is based upon 094 */ 095 Cube getCube(); 096 097 } 098 099 // End PreparedOlapStatement.java