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