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*/
020package org.olap4j;
021
022import org.olap4j.metadata.Member;
023
024import java.sql.*;
025import 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 */
041public 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