001 /*
002 // $Id: //open/mondrian/src/main/mondrian/rolap/MemberSource.java#11 $
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-2008 Julian Hyde and others
008 // All Rights Reserved.
009 // You must accept the terms of that agreement to use this software.
010 //
011 // jhyde, 21 December, 2001
012 */
013
014 package mondrian.rolap;
015
016 import java.util.List;
017
018 import mondrian.olap.Id;
019
020 /**
021 * A <code>MemberSource</code> has the basic operations to read the members of a
022 * {@link RolapHierarchy hierarchy}.
023 *
024 * <p>A <code>MemberSource</code> may optionally support writeback to a
025 * {@link MemberCache}. During the initialization of a
026 * <code>MemberSource</code>, the consumer calls {@link #setCache}; the return
027 * value indicates whether the <code>MemberSource</code> supports
028 * cache-writeback.
029 *
030 * <p>A <dfn>custom member reader</dfn> is a user-defined class which implements
031 * the operations to retrieve members. It either implements the
032 * <code>MemberSource</code> interface, or the derived interface
033 * {@link MemberReader}, which has more operations. In addition to the interface
034 * methods, the class must have a constructor which takes parameters
035 * <code>({@link RolapHierarchy}, {@link java.util.Properties})</code> and
036 * throws no exceptions. To declare a hierarchy based upon the class, use the
037 * <code>memberReaderClass</code> attribute of the
038 * <code><Hierarchy></code> element in your XML schema file; the
039 * <code>properties</code> constructor parameter is populated from any
040 * <ocde><Param name="..." value="..."></code> child elements.
041 *
042 * @see MemberReader
043 * @see MemberCache
044 *
045 * @author jhyde
046 * @since 21 December, 2001
047 * @version $Id: //open/mondrian/src/main/mondrian/rolap/MemberSource.java#11 $
048 */
049 public interface MemberSource {
050 /**
051 * Returns the hierarchy that this source is reading for.
052 */
053 RolapHierarchy getHierarchy();
054 /**
055 * Sets the cache which this <code>MemberSource</code> will write to.
056 *
057 * <p>Cache-writeback is optional (for example, {@link SqlMemberSource}
058 * supports it, and {@link ArrayMemberSource} does not), and the return
059 * value from this method indicates whether this object supports it.
060 *
061 * <p>If this method returns <code>true</code>, the {@link #getMembers},
062 * {@link #getRootMembers} and {@link #getMemberChildren} methods must
063 * write to the cache, in addition to returning members as a return value.
064 *
065 * @param cache The <code>MemberCache</code> which the caller would like
066 * this <code>MemberSource</code> to write to.
067 * @return Whether this <code>MemberSource</code> supports cache-writeback.
068 */
069 boolean setCache(MemberCache cache);
070 /**
071 * Returns all members of this hierarchy, sorted by ordinal.
072 *
073 * <p>If this object {@link #setCache supports cache-writeaback}, also
074 * writes these members to the cache.
075 */
076 List<RolapMember> getMembers();
077 /**
078 * Returns all members of this hierarchy which do not have a parent,
079 * sorted by ordinal.
080 *
081 * <p>If this object {@link #setCache supports cache-writeback}, also
082 * writes these members to the cache.
083 *
084 * @return {@link List} of {@link RolapMember}s
085 */
086 List<RolapMember> getRootMembers();
087
088 /**
089 * Writes all children <code>parentMember</code> to <code>children</code>.
090 *
091 * <p>If this object {@link #setCache supports cache-writeback}, also
092 * writes these members to the cache.
093 */
094 void getMemberChildren(
095 RolapMember parentMember,
096 List<RolapMember> children);
097
098 /**
099 * Returns all members which are a child of one of the members in
100 * <code>parentMembers</code>, sorted by ordinal.
101 *
102 * <p>If this object {@link #setCache supports cache-writeaback}, also
103 * writes these members to the cache.
104 */
105 void getMemberChildren(
106 List<RolapMember> parentMembers,
107 List<RolapMember> children);
108
109 /**
110 * Returns an estimate of number of members in this hierarchy.
111 */
112 int getMemberCount();
113
114 /**
115 * Finds a member based upon its unique name.
116 */
117 RolapMember lookupMember(
118 List<Id.Segment> uniqueNameParts,
119 boolean failIfNotFound);
120 }
121
122 // End MemberSource.java