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