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*/
020package org.olap4j;
021
022import java.sql.ResultSet;
023import java.sql.SQLException;
024import 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 */
067public 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