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