001    /*
002    // $Id: OlapConnection.java 282 2009-10-01 00:57:29Z jhyde $
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) 2006-2008 Julian Hyde
007    // All Rights Reserved.
008    // You must accept the terms of that agreement to use this software.
009    */
010    package org.olap4j;
011    
012    import org.olap4j.mdx.parser.MdxParserFactory;
013    import org.olap4j.metadata.*;
014    
015    import java.sql.Connection;
016    import java.util.Locale;
017    
018    /**
019     * Connection to an OLAP server.
020     *
021     * @author jhyde
022     * @version $Id: OlapConnection.java 282 2009-10-01 00:57:29Z jhyde $
023     * @since Aug 22, 2006
024     */
025    public interface OlapConnection extends Connection, OlapWrapper {
026    
027        // overrides Connection, with refined return type and throws list
028        /**
029         * {@inheritDoc}
030         * @throws OlapException if database error occurs
031         */
032        OlapDatabaseMetaData getMetaData() throws OlapException;
033    
034        /**
035         * Creates a prepared OLAP Statement.
036         *
037         * <p>This method is the equivalent, for OLAP, of the
038         * {@link Connection#prepareStatement(String)} JDBC method.</p>
039         *
040         * @param mdx MDX query string
041         * @return prepared statement
042         * @throws OlapException if database error occurs
043         */
044        PreparedOlapStatement prepareOlapStatement(String mdx) throws OlapException;
045    
046        /**
047         * Returns the factory used to create MDX parsers in this connection.
048         *
049         * @return MDX parser factory
050         */
051        MdxParserFactory getParserFactory();
052    
053        // overrides Connection, with refined return type and throws list
054        /**
055         * {@inheritDoc}
056         * @throws OlapException if database error occurs
057         */
058        OlapStatement createStatement() throws OlapException;
059    
060        /**
061         * Returns the current {@link org.olap4j.metadata.Schema} of this
062         * connection.
063         *
064         * @return current Schema
065         * @throws OlapException if database error occurs
066         */
067        Schema getSchema() throws OlapException;
068    
069        /**
070         * Returns a list of {@link org.olap4j.metadata.Catalog} objects which
071         * belong to this connection's OLAP server.
072         *
073         * <p>The caller should assume that the list is immutable;
074         * if the caller modifies the list, behavior is undefined.</p>
075         *
076         * @see OlapDatabaseMetaData#getCatalogs()
077         * @return List of Catalogs in this connection's OLAP server
078         */
079        NamedList<Catalog> getCatalogs();
080    
081        /**
082         * Sets the current locale of this connection. The value must not be null.
083         *
084         * <p>If the locale is not set, the JDK's current locale is used (see
085         * {@link java.util.Locale#getDefault()}).
086         *
087         * <p>Most drivers support a <code>Locale</code> connect-string property.
088         *
089         * @param locale Locale
090         */
091        void setLocale(Locale locale);
092    
093        /**
094         * Returns this connection's locale. The value is never null.
095         *
096         * @return locale of this connection
097         */
098        Locale getLocale();
099    
100        /**
101         * Sets the name of the role in which this connection executes queries. If
102         * the name of the role is null, the connection reverts to the default
103         * access control context.
104         *
105         * @param roleName Name of role
106         * @throws OlapException if role name is invalid
107         */
108        void setRoleName(String roleName) throws OlapException;
109    
110        /**
111         * Returns the name of the role in which this connection executes queries.
112         *
113         * @return name of the role in which this connection executes queries
114         */
115        String getRoleName();
116    
117        /**
118         * Creates a Scenario.
119         *
120         * <p>It does not become the active scenario for the current connection.
121         * To do this, call {@link #setScenario(Scenario)}.
122         *
123         * @see #setScenario
124         *
125         * @return a new Scenario
126         */
127        Scenario createScenario();
128    
129        /**
130         * Sets the active Scenario of this connection.
131         *
132         * <p>After setting a scenario, the client may call
133         * {@link Cell#setValue} to change the value of cells returned
134         * from queries. The value of those cells is changed. This operation is
135         * referred to as 'writeback', and is used to perform 'what if' analysis,
136         * such as budgeting. See {@link Scenario} for more details.
137         *
138         * <p>If {@code scenario} is null, the connection will have no active
139         * scenario, and writeback is not allowed.
140         *
141         * <p>Scenarios are created using {@link #createScenario()}.
142         *
143         * @param scenario Scenario
144         */
145        void setScenario(Scenario scenario);
146    
147        /**
148         * Returns this connection's active Scenario, or null if there is no
149         * active Scenario.
150         *
151         * @return Active scenario, or null
152         */
153        Scenario getScenario();
154    }
155    
156    // End OlapConnection.java