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