001 /*
002 // $Id: CellSetAxis.java 125 2008-11-02 07:43:12Z jhyde $
003 // This software is subject to the terms of the Common Public License
004 // Agreement, available at the following URL:
005 // http://www.opensource.org/licenses/cpl.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 125 2008-11-02 07:43:12Z 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(getAxisOrdinal().axisOrdinal())</code>
066 * </blockquote>
067 * for other axes.
068 *
069 * @return metadata describing this CellSetAxis
070 */
071 CellSetAxisMetaData getAxisMetaData();
072
073 /**
074 * Returns a list of <code>Position</code> objects on this CellSetAxis.
075 *
076 * @return List of positions on this axis (never null)
077 */
078 List<Position> getPositions();
079
080 /**
081 * Returns the number of positions on this CellSetAxis.
082 *
083 * <p>This method can be called at any time. In particular, it is not
084 * necessary to complete an iteration through all positions before calling
085 * this method.</p>
086 *
087 * <p>The number of positions on an axis is important when computing the
088 * ordinal of a cell.</p>
089 *
090 * @return the number of positions
091 */
092 int getPositionCount();
093
094 /**
095 * Opens an iterator over the positions on this CellSetAxis.
096 *
097 * <p>If this axis has very many positions, this method may be more
098 * efficient than {@link #getPositions()}.
099 *
100 * <p>This method allows CellSetAxis to implement the {@link Iterable}
101 * interface, so one might use it in a foreach construct, for example:
102 *
103 * <blockquote>
104 * <pre>
105 * CellSet cellSet;
106 * for (Position rowPos : cellSet.getAxes().get(0)) {
107 * for (Position colPos : cellSet.getAxes().get(1)) {
108 * Cell cell = cellSet.getCell(colPos, rowPos);
109 * ....
110 * }
111 * }</pre></blockquote>
112 *
113 * @return iterator over the collection of positions
114 */
115 ListIterator<Position> iterator();
116
117 }
118
119 // End CellSetAxis.java