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