001/*
002// Licensed to Julian Hyde under one or more contributor license
003// agreements. See the NOTICE file distributed with this work for
004// additional information regarding copyright ownership.
005//
006// Julian Hyde licenses this file to you under the Apache License,
007// Version 2.0 (the "License"); you may not use this file except in
008// compliance with the License. You may obtain a copy of the License at:
009//
010// http://www.apache.org/licenses/LICENSE-2.0
011//
012// Unless required by applicable law or agreed to in writing, software
013// distributed under the License is distributed on an "AS IS" BASIS,
014// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015// See the License for the specific language governing permissions and
016// limitations under the License.
017*/
018package org.olap4j;
019
020import org.olap4j.metadata.Cube;
021
022import java.sql.PreparedStatement;
023import java.sql.SQLException;
024
025/**
026 * An object that represents a precompiled OLAP statement.
027 *
028 * <p>An OLAP statement is precompiled and stored in a
029 * <code>PreparedOlapStatement</code> object. This object can then be used to
030 * efficiently execute this statement multiple times.</p>
031 *
032 * <p>A <code>PreparedOlapStatement</code> is generally created using
033 * {@link OlapConnection#prepareOlapStatement(String)}.</p>
034 *
035 * <p><B>Note:</B> The setter methods (<code>setShort</code>,
036 * <code>setString</code>, and so on) for setting IN parameter values
037 * must specify types that are compatible with the defined type of
038 * the input parameter. For instance, if the IN parameter has type
039 * <code>INTEGER</code>, then the method <code>setInt</code> should be used.</p>
040 *
041 * <p>If a parameter has Member type, use the {@link #setObject(int, Object)}
042 * method to set it. A {@link OlapException} will be thrown if the object is not
043 * an instance of {@link org.olap4j.metadata.Member} or does not belong to the
044 * correct {@link org.olap4j.metadata.Hierarchy}.</p>
045 *
046 * <p>The method {@link #getParameterMetaData()} returns a description of the
047 * parameters, as in JDBC. The result is an {@link OlapParameterMetaData}.
048 *
049 * <p>Unlike JDBC, it is not necessary to assign a value to every parameter.
050 * This is because OLAP parameters have a default value. Parameters have their
051 * default value until they are set, and then retain their new values for each
052 * subsequent execution of this <code>PreparedOlapStatement</code>.
053 *
054 * @see OlapConnection#prepareOlapStatement(String)
055 * @see CellSet
056*
057 * @author jhyde
058 * @since Aug 22, 2006
059 */
060public interface PreparedOlapStatement
061    extends PreparedStatement, OlapStatement
062{
063    /**
064     * Executes the MDX query in this <code>PreparedOlapStatement</code> object
065     * and returns the <code>CellSet</code> object generated by the query.
066     *
067     * @return an <code>CellSet</code> object that contains the data produced
068     *         by the query; never <code>null</code>
069     * @exception OlapException if a database access error occurs
070     */
071    CellSet executeQuery()  throws OlapException;
072
073    /**
074     * Retrieves the number, types and properties of this
075     * <code>PreparedOlapStatement</code> object's parameters.
076     *
077     * @return an <code>OlapParameterMetaData</code> object that contains
078     *         information about the number, types and properties of this
079     *         <code>PreparedOlapStatement</code> object's parameters
080     * @exception OlapException if a database access error occurs
081     * @see OlapParameterMetaData
082     */
083    OlapParameterMetaData getParameterMetaData() throws OlapException;
084
085    /**
086     * Retrieves a <code>CellSetMetaData</code> object that contains
087     * information about the axes and cells of the <code>CellSet</code> object
088     * that will be returned when this <code>PreparedOlapStatement</code> object
089     * is executed.
090     *
091     * @return the description of this <code>CellSet</code>'s axes
092     * and cells
093     * @exception OlapException if a database access error occurs
094     */
095    CellSetMetaData getMetaData() throws SQLException;
096
097    /**
098     * Returns the cube (or virtual cube) which this statement is based upon.
099     *
100     * @return cube this statement is based upon
101     */
102    Cube getCube();
103
104    /**
105     * Returns whether the value of the designated parameter is set.
106     *
107     * <p>Note that you cannot tell whether the parameter is set by looking to
108     * see whether the value is {@code null}, because {@code null} is a valid
109     * parameter value. When a parameter is not set, its value is derived by
110     * evaluating its default expression.
111     *
112     * <p>To set the value call one of the {@link #setObject setXxx} methods. To
113     * unset the value, call {@link #unset}.
114     *
115     * @param parameterIndex the first parameter is 1, the second is 2, ...
116     * @return whether the parameter's value has been set
117     * @exception java.sql.SQLException if a database access error occurs
118     */
119    boolean isSet(int parameterIndex) throws SQLException;
120
121    /**
122     * Unsets the value of the designated parameter.
123     *
124     * @see #isSet(int)
125     *
126     * @param parameterIndex the first parameter is 1, the second is 2, ...
127     * @exception java.sql.SQLException if a database access error occurs
128     */
129    void unset(int parameterIndex) throws SQLException;
130}
131
132// End PreparedOlapStatement.java