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 * Σ<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> = Π<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