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*/
020package org.olap4j;
021
022import org.olap4j.mdx.parser.MdxParserFactory;
023import org.olap4j.metadata.*;
024
025import java.sql.*;
026import java.util.List;
027import 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 */
054public 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