001    /*
002    // $Id: Member.java 229 2009-05-08 19:11:29Z jhyde $
003    // This software is subject to the terms of the Eclipse Public License v1.0
004    // Agreement, available at the following URL:
005    // http://www.eclipse.org/legal/epl-v10.html.
006    // Copyright (C) 2006-2008 Julian Hyde
007    // All Rights Reserved.
008    // You must accept the terms of that agreement to use this software.
009    */
010    package org.olap4j.metadata;
011    
012    import java.util.List;
013    
014    import org.olap4j.OlapException;
015    import org.olap4j.mdx.ParseTreeNode;
016    
017    /**
018     * <code>Member</code> is a data value in an OLAP Dimension.
019     *
020     * @author jhyde
021     * @version $Id: Member.java 229 2009-05-08 19:11:29Z jhyde $
022     * @since Aug 22, 2006
023     */
024    public interface Member extends MetadataElement {
025        /**
026         * Returns the children of this Member, indexed by name.
027         *
028         * <p>If access-control is in place, the list does not contain inaccessible
029         * children.
030         *
031         * <p>If the member has no children, returns an empty list: the result is
032         * never null.
033         *
034         * <p>The caller should assume that the list is immutable;
035         * if the caller modifies the list, behavior is undefined.</p>
036         *
037         * @see org.olap4j.OlapDatabaseMetaData#getMembers
038         *
039         * @return children of this member
040         */
041        NamedList<? extends Member> getChildMembers() throws OlapException;
042    
043        /**
044         * Returns the number of children this Member has.
045         *
046         * <p>This method has the same effect as
047         * <code>getChildMembers().size()</code>, but is typically less expensive.
048         *
049         * @return number of children
050         */
051        int getChildMemberCount();
052    
053        /**
054         * Returns the parent of this Member, or null if it has no parent.
055         *
056         * @return Parent member, or null if member has no parent
057         */
058        Member getParentMember();
059    
060        /**
061         * Returns the Level of this Member.
062         *
063         * <p>Never returns null.</p>
064         *
065         * @return Level which this Member belongs to
066         */
067        Level getLevel();
068    
069        /**
070         * Returns the Hierarchy of this Member.
071         *
072         * <p>Never returns null.
073         * Result is always the same as <code>getLevel().getHierarchy()</code>.
074         *
075         * @return Hierarchy which this Member belongs to
076         */
077        Hierarchy getHierarchy();
078    
079        /**
080         * Returns the Dimension of this Member.
081         *
082         * <p>Never returns null. Result is always the same as
083         * <code>getLevel().getHierarchy().getDimension()</code>.
084         *
085         * @return Dimension which this Member belongs to
086         */
087        Dimension getDimension();
088    
089        /**
090         * Returns the type of this Member.
091         *
092         * <p>Never returns null.</p>
093         *
094         * @return What kind of member this is
095         */
096        Type getMemberType();
097    
098        /**
099         * Returns whether this Member represents the aggregation of all members
100         * in its Dimension.
101         *
102         * <p>An 'all' member is always the root of its Hierarchy; that is,
103         * its parent member is the null member, and
104         * {@link Hierarchy#getRootMembers()} returns the 'all'
105         * member and no others. Some hierarchies do not have an 'all' member.
106         *
107         * @see Hierarchy#hasAll()
108         *
109         * @return whether this Member is the 'all' member of its Dimension
110         */
111        boolean isAll();
112    
113        /**
114         * Enumeration of types of members.
115         *
116         * <p>The values are as specified by XMLA,
117         * plus the additional {@link #NULL} value not used by XMLA.
118         * For example, XMLA specifies <code>MDMEMBER_TYPE_REGULAR</code> with
119         * ordinal 1, which corresponds to value {@link #REGULAR}.
120         *
121         * <p>The {@link #FORMULA} value takes precedence over {@link #MEASURE}.
122         * For example, if there is a formula (calculated) member on the Measures
123         * dimension, it is listed as <code>FORMULA</code>.
124         */
125        enum Type {
126            UNKNOWN(0),
127            REGULAR(1),
128            ALL(2),
129            MEASURE(3),
130            FORMULA(4),
131            /**
132             * Indicates that this member is its hierarchy's NULL member (such as is
133             * returned by the expression
134             * <code>[Gender]&#46;[All Gender]&#46;PrevMember</code>, for example).
135             */
136            NULL(5);
137    
138            private Type(int ordinal) {
139                assert ordinal == ordinal();
140            }
141        }
142    
143        /**
144         * Returns whether <code>member</code> is equal to, a child of, or a
145         * descendent of this Member.
146         *
147         * @param member Member
148         * @return Whether the given Member is a descendent of this Member
149         */
150        boolean isChildOrEqualTo(Member member);
151    
152        /**
153         * Returns whether this member is calculated using a formula.
154         *
155         * <p>Examples of calculated members include
156         * those defined using a <code>WITH MEMBER</code> clause in an MDX query
157         * ({@link #getMemberType()} will return {@link Type#FORMULA} for these),
158         *  or a calculated member defined in a cube.
159         *
160         * @return Whether this Member is calculated
161         *
162         * @see #isCalculatedInQuery()
163         */
164        boolean isCalculated();
165    
166        /**
167         * Returns the solve order of this member in a formula.
168         *
169         * @return solve order of this Member
170         */
171        int getSolveOrder();
172    
173        /**
174         * Expression by which this member is derived, if it is a calculated
175         * member. If the member is not calulated, returns null.
176         *
177         * @return expression for this member
178         */
179        ParseTreeNode getExpression();
180    
181        /**
182         * Returns array of all members which are ancestor to <code>this</code>.
183         *
184         * @return ancestor Members
185         */
186        List<Member> getAncestorMembers();
187    
188        /**
189         * Returns whether this member is computed from a <code>WITH MEMBER</code>
190         * clause in an MDX query. (Calculated members can also be calculated in a
191         * cube.)
192         *
193         * @return Whether this member is calculated in a query
194         *
195         * @see #isCalculated()
196         */
197        boolean isCalculatedInQuery();
198    
199        /**
200         * Returns the value of a given property.
201         *
202         * <p>Returns null if the property is not set.</p>
203         *
204         * <p>Every member has certain system properties such as "name" and
205         * "caption" (the full list is described in the
206         * {@link org.olap4j.metadata.Property.StandardMemberProperty}
207         * enumeration), as well as extra properties defined for its Level
208         * (see {@link Level#getProperties()}).</p>
209         *
210         * @param property Property
211         *
212         * @return formatted value of the given property
213         *
214         * @see #getPropertyFormattedValue(Property)
215         */
216        Object getPropertyValue(Property property);
217    
218        /**
219         * Returns the formatted value of a given property.
220         *
221         * <p>Returns null if the property is not set.</p>
222         *
223         * <p>Every member has certain system properties such as "name" and
224         * "caption" (the full list is described in the
225         * {@link org.olap4j.metadata.Property.StandardMemberProperty}
226         * enumeration), as well as extra properties defined for its Level
227         * (see {@link Level#getProperties()}).</p>
228         *
229         * @param property Property
230         *
231         * @return formatted value of the given property
232         *
233         * @see #getPropertyValue(Property)
234         */
235        String getPropertyFormattedValue(Property property);
236    
237        /**
238         * Sets a property of this member to a given value.
239         *
240         * <p>Every member has certain system properties such as "name" and
241         * "caption" (the full list is described in the
242         * {@link org.olap4j.metadata.Property.StandardMemberProperty}
243         * enumeration), as well as extra properties defined for its Level
244         * (see {@link Level#getProperties()}).</p>
245         *
246         * @param property property
247         *
248         * @param value Property value
249         *
250         * @throws OlapException if the value not valid for this property
251         *   (for example, a String value assigned to a Boolean property)
252         */
253        void setProperty(Property property, Object value) throws OlapException;
254    
255        /**
256         * Returns the definitions of the properties this member may have.
257         *
258         * <p>For many providers, properties are defined against a Level, so result
259         * of this method will be identical to
260         * <code>member.getLevel().{@link Level#getProperties() getProperties}()</code>.
261         *
262         * @return properties of this Member
263         */
264        NamedList<Property> getProperties();
265    
266        /**
267         * Returns the ordinal of the member.
268         *
269         * @return ordinal of this Member
270         */
271        int getOrdinal();
272    
273        /**
274         * Returns whether this member is 'hidden', as per the rules which define
275         * a ragged hierarchy.
276         *
277         * @return whether this member is a hidden member of a ragged hierarchy
278         */
279        boolean isHidden();
280    
281        /**
282         * Returns the depth of this member.
283         *
284         * <p>In regular hierarchies, this is as the same as the level's depth,
285         * but in parent-child and ragged hierarchies the value may be
286         * different.</p>
287         *
288         * @return depth of this Member
289         */
290        int getDepth();
291    
292        /**
293         * Returns the system-generated data member that is associated with a
294         * non-leaf member of a dimension.
295         *
296         * <p>Returns this member if this member is a leaf member, or if the
297         * non-leaf member does not have an associated data member.</p>
298         *
299         * @return system-generated data member
300         */
301        Member getDataMember();
302    
303        /**
304         * Enumeration of tree operations which can be used when querying
305         * members.
306         *
307         * <p>Some of the values are as specified by XMLA.
308         * For example, XMLA specifies MDTREEOP_CHILDREN with ordinal 1,
309         * which corresponds to the value {@link #CHILDREN}.
310         *
311         * @see org.olap4j.OlapDatabaseMetaData#getMembers
312         */
313        public enum TreeOp {
314            /**
315             * Tree operation which returns only the immediate children.
316             */
317            CHILDREN(1),
318    
319            /**
320             * Tree operation which returns members on the same level.
321             */
322            SIBLINGS(2),
323    
324            /**
325             * Tree operation which returns only the immediate parent.
326             */
327            PARENT(4),
328    
329            /**
330             * Tree operation which returns itself in the list of returned rows.
331             */
332            SELF(8),
333    
334            /**
335             * Tree operation which returns all of the descendants.
336             */
337            DESCENDANTS(16),
338    
339            /**
340             * Tree operation which returns all of the ancestors.
341             */
342            ANCESTORS(32);
343    
344            private final int xmlaOrdinal;
345    
346            private TreeOp(int userOrdinal) {
347                this.xmlaOrdinal = userOrdinal;
348            }
349    
350            /**
351             * Returns the ordinal code as specified by XMLA.
352             *
353             * <p>For example, the XMLA specification says that the ordinal of
354             * {@link #ANCESTORS} is 32.
355             *
356             * @return ordinal code as specified by XMLA.
357             */
358            public int xmlaOrdinal() {
359                return xmlaOrdinal;
360            }
361        }
362    }
363    
364    // End Member.java