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