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  ;
17  import java.util.List  ;
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  [] uniqueNameParts, boolean failIfNotFound, MatchType matchType);
137 
138     Member getMemberByUniqueName(
139         String  [] 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  [] names,
163         boolean failIfNotFound,
164         int category,
165         MatchType matchType);
166 
167     OlapElement lookupCompound(
168         OlapElement parent,
169         String  [] 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  [] 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  [] 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  <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   name, MatchType matchType);
221 
222     OlapElement getElementChild(OlapElement parent, String   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  <Member> getCalculatedMembers(Hierarchy hierarchy);
272 
273     /**
274      * Returns a list of calculated members in a given level.
275      */
276     List  <Member> getCalculatedMembers(Level level);
277 
278     /**
279      * Returns the list of calculated members.
280      */
281     List  <Member> getCalculatedMembers();
282 
283     /**
284      * Finds a child of a member with a given name.
285      */
286     Member lookupMemberChildByName(
287         Member parent, String   childName, MatchType matchType);
288 
289     Member lookupMemberChildByName(Member parent, String   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   name);
308 
309     DataSource   getDataSource();
310 }
311 
312 // End SchemaReader.java
313
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags