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