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