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) 2004-2005 TONBELLER AG
008// Copyright (C) 2006-2011 Pentaho and others
009// All Rights Reserved.
010*/
011package mondrian.rolap;
012
013import mondrian.calc.TupleList;
014
015import java.sql.SQLException;
016import java.util.List;
017import javax.sql.DataSource;
018
019/**
020 * Describes the public methods of {@link mondrian.rolap.SqlTupleReader}.
021 *
022 * @author av
023 * @since Nov 21, 2005
024 */
025public interface TupleReader {
026    /**
027     * Factory to create new members for a
028     * hierarchy from SQL result.
029     *
030     * @author av
031     * @since Nov 11, 2005
032     */
033    public interface MemberBuilder {
034
035        /**
036         * Returns the <code>MemberCache</code> to look up members before
037         * creating them.
038         *
039         * @return member cache
040         */
041        MemberCache getMemberCache();
042
043        /**
044         * Returns the object which acts as the member cache
045         * synchronization lock.
046         *
047         * @return Object to lock
048         */
049        Object getMemberCacheLock();
050
051
052        /**
053         * Creates a new member (together with its properties).
054         *
055         * @param parentMember Parent member
056         * @param childLevel Child level
057         * @param value Member value
058         * @param captionValue Caption
059         * @param parentChild Whether a parent-child hierarchy
060         * @param stmt SQL statement
061         * @param key Member key
062         * @param column Column ordinal (0-based)
063         * @return new member
064         * @throws java.sql.SQLException on error
065         */
066        RolapMember makeMember(
067            RolapMember parentMember,
068            RolapLevel childLevel,
069            Object value,
070            Object captionValue,
071            boolean parentChild,
072            SqlStatement stmt,
073            Object key,
074            int column)
075            throws SQLException;
076
077        /**
078         * Returns the 'all' member of the hierarchy.
079         *
080         * @return The 'all' member
081         */
082        RolapMember allMember();
083    }
084
085    /**
086     * Adds a hierarchy to retrieve members from.
087     *
088     * @param level level that the members correspond to
089     * @param memberBuilder used to build new members for this level
090     * @param srcMembers if set, array of enumerated members that make up
091     *     this level
092     */
093    void addLevelMembers(
094        RolapLevel level,
095        MemberBuilder memberBuilder,
096        List<RolapMember> srcMembers);
097
098    /**
099     * Performs the read.
100     *
101     * @param dataSource Data source
102     * @param partialResult List of rows from previous pass
103     * @param newPartialResult Populated with a new list of rows
104     *
105     * @return a list of tuples
106     */
107    TupleList readTuples(
108        DataSource dataSource,
109        TupleList partialResult,
110        List<List<RolapMember>> newPartialResult);
111
112    /**
113     * Performs the read.
114     *
115     * @param dataSource source for reading tuples
116     * @param partialResult partially cached result that should be used
117     * instead of executing sql query
118     * @param newPartialResult if non-null, return the result of the read;
119     * note that this is a subset of the full return list
120
121     * @return a list of RolapMember
122     */
123    TupleList readMembers(
124        DataSource dataSource,
125        TupleList partialResult,
126        List<List<RolapMember>> newPartialResult);
127
128    /**
129     * Returns an object that uniquely identifies the Result that this
130     * {@link TupleReader} would return. Clients may use this as a key for
131     * caching the result.
132     *
133     * @return Cache key
134     */
135    Object getCacheKey();
136
137}
138
139// End TupleReader.java