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