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) 2001-2005 Julian Hyde
008// Copyright (C) 2005-2012 Pentaho and others
009// All Rights Reserved.
010//
011// jhyde, 10 August, 2001
012*/
013package mondrian.rolap;
014
015import mondrian.olap.Access;
016import mondrian.olap.Hierarchy;
017import mondrian.olap.Member;
018import mondrian.rolap.TupleReader.MemberBuilder;
019import mondrian.rolap.sql.MemberChildrenConstraint;
020import mondrian.rolap.sql.TupleConstraint;
021
022import java.util.List;
023import java.util.Map;
024
025/**
026 * A <code>MemberReader</code> implements common operations to retrieve members
027 * from a hierarchy.
028 *
029 * <p><code>MemberReader</code> is an extension of {@link MemberSource}, which
030 * implements only the very basic operations. {@link CacheMemberReader} is an
031 * adapter which converts a {@link MemberSource} into a {@link MemberReader}
032 * and does caching too.
033 *
034 * @author jhyde
035 * @since 10 August, 2001
036 */
037interface MemberReader extends MemberSource {
038    /**
039     * Returns the member <code>n</code> after <code>member</code> in the same
040     * level (or before, if <code>n</code> is negative).
041     * Returns {@link Hierarchy#getNullMember} if we run off the beginning or
042     * end of the level.
043     */
044    RolapMember getLeadMember(RolapMember member, int n);
045
046    /**
047     * Returns all of the members in <code>level</code> whose ordinal lies
048     * between <code>startOrdinal</code> and <code>endOrdinal</code>.
049     *
050     * <p>If this object
051     * {@link MemberSource#setCache supports cache-writeback}, also
052     * writes these members to the cache.
053     *
054     * @return {@link List} of {@link RolapMember}
055     */
056    List<RolapMember> getMembersInLevel(
057        RolapLevel level);
058
059    /**
060     * Writes all members between <code>startMember</code> and
061     * <code>endMember</code> into <code>list</code>.
062     */
063    void getMemberRange(
064        RolapLevel level,
065        RolapMember startMember,
066        RolapMember endMember,
067        List<RolapMember> list);
068
069    /**
070     * Compares two members according to their order in a prefix ordered
071     * traversal. If <code>siblingsAreEqual</code>, then two members with the
072     * same parent will compare equal.
073     *
074     * @return less than zero if m1 occurs before m2,
075     *     greater than zero if m1 occurs after m2,
076     *     zero if m1 is equal to m2, or if <code>siblingsAreEqual</code> and
077     *         m1 and m2 have the same parent
078     */
079    int compare(
080        RolapMember m1,
081        RolapMember m2,
082        boolean siblingsAreEqual);
083
084    /**
085     * Populates a list of the children of a Member, optionally applying a
086     * constraint.
087     *
088     * @param member Members whose children to find
089     * @param children List to populate with members
090     * @param constraint Constraint
091     * @return After populating the list passed as an argument,
092     * this method returns a map of the members it just populated
093     * along with the Access information applicable. If no access
094     * control applies to the member, the map will contain
095     * <code>null</code> values.
096     */
097    Map<? extends Member, Access> getMemberChildren(
098        RolapMember member,
099        List<RolapMember> children,
100        MemberChildrenConstraint constraint);
101
102    /**
103     * Populates a list of the children of a given set of Members, optionally
104     * applying a constraint.
105     *
106     * @param parentMembers List of members whose children to find
107     * @param children List to populate with members
108     * @param constraint Constraint
109     * @return After populating the list passed as an argument,
110     * this method returns a map of the members it just populated
111     * along with the Access information applicable. If no access
112     * control applies to the member, the map will contain
113     * <code>null</code> values.
114     */
115    Map<? extends Member, Access> getMemberChildren(
116        List<RolapMember> parentMembers,
117        List<RolapMember> children,
118        MemberChildrenConstraint constraint);
119
120    /**
121     * Returns the members in the given Level, optionally applying a constraint.
122     *
123     * @param level Level
124     * @param constraint Constraint
125     * @return list of members
126     */
127    List<RolapMember> getMembersInLevel(
128        RolapLevel level,
129        TupleConstraint constraint);
130
131    /**
132     * Returns the number of members in this level.
133     *
134     * @param level Level
135     * @return number of members in level
136     */
137    int getLevelMemberCount(RolapLevel level);
138
139    MemberBuilder getMemberBuilder();
140
141    RolapMember getDefaultMember();
142
143    RolapMember getMemberParent(RolapMember member);
144
145    /**
146     * Substitutes a given member.
147     * If member is null, returns null.
148     *
149     * <p>This method is called whenever a member is returned from the wrapped
150     * member reader and is to be returned to the caller. You could say that it
151     * translates 'to caller space'.
152     *
153     * @param member Member
154     * @return Substitute member
155     */
156    RolapMember substitute(RolapMember member);
157
158    /**
159     * Returns the member which was substituted.
160     * If member is null, returns null.
161     *
162     * <p>This method is called whenever the caller passes a member into a
163     * method and needs to be passed to a method on the wrapped member reader.
164     * You could say that it translates 'from caller space'.
165     *
166     * @param member Member
167     * @return Internal member
168     */
169    RolapMember desubstitute(RolapMember member);
170
171    /**
172     * Looks up a member by its key value.
173     *
174     * @param level Level
175     * @param keyValues Key values
176     * @return Member, or null
177     */
178    RolapMember getMemberByKey(
179        RolapLevel level,
180        List<Comparable> keyValues);
181}
182
183// End MemberReader.java