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