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