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