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