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) 2010-2011 Pentaho
008// All Rights Reserved.
009*/
010package mondrian.server;
011
012import mondrian.olap.MondrianServer;
013import mondrian.rolap.RolapConnection;
014import mondrian.rolap.RolapSchema;
015
016import org.olap4j.OlapConnection;
017
018import java.sql.SQLException;
019import java.util.*;
020
021 /**
022 * Callback by which a {@link mondrian.olap.MondrianServer} finds its
023 * databases, catalogs and schemas.
024 *
025 * <p>An important implementation is {@link ImplicitRepository}. This
026 * encapsulates the behavior of embedded mondrian: there is no repository,
027 * and each connection specifies schema and catalog on the connect string.
028 * This is the reason that several methods contain a
029 * {@link mondrian.rolap.RolapConnection connection} parameter. Other
030 * implementations of this interface will probably ignore the connection.
031 *
032 * @author Julian Hyde
033 */
034public interface Repository {
035    /**
036     * Returns a list of database names found in this repository.
037     * @param connection A connection object from which to obtain
038     * the metadata. May be null or the Repository implementation
039     * itself might ignore it.
040     * @return A list of database names found in this repository.
041     */
042    List<String> getDatabaseNames(
043        RolapConnection connection);
044
045    /**
046     * Returns a list of catalog names found in the repository.
047     * @param connection A connection object from which to obtain
048     * the metadata. May be null or the Repository implementation
049     * itself might ignore it.
050     * @param databaseName The parent database name of which we
051     * want to list the catalogs.
052     * @return A list of catalog names found in this repository.
053     */
054    List<String> getCatalogNames(
055        RolapConnection connection,
056        String databaseName);
057
058    /**
059     * Must return a map of schema names and schema objects
060     * who are children of the specified datasource and catalog.
061     * @param connection The connection from which to obtain
062     * the metadata. May be null or the Repository implementation
063     * itself might ignore it.
064     * @param databaseName The database name predicate for the list
065     * of returned schemas.
066     * @param catalogName The catalog name predicate for the list
067     * of returned schemas.
068     * @return A map of schema names associated to schema objects,
069     * as found in the repository..
070     */
071    Map<String, RolapSchema> getRolapSchemas(
072        RolapConnection connection,
073        String databaseName,
074        String catalogName);
075
076    /**
077     * Returns a list of databases properties collections,
078     * one per database configured on this server.
079     * @param connection The connection from which to obtain
080     * the metadata. May be null or the Repository implementation
081     * itself might ignore it.
082     * @return A list of databases properties collections
083     */
084    List<Map<String, Object>> getDatabases(
085        RolapConnection connection);
086
087    /**
088     * Returns an OlapConnection object.
089     * @param server The MondrianServer to use.
090     * @param databaseName The database name. Can be null.
091     * @param catalogName The catalog name. Can be null.
092     * @param roleName The role name. Can be null.
093     * @param props Additional connection properties.
094     * @return An opened olap connection.
095     * @throws SQLException If an error is encountered while
096     * creating the connection.
097     */
098    OlapConnection getConnection(
099        MondrianServer server,
100        String databaseName,
101        String catalogName,
102        String roleName,
103        Properties props)
104        throws SQLException;
105
106    /**
107     * Shuts down and terminates a repository.
108     */
109    void shutdown();
110}
111
112// End Repository.java