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.Member;
013
014import java.util.List;
015
016/**
017 * Extension to {@link Iterable} that returns a {@link TupleIterator}.
018 *
019 * <p>If efficiency is important, call {@link #tupleCursor()} rather than
020 * {@link #tupleIterator()} if possible. Because {@link TupleCursor} is a
021 * simpler API to implement than {@link TupleIterator}, in some cases the
022 * implementation may be more efficient.
023 *
024 * @author jhyde
025 */
026public interface TupleIterable extends Iterable<List<Member>> {
027    /**
028     * Creates an iterator over the contents of this iterable.
029     *
030     * <p>Always has the same effect as calling {@link #iterator()}.
031     *
032     * @see #tupleCursor()
033     *
034     * @return cursor over the tuples returned by this iterable
035     */
036    TupleIterator tupleIterator();
037
038    /**
039     * Creates a cursor over the contents of this iterable.
040     *
041     * <p>The contents of the cursor will always be the same as those returned
042     * by {@link #tupleIterator()}. Because {@link TupleCursor} is a simpler API
043     * to implement than {@link TupleIterator}, in some cases the implementation
044     * may be more efficient.
045     *
046     * @return cursor over the tuples returned by this iterable
047     */
048    TupleCursor tupleCursor();
049
050    /**
051     * Returns the number of members in each tuple.
052     *
053     * @return The number of members in each tuple
054     */
055    int getArity();
056
057    /**
058     * Returns an iterable over the members at a given column.
059     *
060     * <p>The iteratble returns an interator that is modifiable if and only if
061     * this TupleIterable is modifiable.
062     *
063     * <p>If this {@code TupleIterable} happens to be a {@link TupleList},
064     * the method is overridden to return a {@link List}&lt;{@link Member}&gt;.
065     *
066     * @param column Ordinal of the member in each tuple to project
067     * @return Iterable that returns an iterator over members
068     * @throws IllegalArgumentException if column is not less than arity
069     */
070    Iterable<Member> slice(int column);
071}
072
073// End TupleIterable.java