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