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