001    /*
002    // $Id: //open/mondrian-release/3.0/src/main/mondrian/olap/Connection.java#4 $
003    // This software is subject to the terms of the Common Public License
004    // Agreement, available at the following URL:
005    // http://www.opensource.org/licenses/cpl.html.
006    // Copyright (C) 2000-2002 Kana Software, Inc.
007    // Copyright (C) 2001-2007 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.0/src/main/mondrian/olap/Connection.java#4 $
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         * Sets the privileges for the this connection.
084         *
085         * @pre role != null
086         * @pre role.isMutable()
087         */
088        void setRole(Role role);
089    
090        /**
091         * Returns the access-control profile for this connection.
092         * @post role != null
093         * @post role.isMutable()
094         */
095        Role getRole();
096    
097        /**
098         * Returns a schema reader with access control appropriate to the current
099         * role.
100         */
101        SchemaReader getSchemaReader();
102    
103        /**
104         * Returns the value of a connection property.
105         *
106         * @param name Name of property, for example "JdbcUser".
107         * @return Value of property, or null if property is not defined.
108         */
109        Object getProperty(String name);
110    
111        /**
112         * Returns an object with which to explicitly control the contents of the
113         * cache.
114         *
115         * @param pw Writer to which to write logging information; may be null
116         */
117        CacheControl getCacheControl(PrintWriter pw);
118    
119        /**
120         * Returns the data source this connection uses to create connections
121         * to the underlying JDBC database.
122         *
123         * @return Data source
124         */
125        DataSource getDataSource();
126    }
127    
128    // End Connection.java