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