001    /*
002    // This software is subject to the terms of the Common Public License
003    // Agreement, available at the following URL:
004    // http://www.opensource.org/licenses/cpl.html.
005    // Copyright (C) 2004-2005 TONBELLER AG
006    // All Rights Reserved.
007    // You must accept the terms of that agreement to use this software.
008    */
009    package mondrian.rolap;
010    
011    import java.sql.Connection;
012    import java.sql.ResultSet;
013    import java.sql.SQLException;
014    import java.util.List;
015    
016    import javax.sql.DataSource;
017    
018    /**
019     * Describes the public methods of {@link mondrian.rolap.SqlTupleReader}.
020     *
021     * @author av
022     * @since Nov 21, 2005
023     * @version $Id: //open/mondrian/src/main/mondrian/rolap/TupleReader.java#11 $
024     */
025    public 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            MemberCache getMemberCache();
040    
041            /**
042             * Returns the object which acts as the member cache
043             * synchronization lock.
044             */
045            Object getMemberCacheLock();
046    
047    
048            /**
049             * Creates a new member (together with its properties).
050             * @see SqlMemberSource#makeMember(RolapMember, RolapLevel, Object, Object, boolean, ResultSet, Object, int)
051             */
052            RolapMember makeMember(RolapMember parentMember, RolapLevel childLevel,
053                    Object value, Object captionValue, boolean parentChild,
054                    ResultSet resultSet, Object key, int column) throws SQLException;
055        }
056    
057        /**
058         * Adds a hierarchy to retrieve members from.
059         *
060         * @param level level that the members correspond to
061         * @param memberBuilder used to build new members for this level
062         * @param srcMembers if set, array of enumerated members that make up
063         * this level
064         */
065        void addLevelMembers(
066            RolapLevel level, MemberBuilder memberBuilder,
067            List<RolapMember> srcMembers);
068    
069        /**
070         * Performs the read.
071         *
072         * @return a list of RolapMember[]
073         */
074        List<RolapMember[]> readTuples(
075            DataSource dataSource,
076            List<List<RolapMember>> partialResult,
077            List<List<RolapMember>> newPartialResult);
078    
079        /**
080         * Performs the read.
081         *
082         * @param dataSource source for reading tuples
083         * @param partialResult partially cached result that should be used
084         * instead of executing sql query
085         * @param newPartialResult if non-null, return the result of the read;
086         * note that this is a subset of the full return list
087    
088         * @return a list of RolapMember
089         */
090        List<RolapMember> readMembers(
091            DataSource dataSource,
092            List<List<RolapMember>> partialResult,
093            List<List<RolapMember>> newPartialResult);
094    
095        /**
096         * Returns an object that uniquely identifies the Result that this
097         * {@link TupleReader} would return. Clients may use this as a key for
098         * caching the result.
099         */
100        Object getCacheKey();
101    
102    }
103    
104    // End TupleReader.java