001    /*
002    // $Id: OlapDatabaseMetaData.java 482 2012-01-05 23:27:27Z 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;
021    
022    import org.olap4j.metadata.Member;
023    
024    import java.sql.*;
025    import java.util.Set;
026    
027    /**
028     * Information about an OLAP database.
029     *
030     * <p>Methods are provided to query the metadata catalog of the database.
031     * There is a method for each metadata class, and each method takes zero or more
032     * parameters to qualify the instances should be returned, and returns a JDBC
033     * {@link java.sql.ResultSet}.
034     *
035     * <p>For example, {@link #getCubes} returns the description of a cube.
036     *
037     * @author jhyde
038     * @version $Id: OlapDatabaseMetaData.java 482 2012-01-05 23:27:27Z jhyde $
039     * @since Oct 12, 2006
040     */
041    public interface OlapDatabaseMetaData extends DatabaseMetaData, OlapWrapper {
042    
043        // override return type
044        /**
045         * {@inheritDoc}
046         */
047        OlapConnection getConnection() throws SQLException;
048    
049        /**
050         * Returns the granularity of changes to cell sets that the database is
051         * capable of providing.
052         *
053         * <p>It's optional whether an olap4j provider supports cellset listeners,
054         * and also optional which granularities it supports. If the provider does
055         * not support the cell set listener API, returns an empty set. Never
056         * returns null.
057         *
058         * @return set of the granularities that are supported when listening for
059         * changes to a cell set, never null
060         */
061        Set<CellSetListener.Granularity> getSupportedCellSetListenerGranularities()
062            throws OlapException;
063    
064        /**
065         * Retrieves a result set describing the Actions in this database.
066         *
067         * <p>Specification as for XML/A MDSCHEMA_ACTIONS schema rowset.
068         *
069         * <p>Each action description has the following columns:
070         * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of
071         *         the database.</li>
072         * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of
073         *         the schema to which this action belongs.</li>
074         * <li><b>CUBE_NAME</b> String => The name of the cube to which this action
075         *         belongs.</li>
076         * <li><b>ACTION_NAME</b> String => The name of the action.</li>
077         * <li><b>COORDINATE</b> String => null</li>
078         * <li><b>COORDINATE_TYPE</b> int => null</li>
079         * </ol>
080         *
081         * @param catalog a catalog name; must match the catalog name as it
082         *        is stored in the database; "" retrieves those without a catalog;
083         *        <code>null</code> means that the catalog name should not be used
084         *        to narrow the search
085         *
086         * @param schemaPattern a schema name pattern; must match the schema name
087         *        as it is stored in the database; "" retrieves those without a
088         *        schema; <code>null</code> means that the schema name should not
089         *        be used to narrow the search
090         *
091         * @param cubeNamePattern a cube name pattern; must match the
092         *        cube name as it is stored in the database; "" retrieves those
093         *        without a cube (such as shared dimensions);
094         *        <code>null</code> means that the cube name should
095         *        not be used to narrow the search
096         *
097         * @param actionNamePattern an action name pattern; must match the
098         *        action name as it is stored in the database; <code>null</code>
099         *        means that the action name should not be used to narrow the
100         *        search
101         *
102         * @return a <code>ResultSet</code> object in which each row is an
103         *         action description
104         *
105         * @exception OlapException if a database access error occurs
106         *
107         * @see #getSearchStringEscape
108         */
109        ResultSet getActions(
110            String catalog,
111            String schemaPattern,
112            String cubeNamePattern,
113            String actionNamePattern) throws OlapException;
114    
115        /**
116         * Retrieves a row set describing the databases that are available on the
117         * server.
118         *
119         * <p>Specification as for XML/A DISCOVER_DATASOURCES schema rowset.
120         *
121         * <ol>
122         * <li><b>DATA_SOURCE_NAME</b> String => The name of the data source, such
123         *         as FoodMart 2000.</li>
124         * <li><b>DATA_SOURCE_DESCRIPTION</b> String => A description of the data
125         *         source, as entered by the publisher. (may be
126         *         <code>null</code>)</li>
127         * <li><b>URL</b> String => The unique path that shows where to invoke the
128         *         XML for Analysis methods for that data source. (may be
129         *         <code>null</code>)</li>
130         * <li><b>DATA_SOURCE_INFO</b> String => A string containing any additional
131         *         information required to connect to the data source. This can
132         *         include the Initial Catalog property or other information for
133         *         the provider.<br/>Example: "Provider=MSOLAP;Data
134         *         Source=Local;" (may be <code>null</code>)</li>
135         * <li><b>PROVIDER_NAME</b> String => The name of the provider behind the
136         *         data source. <br/>Example: "MSDASQL" (may be
137         *         <code>null</code>)</li>
138         * <li><b>PROVIDER_TYPE</b> EnumerationArray => The types of data supported
139         *         by the provider. May include one or more of the following
140         *         types. Example follows this table.<br/>TDP: tabular data
141         *         provider.<br/>MDP: multidimensional data provider.<br/>DMP:
142         *         data mining provider. A DMP provider implements the OLE DB for
143         *         Data Mining specification.</li>
144         * <li><b>AUTHENTICATION_MODE</b> EnumString => Specification of what type
145         *         of security mode the data source uses. Values can be one of
146         *         the following:<br/>Unauthenticated: no user ID or password
147         *         needs to be sent.<br/>Authenticated: User ID and Password must
148         *         be included in the information required for the
149         *         connection.<br/>Integrated: the data source uses the
150         *         underlying security to determine authorization, such as
151         *         Integrated Security provided by Microsoft Internet Information
152         *         Services (IIS).</li>
153         * </ol>
154         *
155         * @return a <code>ResultSet</code> object in which each row is an
156         *         OLAP database description
157         * @throws OlapException if a database access error occurs
158         */
159        ResultSet getDatabases() throws OlapException;
160    
161        /**
162         * Retrieves a list of information on supported literals, including data
163         * types and values.
164         *
165         * <p>Specification as for XML/A DISCOVER_LITERALS schema rowset.
166         *
167         * <ol>
168         * <li><b>LITERAL_NAME</b> String => The name of the literal described in
169         *         the row.<br/>Example: DBLITERAL_LIKE_PERCENT</li>
170         * <li><b>LITERAL_VALUE</b> String (may be <code>null</code>) => Contains
171         *         the actual literal value.<br/>Example, if LiteralName is
172         *         DBLITERAL_LIKE_PERCENT and the percent character (%) is used
173         *         to match zero or more characters in a LIKE clause, this
174         *         column's value would be "%".</li>
175         * <li><b>LITERAL_INVALID_CHARS</b> String (may be <code>null</code>) =>
176         *         The characters, in the literal, that are not valid.<br/>For
177         *         example, if table names can contain anything other than a
178         *         numeric character, this string would be "0123456789".</li>
179         * <li><b>LITERAL_INVALID_STARTING_CHARS</b> String (may be
180         *         <code>null</code>) => The characters that are not valid as the
181         *         first character of the literal. If the literal can start with
182         *         any valid character, this is null.</li>
183         * <li><b>LITERAL_MAX_LENGTH</b> int (may be <code>null</code>) => The
184         *         maximum number of characters in the literal. If there is no
185         *         maximum or the maximum is unknown, the value is -1.</li>
186         * </ol>
187         *
188         * @return a <code>ResultSet</code> object in which each row is a
189         *         literal description
190         *
191         * @exception OlapException if a database access error occurs
192         */
193        ResultSet getLiterals() throws OlapException;
194    
195        /**
196         * Retrieves a list of the standard and provider-specific properties
197         * supported by an olap4j provider. Properties that are not supported by a
198         * provider are not listed in the return result set.
199         *
200         * <p>Specification as for XML/A DISCOVER_PROPERTIES schema rowset.
201         *
202         * <p>Not to be confused with {@link #getProperties}.
203         *
204         * <ol>
205         * <li><b>PROPERTY_NAME</b> String => The name of the property.</li>
206         * <li><b>PROPERTY_DESCRIPTION</b> String => A localizable text description
207         *         of the property.</li>
208         * <li><b>PROPERTY_TYPE</b> String => The XML data type of the
209         *         property.</li>
210         * <li><b>PROPERTY_ACCESS_TYPE</b> EnumString => Access for the property.
211         *         The value can be Read, Write, or ReadWrite.</li>
212         * <li><b>IS_REQUIRED</b> Boolean => True if a property is required, false
213         *         if it is not required.</li>
214         * <li><b>PROPERTY_VALUE</b> String => The current value of the
215         *         property.</li>
216         * </ol>
217         *
218         * @param dataSourceName Name of data source
219         *
220         * @param propertyNamePattern an property name pattern; must match the
221         *        property name as it is stored in the database; <code>null</code>
222         *        means that the property name should not be used to narrow the
223         *        search
224         *
225         * @return a <code>ResultSet</code> object in which each row is a
226         *         the description of a database property
227         *
228         * @exception OlapException if a database access error occurs
229         *
230         * @see #getSearchStringEscape
231         */
232        ResultSet getDatabaseProperties(
233            String dataSourceName,
234            String propertyNamePattern) throws OlapException;
235    
236        /**
237         * Retrieves a result set describing member and cell Properties.
238         *
239         * <p>Specification as for XML/A MDSCHEMA_PROPERTIES schema rowset.
240         *
241         * <p>Not to be confused with {@link #getDatabaseProperties(String,String)}.
242         *
243         * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of
244         *         the database.</li>
245         * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of
246         *         the schema to which this property belongs.</li>
247         * <li><b>CUBE_NAME</b> String => The name of the cube.</li>
248         * <li><b>DIMENSION_UNIQUE_NAME</b> String => The unique name of the
249         *         dimension.</li>
250         * <li><b>HIERARCHY_UNIQUE_NAME</b> String => The unique name of the
251         *         hierarchy.</li>
252         * <li><b>LEVEL_UNIQUE_NAME</b> String => The unique name of the level to
253         *         which this property belongs.</li>
254         * <li><b>MEMBER_UNIQUE_NAME</b> String (may be <code>null</code>) => The
255         *         unique name of the member to which the property belongs.</li>
256         * <li><b>PROPERTY_NAME</b> String => Name of the property.</li>
257         * <li><b>PROPERTY_CAPTION</b> String => A label or caption associated with
258         *         the property, used primarily for display purposes.</li>
259         * <li><b>PROPERTY_TYPE</b> Short => A bitmap that specifies the type of
260         *         the property</li>
261         * <li><b>DATA_TYPE</b> UnsignedShort => Data type of the property.</li>
262         * <li><b>PROPERTY_CONTENT_TYPE</b> Short (may be <code>null</code>) => The
263         *         type of the property. </li>
264         * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A
265         *         human-readable description of the measure. </li>
266         * </ol>
267         *
268         * @param catalog a catalog name; must match the catalog name as it
269         *        is stored in the database; "" retrieves those without a catalog;
270         *        <code>null</code> means that the catalog name should not be used
271         *        to narrow the search
272         *
273         * @param schemaPattern a schema name pattern; must match the schema
274         *        name as it is stored in the database; "" retrieves those without
275         *        a schema; <code>null</code> means that the schema name should not
276         *        be used to narrow the search
277         *
278         * @param cubeNamePattern a cube name pattern; must match the
279         *        cube name as it is stored in the database; "" retrieves those
280         *        without a cube; <code>null</code> means that the cube name should
281         *        not be used to narrow the search
282         *
283         * @param dimensionUniqueName unique name of a dimension (not a pattern);
284         *        must match the dimension name as it is stored in the database;
285         *        <code>null</code> means that the dimension name should not be
286         *        used to narrow the search
287         *
288         * @param hierarchyUniqueName unique name of a hierarchy (not a pattern);
289         *        must match the
290         *        hierarchy name as it is stored in the database; <code>null</code>
291         *        means that the hierarchy name should not be used to narrow the
292         *        search
293         *
294         * @param levelUniqueName unique name of a level (not a pattern);
295         *        must match the
296         *        level name as it is stored in the database; <code>null</code>
297         *        means that the level name should not be used to narrow the
298         *        search
299         *
300         * @param memberUniqueName unique name of member (not a pattern);
301         *        <code>null</code>
302         *        means that the member unique name should not be used to narrow
303         *        the search
304         *
305         * @param propertyNamePattern a property name pattern; must match the
306         *        property name as it is stored in the database; <code>null</code>
307         *        means that the property name should not be used to narrow the
308         *        search
309         *
310         * @return a <code>ResultSet</code> object in which each row is a
311         *         description of a member or cell property
312         *
313         * @exception OlapException if a database access error occurs
314         *
315         * @see #getSearchStringEscape
316         * @see org.olap4j.metadata.Property
317         */
318        ResultSet getProperties(
319            String catalog,
320            String schemaPattern,
321            String cubeNamePattern,
322            String dimensionUniqueName,
323            String hierarchyUniqueName,
324            String levelUniqueName,
325            String memberUniqueName,
326            String propertyNamePattern) throws OlapException;
327    
328        /**
329         * Retrieves a comma-separated list of all of this database's MDX keywords.
330         *
331         * @return the list of this database's MDX keywords
332         *
333         * @exception OlapException if a database access error occurs
334         */
335        String getMdxKeywords() throws OlapException;
336    
337        /**
338         * Retrieves a result set describing the Cubes in this database.
339         *
340         * <p>Specification as for XML/A MDSCHEMA_CUBES schema rowset.
341         *
342         * <p>Each cube description has the following columns:
343         * <ol>
344         * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of
345         *         the catalog to which this cube belongs.</li>
346         * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of
347         *         the schema to which this cube belongs.</li>
348         * <li><b>CUBE_NAME</b> String => Name of the cube.</li>
349         * <li><b>CUBE_TYPE</b> String => Cube type.</li>
350         * <li><b>CUBE_GUID</b> UUID (may be <code>null</code>) => Cube type.</li>
351         * <li><b>CREATED_ON</b> Timestamp (may be <code>null</code>) => Date and
352         *         time of cube creation.</li>
353         * <li><b>LAST_SCHEMA_UPDATE</b> Timestamp (may be <code>null</code>) =>
354         *         Date and time of last schema update.</li>
355         * <li><b>SCHEMA_UPDATED_BY</b> String (may be <code>null</code>) => User
356         *         ID of the person who last updated the schema.</li>
357         * <li><b>LAST_DATA_UPDATE</b> Timestamp (may be <code>null</code>) => Date
358         *         and time of last data update.</li>
359         * <li><b>DATA_UPDATED_BY</b> String (may be <code>null</code>) => User ID
360         *         of the person who last updated the data. </li>
361         * <li><b>IS_DRILLTHROUGH_ENABLED</b> boolean => Describes whether
362         *         DRILLTHROUGH can be performed on the members of a cube</li>
363         * <li><b>IS_WRITE_ENABLED</b> boolean => Describes whether a cube is
364         *         write-enabled</li>
365         * <li><b>IS_LINKABLE</b> boolean => Describes whether a cube can be used
366         *         in a linked cube</li>
367         * <li><b>IS_SQL_ENABLED</b> boolean => Describes whether or not SQL can be
368         *         used on the cube</li>
369         * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A
370         *         user-friendly description of the cube.</li>
371         * <li><b>CUBE_CAPTION</b> String (may be <code>null</code>) =>
372         *         The caption of the cube.</li>
373         * <li><b>BASE_CUBE_NAME</b> String (may be <code>null</code>) =>
374         *         The name of the source cube if this cube is a perspective
375         *         cube.</li>
376         * </ol>
377         *
378         * @param catalog a catalog name; must match the catalog name as it
379         *        is stored in the database; "" retrieves those without a catalog;
380         *        <code>null</code> means that the catalog name should not be used
381         *        to narrow the search
382         *
383         * @param schemaPattern a schema name pattern; must match the schema
384         *        name as it is stored in the database; "" retrieves those without
385         *        a schema; <code>null</code> means that the schema name should not
386         *        be used to narrow the search
387         *
388         * @param cubeNamePattern a cube name pattern; must match the
389         *        cube name as it is stored in the database; <code>null</code>
390         *        means that the cube name should not be used to narrow the search
391         *
392         * @return <code>ResultSet</code> in which each row is a cube description
393         *
394         * @exception OlapException if a database access error occurs
395         *
396         * @see #getSearchStringEscape
397         * @see org.olap4j.metadata.Cube
398         */
399        public ResultSet getCubes(
400            String catalog,
401            String schemaPattern,
402            String cubeNamePattern) throws OlapException;
403    
404        /**
405         * Retrieves a result set describing the shared and private Dimensions
406         * in this database.
407         *
408         * <p>Specification as for XML/A MDSCHEMA_DIMENSIONS schema rowset.
409         *
410         * <p>Each dimension description has the following columns:
411         * <ol>
412         * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of
413         *         the database.</li>
414         * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => Not
415         *         supported.</li>
416         * <li><b>CUBE_NAME</b> String => The name of the cube.</li>
417         * <li><b>DIMENSION_NAME</b> String => The name of the dimension. </li>
418         * <li><b>DIMENSION_UNIQUE_NAME</b> String => The unique name of the
419         *         dimension.</li>
420         * <li><b>DIMENSION_GUID</b> String (may be <code>null</code>) => Not
421         *         supported.</li>
422         * <li><b>DIMENSION_CAPTION</b> String => The caption of the
423         *         dimension.</li>
424         * <li><b>DIMENSION_ORDINAL</b> int => The position of the dimension within
425         *         the cube.</li>
426         * <li><b>DIMENSION_TYPE</b> Short => The type of the dimension.</li>
427         * <li><b>DIMENSION_CARDINALITY</b> int => The number of members in the key
428         *         attribute.</li>
429         * <li><b>DEFAULT_HIERARCHY</b> String => A hierarchy from the dimension.
430         *         Preserved for backwards compatibility.</li>
431         * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A
432         *         user-friendly description of the dimension.</li>
433         * <li><b>IS_VIRTUAL</b> boolean (may be <code>null</code>) => Always
434         *         FALSE.</li>
435         * <li><b>IS_READWRITE</b> boolean (may be <code>null</code>) => A Boolean
436         *         that indicates whether the dimension is write-enabled.</li>
437         * <li><b>DIMENSION_UNIQUE_SETTINGS</b> int (may be <code>null</code>) => A
438         *         bitmap that specifies which columns contain unique values if
439         *         the dimension contains only members with unique names.</li>
440         * <li><b>DIMENSION_MASTER_UNIQUE_NAME</b> String (may be
441         *         <code>null</code>) => Always NULL.</li>
442         * <li><b>DIMENSION_IS_VISIBLE</b> boolean (may be <code>null</code>) =>
443         *         Always TRUE.</li>
444         * </ol>
445         *
446         * @param catalog a catalog name; must match the catalog name as it
447         *        is stored in the database; "" retrieves those without a catalog;
448         *        <code>null</code> means that the catalog name should not be used
449         *        to narrow the search
450         *
451         * @param schemaPattern a schema name pattern; must match the schema name
452         *        as it is stored in the database; "" retrieves those without a
453         *        schema; <code>null</code> means that the schema name should not
454         *        be used to narrow the search
455         *
456         * @param cubeNamePattern a cube name pattern; must match the
457         *        cube name as it is stored in the database; "" retrieves those
458         *        without a cube (such as shared dimensions);
459         *        <code>null</code> means that the cube name should
460         *        not be used to narrow the search
461         *
462         * @param dimensionNamePattern a dimension name pattern; must match the
463         *        dimension name as it is stored in the database; <code>null</code>
464         *        means that the dimension name should not be used to narrow the
465         *        search
466         *
467         * @return a <code>ResultSet</code> object in which each row is a
468         *         dimension description
469         *
470         * @exception OlapException if a database access error occurs
471         *
472         * @see #getSearchStringEscape
473         * @see org.olap4j.metadata.Dimension
474         */
475        ResultSet getDimensions(
476            String catalog,
477            String schemaPattern,
478            String cubeNamePattern,
479            String dimensionNamePattern) throws OlapException;
480    
481        /**
482         * Retrieves a result set describing the Functions available to client
483         * applications connected to the database.
484         *
485         * <p>Specification as for XML/A MDSCHEMA_FUNCTIONS schema rowset.
486         *
487         * <p>Each function description has the following columns:
488         * <li><b>FUNCTION_NAME</b> String => The name of the function.</li>
489         * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A
490         *         description of the function.</li>
491         * <li><b>PARAMETER_LIST</b> String (may be <code>null</code>) => A comma
492         *         delimited list of parameters.</li>
493         * <li><b>RETURN_TYPE</b> int => The VARTYPE of the return data type of the
494         *         function.</li>
495         * <li><b>ORIGIN</b> int => The origin of the function:  1 for MDX
496         *         functions.  2 for user-defined functions.</li>
497         * <li><b>INTERFACE_NAME</b> String => The name of the interface for
498         *         user-defined functions</li>
499         * <li><b>LIBRARY_NAME</b> String (may be <code>null</code>) => The name of
500         *         the type library for user-defined functions. NULL for MDX
501         *         functions.</li>
502         * <li><b>CAPTION</b> String (may be <code>null</code>) => The display
503         *         caption for the function.</li>
504         * </ol>
505         *
506         * @param functionNamePattern a function name pattern; must match the
507         *        function name as it is stored in the database; <code>null</code>
508         *        means that the function name should not be used to narrow the
509         *        search
510         *
511         * @return a <code>ResultSet</code> object in which each row is a
512         *         function description
513         *
514         * @exception OlapException if a database access error occurs
515         *
516         * @see #getSearchStringEscape
517         */
518        // NOTE: '#getFunctions(String, String, String)' above generates a javadoc
519        // error on JDK 1.5, because it is new in JDBC 4.0/JDK 1.6. But please leave
520        // it in. Most olap4j users run on JDK 1.6 or later, and the javadoc is
521        // intended for them.
522        ResultSet getOlapFunctions(
523            String functionNamePattern) throws OlapException;
524    
525        /**
526         * Retrieves a result set describing the Hierarchies in this database.
527         *
528         * <p>Specification as for XML/A MDSCHEMA_HIERARCHIES schema rowset.
529         *
530         * <p>Each hierarchy description has the following columns:
531         * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of
532         *         the catalog to which this hierarchy belongs.</li>
533         * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => Not
534         *         supported</li>
535         * <li><b>CUBE_NAME</b> String => The name of the cube to which this
536         *         hierarchy belongs.</li>
537         * <li><b>DIMENSION_UNIQUE_NAME</b> String => The unique name of the
538         *         dimension to which this hierarchy belongs. </li>
539         * <li><b>HIERARCHY_NAME</b> String => The name of the hierarchy. Blank if
540         *         there is only a single hierarchy in the dimension.</li>
541         * <li><b>HIERARCHY_UNIQUE_NAME</b> String => The unique name of the
542         *         hierarchy.</li>
543         * <li><b>HIERARCHY_GUID</b> String (may be <code>null</code>) => Hierarchy
544         *         GUID.</li>
545         * <li><b>HIERARCHY_CAPTION</b> String => A label or a caption associated
546         *         with the hierarchy.</li>
547         * <li><b>DIMENSION_TYPE</b> Short => The type of the dimension. </li>
548         * <li><b>HIERARCHY_CARDINALITY</b> int => The number of members in the
549         *         hierarchy.</li>
550         * <li><b>DEFAULT_MEMBER</b> String (may be <code>null</code>) => The
551         *         default member for this hierarchy. </li>
552         * <li><b>ALL_MEMBER</b> String (may be <code>null</code>) => The member at
553         *         the highest level of rollup in the hierarchy.</li>
554         * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A
555         *         human-readable description of the hierarchy. NULL if no
556         *         description exists.</li>
557         * <li><b>STRUCTURE</b> Short => The structure of the hierarchy.</li>
558         * <li><b>IS_VIRTUAL</b> boolean => Always returns False.</li>
559         * <li><b>IS_READWRITE</b> boolean => A Boolean that indicates whether the
560         *         Write Back to dimension column is enabled.</li>
561         * <li><b>DIMENSION_UNIQUE_SETTINGS</b> int => Always returns
562         *         MDDIMENSIONS_MEMBER_KEY_UNIQUE (1).</li>
563         * <li><b>DIMENSION_IS_VISIBLE</b> boolean => Always returns true.</li>
564         * <li><b>HIERARCHY_ORDINAL</b> int => The ordinal number of the hierarchy
565         *         across all hierarchies of the cube.</li>
566         * <li><b>DIMENSION_IS_SHARED</b> boolean => Always returns true.</li>
567         * <li><b>PARENT_CHILD</b> boolean (may be <code>null</code>) => Is
568         *         hierarchy a parent.</li>
569         * </ol>
570         *
571         * @param catalog a catalog name; must match the catalog name as it
572         *        is stored in the database; "" retrieves those without a catalog;
573         *        <code>null</code> means that the catalog name should not be used
574         *        to narrow the search
575         *
576         * @param schemaPattern a schema name pattern; must match the schema name
577         *        as it is stored in the database; "" retrieves those without a
578         *        schema; <code>null</code> means that the schema name should not
579         *        be used to narrow the search
580         *
581         * @param cubeNamePattern a cube name pattern; must match the
582         *        cube name as it is stored in the database; "" retrieves those
583         *        without a cube; <code>null</code> means that the cube name should
584         *        not be used to narrow the search
585         *
586         * @param dimensionUniqueName unique name of a dimension (not a pattern);
587         *        must match the
588         *        dimension name as it is stored in the database; <code>null</code>
589         *        means that the dimension name should not be used to narrow the
590         *        search
591         *
592         * @param hierarchyNamePattern a hierarchy name pattern; must match the
593         *        hierarchy name as it is stored in the database; <code>null</code>
594         *        means that the hierarchy name should not be used to narrow the
595         *        search
596         *
597         * @return a <code>ResultSet</code> object in which each row is a
598         *         hierarchy description
599         *
600         * @exception OlapException if a database access error occurs
601         *
602         * @see #getSearchStringEscape
603         * @see org.olap4j.metadata.Hierarchy
604         */
605        ResultSet getHierarchies(
606            String catalog,
607            String schemaPattern,
608            String cubeNamePattern,
609            String dimensionUniqueName,
610            String hierarchyNamePattern) throws OlapException;
611    
612        /**
613         * Retrieves a result set describing the Levels in this database.
614         *
615         * <p>Specification as for XML/A MDSCHEMA_LEVELS schema rowset.
616         *
617         * <p>Each level description has the following columns:
618         * <ol>
619         * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of
620         *         the catalog to which this level belongs.</li>
621         * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of
622         *         the schema to which this level belongs.</li>
623         * <li><b>CUBE_NAME</b> String => The name of the cube to which this level
624         *         belongs.</li>
625         * <li><b>DIMENSION_UNIQUE_NAME</b> String => The unique name of the
626         *         dimension to which this level belongs.</li>
627         * <li><b>HIERARCHY_UNIQUE_NAME</b> String => The unique name of the
628         *         hierarchy.</li>
629         * <li><b>LEVEL_NAME</b> String => The name of the level.</li>
630         * <li><b>LEVEL_UNIQUE_NAME</b> String => The properly escaped unique name
631         *         of the level.</li>
632         * <li><b>LEVEL_GUID</b> String (may be <code>null</code>) => Level
633         *         GUID.</li>
634         * <li><b>LEVEL_CAPTION</b> String => A label or caption associated with
635         *         the hierarchy.</li>
636         * <li><b>LEVEL_NUMBER</b> int => The distance of the level from the root
637         *         of the hierarchy. Root level is zero (0).</li>
638         * <li><b>LEVEL_CARDINALITY</b> int => The number of members in the level.
639         *         This value can be an approximation of the real
640         *         cardinality.</li>
641         * <li><b>LEVEL_TYPE</b> int => Type of the level</li>
642         * <li><b>CUSTOM_ROLLUP_SETTINGS</b> int => A bitmap that specifies the
643         *         custom rollup options.</li>
644         * <li><b>LEVEL_UNIQUE_SETTINGS</b> int => A bitmap that specifies which
645         *         columns contain unique values, if the level only has members
646         *         with unique names or keys.</li>
647         * <li><b>LEVEL_IS_VISIBLE</b> boolean => A Boolean that indicates whether
648         *         the level is visible.</li>
649         * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A
650         *         human-readable description of the level. NULL if no
651         *         description exists.</li>
652         * </ol>
653         *
654         * @param catalog a catalog name; must match the catalog name as it
655         *        is stored in the database; "" retrieves those without a catalog;
656         *        <code>null</code> means that the catalog name should not be used
657         *        to narrow the search
658         *
659         * @param schemaPattern a schema name pattern; must match the schema name
660         *        as it is stored in the database; "" retrieves those without a
661         *        schema; <code>null</code> means that the schema name should not
662         *        be used to narrow the search
663         *
664         * @param cubeNamePattern a cube name pattern; must match the
665         *        cube name as it is stored in the database; "" retrieves those
666         *        without a cube; <code>null</code> means that the cube name should
667         *        not be used to narrow the search
668         *
669         * @param dimensionUniqueName unique name of a dimension (not a pattern);
670         *        must match the
671         *        dimension name as it is stored in the database; <code>null</code>
672         *        means that the dimension name should not be used to narrow the
673         *        search
674         *
675         * @param hierarchyUniqueName unique name of a hierarchy (not a pattern);
676         *        must match the
677         *        hierarchy name as it is stored in the database; <code>null</code>
678         *        means that the hierarchy name should not be used to narrow the
679         *        search
680         *
681         * @param levelNamePattern a level name pattern; must match the
682         *        level name as it is stored in the database; <code>null</code>
683         *        means that the level name should not be used to narrow the
684         *        search
685         *
686         * @return a <code>ResultSet</code> object in which each row is a
687         *         level description
688         *
689         * @exception OlapException if a database access error occurs
690         *
691         * @see #getSearchStringEscape
692         * @see org.olap4j.metadata.Level
693         */
694        ResultSet getLevels(
695            String catalog,
696            String schemaPattern,
697            String cubeNamePattern,
698            String dimensionUniqueName,
699            String hierarchyUniqueName,
700            String levelNamePattern) throws OlapException;
701    
702        /**
703         * Retrieves a result set describing the Measures in this database.
704         *
705         * <p>Specification as for XML/A MDSCHEMA_MEASURES schema rowset.
706         *
707         * <p>Each measure description has the following columns:
708         * <ol>
709         * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of
710         *         the catalog to which this measure belongs. </li>
711         * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of
712         *         the schema to which this measure belongs.</li>
713         * <li><b>CUBE_NAME</b> String => The name of the cube to which this
714         *         measure belongs.</li>
715         * <li><b>MEASURE_NAME</b> String => The name of the measure.</li>
716         * <li><b>MEASURE_UNIQUE_NAME</b> String => The Unique name of the
717         *         measure.</li>
718         * <li><b>MEASURE_CAPTION</b> String => A label or caption associated with
719         *         the measure. </li>
720         * <li><b>MEASURE_GUID</b> String (may be <code>null</code>) => Measure
721         *         GUID.</li>
722         * <li><b>MEASURE_AGGREGATOR</b> int => How a measure was derived. </li>
723         * <li><b>DATA_TYPE</b> UnsignedShort => Data type of the measure.</li>
724         * <li><b>MEASURE_IS_VISIBLE</b> boolean => A Boolean that always returns
725         *         True. If the measure is not visible, it will not be included
726         *         in the schema rowset.</li>
727         * <li><b>LEVELS_LIST</b> String (may be <code>null</code>) => A string
728         *         that always returns NULL. EXCEPT that SQL Server returns
729         *         non-null values!!!</li>
730         * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A
731         *         human-readable description of the measure. </li>
732         * </ol>
733         *
734         * @param catalog a catalog name; must match the catalog name as it
735         *        is stored in the database; "" retrieves those without a catalog;
736         *        <code>null</code> means that the catalog name should not be used
737         *        to narrow the search
738         *
739         * @param schemaPattern a schema name pattern; must match the schema name
740         *        as it is stored in the database; "" retrieves those without a
741         *        schema; <code>null</code> means that the schema name should not
742         *        be used to narrow the search
743         *
744         * @param cubeNamePattern a cube name pattern; must match the
745         *        cube name as it is stored in the database; "" retrieves those
746         *        without a cube; <code>null</code> means that the cube name should
747         *        not be used to narrow the search
748         *
749         * @param measureNamePattern a measure name pattern; must match the
750         *        measure name as it is stored in the database; <code>null</code>
751         *        means that the measure name should not be used to narrow the
752         *        search
753         *
754         * @param measureUniqueName unique name of measure (not a pattern);
755         *        <code>null</code> means that the measure unique name should not
756         *        be used to narrow the search
757         *
758         * @return a <code>ResultSet</code> object in which each row is a
759         *         measure description
760         *
761         * @exception OlapException if a database access error occurs
762         *
763         * @see #getSearchStringEscape
764         * @see org.olap4j.metadata.Measure
765         */
766        ResultSet getMeasures(
767            String catalog,
768            String schemaPattern,
769            String cubeNamePattern,
770            String measureNamePattern,
771            String measureUniqueName) throws OlapException;
772    
773        /**
774         * Retrieves a result set describing the Members in this database.
775         *
776         * <p>Specification as for XML/A MDSCHEMA_MEMBERS schema rowset. Rows
777         * are sorted by level number then by ordinal.
778         *
779         * <p>The <code>treeOps</code> parameter allows you to retrieve members
780         * relative to a given member. It is only applicable if a
781         * <code>memberUniqueName</code> is also specified; otherwise it is
782         * ignored. The following example retrieves all descendants and ancestors
783         * of California, but not California itself:
784         *
785         * <blockquote>
786         * <pre>
787         * OlapDatabaseMetaData metaData;
788         * ResultSet rset = metaData.getMembers(
789         *     "LOCALDB", "FoodMart", "Sales", null, null, null,
790         *     "[Customers].[USA].[CA]",
791         *     EnumSet.of(Member.TreeOp.ANCESTORS, Member.TreeOp.DESCENDANTS));
792         * </pre>
793         * </blockquote>
794         *
795         * <p>Each member description has the following columns:
796         * <ol>
797         * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of
798         *         the catalog to which this member belongs. </li>
799         * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of
800         *         the schema to which this member belongs. </li>
801         * <li><b>CUBE_NAME</b> String => Name of the cube to which this member
802         *         belongs.</li>
803         * <li><b>DIMENSION_UNIQUE_NAME</b> String => Unique name of the dimension
804         *         to which this member belongs. </li>
805         * <li><b>HIERARCHY_UNIQUE_NAME</b> String => Unique name of the hierarchy.
806         *         If the member belongs to more than one hierarchy, there is one
807         *         row for each hierarchy to which it belongs.</li>
808         * <li><b>LEVEL_UNIQUE_NAME</b> String =>  Unique name of the level to
809         *         which the member belongs.</li>
810         * <li><b>LEVEL_NUMBER</b> int => The distance of the member from the root
811         *         of the hierarchy.</li>
812         * <li><b>MEMBER_ORDINAL</b> int => Ordinal number of the member. Sort rank
813         *         of the member when members of this dimension are sorted in
814         *         their natural sort order. If providers do not have the concept
815         *         of natural ordering, this should be the rank when sorted by
816         *         MEMBER_NAME.</li>
817         * <li><b>MEMBER_NAME</b> String => Name of the member.</li>
818         * <li><b>MEMBER_UNIQUE_NAME</b> String =>  Unique name of the member.</li>
819         * <li><b>MEMBER_TYPE</b> int => Type of the member.</li>
820         * <li><b>MEMBER_GUID</b> String (may be <code>null</code>) => Memeber
821         *         GUID.</li>
822         * <li><b>MEMBER_CAPTION</b> String => A label or caption associated with
823         *         the member.</li>
824         * <li><b>CHILDREN_CARDINALITY</b> int => Number of children that the
825         *         member has.</li>
826         * <li><b>PARENT_LEVEL</b> int => The distance of the member's parent from
827         *         the root level of the hierarchy. </li>
828         * <li><b>PARENT_UNIQUE_NAME</b> String (may be <code>null</code>) =>
829         *         Unique name of the member's parent.</li>
830         * <li><b>PARENT_COUNT</b> int => Number of parents that this member
831         *         has.</li>
832         * <li><b>TREE_OP</b> Enumeration (may be <code>null</code>) => Tree
833         *         Operation</li>
834         * <li><b>DEPTH</b> int (may be <code>null</code>) => depth</li>
835         * </ol>
836         *
837         * @param catalog a catalog name; must match the catalog name as it
838         *        is stored in the database; "" retrieves those without a catalog;
839         *        <code>null</code> means that the catalog name should not be used
840         *        to narrow the search
841         *
842         * @param schemaPattern a schema name pattern; must match the schema name
843         *        as it is stored in the database; "" retrieves those without a
844         *        schema; <code>null</code> means that the schema name should not
845         *        be used to narrow the search
846         *
847         * @param cubeNamePattern a cube name pattern; must match the
848         *        cube name as it is stored in the database; "" retrieves those
849         *        without a cube; <code>null</code> means that the cube name should
850         *        not be used to narrow the search
851         *
852         * @param dimensionUniqueName unique name of dimension (not a pattern);
853         *        must match the
854         *        dimension name as it is stored in the database; <code>null</code>
855         *        means that the dimension name should not be used to narrow the
856         *        search
857         *
858         * @param hierarchyUniqueName unique name of hierarchy (not a pattern);
859         *        must match the
860         *        hierarchy name as it is stored in the database; <code>null</code>
861         *        means that the hierarchy name should not be used to narrow the
862         *        search
863         *
864         * @param levelUniqueName unique name of level (not a pattern); must match
865         *        the level name as it is stored in the database; <code>null</code>
866         *        means that the level name should not be used to narrow the
867         *        search
868         *
869         * @param memberUniqueName unique name of member (not a pattern);
870         *        <code>null</code> means that the measure unique name should not
871         *        be used to narrow the search
872         *
873         * @param treeOps set of tree operations to retrieve members relative
874         *        to the member whose unique name was specified; or null to return
875         *        just the member itself.
876         *        Ignored if <code>memberUniqueName</code> is not specified.
877         *
878         * @return a <code>ResultSet</code> object in which each row is a
879         *         member description
880         *
881         * @exception OlapException if a database access error occurs
882         *
883         * @see #getSearchStringEscape
884         * @see org.olap4j.metadata.Member
885         */
886        ResultSet getMembers(
887            String catalog,
888            String schemaPattern,
889            String cubeNamePattern,
890            String dimensionUniqueName,
891            String hierarchyUniqueName,
892            String levelUniqueName,
893            String memberUniqueName,
894            Set<Member.TreeOp> treeOps) throws OlapException;
895    
896        /**
897         * Retrieves a result set describing the named Sets in this database.
898         *
899         * <p>Specification as for XML/A MDSCHEMA_SETS schema rowset.
900         *
901         * <p>Each set description has the following columns:
902         * <ol>
903         * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => null</li>
904         * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => null</li>
905         * <li><b>CUBE_NAME</b> String => null</li>
906         * <li><b>SET_NAME</b> String => null</li>
907         * <li><b>SCOPE</b> int => null</li>
908         *
909         * @param catalog a catalog name; must match the catalog name as it
910         *        is stored in the database; "" retrieves those without a catalog;
911         *        <code>null</code> means that the catalog name should not be used
912         *        to narrow the search
913         *
914         * @param schemaPattern a schema name pattern; must match the schema name
915         *        as it is stored in the database; "" retrieves those without a
916         *        schema; <code>null</code> means that the schema name should not
917         *        be used to narrow the search
918         *
919         * @param cubeNamePattern a cube name pattern; must match the
920         *        cube name as it is stored in the database; "" retrieves those
921         *        without a cube; <code>null</code> means that the cube name should
922         *        not be used to narrow the search
923         *
924         * @param setNamePattern pattern for the unique name of a set; must match
925         *        the set name as it is stored in the database; <code>null</code>
926         *        means that the set name should not be used to narrow the
927         *        search
928         *
929         * @return a <code>ResultSet</code> object in which each row is a
930         *         description of a named set
931         *
932         * @exception OlapException if a database access error occurs
933         *
934         * @see #getSearchStringEscape
935         * @see org.olap4j.metadata.NamedSet
936         */
937        ResultSet getSets(
938            String catalog,
939            String schemaPattern,
940            String cubeNamePattern,
941            String setNamePattern) throws OlapException;
942    }
943    
944    // End OlapDatabaseMetaData.java