001/*
002// This software is subject to the terms of the Eclipse Public License v1.0
003// Agreement, available at the following URL:
004// http://www.eclipse.org/legal/epl-v10.html.
005// You must accept the terms of that agreement to use this software.
006//
007// Copyright (C) 2000-2005 Julian Hyde
008// Copyright (C) 2005-2012 Pentaho and others
009// All Rights Reserved.
010*/
011package mondrian.olap;
012
013import java.io.PrintWriter;
014import java.util.Locale;
015import javax.sql.DataSource;
016
017/**
018 * Connection to a multi-dimensional database.
019 *
020 * @see DriverManager
021 *
022 * @author jhyde
023 */
024public interface Connection {
025
026    /**
027     * Get the Connect String associated with this Connection.
028     *
029     * @return the Connect String (never null).
030     */
031    String getConnectString();
032
033    /**
034     * Get the name of the Catalog associated with this Connection.
035     *
036     * @return the Catalog name (never null).
037     */
038    String getCatalogName();
039
040    /**
041     * Get the Schema associated with this Connection.
042     *
043     * @return the Schema (never null).
044     */
045    Schema getSchema();
046
047    /**
048     * Closes this <code>Connection</code>. You may not use this
049     * <code>Connection</code> after closing it.
050     */
051    void close();
052
053    /**
054     * Executes a query.
055     *
056     * @throws RuntimeException if another thread cancels the query's statement.
057     *
058     * @deprecated This method is deprecated and will be removed in
059     * mondrian-4.0. It operates by internally creating a statement. Better
060     * to use olap4j and explicitly create a statement.
061     */
062    Result execute(Query query);
063
064    /**
065     * Returns the locale this connection belongs to.  Determines, for example,
066     * the currency string used in formatting cell values.
067     *
068     * @see mondrian.util.Format
069     */
070    Locale getLocale();
071
072    /**
073     * Parses an expresion.
074     */
075    Exp parseExpression(String s);
076
077    /**
078     * Parses a query.
079     */
080    Query parseQuery(String s);
081
082    /**
083     * Parses a statement.
084     *
085     * @param mdx MDX string
086     * @return A {@link Query} if it is a SELECT statement, a
087     *   {@link DrillThrough} if it is a DRILLTHROUGH statement
088     */
089    QueryPart parseStatement(String mdx);
090
091    /**
092     * Sets the privileges for the this connection.
093     *
094     * @pre role != null
095     * @pre role.isMutable()
096     */
097    void setRole(Role role);
098
099    /**
100     * Returns the access-control profile for this connection.
101     * @post role != null
102     * @post role.isMutable()
103     */
104    Role getRole();
105
106    /**
107     * Returns a schema reader with access control appropriate to the current
108     * role.
109     */
110    SchemaReader getSchemaReader();
111
112    /**
113     * Returns the value of a connection property.
114     *
115     * @param name Name of property, for example "JdbcUser".
116     * @return Value of property, or null if property is not defined.
117     */
118    Object getProperty(String name);
119
120    /**
121     * Returns an object with which to explicitly control the contents of the
122     * cache.
123     *
124     * @param pw Writer to which to write logging information; may be null
125     */
126    CacheControl getCacheControl(PrintWriter pw);
127
128    /**
129     * Returns the data source this connection uses to create connections
130     * to the underlying JDBC database.
131     *
132     * @return Data source
133     */
134    DataSource getDataSource();
135}
136
137// End Connection.java