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