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