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, 22 December, 2001
012*/
013package mondrian.rolap;
014
015import mondrian.rolap.sql.MemberChildrenConstraint;
016import mondrian.rolap.sql.TupleConstraint;
017
018import java.util.List;
019
020/**
021 * A <code>MemberCache</code> can retrieve members based upon their parent and
022 * name.
023 *
024 * @author jhyde
025 * @since 22 December, 2001
026 */
027interface MemberCache {
028    /**
029     * Creates a key with which to {@link #getMember(Object)} or
030     * {@link #putMember(Object, RolapMember)} the
031     * {@link RolapMember} with a given parent and key.
032     *
033     * @param parent Parent member
034     * @param key Key of member within parent
035     * @return key with which to address this member in the cache
036     */
037    Object makeKey(RolapMember parent, Object key);
038
039    /**
040     * Retrieves the {@link RolapMember} with a given key.
041     *
042     * @param key cache key, created by {@link #makeKey}
043     * @return member with a given cache key
044     */
045    RolapMember getMember(Object key);
046
047    /**
048     * Retrieves the {@link RolapMember} with a given key.
049     *
050     * @param key cache key, created by {@link #makeKey}
051     * @param mustCheckCacheStatus If {@code true}, do not check cache status
052     * @return member with a given cache key
053     */
054    RolapMember getMember(Object key, boolean mustCheckCacheStatus);
055
056    /**
057     * Replaces the {@link RolapMember} with a given key and returns the
058     * previous member if any.
059     *
060     * @param key cache key, created by {@link #makeKey}
061     * @param member new member
062     * @return Previous member with that key, or null.
063     */
064    Object putMember(Object key, RolapMember member);
065
066    /**
067     * Returns whether the cache supports removing selected items. If it does,
068     * it is valid to call the {@link #removeMember(Object)} and
069     * {@link #removeMemberAndDescendants(Object)} methods.
070     *
071     * <p>REVIEW: remove isMutable and move removeMember and
072     * removeMemberAndDescendants to new interface MutableMemberCache
073     *
074     * @return true if the cache supports removing selected items.
075     */
076    boolean isMutable();
077
078    /**
079     * Removes the {@link RolapMember} with a given key from the cache.
080     * Returns the previous member with that key, or null.
081     * Optional operation: see {@link #isMutable}.
082     *
083     * @param key cache key, created by {@link #makeKey}
084     * @return previous member with that key, or null
085     */
086    RolapMember removeMember(Object key);
087
088    /**
089     * Removes the designated {@link RolapMember} and all its descendants.
090     * Returns the previous member with that key, or null.
091     * Optional operation: see {@link #isMutable}.
092     *
093     * @param key cache key, created by {@link #makeKey}
094     * @return previous member with that key, or null
095     */
096    RolapMember removeMemberAndDescendants(Object key);
097
098    /**
099     * Returns the children of <code>member</code> if they are currently in the
100     * cache, otherwise returns null.
101     *
102     * <p>The children may be garbage collected as
103     * soon as the returned list may be garbage collected.</p>
104     *
105     * @param parent the parent member
106     * @param constraint the condition that was used when the members were
107     *    fetched. May be null for all members (no constraint)
108     * @return list of children, or null if not in cache
109     */
110    List<RolapMember> getChildrenFromCache(
111        RolapMember parent,
112        MemberChildrenConstraint constraint);
113
114    /**
115     * Returns the members of <code>level</code> if they are currently in the
116     * cache, otherwise returns null.
117     *
118     * <p>The members may be garbage collected as soon as the
119     * returned list may be garbage collected.</p>
120     *
121     * @param level the level whose members should be fetched
122     * @param constraint the condition that was used when the members were
123     *   fetched. May be null for all members (no constraint)
124     * @return members of level, or null if not in cache
125     */
126    List<RolapMember> getLevelMembersFromCache(
127        RolapLevel level,
128        TupleConstraint constraint);
129
130    /**
131     * Registers that the children of <code>member</code> are
132     * <code>children</code> (a list of {@link RolapMember}s).
133     *
134     * @param member the parent member
135     * @param constraint the condition that was used when the members were
136     *   fetched. May be null for all members (no constraint)
137     * @param children list of children
138     */
139    void putChildren(
140        RolapMember member,
141        MemberChildrenConstraint constraint,
142        List<RolapMember> children);
143
144    /**
145     * Registers that the children of <code>level</code> are
146     * <code>children</code> (a list of {@link RolapMember}s).
147     *
148     * @param level the parent level
149     * @param constraint the condition that was used when the members were
150     *   fetched. May be null for all members (no constraint)
151     * @param children list of children
152     */
153    void putChildren(
154        RolapLevel level,
155        TupleConstraint constraint,
156        List<RolapMember> children);
157}
158
159
160// End MemberCache.java