001/* 002// This software is subject to the terms of the Eclipse Public License v1.0 003// Agreement, available at the following URL: 004// http://www.eclipse.org/legal/epl-v10.html. 005// You must accept the terms of that agreement to use this software. 006// 007// Copyright (C) 2011-2011 Pentaho 008// All Rights Reserved. 009*/ 010package mondrian.calc; 011 012import mondrian.olap.Evaluator; 013import mondrian.olap.Member; 014 015import java.util.List; 016 017/** 018 * Cheap interface for iterating through the contents of a {@link TupleList}. 019 * 020 * <p>Stops short of the full {@link java.util.Iterator} interface. If you want 021 * that, see {@link TupleIterator}. 022 * 023 * @author Julian Hyde 024 */ 025public interface TupleCursor { 026 void setContext(Evaluator evaluator); 027 028 /** 029 * Moves the iterator forward one position. 030 * 031 * <p>Returns false only when end of data has been reached. 032 * 033 * <p>Similar to calling the {@link java.util.Iterator} methods 034 * {@link java.util.Iterator#hasNext()} followed by 035 * {@link java.util.Iterator#next()} but 036 * does not construct an object, and is therefore cheaper. 037 * 038 * <p>If you want to use an Iterator, see {@link TupleIterator}. 039 * 040 * @return Whether was able to move forward a position 041 */ 042 boolean forward(); 043 044 /** 045 * Returns the tuple that this cursor is positioned on. 046 * 047 * <p>This method never returns null, and may safely be called multiple 048 * times (or not all) for each position in the iteration. 049 * 050 * <p>Invalid to call this method when the cursor is has not been 051 * positioned, for example, if {@link #forward()} has not been called or 052 * if the most recent call to {@code forward} returned {@code false}. 053 * 054 * @return Current tuple 055 */ 056 List<Member> current(); 057 058 /** 059 * Returns the number of members in each tuple. 060 * 061 * @return The number of members in each tuple 062 */ 063 int getArity(); 064 065 Member member(int column); 066 067 /** 068 * Writes the member(s) of the next tuple to a given offset in an array. 069 * 070 * <p>This method saves the overhead of a memory allocation when the 071 * resulting tuple will be written immediately to an array. The effect of 072 * {@code currentToArray(members, 0)} is the same as calling 073 * {@code current().toArray(members)}. 074 * 075 * <p>Before calling this method, you must position the iterator at a valid 076 * position. Typically you would call hasNext followed by next; or forward. 077 * 078 * @param members Members 079 * @param offset Offset in the array to write to 080 */ 081 void currentToArray(Member[] members, int offset); 082} 083 084// End TupleCursor.java