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 * List of tuples.
018 *
019 * <h2>Design notes</h2>
020 *
021 * <ul>
022 *
023 * <li>Consider changing
024 * {@link TupleCalc#evaluateTuple(mondrian.olap.Evaluator)}
025 * and {@link mondrian.olap.Evaluator.NamedSetEvaluator#currentTuple()}
026 * to List&lt;Member&gt;</li>
027 *
028 * <li>Search for potential uses of {@link TupleList#get(int, int)}</li>
029 *
030 * <li>Worth creating {@link TupleList}.addAll(TupleIterator)?</li>
031 *
032 * </ul>
033 *
034 * @author jhyde
035 */
036public interface TupleList
037    extends List<List<Member>>, TupleIterable
038{
039    /**
040     * Returns a particular column of a particular row.
041     *
042     * <p>Note that {@code list.get(row, column)}
043     * is equivalent to {@code list.slice(column).get(row)}
044     * and {@code list.get(row).get(column)}
045     * but is more efficient for most implementations of TupleList.
046     *
047     * @param slice Column ordinal
048     * @param index Row ordinal
049     * @return Member at given row and column
050     */
051    Member get(int slice, int index);
052
053    /**
054     * Returns a list of the members at a given column.
055     *
056     * <p>The list is modifiable if and only if this TupleList is modifiable.
057     * Adding an element to a slice will create a tuple whose members in other
058     * columns are null.
059     * Removing an element from a slicer will remove a tuple.
060     *
061     * @param column Ordinal of the member in each tuple to project
062     * @return List of members
063     * @throws IllegalArgumentException if column is not less than arity
064     */
065    List<Member> slice(int column);
066
067    /**
068     * Creates a copy of this list that has the same type and has a given
069     * capacity.
070     *
071     * <p>If capacity is negative, populates the list. A deep copy is made,
072     * so that it the contents of the list are not affected to changes to any
073     * backing collections.
074     *
075     * @param capacity Capacity
076     * @return Copy of list, empty if capacity is non-negative
077     */
078    TupleList cloneList(int capacity);
079
080    void addTuple(Member... members);
081
082    TupleList project(int[] destIndices);
083
084    void addCurrent(TupleCursor tupleIter);
085
086    // override, refining return type
087    TupleList subList(int fromIndex, int toIndex);
088
089    TupleList withPositionCallback(PositionCallback positionCallback);
090
091    /**
092     * Fixes the tuples of this list, so that their contents will not change
093     * even if elements of the list are reordered or removed. Returns this
094     * list if possible.
095     *
096     * @return List whose tuples are invariant if the list is sorted or filtered
097     */
098    TupleList fix();
099
100    interface PositionCallback {
101        void onPosition(int index);
102    }
103}
104
105// End TupleList.java