001 /* 002 // $Id: OlapConnection.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.mdx.parser.MdxParserFactory; 023 import org.olap4j.metadata.*; 024 025 import java.sql.*; 026 import java.util.List; 027 import java.util.Locale; 028 029 /** 030 * Connection to an OLAP server. 031 * 032 * <p>OlapConnection is a subclass of {@link Connection}. It can be pooled 033 * by a connection pooling framework or obtained directly via the Java 034 * standard {@link DriverManager}. The JDBC URL prefix of olap connections 035 * is dependent of the driver implementation. Such implementations are, 036 * among others possible: 037 * 038 * <ul><li>Olap4j's XML/A driver</li><li>Mondrian</li></ul> 039 * 040 * <p>Olap connections have a different metadata hierarchy than regular 041 * JDBC. The connection's metadata is available using 042 * {@link OlapConnection#getMetaData()}, and returns a specialized subclass 043 * of {@link DatabaseMetaData}. The objects at the root of the hierarchy 044 * are {@link Database} class objects. 045 * 046 * <p>A connection needs be bound to a database, a catalog and a schema. 047 * Implementations are expected to automatically discover these if no 048 * driver specific parameters indicated which ones to use. 049 * 050 * @author jhyde 051 * @version $Id: OlapConnection.java 482 2012-01-05 23:27:27Z jhyde $ 052 * @since Aug 22, 2006 053 */ 054 public interface OlapConnection extends Connection, OlapWrapper { 055 056 // overrides Connection, with refined return type and throws list 057 /** 058 * {@inheritDoc} 059 * @throws OlapException if database error occurs 060 */ 061 OlapDatabaseMetaData getMetaData() throws OlapException; 062 063 /** 064 * Creates a prepared OLAP Statement. 065 * 066 * <p>This method is the equivalent, for OLAP, of the 067 * {@link Connection#prepareStatement(String)} JDBC method.</p> 068 * 069 * @param mdx MDX query string 070 * @return prepared statement 071 * @throws OlapException if database error occurs 072 */ 073 PreparedOlapStatement prepareOlapStatement(String mdx) throws OlapException; 074 075 /** 076 * Returns the factory used to create MDX parsers in this connection. 077 * 078 * @return MDX parser factory 079 */ 080 MdxParserFactory getParserFactory(); 081 082 // overrides Connection, with refined return type and throws list 083 /** 084 * {@inheritDoc} 085 * @throws OlapException if database error occurs 086 */ 087 OlapStatement createStatement() throws OlapException; 088 089 /** 090 * Returns the database name currently active for this connection. If no 091 * database name was specified either through the JDBC URL or through 092 * {@link OlapConnection#setDatabase(String)}, the driver will select the 093 * first one available. 094 * 095 * @return The name of the database currently active for this connection. 096 * @throws OlapException 097 * An exception will be thrown, if any of these conditions 098 * are true: 099 * <ul> 100 * <li>A server error occurs.</li> 101 * <li>No databases exist on the server.</li> 102 * <li>The user specified a database name which does not 103 * exist on the server.</li> 104 * </ul> 105 */ 106 String getDatabase() throws OlapException; 107 108 /** 109 * Sets the name of the database that will be used for this connection. 110 * Overrides the value passed, if any, through the JDBC URL. 111 * 112 * @param databaseName 113 * The name of the database to use. 114 * @throws OlapException 115 * An exception will be thrown, if any of these conditions 116 * are true: 117 * <ul> 118 * <li>A server error occurs.</li> 119 * <li>The user specified a database name which does not 120 * exist on the server.</li> 121 * </ul> 122 */ 123 void setDatabase(String databaseName) throws OlapException; 124 125 /** 126 * Returns the current active {@link org.olap4j.metadata.Database} of this 127 * connection. 128 * 129 * <p>If the user has not specified a database name to use for this 130 * connection, the driver will auto-select the first Database available. 131 * 132 * @see #setDatabase(String) 133 * @see #getOlapDatabases() 134 * @return The currently active Database, or null of none are currently 135 * selected. 136 * @throws OlapException 137 * An exception will be thrown, if any of these conditions 138 * are true: 139 * <ul> 140 * <li>A server error occurs.</li> 141 * <li>No databases exist on the server.</li> 142 * <li>The user specified a database name which does not 143 * exist on the server.</li> 144 * </ul> 145 */ 146 Database getOlapDatabase() throws OlapException; 147 148 /** 149 * Returns a list of {@link org.olap4j.metadata.Database} objects which 150 * belong to this connection's OLAP server. 151 * 152 * <p>The caller should assume that the list is immutable; 153 * if the caller modifies the list, behavior is undefined.</p> 154 * 155 * @return List of Database objects in this connection's OLAP server 156 * @throws OlapException if a database access error occurs 157 */ 158 NamedList<Database> getOlapDatabases() throws OlapException; 159 160 /** 161 * Returns the {@link Catalog} name which is currently active for this 162 * connection. 163 * 164 * <p> 165 * If the user has not specified a database name to use for this 166 * connection, the driver will automatically select the first one 167 * available. If the user has not specified a catalog name to use, 168 * the driver will also use the first one available on the server. 169 * 170 * @return The name of the catalog which is active for this connection. 171 * @throws OlapException 172 * An exception will be thrown, if any of these conditions 173 * are true: 174 * <ul> 175 * <li>A server error occurs.</li> 176 * <li>No database name was specified and no databases exist 177 * on the server.</li> 178 * <li>The user specified a database name which does not 179 * exist on the server.</li> 180 * <li>No catalog names were specified and no catalogs 181 * exist on the server.</li> 182 * <li>The user specified a catalog name which does not exist 183 * on the server.</li> 184 * </ul> 185 */ 186 String getCatalog() throws OlapException; 187 188 /** 189 * Sets the name of the catalog that will be used for this connection. 190 * Overrides the value passed, if any, through the JDBC URL. 191 * 192 * @param catalogName 193 * The name of the catalog to use for this connection. 194 * @throws OlapException 195 * An exception will be thrown, if any of these conditions 196 * are true: 197 * <ul> 198 * <li>A server error occurs.</li> 199 * <li>No database name was specified and no databases 200 * exist on the server.</li> 201 * <li>The user specified a database name which does not 202 * exist on the server.</li> 203 * <li>The user specified a catalog name which does not exist 204 * on the server.</li> 205 * </ul> 206 */ 207 void setCatalog(String catalogName) throws OlapException; 208 209 /** 210 * Returns the current active {@link org.olap4j.metadata.Catalog} 211 * of this connection. 212 * 213 * <p>If the user has not selected a Database and Catalog to use for 214 * this connection, the driver will auto-select the first 215 * Database and Catalog available on the server. 216 * 217 * <p>Any auto-discovery performed by implementations must take into 218 * account the specified database name and catalog name, if any. 219 * 220 * @return The currently active catalog, or null of none are 221 * currently selected. 222 * @throws OlapException 223 * An exception will be thrown, if any of these conditions 224 * are true: 225 * <ul> 226 * <li>A server error occurs.</li> 227 * <li>No database name was specified and no databases 228 * exist on the server.</li> 229 * <li>The user specified a database name which does not 230 * exist on the server.</li> 231 * <li>No catalog name was specified and no catalogs 232 * exist on the server.</li> 233 * <li>The user specified a catalog name which does not exist 234 * on the server.</li> 235 * </ul> 236 */ 237 Catalog getOlapCatalog() throws OlapException; 238 239 /** 240 * Returns a list of {@link org.olap4j.metadata.Catalog} objects which 241 * belong to this connection's OLAP server. 242 * 243 * <p>If the user has not selected a Database to use for 244 * this connection, the implementation auto-selects 245 * the first Database available. Any auto-discovery performed 246 * by implementations must take into account the connection 247 * Database parameter. 248 * 249 * <p>The caller should assume that the list is immutable; 250 * if the caller modifies the list, behavior is undefined. 251 * 252 * @return List of Catalogs in this connection's OLAP server 253 * @throws OlapException 254 * An exception will be thrown, if any of these conditions 255 * are true: 256 * <ul> 257 * <li>A server error occurs.</li> 258 * <li>No database name was specified and no databases 259 * exist on the server.</li> 260 * <li>The user specified a database name which does not 261 * exist on the server.</li> 262 * </ul> 263 */ 264 NamedList<Catalog> getOlapCatalogs() throws OlapException; 265 266 /** 267 * Returns the {@link Schema} name that was selected for this connection, 268 * either through the JDBC URL or via 269 * {@link #setSchema(String)}. 270 * 271 * <p>If the user has not selected a Database, Catalog and Schema to use 272 * for this connection, the driver will auto-select the first Database, 273 * Catalog and Schema available. 274 * 275 * <p>Any auto-discovery performed by implementations must take into 276 * account the specified Database, Catalog and Schema names, if any. 277 * 278 * @return The name of the schema currently selected for this connection. 279 * @throws OlapException 280 * An exception will be thrown, if any of these conditions 281 * are true: 282 * <ul> 283 * <li>A server error occurs.</li> 284 * <li>No database name was specified and no databases 285 * exist on the server.</li> 286 * <li>The user specified a database name which does not 287 * exist on the server.</li> 288 * <li>No catalog name was specified and no catalogs 289 * exist on the server.</li> 290 * <li>The user specified a catalog name which does not exist 291 * on the server.</li> 292 * <li>No schema name was specified and no schema 293 * exist on the server.</li> 294 * <li>The user specified a schema name which does not exist 295 * on the server.</li> 296 * </ul> 297 */ 298 String getSchema() throws OlapException; 299 300 /** 301 * Sets the name of the active schema for this connection. 302 * Overrides the value passed, if any, through the JDBC URL. 303 * 304 * @param schemaName The name of the schema to use for this connection. 305 * @throws OlapException 306 * An exception will be thrown, if any of these conditions 307 * are true: 308 * <ul> 309 * <li>A server error occurs.</li> 310 * <li>No database name was specified and no databases 311 * exist on the server.</li> 312 * <li>The user specified a database name which does not 313 * exist on the server.</li> 314 * <li>No catalog name was specified and no catalogs 315 * exist on the server.</li> 316 * <li>The user specified a catalog name which does not exist 317 * on the server.</li> 318 * <li>No schema name was specified and no schema 319 * exist on the server.</li> 320 * <li>The user specified a schema name which does not exist 321 * on the server.</li> 322 * </ul> 323 */ 324 void setSchema(String schemaName) throws OlapException; 325 326 /** 327 * Returns the current active {@link org.olap4j.metadata.Schema} 328 * of this connection. 329 * 330 * <p>If the user has not selected a Database, Catalog and Schema to use 331 * for this connection, the driver will auto-select the first Database, 332 * Catalog and Schema available. 333 * 334 * <p>Any auto-discovery performed by implementations must take into 335 * account the specified Database, Catalog and Schema names, if any. 336 * 337 * @return The currently active schema 338 * @throws OlapException 339 * An exception will be thrown, if any of these conditions 340 * are true: 341 * <ul> 342 * <li>A server error occurs.</li> 343 * <li>No database name was specified and no databases 344 * exist on the server.</li> 345 * <li>The user specified a database name which does not 346 * exist on the server.</li> 347 * <li>No catalog name was specified and no catalogs 348 * exist on the server.</li> 349 * <li>The user specified a catalog name which does not exist 350 * on the server.</li> 351 * <li>No schema name was specified and no schema 352 * exist on the server.</li> 353 * <li>The user specified a schema name which does not exist 354 * on the server.</li> 355 * </ul> 356 */ 357 Schema getOlapSchema() throws OlapException; 358 359 /** 360 * Returns a list of {@link org.olap4j.metadata.Schema} objects which 361 * belong to this connection's OLAP server. 362 * 363 * <p>If the user has not selected a Database, Catalog and Schema to use 364 * for this connection, the driver will auto-select the first Database and 365 * Catalog available. 366 * 367 * <p>Any auto-discovery performed by implementations must take into 368 * account the specified Database, Catalog and Schema names, if any. 369 * 370 * <p>The caller should assume that the list is immutable; 371 * if the caller modifies the list, behavior is undefined. 372 * 373 * @return List of Catalogs in this connection's OLAP server 374 * @throws OlapException 375 * An exception will be thrown, if any of these conditions 376 * are true: 377 * <ul> 378 * <li>A server error occurs.</li> 379 * <li>No database name was specified and no databases 380 * exist on the server.</li> 381 * <li>The user specified a database name which does not 382 * exist on the server.</li> 383 * <li>No catalog name was specified and no catalogs 384 * exist on the server.</li> 385 * <li>The user specified a catalog name which does not exist 386 * on the server.</li> 387 * <li>No schema name was specified and no schema 388 * exist on the server.</li> 389 * <li>The user specified a schema name which does not exist 390 * on the server.</li> 391 * </ul> 392 */ 393 NamedList<Schema> getOlapSchemas() throws OlapException; 394 395 /** 396 * Sets the current locale of this connection. The value must not be null. 397 * 398 * <p>If the locale is not set, the JDK's current locale is used (see 399 * {@link java.util.Locale#getDefault()}). 400 * 401 * <p>Most drivers support a <code>Locale</code> connect-string property. 402 * 403 * @param locale Locale 404 * 405 * @see #getLocale() 406 */ 407 void setLocale(Locale locale); 408 409 /** 410 * Returns this connection's locale. The value is never null. 411 * 412 * @return locale of this connection 413 * 414 * @see #setLocale(java.util.Locale) 415 * @see org.olap4j.metadata.MetadataElement#getCaption() 416 * @see org.olap4j.metadata.MetadataElement#getDescription() 417 */ 418 Locale getLocale(); 419 420 /** 421 * Sets the name of the role in which this connection executes queries. If 422 * the name of the role is null, the connection reverts to the default 423 * access control context. 424 * 425 * @param roleName Name of role 426 * @throws OlapException if role name is invalid 427 */ 428 void setRoleName(String roleName) throws OlapException; 429 430 /** 431 * Returns the name of the role in which this connection executes queries. 432 * 433 * @return name of the role in which this connection executes queries 434 */ 435 String getRoleName(); 436 437 /** 438 * Returns a list of the names of roles that are available for this user to 439 * execute queries. 440 * 441 * @return a list of role names, or null if the available roles are not 442 * known 443 * 444 * @throws OlapException if database error occurs 445 */ 446 List<String> getAvailableRoleNames() throws OlapException; 447 448 /** 449 * Creates a Scenario. 450 * 451 * <p>It does not become the active scenario for the current connection. 452 * To do this, call {@link #setScenario(Scenario)}. 453 * 454 * @see #setScenario 455 * 456 * @return a new Scenario 457 * 458 * @throws OlapException if database error occurs 459 */ 460 Scenario createScenario() throws OlapException; 461 462 /** 463 * Sets the active Scenario of this connection. 464 * 465 * <p>After setting a scenario, the client may call 466 * {@link Cell#setValue} to change the value of cells returned 467 * from queries. The value of those cells is changed. This operation is 468 * referred to as 'writeback', and is used to perform 'what if' analysis, 469 * such as budgeting. See {@link Scenario} for more details. 470 * 471 * <p>If {@code scenario} is null, the connection will have no active 472 * scenario, and writeback is not allowed. 473 * 474 * <p>Scenarios are created using {@link #createScenario()}. 475 * 476 * @param scenario Scenario 477 * 478 * @throws OlapException if database error occurs 479 */ 480 void setScenario(Scenario scenario) throws OlapException; 481 482 /** 483 * Returns this connection's active Scenario, or null if there is no 484 * active Scenario. 485 * 486 * @return Active scenario, or null 487 * 488 * @throws OlapException if database error occurs 489 */ 490 Scenario getScenario() throws OlapException; 491 } 492 493 // End OlapConnection.java