001/* 002// This software is subject to the terms of the Eclipse Public License v1.0 003// Agreement, available at the following URL: 004// http://www.eclipse.org/legal/epl-v10.html. 005// You must accept the terms of that agreement to use this software. 006// 007// Copyright (C) 2006-2010 Pentaho 008// All Rights Reserved. 009*/ 010package mondrian.olap; 011 012import mondrian.rolap.RolapConnection; 013import mondrian.rolap.RolapResultShepherd; 014import mondrian.rolap.agg.AggregationManager; 015import mondrian.server.*; 016import mondrian.server.monitor.Monitor; 017import mondrian.spi.CatalogLocator; 018import mondrian.util.LockBox; 019 020import org.olap4j.OlapConnection; 021 022import java.sql.SQLException; 023import java.util.*; 024 025/** 026 * Interface by which to control an instance of Mondrian. 027 * 028 * <p>Typically, there is only one instance of Mondrian per JVM. However, you 029 * access a MondrianServer via the {@link #forConnection} method for future 030 * expansion. 031 * 032 * @author jhyde 033 * @since Jun 25, 2006 034 */ 035public abstract class MondrianServer { 036 /** 037 * Returns the MondrianServer that hosts a given connection. 038 * 039 * @param connection Connection (not null) 040 * @return server this connection belongs to (not null) 041 */ 042 public static MondrianServer forConnection(Connection connection) { 043 return ((RolapConnection) connection).getServer(); 044 } 045 046 /** 047 * Creates a server. 048 * 049 * <p>When creating a server, the calling code must call the 050 * {@link MondrianServer#shutdown()} method to dispose of it. 051 * 052 * @param contentFinder Repository content finder 053 * @param catalogLocator Catalog locator 054 * @return Server that reads from the given repository 055 */ 056 public static MondrianServer createWithRepository( 057 RepositoryContentFinder contentFinder, 058 CatalogLocator catalogLocator) 059 { 060 return MondrianServerRegistry.INSTANCE.createWithRepository( 061 contentFinder, 062 catalogLocator); 063 } 064 065 /** 066 * Returns the server with the given id. 067 * 068 * <p>If id is null, returns the catalog-less server. (The catalog-less 069 * server can also be acquired using its id.)</p> 070 * 071 * <p>If server is not found, returns null.</p> 072 * 073 * @param instanceId Server instance id 074 * @return Server, or null if no server with this id 075 */ 076 public static MondrianServer forId(String instanceId) { 077 return MondrianServerRegistry.INSTANCE.serverForId(instanceId); 078 } 079 080 /** 081 * Disposes of a server and cleans up everything. 082 * 083 * @param instanceId The instance ID of the server 084 * to shutdown gracefully. 085 */ 086 public static void dispose(String instanceId) { 087 final MondrianServer server = 088 forId(instanceId); 089 if (server != null) { 090 server.shutdown(); 091 } 092 } 093 094 /** 095 * Returns an integer uniquely identifying this server within its JVM. 096 * 097 * @return Server's unique identifier 098 */ 099 public abstract int getId(); 100 101 /** 102 * Returns the version of this MondrianServer. 103 * 104 * @return Server's version 105 */ 106 public MondrianVersion getVersion() { 107 return MondrianServerRegistry.INSTANCE.getOrLoadVersion(); 108 } 109 110 /** 111 * Returns a list of MDX keywords. 112 * @return list of MDX keywords 113 */ 114 public abstract List<String> getKeywords(); 115 116 public abstract RolapResultShepherd getResultShepherd(); 117 118 /** 119 * Returns the lock box that can be used to pass objects via their string 120 * key. 121 * 122 * @return Lock box for this server 123 */ 124 public abstract LockBox getLockBox(); 125 126 /** 127 * Gets a Connection given a catalog (and implicitly the catalog's data 128 * source) and the name of a user role. 129 * 130 * <p>If you want to pass in a role object, and you are making the call 131 * within the same JVM (i.e. not RPC), register the role using 132 * {@link MondrianServer#getLockBox()} and pass in the moniker 133 * for the generated lock box entry. The server will retrieve the role from 134 * the moniker. 135 * 136 * @param catalogName Catalog name 137 * @param schemaName Schema name 138 * @param roleName User role name 139 * @return Connection 140 * @throws SQLException If error occurs 141 * @throws SecurityException If security error occurs 142 */ 143 public abstract OlapConnection getConnection( 144 String catalogName, 145 String schemaName, 146 String roleName) 147 throws SQLException, SecurityException; 148 149 /** 150 * Extended version of 151 * {@link MondrianServer#getConnection(String, String, String)} 152 * taking a list of properties to pass down to the native connection. 153 * 154 * <p>Gets a Connection given a catalog (and implicitly the catalog's data 155 * source) and the name of a user role. 156 * 157 * <p>If you want to pass in a role object, and you are making the call 158 * within the same JVM (i.e. not RPC), register the role using 159 * {@link MondrianServer#getLockBox()} and pass in the moniker 160 * for the generated lock box entry. The server will retrieve the role from 161 * the moniker. 162 * 163 * @param catalogName Catalog name 164 * @param schemaName Schema name 165 * @param roleName User role name 166 * @param props Properties to pass down to the native driver. 167 * @return Connection 168 * @throws SQLException If error occurs 169 * @throws SecurityException If security error occurs 170 */ 171 public abstract OlapConnection getConnection( 172 String catalogName, 173 String schemaName, 174 String roleName, 175 Properties props) 176 throws SQLException, SecurityException; 177 178 /** 179 * Returns a list of the databases in this server. One element 180 * per database, each element a map whose keys are the XMLA fields 181 * describing a data source: "DataSourceName", "DataSourceDescription", 182 * "URL", etc. Unrecognized fields are ignored. 183 * 184 * @return List of data source definitions 185 * @param connection Connection 186 */ 187 public abstract List<Map<String, Object>> getDatabases( 188 RolapConnection connection); 189 190 public abstract CatalogLocator getCatalogLocator(); 191 192 /** 193 * Called when the server must terminate all background tasks 194 * and cleanup all potential memory leaks. 195 */ 196 public abstract void shutdown(); 197 198 /** 199 * Called just after a connection has been created. 200 * 201 * @param connection Connection 202 */ 203 public abstract void addConnection(RolapConnection connection); 204 205 /** 206 * Called when a connection is closed. 207 * 208 * @param connection Connection 209 */ 210 public abstract void removeConnection(RolapConnection connection); 211 212 /** 213 * Retrieves a connection. 214 * 215 * @param connectionId Connection id, per 216 * {@link mondrian.rolap.RolapConnection#getId()} 217 * 218 * @return Connection, or null if connection is not registered 219 */ 220 public abstract RolapConnection getConnection(int connectionId); 221 222 /** 223 * Called just after a statement has been created. 224 * 225 * @param statement Statement 226 */ 227 public abstract void addStatement(Statement statement); 228 229 /** 230 * Called when a statement is closed. 231 * 232 * @param statement Statement 233 */ 234 public abstract void removeStatement(Statement statement); 235 236 public abstract Monitor getMonitor(); 237 238 public abstract AggregationManager getAggregationManager(); 239 240 /** 241 * Description of the version of the server. 242 */ 243 public interface MondrianVersion { 244 /** 245 * Returns the version string, for example "2.3.0". 246 * 247 * @see java.sql.DatabaseMetaData#getDatabaseProductVersion() 248 * @return Version of this server 249 */ 250 String getVersionString(); 251 252 /** 253 * Returns the major part of the version number. 254 * 255 * <p>For example, if the full version string is "2.3.0", the major 256 * version is 2. 257 * 258 * @return major part of the version number 259 * @see java.sql.DatabaseMetaData#getDatabaseMajorVersion() 260 */ 261 int getMajorVersion(); 262 263 /** 264 * Returns the minor part of the version number. 265 * 266 * <p>For example, if the full version string is "2.3.0", the minor 267 * version is 3. 268 * 269 * @return minor part of the version number 270 * 271 * @see java.sql.DatabaseMetaData#getDatabaseProductVersion() 272 */ 273 int getMinorVersion(); 274 275 /** 276 * Retrieves the name of this database product. 277 * 278 * @return database product name 279 * @see java.sql.DatabaseMetaData#getDatabaseProductName() 280 */ 281 String getProductName(); 282 } 283 284} 285 286// End MondrianServer.java