/*
// Licensed to Julian Hyde under one or more contributor license
// agreements. See the NOTICE file distributed with this work for
// additional information regarding copyright ownership.
//
// Julian Hyde licenses this file to you under the Apache License,
// Version 2.0 (the "License"); you may not use this file except in
// compliance with the License. You may obtain a copy of the License at:
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
*/
package org.olap4j;

import java.util.List;
import java.util.ListIterator;

/**
 * Axis of a CellSet.
 *
 * <p>A cell set has the same number of axes as the MDX statement which was
 * executed to produce it. For example, a typical cell set, resulting from an
 * MDX query with COLUMNS and ROWS expressions is two-dimensional, and
 * therefore has two axes.</p>
 *
 * <p>Each axis is an ordered collection of members or tuples. Each member or
 * tuple on an axis is called a {@link Position}.</p>
 *
 * <p>The positions on the cell set axis can be accessed sequentially or
 * random-access. Use the {@link #getPositions()} method to return a list for
 * random access, or the {@link #iterator()} method to obtain an iterator for
 * sequential access.
 *
 * @author jhyde
 * @since Aug 22, 2006
 */
public interface CellSetAxis extends Iterable<Position> {
    /**
     * Returns the axis ordinal of this <code>CellSetAxis</code>.
     *
     * <p>The first axis in a CellSet will return {@link Axis#COLUMNS},
     * the second {@link Axis#ROWS}, and so forth, as described by the
     * {@link Axis#axisOrdinal()} method of the {@link Axis} enumeration.</p>
     *
     * @return the ordinal of this axis
     */
    Axis getAxisOrdinal();

    /**
     * Returns the {@link CellSet} which this <code>CellSetAxis</code>
     * belongs to.
     *
     * @return the CellSet
     */
    CellSet getCellSet();

    /**
     * Returns a description of the type (e.g. {@link Axis#ROWS}) of this
     * axis, and the hierarchies and properties which will be found on it.
     *
     * <p>The result is identical to evaluating
     * <blockquote>
     * <code>getCellSet().getMetaData().getSlicerAxisMetaData()</code>
     * </blockquote>
     * for a filter axis, and
     * <blockquote>
     * <code>getCellSet().getMetaData().getAxesMetaData().get(
     * getAxisOrdinal().axisOrdinal())</code>
     * </blockquote>
     * for other axes.
     *
     * @return metadata describing this CellSetAxis
     */
    CellSetAxisMetaData getAxisMetaData();

    /**
     * Returns a list of <code>Position</code> objects on this CellSetAxis.
     *
     * @return List of positions on this axis (never null)
     */
    List<Position> getPositions();

    /**
     * Returns the number of positions on this CellSetAxis.
     *
     * <p>This method can be called at any time. In particular, it is not
     * necessary to complete an iteration through all positions before calling
     * this method.</p>
     *
     * <p>The number of positions on an axis is important when computing the
     * ordinal of a cell.</p>
     *
     * @return the number of positions
     */
    int getPositionCount();

    /**
     * Opens an iterator over the positions on this CellSetAxis.
     *
     * <p>If this axis has very many positions, this method may be more
     * efficient than {@link #getPositions()}.
     *
     * <p>This method allows CellSetAxis to implement the {@link Iterable}
     * interface, so one might use it in a foreach construct, for example:
     *
     * <blockquote>
     * <pre>
     * CellSet cellSet;
     * for (Position rowPos : cellSet.getAxes().get(0)) {
     *     for (Position colPos : cellSet.getAxes().get(1)) {
     *          Cell cell = cellSet.getCell(colPos, rowPos);
     *          ....
     *     }
     * }</pre></blockquote>
     *
     * @return iterator over the collection of positions
     */
    ListIterator<Position> iterator();

}

// End CellSetAxis.java
