001 /*
002 // $Id: //open/mondrian/src/main/mondrian/rolap/MemberReader.java#19 $
003 // This software is subject to the terms of the Common Public License
004 // Agreement, available at the following URL:
005 // http://www.opensource.org/licenses/cpl.html.
006 // Copyright (C) 2001-2002 Kana Software, Inc.
007 // Copyright (C) 2001-2007 Julian Hyde and others
008 // All Rights Reserved.
009 // You must accept the terms of that agreement to use this software.
010 //
011 // jhyde, 10 August, 2001
012 */
013
014 package mondrian.rolap;
015 import java.util.List;
016
017 import mondrian.olap.*;
018 import mondrian.rolap.TupleReader.MemberBuilder;
019 import mondrian.rolap.sql.TupleConstraint;
020 import mondrian.rolap.sql.MemberChildrenConstraint;
021
022 /**
023 * A <code>MemberReader</code> implements common operations to retrieve members
024 * from a hierarchy.
025 *
026 * <p><code>MemberReader</code> is an extension of {@link MemberSource}, which
027 * implements only the very basic operations. {@link CacheMemberReader} is an
028 * adapter which converts a {@link MemberSource} into a {@link MemberReader}
029 * and does caching too.
030 *
031 * @author jhyde
032 * @since 10 August, 2001
033 * @version $Id: //open/mondrian/src/main/mondrian/rolap/MemberReader.java#19 $
034 */
035 interface MemberReader extends MemberSource {
036 /**
037 * Returns the member <code>n</code> after <code>member</code> in the same
038 * level (or before, if <code>n</code> is negative).
039 * Returns {@link Hierarchy#getNullMember} if we run off the beginning or
040 * end of the level.
041 */
042 RolapMember getLeadMember(RolapMember member, int n);
043
044 /**
045 * Returns all of the members in <code>level</code> whose ordinal lies
046 * between <code>startOrdinal</code> and <code>endOrdinal</code>.
047 *
048 * <p>If this object
049 * {@link MemberSource#setCache supports cache-writeback}, also
050 * writes these members to the cache.
051 *
052 * @return {@link List} of {@link RolapMember}
053 */
054 List<RolapMember> getMembersInLevel(RolapLevel level, int startOrdinal, int endOrdinal);
055
056 /**
057 * Writes all members between <code>startMember</code> and
058 * <code>endMember</code> into <code>list</code>.
059 */
060 void getMemberRange(
061 RolapLevel level,
062 RolapMember startMember,
063 RolapMember endMember,
064 List<RolapMember> list);
065
066 /**
067 * Compares two members according to their order in a prefix ordered
068 * traversal. If <code>siblingsAreEqual</code>, then two members with the
069 * same parent will compare equal.
070 *
071 * @return less than zero if m1 occurs before m2,
072 * greater than zero if m1 occurs after m2,
073 * zero if m1 is equal to m2, or if <code>siblingsAreEqual</code> and
074 * m1 and m2 have the same parent
075 */
076 int compare(
077 RolapMember m1,
078 RolapMember m2,
079 boolean siblingsAreEqual);
080
081 /**
082 * Populates a list of the children of a Member, optionally applying a
083 * constraint.
084 *
085 * @param member Members whose children to find
086 * @param children List to populate with members
087 * @param constraint Constraint
088 */
089 void getMemberChildren(
090 RolapMember member,
091 List<RolapMember> children,
092 MemberChildrenConstraint constraint);
093
094 /**
095 * Populates a list of the children of a given set of Members, optionally
096 * applying a constraint.
097 *
098 * @param parentMembers List of members whose children to find
099 * @param children List to populate with members
100 * @param constraint Constraint
101 */
102 void getMemberChildren(
103 List<RolapMember> parentMembers,
104 List<RolapMember> children,
105 MemberChildrenConstraint constraint);
106
107 /**
108 * Returns the members in the given Level, optionally between a range
109 * of ordinals and applying a constraint.
110 *
111 * @param level Level
112 * @param startOrdinal Ordinal of first member to retrieve
113 * @param endOrdinal Ordinal of last member to upper bound
114 * @param constraint Constraint
115 * @return list of members
116 */
117 List<RolapMember> getMembersInLevel(
118 RolapLevel level,
119 int startOrdinal,
120 int endOrdinal,
121 TupleConstraint constraint);
122
123 /**
124 * Returns the number of members in this level.
125 *
126 * @param level Level
127 * @return number of members in level
128 */
129 int getLevelMemberCount(RolapLevel level);
130
131 MemberBuilder getMemberBuilder();
132
133 RolapMember getDefaultMember();
134
135 RolapMember getMemberParent(RolapMember member);
136
137 /**
138 * Substitutes a given member.
139 * If member is null, returns null.
140 *
141 * <p>This method is called whenever a member is returned from the wrapped
142 * member reader and is to be returned to the caller. You could say that it
143 * translates 'to caller space'.
144 *
145 * @param member Member
146 * @return Substitute member
147 */
148 RolapMember substitute(RolapMember member);
149
150 /**
151 * Returns the member which was substituted.
152 * If member is null, returns null.
153 *
154 * <p>This method is called whenever the caller passes a member into a
155 * method and needs to be passed to a method on the wrapped member reader.
156 * You could say that it translates 'from caller space'.
157 *
158 * @param member Member
159 * @return Internal member
160 */
161 RolapMember desubstitute(RolapMember member);
162 }
163
164 // End MemberReader.java