/*
// Licensed to Julian Hyde under one or more contributor license
// agreements. See the NOTICE file distributed with this work for
// additional information regarding copyright ownership.
//
// Julian Hyde licenses this file to you under the Apache License,
// Version 2.0 (the "License"); you may not use this file except in
// compliance with the License. You may obtain a copy of the License at:
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
*/
package org.olap4j.metadata;

import org.olap4j.OlapConnection;
import org.olap4j.OlapException;

import java.util.List;

/**
 * Highest level element in the hierarchy of metadata objects.
 *
 * <p>A Database contains one or more {@link Catalog}s.</p>
 *
 * <p>To obtain the collection of databases in the current server, call the
 * {@link OlapConnection#getOlapDatabases()} method. To obtain the current
 * active catalog object, to which a connection is bound, use
 * {@link OlapConnection#getOlapDatabase()}.
 *
 * <p>The hierarchy of metadata objects, rooted at the connection from which
 * they are accessed, is as follows:
 * <blockquote>
 * <ul>
 * <li type="circle">{@link org.olap4j.OlapConnection}<ul>
 *     <li type="circle">{@link Database}<ul>
 *         <li type="circle">{@link Catalog}<ul>
 *             <li type="circle">{@link Schema}<ul>
 *                 <li type="circle">{@link Cube}<ul>
 *                     <li type="circle">{@link Dimension}<ul>
 *                         <li type="circle">{@link Hierarchy}<ul>
 *                             <li type="circle">{@link Level}<ul>
 *                                 <li type="circle">{@link Member}</li>
 *                                 <li type="circle">{@link Property}</li>
 *                             </ul></li>
 *                         </ul></li>
 *                     </ul></li>
 *                 <li type="circle">{@link NamedSet}</li>
 *                 </ul></li>
 *             <li type="circle">{@link Dimension} (shared)</li>
 *             </ul></li>
 *         </ul></li>
 *     </ul></li>
 *  </ul>
 * </blockquote>
 * </p>
 *
 * @author Luc Boudreau
 * @since Jan 15 2011
 */
public interface Database {

    /**
     * Retrieves the parent {@link OlapConnection} of this
     * Database object.
     * @return The parent conenction object.
     */
    OlapConnection getOlapConnection();

    /**
     * Returns the unique name of this Database.
     * @return The database name.
     * @throws OlapException if error occurs.
     */
    String getName() throws OlapException;

    /**
     * Returns a human-readable description of this Database.
     *
     * @return The database description. Can be <code>null</code>.
     * @throws OlapException if error occurs.
     */
    String getDescription() throws OlapException;

    /**
     * Returns a redirection URL. This value is used only in
     * distributed architectures. An OLAP server can serve as a
     * frontal distribution server and redirect clients to delegate
     * servers.
     *
     * <p>Implementations are free to implement a distributed system.
     * Most implementations don't make any use of it and
     * will return the same URL which was used to connect in
     * the first place.
     *
     * @return The database URL. Can be <code>null</code>.
     * @throws OlapException if error occurs.
     */
    String getURL() throws OlapException;

    /**
     * Returns provider-specific information.
     *
     * @return A string containing provider-specific information.
     * @throws OlapException if error cccurs
     */
    String getDataSourceInfo() throws OlapException;

    /**
     * Returns the name of the underlying OLAP provider.
     *
     * <p>This usually is the server vendor name, for example "Mondrian" or
     * "MSOLAP".
     *
     * @return The provider name.
     * @throws OlapException if error occurs.
     */
    String getProviderName() throws OlapException;

    /**
     * Returns the types of data that are supported by this provider.
     *
     * @return The provider types.
     * @throws OlapException if error occurs.
     */
    List<ProviderType> getProviderTypes() throws OlapException;

    /**
     * Returns the authentication modes supported by this
     * server.
     * @return The authentication mode supported.
     * @throws OlapException if error occurs.
     */
    List<AuthenticationMode> getAuthenticationModes() throws OlapException;

    /**
     * Returns a list of {@link Catalog} objects which belong to
     * this Database.
     *
     * <p>The caller should assume that the list is immutable;
     * if the caller modifies the list, behavior is undefined.</p>
     *
     * @see org.olap4j.OlapConnection#getOlapCatalogs()
     * @return List of Catalog in this <code>Database</code>
     * @throws OlapException if error occurs
     */
    NamedList<Catalog> getCatalogs() throws OlapException;

    /**
     * Describes the supported authentication modes.
     */
    public enum AuthenticationMode {
        /**
         * Designates providers which don't support
         * authentication.
         */
        Unauthenticated("No user ID or password needs to be sent."),
        /**
         * Designates providers which support authentication
         * through the JDBC interface.
         */
        Authenticated(
            "User ID and Password must be included in the information required"
            + " for the connection."),
        /**
         * Designates providers which support authentication through
         * vendor or implementation specific means.
         */
        Integrated(
            "The data source uses the underlying security to determine "
            + "authorization, such as Integrated Security provided by "
            + "Microsoft Internet Information Services (IIS).");

        private final String description;

        AuthenticationMode(String description) {
            this.description = description;
        }

        /**
         * Provides a human readable description of the authentication mode.
         * @return A description string.
         */
        public String getDescription() {
            return description;
        }
    }

    /**
     * Describes the possible provider types.
     */
    public static enum ProviderType {
        /**
         * Designates providers which provide results in the form of
         * tabular data sets.
         */
        TDP("Tabular Data Provider."),
        /**
         * Designates providers which provide results in the form of
         * multidimensional data sets.
         */
        MDP("Multidimensional Data Provider."),
        /**
         * Designates providers which provide results optimized for
         * data mining operations.
         */
        DMP(
            "Data Mining Provider. A DMP provider implements the OLE DB for "
            + "Data Mining specification.");

        private final String description;

        private ProviderType(String description) {
            this.description = description;
        }

        /**
         * Provides a human readable description of the provider type.
         * @return A description string.
         */
        public String getDescription() {
            return description;
        }
    }
}

// End Database.java
