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