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    */
020    package org.olap4j.metadata;
021    
022    import org.olap4j.OlapConnection;
023    import org.olap4j.OlapException;
024    
025    import 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     */
068    public 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