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) 2002-2005 Julian Hyde
008// Copyright (C) 2005-2009 Pentaho and others
009// All Rights Reserved.
010//
011// jhyde, Oct 5, 2002
012*/
013package mondrian.olap;
014
015/**
016 * A <code>Role</code> is a collection of access rights to cubes, permissions,
017 * and so forth.
018 *
019 * <p>At present, the only way to create a role is programmatically. You then
020 * add appropriate permissions, and associate the role with a connection.
021 * Queries executed for the duration of the connection will b.
022 *
023 * <p>Mondrian does not have any notion of a 'user'. It is the client
024 * application's responsibility to create a role appropriate for the user who
025 * is establishing the connection.
026 *
027 * @author jhyde
028 * @since Oct 5, 2002
029 */
030public interface Role {
031
032    /**
033     * Returns the access this role has to a given schema.
034     *
035     * @pre schema != null
036     * @post return == Access.ALL
037     * || return == Access.NONE
038     * || return == Access.ALL_DIMENSIONS
039     */
040    Access getAccess(Schema schema);
041
042    /**
043     * Returns the access this role has to a given cube.
044     *
045     * @pre cube != null
046     * @post return == Access.ALL || return == Access.NONE
047     */
048    Access getAccess(Cube cube);
049
050    /**
051     * Represents the access that a role has to a particular hierarchy.
052     */
053    public interface HierarchyAccess {
054        /**
055         * Returns the access the current role has to a given member.
056         *
057         * <p>Visibility is:<ul>
058         * <li>{@link Access#NONE} if member is not visible,
059         * <li>{@link Access#ALL} if member and all children are visible,
060         * <li>{@link Access#CUSTOM} if some of the children are not visible.
061         * </ul></p>
062         *
063         * <p>For these purposes, children which are below the bottom level are
064         * regarded as visible.</p>
065         *
066         * @param member Member
067         * @return current role's access to member
068         */
069        Access getAccess(Member member);
070
071        /**
072         * Returns the depth of the highest level to which the current Role has
073         * access. The 'all' level, if present, has a depth of zero.
074         *
075         * @return depth of the highest accessible level
076         */
077        int getTopLevelDepth();
078
079        /**
080         * Returns the depth of the lowest level to which the current Role has
081         * access. The 'all' level, if present, has a depth of zero.
082         *
083         * @return depth of the lowest accessible level
084         */
085        int getBottomLevelDepth();
086
087        /**
088         * Returns the policy by which cell values are calculated if not all
089         * of a member's children are visible.
090         *
091         * @return rollup policy
092         */
093        RollupPolicy getRollupPolicy();
094
095        /**
096         * Returns <code>true</code> if at least one of the descendants of the
097         * given Member is inaccessible to this Role.
098         *
099         * <p>Descendants which are inaccessible because they are below the
100         * bottom level are ignored.
101         *
102         * @param member Member
103         * @return whether a descendant is inaccessible
104         */
105        boolean hasInaccessibleDescendants(Member member);
106    }
107
108    /**
109     * Returns the access this role has to a given dimension.
110     *
111     * @pre dimension != null
112     * @post Access.instance().isValid(return)
113     */
114    Access getAccess(Dimension dimension);
115
116    /**
117     * Returns the access this role has to a given hierarchy.
118     *
119     * @pre hierarchy != null
120     * @post return == Access.NONE
121     *   || return == Access.ALL
122     *   || return == Access.CUSTOM
123     */
124    Access getAccess(Hierarchy hierarchy);
125
126    /**
127     * Returns the details of this hierarchy's access, or null if the hierarchy
128     * has not been given explicit access.
129     *
130     * @pre hierarchy != null
131     */
132    HierarchyAccess getAccessDetails(Hierarchy hierarchy);
133
134    /**
135     * Returns the access this role has to a given level.
136     *
137     * @pre level != null
138     * @post Access.instance().isValid(return)
139     */
140    Access getAccess(Level level);
141
142    /**
143     * Returns the access this role has to a given member.
144     *
145     * @pre member != null
146     * @pre isMutable()
147     * @post return == Access.NONE
148     *    || return == Access.ALL
149     *    || return == Access.CUSTOM
150     */
151    Access getAccess(Member member);
152
153    /**
154     * Returns the access this role has to a given named set.
155     *
156     * @pre set != null
157     * @pre isMutable()
158     * @post return == Access.NONE || return == Access.ALL
159     */
160    Access getAccess(NamedSet set);
161
162    /**
163     * Returns whether this role is allowed to see a given element.
164     * @pre olapElement != null
165     */
166    boolean canAccess(OlapElement olapElement);
167
168    /**
169     * Enumeration of the policies by which a cell is calculated if children
170     * of a member are not accessible.
171     */
172    enum RollupPolicy {
173        /**
174         * The value of the cell is null if any of the children are
175         * inaccessible.
176         */
177        HIDDEN,
178
179        /**
180         * The value of the cell is obtained by rolling up the values of
181         * accessible children.
182         */
183        PARTIAL,
184
185        /**
186         * The value of the cell is obtained by rolling up the values of all
187         * children.
188         */
189        FULL,
190    }
191}
192
193// End Role.java