001 /*
002 // $Id: //open/mondrian/src/main/mondrian/olap/CacheControl.java#6 $
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) 2006-2008 Julian Hyde and others.
007 // All Rights Reserved.
008 // You must accept the terms of that agreement to use this software.
009 */
010 package mondrian.olap;
011
012 import javax.sql.DataSource;
013 import java.util.*;
014 import java.io.PrintWriter;
015
016 /**
017 * API for controlling the contents of the cell cache and the member cache.
018 * A {@link CellRegion} denotes a portion of the cell cache, and a
019 * {@link MemberSet} denotes a portion of the member cache. Both caches can be
020 * flushed, and the member cache can be edited.
021 *
022 * <p>To create an instance of this interface, use
023 * {@link mondrian.olap.Connection#getCacheControl}.</p>
024 *
025 * <p>Methods concerning cell cache:<ul>
026 * <li>{@link #createMemberRegion(Member, boolean)}</li>
027 * <li>{@link #createMemberRegion(boolean, Member, boolean, Member, boolean)}</li>
028 * <li>{@link #createUnionRegion(mondrian.olap.CacheControl.CellRegion[])}</li>
029 * <li>{@link #createCrossjoinRegion(mondrian.olap.CacheControl.CellRegion[])}</li>
030 * <li>{@link #createMeasuresRegion(Cube)}</li>
031 * <li>{@link #flush(mondrian.olap.CacheControl.CellRegion)}</li>
032 * </ul></p>
033 *
034 * <p>Methods concerning member cache:<ul>
035 * <li>{@link #createMemberSet(Member, boolean)}</li>
036 * <li>{@link #createMemberSet(boolean, Member, boolean, Member, boolean)}</li>
037 * <li>{@link #createAddCommand(Member)}</li>
038 * <li>{@link #createDeleteCommand(Member)}</li>
039 * <li>{@link #createDeleteCommand(mondrian.olap.CacheControl.MemberSet)}</li>
040 * <li>{@link #createCompoundCommand(java.util.List)}</li>
041 * <li>{@link #createCompoundCommand(mondrian.olap.CacheControl.MemberEditCommand[])}</li>
042 * <li>{@link #createSetPropertyCommand(Member, String, Object)}</li>
043 * <li>{@link #createSetPropertyCommand(mondrian.olap.CacheControl.MemberSet,java.util.Map)}</li>
044 * <li>{@link #flush(mondrian.olap.CacheControl.MemberSet)}</li>
045 * <li>{@link #execute(mondrian.olap.CacheControl.MemberEditCommand)}</li>
046 * </ul></p>
047 *
048 * @author jhyde
049 * @version $Id: //open/mondrian/src/main/mondrian/olap/CacheControl.java#6 $
050 * @since Sep 27, 2006
051 */
052 public interface CacheControl {
053
054 // cell cache control
055
056 /**
057 * Creates a cell region consisting of a single member.
058 *
059 * @param member the member
060 * @param descendants When true, include descendants of the member in the
061 * region.
062 * @return the new cell region
063 */
064 CellRegion createMemberRegion(Member member, boolean descendants);
065
066 /**
067 * Creates a cell region consisting of a range between two members.
068 *
069 * <p>The members must belong to the same level of the same hierarchy.
070 * One of the bounds may be null.
071 *
072 * <p>For example, given
073 *
074 * <code><pre>Member member97Q3; // [Time].[1997].[Q3]
075 * Member member98Q2; // [Time].[1998].[Q2]
076 * </pre></code>
077 *
078 * then
079 *
080 * <table border="1">
081 * <tr>
082 * <th>Expression</th>
083 * <th>Meaning</th>
084 * </tr>
085 *
086 * <tr>
087 * <td>
088 * <code>createMemberRegion(true, member97Q3, true, member98Q2, false)</code>
089 * </td>
090 * <td>The members between 97Q3 and 98Q2, inclusive:<br/>
091 * [Time].[1997].[Q3],<br/>
092 * [Time].[1997].[Q4],<br/>
093 * [Time].[1998].[Q1],<br/>
094 * [Time].[1998].[Q2]</td>
095 * </tr>
096 *
097 * <tr>
098 * <td>
099 * <code>createMemberRegion(true, member97Q3, false, member98Q2, false)</code>
100 * </td>
101 * <td>The members between 97Q3 and 98Q2, exclusive:<br/>
102 * [Time].[1997].[Q4],<br/>
103 * [Time].[1998].[Q1]</td>
104 * </tr>
105 *
106 * <tr>
107 * <td>
108 * <code>createMemberRegion(true, member97Q3, false, member98Q2, false)</code>
109 * </td>
110 * <td>The members between 97Q3 and 98Q2, including their descendants, and
111 * including the lower bound but not the upper bound:<br/>
112 * [Time].[1997].[Q3],<br/>
113 * [Time].[1997].[Q3].[7],<br/>
114 * [Time].[1997].[Q3].[8],<br/>
115 * [Time].[1997].[Q3].[9],<br/>
116 * [Time].[1997].[Q4],<br/>
117 * [Time].[1997].[Q4].[10],<br/>
118 * [Time].[1997].[Q4].[11],<br/>
119 * [Time].[1997].[Q4].[12],<br/>
120 * [Time].[1998].[Q1],<br/>
121 * [Time].[1998].[Q1].[1],<br/>
122 * [Time].[1998].[Q1].[2],<br/>
123 * [Time].[1998].[Q1].[3]</td>
124 * </tr>
125 * </table>
126 *
127 * @param lowerInclusive whether the the range includes the lower bound;
128 * ignored if the lower bound is not specified
129 * @param lowerMember lower bound member.
130 * If null, takes all preceding members
131 * @param upperInclusive whether the the range includes the upper bound;
132 * ignored if the upper bound is not specified
133 * @param upperMember upper bound member.
134 * If null, takes all preceding members
135 * @param descendants when true, include descendants of the member in the
136 * region
137 * @return the new cell region
138 */
139 CellRegion createMemberRegion(
140 boolean lowerInclusive,
141 Member lowerMember,
142 boolean upperInclusive,
143 Member upperMember,
144 boolean descendants);
145
146 /**
147 * Forms the cartesian product of two or more cell regions.
148 * @param regions the operands
149 * @return the cartesian product of the operands
150 */
151 CellRegion createCrossjoinRegion(CellRegion... regions);
152
153 /**
154 * Forms the union of two or more cell regions.
155 * The regions must have the same dimensionality.
156 *
157 * @param regions the operands
158 * @return the cartesian product of the operands
159
160 */
161 CellRegion createUnionRegion(CellRegion... regions);
162
163 /**
164 * Creates a region consisting of all measures in a given cube.
165 * @param cube a cube
166 * @return the region
167 */
168 CellRegion createMeasuresRegion(Cube cube);
169
170 /**
171 * Atomically flushes all the cells in the cell cache that correspond to
172 * measures in a cube and to a given region.
173 *
174 * @param region a region
175 */
176 void flush(CellRegion region);
177
178 /**
179 * Prints the state of the cell cache as it pertains to a given region.
180 * @param pw the output target
181 * @param region the CellRegion of interest
182 */
183 void printCacheState(PrintWriter pw, CellRegion region);
184
185 // member cache control
186
187 /**
188 * Creates a member set containing either a single member, or a member and
189 * its descendants.
190 * @param member a member
191 * @param descendants when true, include descendants in the set
192 * @return the set
193 */
194 MemberSet createMemberSet(Member member, boolean descendants);
195
196 /**
197 * Creates a member set consisting of a range between two members.
198 * The members must belong to the same level of the same hierarchy. One of
199 * the bounds may be null. (Similar to {@link #createMemberRegion(boolean,
200 * Member, boolean, Member, boolean)}, which see for examples.)
201 *
202 * @param lowerInclusive whether the the range includes the lower bound;
203 * ignored if the lower bound is not specified
204 * @param lowerMember lower bound member.
205 * If null, takes all preceding members
206 * @param upperInclusive whether the the range includes the upper bound;
207 * ignored if the upper bound is not specified
208 * @param upperMember upper bound member.
209 * If null, takes all preceding members
210 * @param descendants when true, include descendants of the member in the
211 * region
212 * @return the set
213 */
214 MemberSet createMemberSet(
215 boolean lowerInclusive,
216 Member lowerMember,
217 boolean upperInclusive,
218 Member upperMember,
219 boolean descendants);
220
221 /**
222 * Forms the union of two or more member sets.
223 *
224 * @param sets the operands
225 * @return the union of the operands
226 */
227 MemberSet createUnionSet(MemberSet... sets);
228
229 /**
230 * Filters a member set, keeping all members at a given Level.
231 *
232 * @param level Level
233 * @param baseSet Member set
234 * @return Member set with members not at the given level removed
235 */
236 MemberSet filter(Level level, MemberSet baseSet);
237
238 /**
239 * Atomically flushes all members in the member cache which belong to a
240 * given set.
241 *
242 * @param set a set of members
243 */
244 void flush(MemberSet set);
245
246 /**
247 * Prints the state of the member cache as it pertains to a given member
248 * set.
249 * @param pw the output target
250 * @param set the MemberSet of interest
251 */
252 void printCacheState(PrintWriter pw, MemberSet set);
253
254
255 // edit member cache contents
256
257 /**
258 * Executes a command that edits the member cache.
259 * @param cmd the command
260 */
261 void execute(MemberEditCommand cmd);
262
263 /**
264 * Builds a compound command which is executed atomically.
265 *
266 * @param cmds a list of the component commands
267 * @return the compound command
268 */
269 MemberEditCommand createCompoundCommand(List<MemberEditCommand> cmds);
270
271 /**
272 * Builds a compound command which is executed atomically.
273 * @param cmds the component commands
274 * @return the compound command
275 */
276 MemberEditCommand createCompoundCommand(MemberEditCommand... cmds);
277
278 // commands to change the structure of the member cache
279
280 /**
281 * Creates a command to delete a member and its descendants from the member
282 * cache.
283 *
284 * @param member the member
285 * @return the command
286 */
287 MemberEditCommand createDeleteCommand(Member member);
288
289 /**
290 * Creates a command to delete a set of members from the member cache.
291 *
292 * @param memberSet the set
293 * @return the command
294 */
295 MemberEditCommand createDeleteCommand(MemberSet memberSet);
296
297 /**
298 * Creates a command to add a member to the cache. The added member and its
299 * parent must have the same Dimension and the correct Levels, Null parent
300 * means add to the top level of its Dimension.
301 *
302 * <p>The ordinal position of the new member among its siblings is implied
303 * by its properties.</p>
304 *
305 * @param member the new member
306 * @return the command
307 *
308 * @throws IllegalArgumentException if member null
309 * or if member belongs to a parent-child hierarchy
310 */
311 MemberEditCommand createAddCommand(
312 Member member) throws IllegalArgumentException;
313
314 /**
315 * Creates a command to Move a member (with its descendants) to a new
316 * location, that is to a new parent.
317 * @param member the member moved
318 * @param loc the new parent
319 * @return the command
320 *
321 * @throws IllegalArgumentException if member is null,
322 * or loc is null,
323 * or member belongs to a parent-child hierarchy,
324 * or if loc is incompatible with member
325 */
326 MemberEditCommand createMoveCommand(
327 Member member,
328 Member loc) throws IllegalArgumentException;
329
330 // commands to change member properties
331
332 /**
333 * Creates a command to change one property of a member.
334 *
335 * @param member the member
336 * @param name the property name
337 * @param value the property value
338 * @return the command
339 * @throws IllegalArgumentException if the property is invalid for the
340 * member
341 */
342 MemberEditCommand createSetPropertyCommand(
343 Member member,
344 String name,
345 Object value) throws IllegalArgumentException;
346
347 /**
348 * Creates a command to several properties changes over a set of
349 * members. All members must belong to the same Level.
350 *
351 * @param set the set of members
352 * @param propertyValues Collection of property-value pairs
353 * @return the command
354 * @throws IllegalArgumentException for an invalid property, or if all
355 * members in the set do not belong to the same Level.
356 */
357 MemberEditCommand createSetPropertyCommand(
358 MemberSet set,
359 Map<String,Object> propertyValues)
360 throws IllegalArgumentException;
361
362 // other
363
364 /**
365 * Prints a debug message.
366 *
367 * @param message the message
368 */
369 void trace(String message);
370
371 /**
372 * Flushes the cache which maps schema URLs to metadata.
373 *
374 * <p>This cache is referenced only when creating a new connection, so
375 * existing connections will continue to use the same schema definition.
376 */
377 void flushSchemaCache();
378
379 // todo: document
380 void flushSchema(
381 final String catalogUrl,
382 final String connectionKey,
383 final String jdbcUser,
384 String dataSourceStr);
385
386 // todo: document
387 void flushSchema(
388 String catalogUrl,
389 DataSource dataSource);
390
391 /**
392 * Flushes the given Schema instance from the pool
393 *
394 * @param schema Schema
395 */
396 void flushSchema(Schema schema);
397
398
399 /** a region of cells in the cell cache */
400 public interface CellRegion {
401 /**
402 * Returns the dimensionality of a region.
403 * @return a list of {@link mondrian.olap.Dimension} objects.
404 */
405 List<Dimension> getDimensionality();
406 }
407
408 /**
409 * A specification of a set of members in the member cache.
410 *
411 * <p>Member sets can be created using methods
412 * {@link CacheControl#createMemberSet(Member, boolean)},
413 * {@link CacheControl#createMemberSet(boolean, Member, boolean, Member, boolean)},
414 * {@link CacheControl#createUnionSet(mondrian.olap.CacheControl.MemberSet[])}.
415 */
416 public interface MemberSet {
417 }
418
419 /**
420 * An operation to be applied to the member cache. The operation does not
421 * take effect until {@link CacheControl#execute} is called.
422 */
423 public interface MemberEditCommand {
424 }
425
426 }
427
428 // End CacheControl.java