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