001    /*
002    // $Id: CellSetAxis.java 243 2009-05-22 07:21:37Z 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.util.ListIterator;
014    
015    /**
016     * Axis of a CellSet.
017     *
018     * <p>A cell set has the same number of axes as the MDX statement which was
019     * executed to produce it. For example, a typical cell set, resulting from an
020     * MDX query with COLUMNS and ROWS expressions is two-dimensional, and
021     * therefore has two axes.</p>
022     *
023     * <p>Each axis is an ordered collection of members or tuples. Each member or
024     * tuple on an axis is called a {@link Position}.</p>
025     *
026     * <p>The positions on the cell set axis can be accessed sequentially or
027     * random-access. Use the {@link #getPositions()} method to return a list for
028     * random access, or the {@link #iterator()} method to obtain an iterator for
029     * sequential access.
030     *
031     * @author jhyde
032     * @version $Id: CellSetAxis.java 243 2009-05-22 07:21:37Z jhyde $
033     * @since Aug 22, 2006
034     */
035    public interface CellSetAxis extends Iterable<Position> {
036        /**
037         * Returns the axis ordinal of this <code>CellSetAxis</code>.
038         *
039         * <p>The first axis in a CellSet will return {@link Axis#COLUMNS},
040         * the second {@link Axis#ROWS}, and so forth, as described by the
041         * {@link Axis#axisOrdinal()} method of the {@link Axis} enumeration.</p>
042         *
043         * @return the ordinal of this axis
044         */
045        Axis getAxisOrdinal();
046    
047        /**
048         * Returns the {@link CellSet} which this <code>CellSetAxis</code>
049         * belongs to.
050         *
051         * @return the CellSet
052         */
053        CellSet getCellSet();
054    
055        /**
056         * Returns a description of the type (e.g. {@link Axis#ROWS}) of this
057         * axis, and the hierarchies and properties which will be found on it.
058         *
059         * <p>The result is identical to evaluating
060         * <blockquote>
061         * <code>getCellSet().getMetaData().getSlicerAxisMetaData()</code>
062         * </blockquote>
063         * for a filter axis, and
064         * <blockquote>
065         * <code>getCellSet().getMetaData().getAxesMetaData().get(
066         * getAxisOrdinal().axisOrdinal())</code>
067         * </blockquote>
068         * for other axes.
069         *
070         * @return metadata describing this CellSetAxis
071         */
072        CellSetAxisMetaData getAxisMetaData();
073    
074        /**
075         * Returns a list of <code>Position</code> objects on this CellSetAxis.
076         *
077         * @return List of positions on this axis (never null)
078         */
079        List<Position> getPositions();
080    
081        /**
082         * Returns the number of positions on this CellSetAxis.
083         *
084         * <p>This method can be called at any time. In particular, it is not
085         * necessary to complete an iteration through all positions before calling
086         * this method.</p>
087         *
088         * <p>The number of positions on an axis is important when computing the
089         * ordinal of a cell.</p>
090         *
091         * @return the number of positions
092         */
093        int getPositionCount();
094    
095        /**
096         * Opens an iterator over the positions on this CellSetAxis.
097         *
098         * <p>If this axis has very many positions, this method may be more
099         * efficient than {@link #getPositions()}.
100         *
101         * <p>This method allows CellSetAxis to implement the {@link Iterable}
102         * interface, so one might use it in a foreach construct, for example:
103         *
104         * <blockquote>
105         * <pre>
106         * CellSet cellSet;
107         * for (Position rowPos : cellSet.getAxes().get(0)) {
108         *     for (Position colPos : cellSet.getAxes().get(1)) {
109         *          Cell cell = cellSet.getCell(colPos, rowPos);
110         *          ....
111         *     }
112         * }</pre></blockquote>
113         *
114         * @return iterator over the collection of positions
115         */
116        ListIterator<Position> iterator();
117    
118    }
119    
120    // End CellSetAxis.java