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