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