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