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