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 * Σ<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 */ 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