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     * &#931;<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> = &#928;<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