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