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    */
020    package org.olap4j;
021    
022    import java.util.List;
023    import 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     */
045    public 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