KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > mondrian > olap > SchemaReader


1 /*
2 // $Id: //open/mondrian/src/main/mondrian/olap/SchemaReader.java#25 $
3 // This software is subject to the terms of the Common Public License
4 // Agreement, available at the following URL:
5 // http://www.opensource.org/licenses/cpl.html.
6 // Copyright (C) 2003-2006 Julian Hyde
7 // All Rights Reserved.
8 // You must accept the terms of that agreement to use this software.
9 //
10 // jhyde, Feb 24, 2003
11 */

12 package mondrian.olap;
13
14 import mondrian.calc.Calc;
15
16 import javax.sql.DataSource JavaDoc;
17 import java.util.List JavaDoc;
18
19 /**
20  * A <code>SchemaReader</code> queries schema objects ({@link Schema},
21  * {@link Cube}, {@link Dimension}, {@link Hierarchy}, {@link Level},
22  * {@link Member}).
23  *
24  * <p>It is generally created using {@link Connection#getSchemaReader}.
25  *
26  * @author jhyde
27  * @since Feb 24, 2003
28  * @version $Id: //open/mondrian/src/main/mondrian/olap/SchemaReader.java#25 $
29  */

30 public interface SchemaReader {
31     /**
32      * Returns the access-control profile that this <code>SchemaReader</code>
33      * is implementing.
34      */

35     Role getRole();
36
37     /**
38      * Returns an array of the root members of <code>hierarchy</code>. If the
39      * hierarchy is access-controlled, returns the most senior visible members.
40      *
41      * @see #getCalculatedMembers(Hierarchy)
42      */

43     Member[] getHierarchyRootMembers(Hierarchy hierarchy);
44
45     /**
46      * Returns number of children parent of a member,
47      * if the information can be retrieved from cache.
48      * Otherwise -1 is returned
49      */

50     int getChildrenCountFromCache(Member member);
51
52     /**
53      * Returns the number of members in a level, returning an approximation if
54      * acceptable.
55      *
56      * @param level Level
57      * @param approximate Whether an approximation is acceptable
58      * @param materialize Whether to go to disk if no approximation for the count
59      * is available and the members are not in cache. If false, returns
60      * {@link Integer#MIN_VALUE} if value is not in cache.
61      */

62     int getLevelCardinality(
63         Level level, boolean approximate, boolean materialize);
64
65     /**
66      * Returns direct children of <code>member</code>.
67      * @pre member != null
68      * @post return != null
69      */

70     Member[] getMemberChildren(Member member);
71
72     /**
73      * Returns direct children of <code>member</code>, optimized
74      * for NON EMPTY.
75      * <p>
76      * If <code>context == null</code> then
77      * there is no context and all members are returned - then
78      * its identical to {@link #getMemberChildren(Member)}.
79      * If <code>context</code> is not null, the resulting members
80      * <em>may</em> be restricted to those members that have a
81      * non empty row in the fact table for <code>context</code>.
82      * Wether or not optimization is possible depends
83      * on the SchemaReader implementation.
84      */

85     Member[] getMemberChildren(Member member, Evaluator context);
86
87     /**
88      * Returns direct children of each element of <code>members</code>.
89      * @pre members != null
90      * @post return != null
91      */

92     Member[] getMemberChildren(Member[] members);
93     Member[] getMemberChildren(Member[] members, Evaluator context);
94
95     /**
96      * Returns the parent of <code>member</code>.
97      * @param member
98      * @pre member != null
99      * @return null if member is a root member
100      */

101     Member getMemberParent(Member member);
102
103
104     /**
105      * Returns the depth of a member.
106      *
107      * <p>This may not be the same as
108      * <code>member.{@link Member#getLevel getLevel}().
109      * {@link Level#getDepth getDepth}()</code>
110      * for three reasons:<ol>
111      * <li><b>Access control</b>. The most senior <em>visible</em> member has
112      * level 0. If the client is not allowed to see the "All" and "Nation"
113      * levels of the "Store" hierarchy, then members of the "State" level will
114      * have depth 0.</li>
115      * <li><b>Parent-child hierarchies</b>. Suppose Fred reports to Wilma, and
116      * Wilma reports to no one. "All Employees" has depth 0, Wilma has depth
117      * 1, and Fred has depth 2. Fred and Wilma are both in the "Employees"
118      * level, which has depth 1.</li>
119      * <li><b>Ragged hierarchies</b>. If Israel has only one, hidden, province
120      * then the depth of Tel Aviv, Israel is 2, whereas the depth of another
121      * city, San Francisco, CA, USA is 3.</li>
122      * </ol>
123      */

124     int getMemberDepth(Member member);
125
126     /**
127      * Finds a member based upon its unique name.
128      *
129      * @param uniqueNameParts Unique name of member
130      * @param failIfNotFound Whether to throw an error, as opposed to returning
131      * <code>null</code>, if there is no such member.
132      * @param matchType indicates the match mode; if not specified, EXACT
133      * @return The member, or null if not found
134      */

135     Member getMemberByUniqueName(
136         String JavaDoc[] uniqueNameParts, boolean failIfNotFound, MatchType matchType);
137
138     Member getMemberByUniqueName(
139         String JavaDoc[] uniqueNameParts, boolean failIfNotFound);
140
141     /**
142      * Looks up an MDX object by name.
143      *
144      * <p>Resolves a name such as
145      * '[Products]&#46;[Product Department]&#46;[Produce]' by resolving the
146      * components ('Products', and so forth) one at a time.
147      *
148      * @param parent Parent element to search in
149      * @param names Exploded compound name, such as {"Products",
150      * "Product Department", "Produce"}
151      * @param failIfNotFound If the element is not found, determines whether
152      * to return null or throw an error
153      * @param category Type of returned element, a {@link mondrian.olap.Category} value;
154      * {@link mondrian.olap.Category#Unknown} if it doesn't matter.
155      * @param matchType indicates the match mode; if not specified, EXACT
156      *
157      * @pre parent != null
158      * @post !(failIfNotFound && return == null)
159      */

160     OlapElement lookupCompound(
161         OlapElement parent,
162         String JavaDoc[] names,
163         boolean failIfNotFound,
164         int category,
165         MatchType matchType);
166
167     OlapElement lookupCompound(
168         OlapElement parent,
169         String JavaDoc[] names,
170         boolean failIfNotFound,
171         int category);
172
173     /**
174      * Looks up a calculated member by name. If the name is not found in the
175      * current scope, returns null.
176      */

177     Member getCalculatedMember(String JavaDoc[] nameParts);
178
179     /**
180      * Looks up a set by name. If the name is not found in the current scope,
181      * returns null.
182      */

183     NamedSet getNamedSet(String JavaDoc[] nameParts);
184
185     /**
186      * Appends to <code>list</code> all members between <code>startMember</code>
187      * and <code>endMember</code> (inclusive) which belong to
188      * <code>level</code>.
189      */

190     void getMemberRange(
191         Level level, Member startMember, Member endMember, List JavaDoc<Member> list);
192
193     /**
194      * Returns a member <code>n</code> further along in the same level from
195      * <code>member</code>.
196      *
197      * @pre member != null
198      */

199     Member getLeadMember(Member member, int n);
200
201     /**
202      * Compares a pair of {@link Member}s according to their order in a prefix
203      * traversal. (that is, it
204      * is an ancestor or a earlier ), is a sibling, or comes later in a prefix
205      * traversal.
206      * @return A negative integer if <code>m1</code> is an ancestor, an earlier
207      * sibling of an ancestor, or a descendent of an earlier sibling, of
208      * <code>m2</code>;
209      * zero if <code>m1</code> is a sibling of <code>m2</code>;
210      * a positive integer if <code>m1</code> comes later in the prefix
211      * traversal then <code>m2</code>.
212      */

213     int compareMembersHierarchically(Member m1, Member m2);
214
215     /**
216      * Looks up the child of <code>parent</code> called <code>s</code>; returns
217      * null if no element is found.
218      */

219     OlapElement getElementChild(
220         OlapElement parent, String JavaDoc name, MatchType matchType);
221
222     OlapElement getElementChild(OlapElement parent, String JavaDoc name);
223
224     /**
225      * Returns the members of a level, optionally including calculated members.
226      */

227     Member[] getLevelMembers(Level level, boolean includeCalculated);
228
229     /**
230      * Returns the members of a level, optionally filtering out members which
231      * are empty.
232      *
233      * @param level Level
234      * @param context Context for filtering
235      * @return Members of this level
236      */

237     Member[] getLevelMembers(Level level, Evaluator context);
238
239     /**
240      * Returns the accessible levels of a hierarchy.
241      *
242      * @pre hierarchy != null
243      * @post return.length >= 1
244      */

245     Level[] getHierarchyLevels(Hierarchy hierarchy);
246
247     /**
248      * Returns the default member of a hierarchy. If the default member is in
249      * an inaccessible level, returns the nearest ascendant/descendant member.
250      */

251     Member getHierarchyDefaultMember(Hierarchy hierarchy);
252
253     /**
254      * Returns whether a member has visible children.
255      */

256     boolean isDrillable(Member member);
257
258     /**
259      * Returns whether a member is visible.
260      */

261     boolean isVisible(Member member);
262
263     /**
264      * Returns the list of accessible cubes.
265      */

266     Cube[] getCubes();
267
268     /**
269      * Returns a list of calculated members in a given hierarchy.
270      */

271     List JavaDoc<Member> getCalculatedMembers(Hierarchy hierarchy);
272
273     /**
274      * Returns a list of calculated members in a given level.
275      */

276     List JavaDoc<Member> getCalculatedMembers(Level level);
277
278     /**
279      * Returns the list of calculated members.
280      */

281     List JavaDoc<Member> getCalculatedMembers();
282
283     /**
284      * Finds a child of a member with a given name.
285      */

286     Member lookupMemberChildByName(
287         Member parent, String JavaDoc childName, MatchType matchType);
288
289     Member lookupMemberChildByName(Member parent, String JavaDoc childName);
290
291     /**
292      * Returns an object which can evaluate an expression in native SQL, or
293      * null if this is not possible.
294      *
295      * @param fun Function
296      * @param args Arguments to the function
297      * @param evaluator Evaluator, provides context
298      * @param calc
299      */

300     NativeEvaluator getNativeSetEvaluator(
301             FunDef fun, Exp[] args, Evaluator evaluator, Calc calc);
302
303     /**
304      * Returns the definition of a parameter with a given name, or null if not
305      * found.
306      */

307     Parameter getParameter(String JavaDoc name);
308
309     DataSource JavaDoc getDataSource();
310 }
311
312 // End SchemaReader.java
313
Popular Tags