001/*
002// $Id: Database.java 483 2012-01-05 23:43:18Z jhyde $
003//
004// Licensed to Julian Hyde under one or more contributor license
005// agreements. See the NOTICE file distributed with this work for
006// additional information regarding copyright ownership.
007//
008// Julian Hyde licenses this file to you under the Apache License,
009// Version 2.0 (the "License"); you may not use this file except in
010// compliance with the License. You may obtain a copy of the License at:
011//
012// http://www.apache.org/licenses/LICENSE-2.0
013//
014// Unless required by applicable law or agreed to in writing, software
015// distributed under the License is distributed on an "AS IS" BASIS,
016// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017// See the License for the specific language governing permissions and
018// limitations under the License.
019*/
020package org.olap4j.metadata;
021
022import org.olap4j.OlapConnection;
023import org.olap4j.OlapException;
024
025import java.util.List;
026
027/**
028 * Highest level element in the hierarchy of metadata objects.
029 *
030 * <p>A Database contains one or more {@link Catalog}s.</p>
031 *
032 * <p>To obtain the collection of databases in the current server, call the
033 * {@link OlapConnection#getOlapDatabases()} method. To obtain the current
034 * active catalog object, to which a connection is bound, use
035 * {@link OlapConnection#getOlapDatabase()}.
036 *
037 * <p>The hierarchy of metadata objects, rooted at the connection from which
038 * they are accessed, is as follows:
039 * <blockquote>
040 * <ul>
041 * <li type="circle">{@link org.olap4j.OlapConnection}<ul>
042 *     <li type="circle">{@link Database}<ul>
043 *         <li type="circle">{@link Catalog}<ul>
044 *             <li type="circle">{@link Schema}<ul>
045 *                 <li type="circle">{@link Cube}<ul>
046 *                     <li type="circle">{@link Dimension}<ul>
047 *                         <li type="circle">{@link Hierarchy}<ul>
048 *                             <li type="circle">{@link Level}<ul>
049 *                                 <li type="circle">{@link Member}</li>
050 *                                 <li type="circle">{@link Property}</li>
051 *                             </ul></li>
052 *                         </ul></li>
053 *                     </ul></li>
054 *                 <li type="circle">{@link NamedSet}</li>
055 *                 </ul></li>
056 *             <li type="circle">{@link Dimension} (shared)</li>
057 *             </ul></li>
058 *         </ul></li>
059 *     </ul></li>
060 *  </ul>
061 * </blockquote>
062 * </p>
063 *
064 * @author Luc Boudreau
065 * @version $Id: Database.java 483 2012-01-05 23:43:18Z jhyde $
066 * @since Jan 15 2011
067 */
068public interface Database {
069
070    /**
071     * Retrieves the parent {@link OlapConnection} of this
072     * Database object.
073     * @return The parent conenction object.
074     */
075    OlapConnection getOlapConnection();
076
077    /**
078     * Returns the unique name of this Database.
079     * @return The database name.
080     * @throws OlapException if error occurs.
081     */
082    String getName() throws OlapException;
083
084    /**
085     * Returns a human-readable description of this Database.
086     *
087     * @return The database description. Can be <code>null</code>.
088     * @throws OlapException if error occurs.
089     */
090    String getDescription() throws OlapException;
091
092    /**
093     * Returns a redirection URL. This value is used only in
094     * distributed architectures. An OLAP server can serve as a
095     * frontal distribution server and redirect clients to delegate
096     * servers.
097     *
098     * <p>Implementations are free to implement a distributed system.
099     * Most implementations don't make any use of it and
100     * will return the same URL which was used to connect in
101     * the first place.
102     *
103     * @return The database URL. Can be <code>null</code>.
104     * @throws OlapException if error occurs.
105     */
106    String getURL() throws OlapException;
107
108    /**
109     * Returns provider-specific information.
110     *
111     * @return A string containing provider-specific information.
112     * @throws OlapException if error cccurs
113     */
114    String getDataSourceInfo() throws OlapException;
115
116    /**
117     * Returns the name of the underlying OLAP provider.
118     *
119     * <p>This usually is the server vendor name, for example "Mondrian" or
120     * "MSOLAP".
121     *
122     * @return The provider name.
123     * @throws OlapException if error occurs.
124     */
125    String getProviderName() throws OlapException;
126
127    /**
128     * Returns the types of data that are supported by this provider.
129     *
130     * @return The provider types.
131     * @throws OlapException if error occurs.
132     */
133    List<ProviderType> getProviderTypes() throws OlapException;
134
135    /**
136     * Returns the authentication modes supported by this
137     * server.
138     * @return The authentication mode supported.
139     * @throws OlapException if error occurs.
140     */
141    List<AuthenticationMode> getAuthenticationModes() throws OlapException;
142
143    /**
144     * Returns a list of {@link Catalog} objects which belong to
145     * this Database.
146     *
147     * <p>The caller should assume that the list is immutable;
148     * if the caller modifies the list, behavior is undefined.</p>
149     *
150     * @see org.olap4j.OlapConnection#getOlapCatalogs()
151     * @return List of Catalog in this <code>Database</code>
152     * @throws OlapException if error occurs
153     */
154    NamedList<Catalog> getCatalogs() throws OlapException;
155
156    /**
157     * Describes the supported authentication modes.
158     */
159    public enum AuthenticationMode {
160        /**
161         * Designates providers which don't support
162         * authentication.
163         */
164        Unauthenticated("No user ID or password needs to be sent."),
165        /**
166         * Designates providers which support authentication
167         * through the JDBC interface.
168         */
169        Authenticated(
170            "User ID and Password must be included in the information required"
171            + " for the connection."),
172        /**
173         * Designates providers which support authentication through
174         * vendor or implementation specific means.
175         */
176        Integrated(
177            "The data source uses the underlying security to determine "
178            + "authorization, such as Integrated Security provided by "
179            + "Microsoft Internet Information Services (IIS).");
180
181        private final String description;
182
183        AuthenticationMode(String description) {
184            this.description = description;
185        }
186
187        /**
188         * Provides a human readable description of the authentication mode.
189         * @return A description string.
190         */
191        public String getDescription() {
192            return description;
193        }
194    }
195
196    /**
197     * Describes the possible provider types.
198     */
199    public static enum ProviderType {
200        /**
201         * Designates providers which provide results in the form of
202         * tabular data sets.
203         */
204        TDP("Tabular Data Provider."),
205        /**
206         * Designates providers which provide results in the form of
207         * multidimensional data sets.
208         */
209        MDP("Multidimensional Data Provider."),
210        /**
211         * Designates providers which provide results optimized for
212         * data mining operations.
213         */
214        DMP(
215            "Data Mining Provider. A DMP provider implements the OLE DB for "
216            + "Data Mining specification.");
217
218        private final String description;
219
220        private ProviderType(String description) {
221            this.description = description;
222        }
223
224        /**
225         * Provides a human readable description of the provider type.
226         * @return A description string.
227         */
228        public String getDescription() {
229            return description;
230        }
231    }
232}
233
234// End Database.java