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