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