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