001 /*
002 // $Id: CellSet.java 229 2009-05-08 19:11:29Z 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-2008 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.util.List;
013 import java.sql.ResultSet;
014
015 /**
016 * Result of executing an OLAP Statement.
017 *
018 * <p>An <codeOlapResultSet</code> consists of a set of (typically two) axes,
019 * each populated with a sequence of members, and a collection of cells at the
020 * intersection of these axes.
021 *
022 * <p><b>Cell ordinals and coordinates</b></p>
023 *
024 * <p>There are two ways to identify a particular cell: ordinal and coordinates.
025 * Suppose that there are <code>p</code> axes, and each axis <code>k</code>
026 * (<code>k</code> between 0 and <code>p - 1</code>) has
027 * <code>U<sub>k</sub></code> positions.
028 * There are <code>U</code>
029 * = <code>U<sub>0</sub> * ... * U<sub>p - 1</sub></code> cells in total.
030 * Then:<ul>
031 * <li>A cell's <code>ordinal</code> is an integer between 0 and
032 * <code>U - 1</code>.</li>
033 * <li>A cell's <code>coordinates</code> are a list of <code>p</code> integers,
034 * indicating the cell's position on each axis.
035 * Each integer is between 0 and <code>U<sub>p</sub>-1</code>.</li>
036 * </ul>
037 *
038 * <p>The ordinal number of a cell whose tuple ordinals are
039 * <code>(S<sub>0</sub>, S<sub>1</sub>, ... S<sub>p-1</sub>)</code> is
040 * <blockquote>
041 * <code>
042 * Σ<sub>i=0</sub><sup>p-1</sup> S<sub>i</sub> . E<sub>i</sub>
043 * </code>
044 * where
045 * <code>E<sub>0</sub> = 1</code>
046 * and
047 * <code>
048 * E<sub>i</sub> = Π<sub>i=0</sub><sup>p-1</sup> U<sub>k</sub>
049 * </code>
050 * </blockquote></p>
051 *
052 * @author jhyde
053 * @version $Id: CellSet.java 229 2009-05-08 19:11:29Z jhyde $
054 * @since Aug 22, 2006
055 */
056 public interface CellSet extends ResultSet, OlapWrapper {
057 /**
058 * Retrieves the description of this <code>CellSet</code>'s axes
059 * and cells.
060 *
061 * @return the description of this <code>CellSet</code>'s axes
062 * and cells
063 * @exception OlapException if a database access error occurs
064 */
065 CellSetMetaData getMetaData() throws OlapException;
066
067 /**
068 * Retrieves a list of CellSetAxis objects containing the result.
069 *
070 * <p>The list contains axes according to their ordinal: 0 is the columns
071 * axis, 1 the rows axis, and so forth.
072 *
073 * @return list of CellSetAxis objects containing the result
074 */
075 List<CellSetAxis> getAxes();
076
077 /**
078 * Retrieves the CellSetAxis representing the filter axis.
079 *
080 * <p>This axis always has one row, and contains one member for each
081 * dimension not included in any other axis. Some of these dimensions may
082 * have been explicitly mentioned in the WHERE clause of the MDX statement;
083 * others dimensions are represented by their default member.
084 *
085 * @return the filter axis
086 */
087 CellSetAxis getFilterAxis();
088
089 /**
090 * Returns the Cell at a given set of coordinates.
091 *
092 * @param coordinates List of 0-based coordinates of the cell
093 *
094 * @return Cell
095 *
096 * @throws IndexOutOfBoundsException if coordinates are outside CellSet
097 * bounds
098 */
099 Cell getCell(List<Integer> coordinates);
100
101 /**
102 * Returns the Cell at an ordinal.
103 *
104 * <p>Equivalent to
105 *
106 * <blockquote><code>
107 * getCell(ordinalToCoordinates(ordinal))
108 * </code></blockquote>
109 *
110 * @param ordinal 0-based ordinal of the cell
111 *
112 * @return Cell
113 *
114 * @throws IndexOutOfBoundsException if ordinal lies outside CellSet bounds
115 */
116 Cell getCell(int ordinal);
117
118 /**
119 * Returns the Cell at the intersection of a set of axis positions.
120 *
121 * <p>Equivalent to
122 *
123 * <blockquote><pre><code>
124 * getCell(
125 * Arrays.asList(
126 * positions[0].ordinal(),
127 * positions[1].ordinal() [, ...]))
128 * </code></pre></blockquote>
129 *
130 * @param positions Array of positions
131 *
132 * @return Cell
133 *
134 * @throws IllegalArgumentException if positions does not have the same
135 * number of members as the cell set has axes
136 *
137 * @throws IndexOutOfBoundsException if positions lie outside CellSet
138 * bounds
139 */
140 Cell getCell(Position... positions);
141
142 /**
143 * Converts a cell ordinal to a list of cell coordinates.
144 *
145 * @param ordinal Cell ordinal
146 * @return Cell coordinates
147 */
148 List<Integer> ordinalToCoordinates(int ordinal);
149
150 /**
151 * Converts a list of cell coordinates to a cell ordinal.
152 *
153 * @param coordinates Cell coordinates
154 * @return Cell ordinal
155 */
156 int coordinatesToOrdinal(List<Integer> coordinates);
157
158 }
159
160 // End CellSet.java