001    /*
002    // $Id: CellSet.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 java.sql.ResultSet;
023    import java.sql.SQLException;
024    import java.util.List;
025    
026    /**
027     * Result of executing an OLAP Statement.
028     *
029     * <p>A <code>CellSet</code> consists of a set of (typically two) axes,
030     * each populated with a sequence of members, and a collection of cells at the
031     * intersection of these axes.
032     *
033     * <p><b>Cell ordinals and coordinates</b></p>
034     *
035     * <p>There are two ways to identify a particular cell: ordinal and coordinates.
036     * Suppose that there are <code>p</code> axes, and each axis <code>k</code>
037     * (<code>k</code> between 0 and <code>p - 1</code>) has
038     * <code>U<sub>k</sub></code> positions.
039     * There are <code>U</code>
040     * = <code>U<sub>0</sub> * ... * U<sub>p - 1</sub></code> cells in total.
041     * Then:<ul>
042     * <li>A cell's <code>ordinal</code> is an integer between 0 and
043     *     <code>U - 1</code>.</li>
044     * <li>A cell's <code>coordinates</code> are a list of <code>p</code> integers,
045     *     indicating the cell's position on each axis.
046     *     Each integer is between 0 and <code>U<sub>p</sub>-1</code>.</li>
047     * </ul>
048     *
049     * <p>The ordinal number of a cell whose tuple ordinals are
050     * <code>(S<sub>0</sub>, S<sub>1</sub>, ... S<sub>p-1</sub>)</code> is
051     * <blockquote>
052     * <code>
053     * &#931;<sub>i=0</sub><sup>p-1</sup> S<sub>i</sub> . E<sub>i</sub>
054     * </code>
055     * where
056     * <code>E<sub>0</sub> = 1</code>
057     * and
058     * <code>
059     * E<sub>i</sub> = &#928;<sub>i=0</sub><sup>p-1</sup> U<sub>k</sub>
060     * </code>
061     * </blockquote></p>
062     *
063     * @author jhyde
064     * @version $Id: CellSet.java 482 2012-01-05 23:27:27Z jhyde $
065     * @since Aug 22, 2006
066     */
067    public interface CellSet extends ResultSet, OlapWrapper {
068    
069        /**
070         * Retrieves the <code>OlapStatement</code> object that produced this
071         * <code>CellSet</code> object.
072         * If the result set was generated some other way, such as by a
073         * {@link org.olap4j.OlapDatabaseMetaData} method, this method may return
074         * <code>null</code>.
075         *
076         * @return the <code>OlapStatment</code> object that produced
077         * this <code>CellSet</code> object or <code>null</code>
078         * if the cell set was produced some other way
079         *
080         * @exception SQLException if a database access error occurs
081         * or this method is called on a closed cell set
082         */
083        OlapStatement getStatement() throws SQLException;
084    
085        /**
086         * Retrieves the description of this <code>CellSet</code>'s axes
087         * and cells.
088         *
089         * @return the description of this <code>CellSet</code>'s axes
090         * and cells
091         * @exception OlapException if a database access error occurs
092         */
093        CellSetMetaData getMetaData() throws OlapException;
094    
095        /**
096         * Retrieves a list of CellSetAxis objects containing the result.
097         *
098         * <p>The list contains axes according to their ordinal: 0 is the columns
099         * axis, 1 the rows axis, and so forth.
100         *
101         * @return list of CellSetAxis objects containing the result
102         *
103         * @see #getFilterAxis()
104         */
105        List<CellSetAxis> getAxes();
106    
107        /**
108         * Retrieves the CellSetAxis representing the filter axis.
109         *
110         * <p>If the query has a WHERE clause, the contains the members returned
111         * by that expression. Most query authors write a WHERE clause so that it
112         * evaluates to just one member or tuple. The members in this tuple (or
113         * the sole member), are referred to as the 'slicer context' of the query.
114         * The tuple contains only members of hierarchies explicitly mentioned in
115         * the WHERE expression; the slicer context of every hierarchy in the
116         * query's cube is implicitly the default member of that hierarchy.
117         *
118         * <p>While not typical, note that a query's WHERE clause may also evaluate
119         * to zero or more than one tuples.
120         *
121         * <p>If the query has no WHERE clause, the filter axis has a single
122         * position, but the position has no members.
123         *
124         * <p>The filter axis is not included in the {@link #getAxes()} collection.
125         *
126         * @return the filter axis
127         */
128        CellSetAxis getFilterAxis();
129    
130        /**
131         * Returns the Cell at a given set of coordinates.
132         *
133         * @param coordinates List of 0-based coordinates of the cell
134         *
135         * @return Cell
136         *
137         * @throws IndexOutOfBoundsException if coordinates are outside CellSet
138         * bounds
139         */
140        Cell getCell(List<Integer> coordinates);
141    
142        /**
143         * Returns the Cell at an ordinal.
144         *
145         * <p>Equivalent to
146         *
147         * <blockquote><code>
148         * getCell(ordinalToCoordinates(ordinal))
149         * </code></blockquote>
150         *
151         * @param ordinal 0-based ordinal of the cell
152         *
153         * @return Cell
154         *
155         * @throws IndexOutOfBoundsException if ordinal lies outside CellSet bounds
156         */
157        Cell getCell(int ordinal);
158    
159        /**
160         * Returns the Cell at the intersection of a set of axis positions.
161         *
162         * <p>Equivalent to
163         *
164         * <blockquote><pre><code>
165         * getCell(
166         *     Arrays.asList(
167         *         positions[0].ordinal(),
168         *         positions[1].ordinal() [, ...]))
169         * </code></pre></blockquote>
170         *
171         * @param positions Array of positions
172         *
173         * @return Cell
174         *
175         * @throws IllegalArgumentException if positions does not have the same
176         * number of members as the cell set has axes
177         *
178         * @throws IndexOutOfBoundsException if positions lie outside CellSet
179         * bounds
180         */
181        Cell getCell(Position... positions);
182    
183        /**
184         * Converts a cell ordinal to a list of cell coordinates.
185         *
186         * @param ordinal Cell ordinal
187         * @return Cell coordinates
188         */
189        List<Integer> ordinalToCoordinates(int ordinal);
190    
191        /**
192         * Converts a list of cell coordinates to a cell ordinal.
193         *
194         * @param coordinates Cell coordinates
195         * @return Cell ordinal
196         */
197        int coordinatesToOrdinal(List<Integer> coordinates);
198    
199    }
200    
201    // End CellSet.java