001    /*
002    // $Id: //open/mondrian-release/3.2/src/main/mondrian/olap/Connection.java#2 $
003    // This software is subject to the terms of the Eclipse Public License v1.0
004    // Agreement, available at the following URL:
005    // http://www.eclipse.org/legal/epl-v10.html.
006    // Copyright (C) 2000-2002 Kana Software, Inc.
007    // Copyright (C) 2001-2010 Julian Hyde and others
008    // All Rights Reserved.
009    // You must accept the terms of that agreement to use this software.
010    //
011    // jhyde, 29 February, 2000
012    */
013    
014    package mondrian.olap;
015    
016    import javax.sql.DataSource;
017    import java.util.Locale;
018    import java.io.PrintWriter;
019    
020    /**
021     * Connection to a multi-dimensional database.
022     *
023     * @see DriverManager
024     *
025     * @version $Id: //open/mondrian-release/3.2/src/main/mondrian/olap/Connection.java#2 $
026     * @author jhyde
027     */
028    public interface Connection {
029    
030        /**
031         * Get the Connect String associated with this Connection.
032         *
033         * @return the Connect String (never null).
034         */
035        String getConnectString();
036    
037        /**
038         * Get the name of the Catalog associated with this Connection.
039         *
040         * @return the Catalog name (never null).
041         */
042        String getCatalogName();
043    
044        /**
045         * Get the Schema associated with this Connection.
046         *
047         * @return the Schema (never null).
048         */
049        Schema getSchema();
050    
051        /**
052         * Closes this <code>Connection</code>. You may not use this
053         * <code>Connection</code> after closing it.
054         */
055        void close();
056    
057        /**
058         * Executes a query.
059         *
060         * @throws RuntimeException if another thread calls {@link Query#cancel()}.
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