001 /*
002 // $Id: //open/mondrian/src/main/mondrian/olap/Evaluator.java#29 $
003 // This software is subject to the terms of the Common Public License
004 // Agreement, available at the following URL:
005 // http://www.opensource.org/licenses/cpl.html.
006 // Copyright (C) 2001-2002 Kana Software, Inc.
007 // Copyright (C) 2001-2008 Julian Hyde and others
008 // All Rights Reserved.
009 // You must accept the terms of that agreement to use this software.
010 //
011 // jhyde, 27 July, 2001
012 */
013
014 package mondrian.olap;
015
016 import mondrian.calc.ParameterSlot;
017 import java.util.List;
018 import java.util.Locale;
019 import java.util.Date;
020
021 /**
022 * An <code>Evaluator</code> holds the context necessary to evaluate an
023 * expression.
024 *
025 * @author jhyde
026 * @since 27 July, 2001
027 * @version $Id: //open/mondrian/src/main/mondrian/olap/Evaluator.java#29 $
028 */
029 public interface Evaluator {
030
031 /**
032 * Returns the current cube.
033 */
034 Cube getCube();
035
036 /**
037 * Returns the current query.
038 */
039 Query getQuery();
040
041 /**
042 * Returns the start time of the current query.
043 */
044 Date getQueryStartTime();
045
046 /**
047 * Creates a new Evaluator with each given member overriding the context of
048 * the current Evaluator for its dimension. Other dimensions retain the
049 * same context as this Evaluator.
050 *
051 * <p>You can retrieve this Evaluator by calling the new Evaluator's
052 * {@link #pop()} method, but it is not necessary to call <code>pop</code>.
053 *
054 * @param members Array of members to add to the context
055 * @return Evaluator with each given member overriding the state of the
056 * current Evaluator for its dimension
057 */
058 Evaluator push(Member[] members);
059
060 /**
061 * Creates a new Evaluator with the same context as this evaluator.
062 * Equivalent to {@link #push(Member[]) push(new Member[0])}.
063 *
064 * <p>This method is typically called before evaluating an expression which
065 * is known to corrupt the evaluation context.
066 *
067 * <p>You can retrieve this Evaluator by calling the new Evaluator's
068 * {@link #pop()} method, but it is not necessary to call <code>pop</code>.
069 *
070 * @return Evaluator with each given member overriding the state of the
071 * current Evaluator for its dimension
072 */
073 Evaluator push();
074
075 /**
076 * Creates a new Evaluator with the same context except for one member.
077 * Equivalent to
078 * {@link #push(Member[]) push(new Member[] |member})}.
079 *
080 * <p>You can retrieve this Evaluator by calling the new Evaluator's
081 * {@link #pop()} method, but it is not necessary to call <code>pop</code>.
082 *
083 * @param member Member to add to the context
084 * @return Evaluator with each given member overriding the state of the
085 * current Evaluator for its dimension
086 */
087 Evaluator push(Member member);
088
089 /**
090 * Restores previous evaluator.
091 */
092 Evaluator pop();
093
094 /**
095 * Makes <code>member</code> the current member of its dimension. Returns
096 * the previous context.
097 *
098 * @pre member != null
099 * @post return != null
100 */
101 Member setContext(Member member);
102
103 void setContext(List<Member> memberList);
104
105 void setContext(Member[] members);
106
107 Member getContext(Dimension dimension);
108
109 /**
110 * Calculates and returns the value of the cell at the current context.
111 */
112 Object evaluateCurrent();
113
114 /**
115 * Returns the format string for this cell. This is computed by evaluating
116 * the format expression in the current context, and therefore different
117 * cells may have different format strings.
118 */
119 public String getFormatString();
120
121 /**
122 * Formats a value as a string according to the current context's
123 * format.
124 */
125 String format(Object o);
126
127 /**
128 * Formats a value as a string according to the current context's
129 * format, using a given format string.
130 */
131 String format(Object o, String formatString);
132
133 /**
134 * Returns number of ancestor evaluators. Used to check for infinite
135 * loops.
136 *
137 * @post return getParent() == null ? 0 : getParent().getDepth() + 1
138 */
139 int getDepth();
140
141 /**
142 * Returns parent evaluator.
143 */
144 Evaluator getParent();
145
146 /**
147 * Returns the connection's locale.
148 */
149 Locale getConnectionLocale();
150
151 /**
152 * Retrieves the value of property <code>name</code>. If more than one
153 * member in the current context defines that property, the one with the
154 * highest solve order has precedence.
155 *
156 * <p>If the property is not defined, default value is returned.
157 */
158 Object getProperty(String name, Object defaultValue);
159
160 /**
161 * Returns a {@link SchemaReader} appropriate for the current
162 * access-control context.
163 */
164 SchemaReader getSchemaReader();
165
166 /**
167 * Simple caching of the result of an <code>Exp</code>. The
168 * key for the cache consists of all members of the current
169 * context that <code>exp</code> depends on. Members of
170 * independent dimensions are not part of the key.
171 *
172 * @see mondrian.calc.Calc#dependsOn
173 */
174 Object getCachedResult(ExpCacheDescriptor key);
175
176 /**
177 * Returns true for an axis that is NON EMPTY.
178 *
179 * <p>May be used by expression
180 * evaluators to optimize their result. For example, a top-level crossjoin
181 * may be optimized by removing all non-empty set elements before
182 * performing the crossjoin. This is possible because of the identity
183 *
184 * <blockquote><code>nonempty(crossjoin(a, b)) ==
185 * nonempty(crossjoin(nonempty(a), nonempty(b));</code></blockquote>
186 */
187 boolean isNonEmpty();
188
189 /**
190 * Sets whether an expression evaluation should filter out empty cells.
191 * Allows expressions to modify non empty flag to evaluate their children.
192 */
193 void setNonEmpty(boolean nonEmpty);
194
195 /**
196 * Creates an exception which indicates that an error has occurred during
197 * the runtime evaluation of a function. The caller should then throw that
198 * exception.
199 */
200 RuntimeException newEvalException(Object context, String s);
201
202 /**
203 * Evaluates a named set.
204 */
205 Object evaluateNamedSet(String name, Exp exp);
206
207 /**
208 * Returns an array of the members which make up the current context.
209 */
210 Member[] getMembers();
211
212 /**
213 * Returns the number of times that this evaluator has told a lie when
214 * retrieving cell values.
215 */
216 int getMissCount();
217
218 /**
219 * Returns the value of a parameter, evaluating its default value if it is
220 * not set.
221 */
222 Object getParameterValue(ParameterSlot slot);
223
224 /**
225 * @return the iteration length of the current context
226 */
227 int getIterationLength();
228
229 /**
230 * Sets the iteration length for the current evaluator context
231 *
232 * @param length length to be set
233 */
234 void setIterationLength(int length);
235
236 /**
237 * @return true if evaluating axes
238 */
239 boolean isEvalAxes();
240
241 /**
242 * Indicate whether the evaluator is evaluating the axes
243 *
244 * @param evalAxes true if evaluating axes
245 */
246 void setEvalAxes(boolean evalAxes);
247
248 /**
249 * Returns a new Aggregator whose aggregation context adds a given list of
250 * tuples, and whose dimensional context is the same as this
251 * Aggregator.
252 *
253 * @param list List of tuples
254 * @return Aggregator with <code>list</code> added to its aggregation
255 * context
256 */
257 Evaluator pushAggregation(List<Member[]> list);
258
259 /**
260 * Checks if unrelated dimensions to the measure in the current context
261 * should be ignored
262 * @return boolean
263 */
264 boolean shouldIgnoreUnrelatedDimensions();
265
266 /**
267 * Returns the base (non-virtual) cube that the current measure in the
268 * context belongs to.
269 * @return Cube
270 */
271 Cube getMeasureCube();
272
273 /**
274 * If IgnoreMeasureForNonJoiningDimension is set to true and one or more
275 * members are on unrelated dimension for the measure in current context
276 * then returns true.
277 * @param members
278 * dimensions for the members need to be checked whether
279 * related or unrelated
280 * @return boolean
281 */
282 boolean needToReturnNullForUnrelatedDimension(Member[] members);
283 }
284
285 // End Evaluator.java