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