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