001 /*
002 // $Id: OlapDatabaseMetaData.java 125 2008-11-02 07:43:12Z jhyde $
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
007 // All Rights Reserved.
008 // You must accept the terms of that agreement to use this software.
009 */
010 package org.olap4j;
011
012 import org.olap4j.metadata.Member;
013
014 import java.sql.DatabaseMetaData;
015 import java.sql.ResultSet;
016 import java.sql.SQLException;
017 import java.util.Set;
018
019 /**
020 * Information about an OLAP database.
021 *
022 * <p>Methods are provided to query the metadata catalog of the database.
023 * There is a method for each metadata class, and each method takes zero or more
024 * parameters to qualify the instances should be returned, and returns a JDBC
025 * {@link java.sql.ResultSet}.
026 *
027 * <p>For example, {@link #getCubes} returns the description of a cube.
028 *
029 * @author jhyde
030 * @version $Id: OlapDatabaseMetaData.java 125 2008-11-02 07:43:12Z jhyde $
031 * @since Oct 12, 2006
032 */
033 public interface OlapDatabaseMetaData extends DatabaseMetaData, OlapWrapper {
034
035 // override return type
036 /**
037 * {@inheritDoc}
038 */
039 OlapConnection getConnection() throws SQLException;
040
041 /**
042 * Retrieves a result set describing the Actions in this database.
043 *
044 * <p>Specification as for XML/A MDSCHEMA_ACTIONS schema rowset.
045 *
046 * <p>Each action description has the following columns:
047 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of
048 * the schema to which this action belongs.</li>
049 * <li><b>CUBE_NAME</b> String => The name of the cube to which this action
050 * belongs.</li>
051 * <li><b>ACTION_NAME</b> String => The name of the action.</li>
052 * <li><b>COORDINATE</b> String => null</li>
053 * <li><b>COORDINATE_TYPE</b> int => null</li>
054 * </ol>
055 *
056 * @param catalog a catalog name; must match the catalog name as it
057 * is stored in the database; "" retrieves those without a catalog;
058 * <code>null</code> means that the catalog name should not be used
059 * to narrow the search
060 *
061 * @param schemaPattern a schema name pattern; must match the schema name
062 * as it is stored in the database; "" retrieves those without a
063 * schema; <code>null</code> means that the schema name should not
064 * be used to narrow the search
065 *
066 * @param cubeNamePattern a cube name pattern; must match the
067 * cube name as it is stored in the database; "" retrieves those
068 * without a cube (such as shared dimensions);
069 * <code>null</code> means that the cube name should
070 * not be used to narrow the search
071 *
072 * @param actionNamePattern an action name pattern; must match the
073 * action name as it is stored in the database; <code>null</code>
074 * means that the action name should not be used to narrow the
075 * search
076 *
077 * @return a <code>ResultSet</code> object in which each row is an
078 * action description
079 *
080 * @exception OlapException if a database access error occurs
081 *
082 * @see #getSearchStringEscape
083 */
084 ResultSet getActions(
085 String catalog,
086 String schemaPattern,
087 String cubeNamePattern,
088 String actionNamePattern) throws OlapException;
089
090 /**
091 * Retrives a list of olap4j data sources that are available on the server.
092 *
093 * <p>Specification as for XML/A DISCOVER_DATASOURCES schema rowset.
094 *
095 * <ol>
096 * <li><b>DATA_SOURCE_NAME</b> String => The name of the data source, such
097 * as FoodMart 2000.</li>
098 * <li><b>DATA_SOURCE_DESCRIPTION</b> String => A description of the data
099 * source, as entered by the publisher. (may be
100 * <code>null</code>)</li>
101 * <li><b>URL</b> String => The unique path that shows where to invoke the
102 * XML for Analysis methods for that data source. (may be
103 * <code>null</code>)</li>
104 * <li><b>DATA_SOURCE_INFO</b> String => A string containing any additional
105 * information required to connect to the data source. This can
106 * include the Initial Catalog property or other information for
107 * the provider.<br/>Example: "Provider=MSOLAP;Data
108 * Source=Local;" (may be <code>null</code>)</li>
109 * <li><b>PROVIDER_NAME</b> String => The name of the provider behind the
110 * data source. <br/>Example: "MSDASQL" (may be
111 * <code>null</code>)</li>
112 * <li><b>PROVIDER_TYPE</b> EnumerationArray => The types of data supported
113 * by the provider. May include one or more of the following
114 * types. Example follows this table.<br/>TDP: tabular data
115 * provider.<br/>MDP: multidimensional data provider.<br/>DMP:
116 * data mining provider. A DMP provider implements the OLE DB for
117 * Data Mining specification.</li>
118 * <li><b>AUTHENTICATION_MODE</b> EnumString => Specification of what type
119 * of security mode the data source uses. Values can be one of
120 * the following:<br/>Unauthenticated: no user ID or password
121 * needs to be sent.<br/>Authenticated: User ID and Password must
122 * be included in the information required for the
123 * connection.<br/>Integrated: the data source uses the
124 * underlying security to determine authorization, such as
125 * Integrated Security provided by Microsoft Internet Information
126 * Services (IIS).</li>
127 * </ol>
128 *
129 * @return a <code>ResultSet</code> object in which each row is a
130 * datasource description
131 *
132 * @exception OlapException if a database access error occurs
133 */
134 ResultSet getDatasources() throws OlapException;
135
136 /**
137 * Retrieves a list of information on supported literals, including data
138 * types and values.
139 *
140 * <p>Specification as for XML/A DISCOVER_LITERALS schema rowset.
141 *
142 * <ol>
143 * <li><b>LITERAL_NAME</b> String => The name of the literal described in
144 * the row.<br/>Example: DBLITERAL_LIKE_PERCENT</li>
145 * <li><b>LITERAL_VALUE</b> String (may be <code>null</code>) => Contains
146 * the actual literal value.<br/>Example, if LiteralName is
147 * DBLITERAL_LIKE_PERCENT and the percent character (%) is used
148 * to match zero or more characters in a LIKE clause, this
149 * column's value would be "%".</li>
150 * <li><b>LITERAL_INVALID_CHARS</b> String (may be <code>null</code>) =>
151 * The characters, in the literal, that are not valid.<br/>For
152 * example, if table names can contain anything other than a
153 * numeric character, this string would be "0123456789".</li>
154 * <li><b>LITERAL_INVALID_STARTING_CHARS</b> String (may be
155 * <code>null</code>) => The characters that are not valid as the
156 * first character of the literal. If the literal can start with
157 * any valid character, this is null.</li>
158 * <li><b>LITERAL_MAX_LENGTH</b> int (may be <code>null</code>) => The
159 * maximum number of characters in the literal. If there is no
160 * maximum or the maximum is unknown, the value is -1.</li>
161 * </ol>
162 *
163 * @return a <code>ResultSet</code> object in which each row is a
164 * literal description
165 *
166 * @exception OlapException if a database access error occurs
167 */
168 ResultSet getLiterals() throws OlapException;
169
170 /**
171 * Retrieves a list of the standard and provider-specific properties
172 * supported by an olap4j provider. Properties that are not supported by a
173 * provider are not listed in the return result set.
174 *
175 * <p>Specification as for XML/A DISCOVER_PROPERTIES schema rowset.
176 *
177 * <p>Not to be confused with {@link #getProperties}.
178 *
179 * <ol>
180 * <li><b>PROPERTY_NAME</b> String => The name of the property.</li>
181 * <li><b>PROPERTY_DESCRIPTION</b> String => A localizable text description
182 * of the property.</li>
183 * <li><b>PROPERTY_TYPE</b> String => The XML data type of the
184 * property.</li>
185 * <li><b>PROPERTY_ACCESS_TYPE</b> EnumString => Access for the property.
186 * The value can be Read, Write, or ReadWrite.</li>
187 * <li><b>IS_REQUIRED</b> Boolean => True if a property is required, false
188 * if it is not required.</li>
189 * <li><b>PROPERTY_VALUE</b> String => The current value of the
190 * property.</li>
191 * </ol>
192 *
193 * @param dataSourceName Name of data source
194 *
195 * @param propertyNamePattern an property name pattern; must match the
196 * property name as it is stored in the database; <code>null</code>
197 * means that the property name should not be used to narrow the
198 * search
199 *
200 * @return a <code>ResultSet</code> object in which each row is a
201 * the description of a database property
202 *
203 * @exception OlapException if a database access error occurs
204 *
205 * @see #getSearchStringEscape
206 */
207 ResultSet getDatabaseProperties(
208 String dataSourceName,
209 String propertyNamePattern) throws OlapException;
210
211 /**
212 * Retrieves a result set describing member and cell Properties.
213 *
214 * <p>Specification as for XML/A MDSCHEMA_PROPERTIES schema rowset.
215 *
216 * <p>Not to be confused with {@link #getDatabaseProperties(String,String)}.
217 *
218 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of
219 * the database.</li>
220 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of
221 * the schema to which this property belongs.</li>
222 * <li><b>CUBE_NAME</b> String => The name of the cube.</li>
223 * <li><b>DIMENSION_UNIQUE_NAME</b> String => The unique name of the
224 * dimension.</li>
225 * <li><b>HIERARCHY_UNIQUE_NAME</b> String => The unique name of the
226 * hierarchy.</li>
227 * <li><b>LEVEL_UNIQUE_NAME</b> String => The unique name of the level to
228 * which this property belongs.</li>
229 * <li><b>MEMBER_UNIQUE_NAME</b> String (may be <code>null</code>) => The
230 * unique name of the member to which the property belongs.</li>
231 * <li><b>PROPERTY_NAME</b> String => Name of the property.</li>
232 * <li><b>PROPERTY_CAPTION</b> String => A label or caption associated with
233 * the property, used primarily for display purposes.</li>
234 * <li><b>PROPERTY_TYPE</b> Short => A bitmap that specifies the type of
235 * the property</li>
236 * <li><b>DATA_TYPE</b> UnsignedShort => Data type of the property.</li>
237 * <li><b>PROPERTY_CONTENT_TYPE</b> Short (may be <code>null</code>) => The
238 * type of the property. </li>
239 * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A
240 * human-readable description of the measure. </li>
241 * </ol>
242 *
243 * @param catalog a catalog name; must match the catalog name as it
244 * is stored in the database; "" retrieves those without a catalog;
245 * <code>null</code> means that the catalog name should not be used
246 * to narrow the search
247 *
248 * @param schemaPattern a schema name pattern; must match the schema
249 * name as it is stored in the database; "" retrieves those without
250 * a schema; <code>null</code> means that the schema name should not
251 * be used to narrow the search
252 *
253 * @param cubeNamePattern a cube name pattern; must match the
254 * cube name as it is stored in the database; "" retrieves those
255 * without a cube; <code>null</code> means that the cube name should
256 * not be used to narrow the search
257 *
258 * @param dimensionUniqueName unique name of a dimension (not a pattern);
259 * must match the dimension name as it is stored in the database;
260 * <code>null</code> means that the dimension name should not be
261 * used to narrow the search
262 *
263 * @param hierarchyUniqueName unique name of a hierarchy (not a pattern);
264 * must match the
265 * hierarchy name as it is stored in the database; <code>null</code>
266 * means that the hierarchy name should not be used to narrow the
267 * search
268 *
269 * @param levelUniqueName unique name of a level (not a pattern);
270 * must match the
271 * level name as it is stored in the database; <code>null</code>
272 * means that the level name should not be used to narrow the
273 * search
274 *
275 * @param memberUniqueName unique name of member (not a pattern);
276 * <code>null</code>
277 * means that the member unique name should not be used to narrow
278 * the search
279 *
280 * @param propertyNamePattern a property name pattern; must match the
281 * property name as it is stored in the database; <code>null</code>
282 * means that the property name should not be used to narrow the
283 * search
284 *
285 * @return a <code>ResultSet</code> object in which each row is a
286 * description of a member or cell property
287 *
288 * @exception OlapException if a database access error occurs
289 *
290 * @see #getSearchStringEscape
291 * @see org.olap4j.metadata.Property
292 */
293 ResultSet getProperties(
294 String catalog,
295 String schemaPattern,
296 String cubeNamePattern,
297 String dimensionUniqueName,
298 String hierarchyUniqueName,
299 String levelUniqueName,
300 String memberUniqueName,
301 String propertyNamePattern) throws OlapException;
302
303 /**
304 * Retrieves a comma-separated list of all of this database's MDX keywords.
305 *
306 * @return the list of this database's MDX keywords
307 *
308 * @exception OlapException if a database access error occurs
309 */
310 String getMdxKeywords() throws OlapException;
311
312 /**
313 * Retrieves a result set describing the Cubes in this database.
314 *
315 * <p>Specification as for XML/A MDSCHEMA_CUBES schema rowset.
316 *
317 * <p>Each cube description has the following columns:
318 * <ol>
319 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of
320 * the catalog to which this cube belongs.</li>
321 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of
322 * the schema to which this cube belongs.</li>
323 * <li><b>CUBE_NAME</b> String => Name of the cube.</li>
324 * <li><b>CUBE_TYPE</b> String => Cube type.</li>
325 * <li><b>CUBE_GUID</b> UUID (may be <code>null</code>) => Cube type.</li>
326 * <li><b>CREATED_ON</b> Timestamp (may be <code>null</code>) => Date and
327 * time of cube creation.</li>
328 * <li><b>LAST_SCHEMA_UPDATE</b> Timestamp (may be <code>null</code>) =>
329 * Date and time of last schema update.</li>
330 * <li><b>SCHEMA_UPDATED_BY</b> String (may be <code>null</code>) => User
331 * ID of the person who last updated the schema.</li>
332 * <li><b>LAST_DATA_UPDATE</b> Timestamp (may be <code>null</code>) => Date
333 * and time of last data update.</li>
334 * <li><b>DATA_UPDATED_BY</b> String (may be <code>null</code>) => User ID
335 * of the person who last updated the data. </li>
336 * <li><b>IS_DRILLTHROUGH_ENABLED</b> boolean => Describes whether
337 * DRILLTHROUGH can be performed on the members of a cube</li>
338 * <li><b>IS_WRITE_ENABLED</b> boolean => Describes whether a cube is
339 * write-enabled</li>
340 * <li><b>IS_LINKABLE</b> boolean => Describes whether a cube can be used
341 * in a linked cube</li>
342 * <li><b>IS_SQL_ENABLED</b> boolean => Describes whether or not SQL can be
343 * used on the cube</li>
344 * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A
345 * user-friendly description of the dimension.</li>
346 * </ol>
347 *
348 * @param catalog a catalog name; must match the catalog name as it
349 * is stored in the database; "" retrieves those without a catalog;
350 * <code>null</code> means that the catalog name should not be used
351 * to narrow the search
352 *
353 * @param schemaPattern a schema name pattern; must match the schema
354 * name as it is stored in the database; "" retrieves those without
355 * a schema; <code>null</code> means that the schema name should not
356 * be used to narrow the search
357 *
358 * @param cubeNamePattern a cube name pattern; must match the
359 * cube name as it is stored in the database; <code>null</code>
360 * means that the cube name should not be used to narrow the search
361 *
362 * @return <code>ResultSet</code> in which each row is a cube description
363 *
364 * @exception OlapException if a database access error occurs
365 *
366 * @see #getSearchStringEscape
367 * @see org.olap4j.metadata.Cube
368 */
369 public ResultSet getCubes(
370 String catalog,
371 String schemaPattern,
372 String cubeNamePattern) throws OlapException;
373
374 /**
375 * Retrieves a result set describing the shared and private Dimensions
376 * in this database.
377 *
378 * <p>Specification as for XML/A MDSCHEMA_DIMENSIONS schema rowset.
379 *
380 * <p>Each dimension description has the following columns:
381 * <ol>
382 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of
383 * the database.</li>
384 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => Not
385 * supported.</li>
386 * <li><b>CUBE_NAME</b> String => The name of the cube.</li>
387 * <li><b>DIMENSION_NAME</b> String => The name of the dimension. </li>
388 * <li><b>DIMENSION_UNIQUE_NAME</b> String => The unique name of the
389 * dimension.</li>
390 * <li><b>DIMENSION_GUID</b> String (may be <code>null</code>) => Not
391 * supported.</li>
392 * <li><b>DIMENSION_CAPTION</b> String => The caption of the
393 * dimension.</li>
394 * <li><b>DIMENSION_ORDINAL</b> int => The position of the dimension within
395 * the cube.</li>
396 * <li><b>DIMENSION_TYPE</b> Short => The type of the dimension.</li>
397 * <li><b>DIMENSION_CARDINALITY</b> int => The number of members in the key
398 * attribute.</li>
399 * <li><b>DEFAULT_HIERARCHY</b> String => A hierarchy from the dimension.
400 * Preserved for backwards compatibility.</li>
401 * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A
402 * user-friendly description of the dimension.</li>
403 * <li><b>IS_VIRTUAL</b> boolean (may be <code>null</code>) => Always
404 * FALSE.</li>
405 * <li><b>IS_READWRITE</b> boolean (may be <code>null</code>) => A Boolean
406 * that indicates whether the dimension is write-enabled.</li>
407 * <li><b>DIMENSION_UNIQUE_SETTINGS</b> int (may be <code>null</code>) => A
408 * bitmap that specifies which columns contain unique values if
409 * the dimension contains only members with unique names.</li>
410 * <li><b>DIMENSION_MASTER_UNIQUE_NAME</b> String (may be
411 * <code>null</code>) => Always NULL.</li>
412 * <li><b>DIMENSION_IS_VISIBLE</b> boolean (may be <code>null</code>) =>
413 * Always TRUE.</li>
414 * </ol>
415 *
416 * @param catalog a catalog name; must match the catalog name as it
417 * is stored in the database; "" retrieves those without a catalog;
418 * <code>null</code> means that the catalog name should not be used
419 * to narrow the search
420 *
421 * @param schemaPattern a schema name pattern; must match the schema name
422 * as it is stored in the database; "" retrieves those without a
423 * schema; <code>null</code> means that the schema name should not
424 * be used to narrow the search
425 *
426 * @param cubeNamePattern a cube name pattern; must match the
427 * cube name as it is stored in the database; "" retrieves those
428 * without a cube (such as shared dimensions);
429 * <code>null</code> means that the cube name should
430 * not be used to narrow the search
431 *
432 * @param dimensionNamePattern a dimension name pattern; must match the
433 * dimension name as it is stored in the database; <code>null</code>
434 * means that the dimension name should not be used to narrow the
435 * search
436 *
437 * @return a <code>ResultSet</code> object in which each row is a
438 * dimension description
439 *
440 * @exception OlapException if a database access error occurs
441 *
442 * @see #getSearchStringEscape
443 * @see org.olap4j.metadata.Dimension
444 */
445 ResultSet getDimensions(
446 String catalog,
447 String schemaPattern,
448 String cubeNamePattern,
449 String dimensionNamePattern) throws OlapException;
450
451 /**
452 * Retrieves a result set describing the Functions available to client
453 * applications connected to the database.
454 *
455 * <p>Specification as for XML/A MDSCHEMA_FUNCTIONS schema rowset.
456 *
457 * <p>Each function description has the following columns:
458 * <li><b>FUNCTION_NAME</b> String => The name of the function.</li>
459 * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A
460 * description of the function.</li>
461 * <li><b>PARAMETER_LIST</b> String (may be <code>null</code>) => A comma
462 * delimited list of parameters.</li>
463 * <li><b>RETURN_TYPE</b> int => The VARTYPE of the return data type of the
464 * function.</li>
465 * <li><b>ORIGIN</b> int => The origin of the function: 1 for MDX
466 * functions. 2 for user-defined functions.</li>
467 * <li><b>INTERFACE_NAME</b> String => The name of the interface for
468 * user-defined functions</li>
469 * <li><b>LIBRARY_NAME</b> String (may be <code>null</code>) => The name of
470 * the type library for user-defined functions. NULL for MDX
471 * functions.</li>
472 * <li><b>CAPTION</b> String (may be <code>null</code>) => The display
473 * caption for the function.</li>
474 * </ol>
475 *
476 * @param functionNamePattern a function name pattern; must match the
477 * function name as it is stored in the database; <code>null</code>
478 * means that the function name should not be used to narrow the
479 * search
480 *
481 * @return a <code>ResultSet</code> object in which each row is a
482 * function description
483 *
484 * @exception OlapException if a database access error occurs
485 *
486 * @see java.sql.DatabaseMetaData#getFunctions(String, String, String)
487 * @see #getSearchStringEscape
488 */
489 ResultSet getOlapFunctions(
490 String functionNamePattern) throws OlapException;
491
492 /**
493 * Retrieves a result set describing the Hierarchies in this database.
494 *
495 * <p>Specification as for XML/A MDSCHEMA_HIERARCHIES schema rowset.
496 *
497 * <p>Each hierarchy description has the following columns:
498 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of
499 * the catalog to which this hierarchy belongs.</li>
500 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => Not
501 * supported</li>
502 * <li><b>CUBE_NAME</b> String => The name of the cube to which this
503 * hierarchy belongs.</li>
504 * <li><b>DIMENSION_UNIQUE_NAME</b> String => The unique name of the
505 * dimension to which this hierarchy belongs. </li>
506 * <li><b>HIERARCHY_NAME</b> String => The name of the hierarchy. Blank if
507 * there is only a single hierarchy in the dimension.</li>
508 * <li><b>HIERARCHY_UNIQUE_NAME</b> String => The unique name of the
509 * hierarchy.</li>
510 * <li><b>HIERARCHY_GUID</b> String (may be <code>null</code>) => Hierarchy
511 * GUID.</li>
512 * <li><b>HIERARCHY_CAPTION</b> String => A label or a caption associated
513 * with the hierarchy.</li>
514 * <li><b>DIMENSION_TYPE</b> Short => The type of the dimension. </li>
515 * <li><b>HIERARCHY_CARDINALITY</b> int => The number of members in the
516 * hierarchy.</li>
517 * <li><b>DEFAULT_MEMBER</b> String (may be <code>null</code>) => The
518 * default member for this hierarchy. </li>
519 * <li><b>ALL_MEMBER</b> String (may be <code>null</code>) => The member at
520 * the highest level of rollup in the hierarchy.</li>
521 * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A
522 * human-readable description of the hierarchy. NULL if no
523 * description exists.</li>
524 * <li><b>STRUCTURE</b> Short => The structure of the hierarchy.</li>
525 * <li><b>IS_VIRTUAL</b> boolean => Always returns False.</li>
526 * <li><b>IS_READWRITE</b> boolean => A Boolean that indicates whether the
527 * Write Back to dimension column is enabled.</li>
528 * <li><b>DIMENSION_UNIQUE_SETTINGS</b> int => Always returns
529 * MDDIMENSIONS_MEMBER_KEY_UNIQUE (1).</li>
530 * <li><b>DIMENSION_IS_VISIBLE</b> boolean => Always returns true.</li>
531 * <li><b>HIERARCHY_ORDINAL</b> int => The ordinal number of the hierarchy
532 * across all hierarchies of the cube.</li>
533 * <li><b>DIMENSION_IS_SHARED</b> boolean => Always returns true.</li>
534 * <li><b>PARENT_CHILD</b> boolean (may be <code>null</code>) => Is
535 * hierarchy a parent.</li>
536 * </ol>
537 *
538 * @param catalog a catalog name; must match the catalog name as it
539 * is stored in the database; "" retrieves those without a catalog;
540 * <code>null</code> means that the catalog name should not be used
541 * to narrow the search
542 *
543 * @param schemaPattern a schema name pattern; must match the schema name
544 * as it is stored in the database; "" retrieves those without a
545 * schema; <code>null</code> means that the schema name should not
546 * be used to narrow the search
547 *
548 * @param cubeNamePattern a cube name pattern; must match the
549 * cube name as it is stored in the database; "" retrieves those
550 * without a cube; <code>null</code> means that the cube name should
551 * not be used to narrow the search
552 *
553 * @param dimensionNamePattern a dimension name pattern; must match the
554 * dimension name as it is stored in the database; <code>null</code>
555 * means that the dimension name should not be used to narrow the
556 * search
557 *
558 * @param hierarchyNamePattern a hierarchy name pattern; must match the
559 * hierarchy name as it is stored in the database; <code>null</code>
560 * means that the hierarchy name should not be used to narrow the
561 * search
562 *
563 * @return a <code>ResultSet</code> object in which each row is a
564 * hierarchy description
565 *
566 * @exception OlapException if a database access error occurs
567 *
568 * @see #getSearchStringEscape
569 * @see org.olap4j.metadata.Hierarchy
570 */
571 ResultSet getHierarchies(
572 String catalog,
573 String schemaPattern,
574 String cubeNamePattern,
575 String dimensionNamePattern,
576 String hierarchyNamePattern) throws OlapException;
577
578 /**
579 * Retrieves a result set describing the Levels in this database.
580 *
581 * <p>Specification as for XML/A MDSCHEMA_LEVELS schema rowset.
582 *
583 * <p>Each level description has the following columns:
584 * <ol>
585 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of
586 * the catalog to which this level belongs.</li>
587 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of
588 * the schema to which this level belongs.</li>
589 * <li><b>CUBE_NAME</b> String => The name of the cube to which this level
590 * belongs.</li>
591 * <li><b>DIMENSION_UNIQUE_NAME</b> String => The unique name of the
592 * dimension to which this level belongs.</li>
593 * <li><b>HIERARCHY_UNIQUE_NAME</b> String => The unique name of the
594 * hierarchy.</li>
595 * <li><b>LEVEL_NAME</b> String => The name of the level.</li>
596 * <li><b>LEVEL_UNIQUE_NAME</b> String => The properly escaped unique name
597 * of the level.</li>
598 * <li><b>LEVEL_GUID</b> String (may be <code>null</code>) => Level
599 * GUID.</li>
600 * <li><b>LEVEL_CAPTION</b> String => A label or caption associated with
601 * the hierarchy.</li>
602 * <li><b>LEVEL_NUMBER</b> int => The distance of the level from the root
603 * of the hierarchy. Root level is zero (0).</li>
604 * <li><b>LEVEL_CARDINALITY</b> int => The number of members in the level.
605 * This value can be an approximation of the real
606 * cardinality.</li>
607 * <li><b>LEVEL_TYPE</b> int => Type of the level</li>
608 * <li><b>CUSTOM_ROLLUP_SETTINGS</b> int => A bitmap that specifies the
609 * custom rollup options.</li>
610 * <li><b>LEVEL_UNIQUE_SETTINGS</b> int => A bitmap that specifies which
611 * columns contain unique values, if the level only has members
612 * with unique names or keys.</li>
613 * <li><b>LEVEL_IS_VISIBLE</b> boolean => A Boolean that indicates whether
614 * the level is visible.</li>
615 * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A
616 * human-readable description of the level. NULL if no
617 * description exists.</li>
618 * </ol>
619 *
620 * @param catalog a catalog name; must match the catalog name as it
621 * is stored in the database; "" retrieves those without a catalog;
622 * <code>null</code> means that the catalog name should not be used
623 * to narrow the search
624 *
625 * @param schemaPattern a schema name pattern; must match the schema name
626 * as it is stored in the database; "" retrieves those without a
627 * schema; <code>null</code> means that the schema name should not
628 * be used to narrow the search
629 *
630 * @param cubeNamePattern a cube name pattern; must match the
631 * cube name as it is stored in the database; "" retrieves those
632 * without a cube; <code>null</code> means that the cube name should
633 * not be used to narrow the search
634 *
635 * @param dimensionUniqueName unique name of a dimension (not a pattern);
636 * must match the
637 * dimension name as it is stored in the database; <code>null</code>
638 * means that the dimension name should not be used to narrow the
639 * search
640 *
641 * @param hierarchyUniqueName unique name of a hierarchy (not a pattern);
642 * must match the
643 * hierarchy name as it is stored in the database; <code>null</code>
644 * means that the hierarchy name should not be used to narrow the
645 * search
646 *
647 * @param levelNamePattern a level name pattern; must match the
648 * level name as it is stored in the database; <code>null</code>
649 * means that the level name should not be used to narrow the
650 * search
651 *
652 * @return a <code>ResultSet</code> object in which each row is a
653 * level description
654 *
655 * @exception OlapException if a database access error occurs
656 *
657 * @see #getSearchStringEscape
658 * @see org.olap4j.metadata.Level
659 */
660 ResultSet getLevels(
661 String catalog,
662 String schemaPattern,
663 String cubeNamePattern,
664 String dimensionUniqueName,
665 String hierarchyUniqueName,
666 String levelNamePattern) throws OlapException;
667
668 /**
669 * Retrieves a result set describing the Measures in this database.
670 *
671 * <p>Specification as for XML/A MDSCHEMA_MEASURES schema rowset.
672 *
673 * <p>Each measure description has the following columns:
674 * <ol>
675 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of
676 * the catalog to which this measure belongs. </li>
677 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of
678 * the schema to which this measure belongs.</li>
679 * <li><b>CUBE_NAME</b> String => The name of the cube to which this
680 * measure belongs.</li>
681 * <li><b>MEASURE_NAME</b> String => The name of the measure.</li>
682 * <li><b>MEASURE_UNIQUE_NAME</b> String => The Unique name of the
683 * measure.</li>
684 * <li><b>MEASURE_CAPTION</b> String => A label or caption associated with
685 * the measure. </li>
686 * <li><b>MEASURE_GUID</b> String (may be <code>null</code>) => Measure
687 * GUID.</li>
688 * <li><b>MEASURE_AGGREGATOR</b> int => How a measure was derived. </li>
689 * <li><b>DATA_TYPE</b> UnsignedShort => Data type of the measure.</li>
690 * <li><b>MEASURE_IS_VISIBLE</b> boolean => A Boolean that always returns
691 * True. If the measure is not visible, it will not be included
692 * in the schema rowset.</li>
693 * <li><b>LEVELS_LIST</b> String (may be <code>null</code>) => A string
694 * that always returns NULL. EXCEPT that SQL Server returns
695 * non-null values!!!</li>
696 * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A
697 * human-readable description of the measure. </li>
698 * </ol>
699 *
700 * @param catalog a catalog name; must match the catalog name as it
701 * is stored in the database; "" retrieves those without a catalog;
702 * <code>null</code> means that the catalog name should not be used
703 * to narrow the search
704 *
705 * @param schemaPattern a schema name pattern; must match the schema name
706 * as it is stored in the database; "" retrieves those without a
707 * schema; <code>null</code> means that the schema name should not
708 * be used to narrow the search
709 *
710 * @param cubeNamePattern a cube name pattern; must match the
711 * cube name as it is stored in the database; "" retrieves those
712 * without a cube; <code>null</code> means that the cube name should
713 * not be used to narrow the search
714 *
715 * @param measureNamePattern a measure name pattern; must match the
716 * measure name as it is stored in the database; <code>null</code>
717 * means that the measure name should not be used to narrow the
718 * search
719 *
720 * @param measureUniqueName unique name of measure (not a pattern);
721 * <code>null</code> means that the measure unique name should not
722 * be used to narrow the search
723 *
724 * @return a <code>ResultSet</code> object in which each row is a
725 * measure description
726 *
727 * @exception OlapException if a database access error occurs
728 *
729 * @see #getSearchStringEscape
730 * @see org.olap4j.metadata.Measure
731 */
732 ResultSet getMeasures(
733 String catalog,
734 String schemaPattern,
735 String cubeNamePattern,
736 String measureNamePattern,
737 String measureUniqueName) throws OlapException;
738
739 /**
740 * Retrieves a result set describing the Members in this database.
741 *
742 * <p>Specification as for XML/A MDSCHEMA_MEMBERS schema rowset. Rows
743 * are sorted by level number then by ordinal.
744 *
745 * <p>The <code>treeOps</code> parameter allows you to retrieve members
746 * relative to a given member. It is only applicable if a
747 * <code>memberUniqueName</code> is also specified; otherwise it is
748 * ignored. The following example retrieves all descendants and ancestors
749 * of California, but not California itself:
750 *
751 * <blockquote>
752 * <pre>
753 * OlapDatabaseMetaData metaData;
754 * ResultSet rset = metaData.getMembers(
755 * "LOCALDB", "FoodMart", "Sales", null, null, null,
756 * "[Customers].[USA].[CA]",
757 * EnumSet.of(Member.TreeOp.ANCESTORS, Member.TreeOp.DESCENDANTS));
758 * </pre>
759 * </blockquote>
760 *
761 * <p>Each member description has the following columns:
762 * <ol>
763 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of
764 * the catalog to which this member belongs. </li>
765 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of
766 * the schema to which this member belongs. </li>
767 * <li><b>CUBE_NAME</b> String => Name of the cube to which this member
768 * belongs.</li>
769 * <li><b>DIMENSION_UNIQUE_NAME</b> String => Unique name of the dimension
770 * to which this member belongs. </li>
771 * <li><b>HIERARCHY_UNIQUE_NAME</b> String => Unique name of the hierarchy.
772 * If the member belongs to more than one hierarchy, there is one
773 * row for each hierarchy to which it belongs.</li>
774 * <li><b>LEVEL_UNIQUE_NAME</b> String => Unique name of the level to
775 * which the member belongs.</li>
776 * <li><b>LEVEL_NUMBER</b> int => The distance of the member from the root
777 * of the hierarchy.</li>
778 * <li><b>MEMBER_ORDINAL</b> int => Ordinal number of the member. Sort rank
779 * of the member when members of this dimension are sorted in
780 * their natural sort order. If providers do not have the concept
781 * of natural ordering, this should be the rank when sorted by
782 * MEMBER_NAME.</li>
783 * <li><b>MEMBER_NAME</b> String => Name of the member.</li>
784 * <li><b>MEMBER_UNIQUE_NAME</b> String => Unique name of the member.</li>
785 * <li><b>MEMBER_TYPE</b> int => Type of the member.</li>
786 * <li><b>MEMBER_GUID</b> String (may be <code>null</code>) => Memeber
787 * GUID.</li>
788 * <li><b>MEMBER_CAPTION</b> String => A label or caption associated with
789 * the member.</li>
790 * <li><b>CHILDREN_CARDINALITY</b> int => Number of children that the
791 * member has.</li>
792 * <li><b>PARENT_LEVEL</b> int => The distance of the member's parent from
793 * the root level of the hierarchy. </li>
794 * <li><b>PARENT_UNIQUE_NAME</b> String (may be <code>null</code>) =>
795 * Unique name of the member's parent.</li>
796 * <li><b>PARENT_COUNT</b> int => Number of parents that this member
797 * has.</li>
798 * <li><b>TREE_OP</b> Enumeration (may be <code>null</code>) => Tree
799 * Operation</li>
800 * <li><b>DEPTH</b> int (may be <code>null</code>) => depth</li>
801 * </ol>
802 *
803 * @param catalog a catalog name; must match the catalog name as it
804 * is stored in the database; "" retrieves those without a catalog;
805 * <code>null</code> means that the catalog name should not be used
806 * to narrow the search
807 *
808 * @param schemaPattern a schema name pattern; must match the schema name
809 * as it is stored in the database; "" retrieves those without a
810 * schema; <code>null</code> means that the schema name should not
811 * be used to narrow the search
812 *
813 * @param cubeNamePattern a cube name pattern; must match the
814 * cube name as it is stored in the database; "" retrieves those
815 * without a cube; <code>null</code> means that the cube name should
816 * not be used to narrow the search
817 *
818 * @param dimensionUniqueName unique name of dimension (not a pattern);
819 * must match the
820 * dimension name as it is stored in the database; <code>null</code>
821 * means that the dimension name should not be used to narrow the
822 * search
823 *
824 * @param hierarchyUniqueName unique name of hierarchy (not a pattern);
825 * must match the
826 * hierarchy name as it is stored in the database; <code>null</code>
827 * means that the hierarchy name should not be used to narrow the
828 * search
829 *
830 * @param levelUniqueName unique name of level (not a pattern); must match
831 * the level name as it is stored in the database; <code>null</code>
832 * means that the level name should not be used to narrow the
833 * search
834 *
835 * @param memberUniqueName unique name of member (not a pattern);
836 * <code>null</code> means that the measure unique name should not
837 * be used to narrow the search
838 *
839 * @param treeOps set of tree operations to retrieve members relative
840 * to the member whose unique name was specified; or null to return
841 * just the member itself.
842 * Ignored if <code>memberUniqueName</code> is not specified.
843 *
844 * @return a <code>ResultSet</code> object in which each row is a
845 * member description
846 *
847 * @exception OlapException if a database access error occurs
848 *
849 * @see #getSearchStringEscape
850 * @see org.olap4j.metadata.Member
851 */
852 ResultSet getMembers(
853 String catalog,
854 String schemaPattern,
855 String cubeNamePattern,
856 String dimensionUniqueName,
857 String hierarchyUniqueName,
858 String levelUniqueName,
859 String memberUniqueName,
860 Set<Member.TreeOp> treeOps) throws OlapException;
861
862 /**
863 * Retrieves a result set describing the named Sets in this database.
864 *
865 * <p>Specification as for XML/A MDSCHEMA_SETS schema rowset.
866 *
867 * <p>Each set description has the following columns:
868 * <ol>
869 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => null</li>
870 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => null</li>
871 * <li><b>CUBE_NAME</b> String => null</li>
872 * <li><b>SET_NAME</b> String => null</li>
873 * <li><b>SCOPE</b> int => null</li>
874 *
875 * @param catalog a catalog name; must match the catalog name as it
876 * is stored in the database; "" retrieves those without a catalog;
877 * <code>null</code> means that the catalog name should not be used
878 * to narrow the search
879 *
880 * @param schemaPattern a schema name pattern; must match the schema name
881 * as it is stored in the database; "" retrieves those without a
882 * schema; <code>null</code> means that the schema name should not
883 * be used to narrow the search
884 *
885 * @param cubeNamePattern a cube name pattern; must match the
886 * cube name as it is stored in the database; "" retrieves those
887 * without a cube; <code>null</code> means that the cube name should
888 * not be used to narrow the search
889 *
890 * @param setNamePattern pattern for the unique name of a set; must match
891 * the set name as it is stored in the database; <code>null</code>
892 * means that the set name should not be used to narrow the
893 * search
894 *
895 * @return a <code>ResultSet</code> object in which each row is a
896 * description of a named set
897 *
898 * @exception OlapException if a database access error occurs
899 *
900 * @see #getSearchStringEscape
901 * @see org.olap4j.metadata.NamedSet
902 */
903 ResultSet getSets(
904 String catalog,
905 String schemaPattern,
906 String cubeNamePattern,
907 String setNamePattern) throws OlapException;
908 }
909
910 // End OlapDatabaseMetaData.java