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>&lt;Hierarchy&gt;</code> element in your XML schema file; the
038 * <code>properties</code> constructor parameter is populated from any
039 * <ocde>&lt;Param name="..." value="..."&gt;</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