001 /*
002 // $Id: PreparedOlapStatement.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 */
020 package org.olap4j;
021
022 import org.olap4j.metadata.Cube;
023
024 import java.sql.PreparedStatement;
025 import java.sql.SQLException;
026
027 /**
028 * An object that represents a precompiled OLAP statement.
029 *
030 * <p>An OLAP statement is precompiled and stored in a
031 * <code>PreparedOlapStatement</code> object. This object can then be used to
032 * efficiently execute this statement multiple times.</p>
033 *
034 * <p>A <code>PreparedOlapStatement</code> is generally created using
035 * {@link OlapConnection#prepareOlapStatement(String)}.</p>
036 *
037 * <p><B>Note:</B> The setter methods (<code>setShort</code>,
038 * <code>setString</code>, and so on) for setting IN parameter values
039 * must specify types that are compatible with the defined type of
040 * the input parameter. For instance, if the IN parameter has type
041 * <code>INTEGER</code>, then the method <code>setInt</code> should be used.</p>
042 *
043 * <p>If a parameter has Member type, use the {@link #setObject(int, Object)}
044 * method to set it. A {@link OlapException} will be thrown if the object is not
045 * an instance of {@link org.olap4j.metadata.Member} or does not belong to the
046 * correct {@link org.olap4j.metadata.Hierarchy}.</p>
047 *
048 * <p>The method {@link #getParameterMetaData()} returns a description of the
049 * parameters, as in JDBC. The result is an {@link OlapParameterMetaData}.
050 *
051 * <p>Unlike JDBC, it is not necessary to assign a value to every parameter.
052 * This is because OLAP parameters have a default value. Parameters have their
053 * default value until they are set, and then retain their new values for each
054 * subsequent execution of this <code>PreparedOlapStatement</code>.
055 *
056 * @see OlapConnection#prepareOlapStatement(String)
057 * @see CellSet
058 *
059 * @author jhyde
060 * @version $Id: PreparedOlapStatement.java 482 2012-01-05 23:27:27Z jhyde $
061 * @since Aug 22, 2006
062 */
063 public interface PreparedOlapStatement
064 extends PreparedStatement, OlapStatement
065 {
066 /**
067 * Executes the MDX query in this <code>PreparedOlapStatement</code> object
068 * and returns the <code>CellSet</code> object generated by the query.
069 *
070 * @return an <code>CellSet</code> object that contains the data produced
071 * by the query; never <code>null</code>
072 * @exception OlapException if a database access error occurs
073 */
074 CellSet executeQuery() throws OlapException;
075
076 /**
077 * Retrieves the number, types and properties of this
078 * <code>PreparedOlapStatement</code> object's parameters.
079 *
080 * @return an <code>OlapParameterMetaData</code> object that contains
081 * information about the number, types and properties of this
082 * <code>PreparedOlapStatement</code> object's parameters
083 * @exception OlapException if a database access error occurs
084 * @see OlapParameterMetaData
085 */
086 OlapParameterMetaData getParameterMetaData() throws OlapException;
087
088 /**
089 * Retrieves a <code>CellSetMetaData</code> object that contains
090 * information about the axes and cells of the <code>CellSet</code> object
091 * that will be returned when this <code>PreparedOlapStatement</code> object
092 * is executed.
093 *
094 * @return the description of this <code>CellSet</code>'s axes
095 * and cells
096 * @exception OlapException if a database access error occurs
097 */
098 CellSetMetaData getMetaData() throws SQLException;
099
100 /**
101 * Returns the cube (or virtual cube) which this statement is based upon.
102 *
103 * @return cube this statement is based upon
104 */
105 Cube getCube();
106
107 /**
108 * Returns whether the value of the designated parameter is set.
109 *
110 * <p>Note that you cannot tell whether the parameter is set by looking to
111 * see whether the value is {@code null}, because {@code null} is a valid
112 * parameter value. When a parameter is not set, its value is derived by
113 * evaluating its default expression.
114 *
115 * <p>To set the value call one of the {@link #setObject setXxx} methods. To
116 * unset the value, call {@link #unset}.
117 *
118 * @param parameterIndex the first parameter is 1, the second is 2, ...
119 * @return whether the parameter's value has been set
120 * @exception java.sql.SQLException if a database access error occurs
121 */
122 boolean isSet(int parameterIndex) throws SQLException;
123
124 /**
125 * Unsets the value of the designated parameter.
126 *
127 * @see #isSet(int)
128 *
129 * @param parameterIndex the first parameter is 1, the second is 2, ...
130 * @exception java.sql.SQLException if a database access error occurs
131 */
132 void unset(int parameterIndex) throws SQLException;
133 }
134
135 // End PreparedOlapStatement.java