4.1 Overview of the Procedure for Discovering Metadata

The OLAP API provides access to a collection of Oracle data for which a database administrator has created OLAP Catalog metadata. This collection of data is the data store for the application. The API also provides the ability to create custom metadata objects and map relational table data to the metadata objects, and to create queries that use the data to which the custom objects are mapped.

Potentially, the data store includes all of the measure folders that were created by the database administrator in the OLAP Catalog. However, the scope of the data store that is visible when an application is running depends on the database privileges that apply to the user ID through which the connection was made. A user sees all of the measure folders (as MdmSchema objects) that the database administrator or the application created, but the user sees the measures and dimensions that are contained in those measure folders only if he or she has access rights to the relational tables to which the measures and dimensions are mapped.

4.1.1 MDM Metadata

When the database administrator created the OLAP Catalog metadata, the administrator created measures, dimensions, and other OLAP metadata objects by mapping them to columns in database tables or views. In the OLAP API, these objects are accessed as multidimensional metadata (MDM) objects, as described in Chapter 2, " Understanding OLAP API Metadata".

The mapping between the OLAP metadata objects and the MDM objects is automatically performed by Oracle OLAP. You can, however, discover the mapping of the MDM objects by using classes in the oracle.olapi.metadata.mtm package, as described in Chapter 5, " Working with Metadata Mapping Objects". You can also create your own custom MDM metadata objects and map them to database tables or views using MTM objects.

4.1.2 Purpose of Discovering the Metadata

The metadata objects in the data store help your application to make sense of the data. They provide a way for you to find out what data is available, how it is structured, and what its characteristics are.

Therefore, after connecting, your first step is to find out what metadata is available. Armed with this knowledge, you can present choices to the end user about what data should be selected or calculated and how it should be displayed.

4.1.3 Steps in Discovering the Metadata

Before investigating the metadata, your application must make a connection to Oracle OLAP, as described in Chapter 3, " Connecting to a Data Store". Then, your application might perform the following steps:

Create an MdmMetadataProvider.

Get the root MdmSchema from the MdmMetadataProvider.

Get the contents of the root MdmSchema, which include MdmMeasure, MdmDimension, MdmMeasureDimension, and MdmSchema objects. In addition, get the contents of any subschemas.

Get the components or related objects of each MdmMeasure and MdmDimension. For example, get the MdmDimension objects for each MdmMeasure, and for each MdmDimension get its MdmHierarchy objects.

The next four topics in this chapter describe these steps in detail.

4.1.4 Discovering Metadata and Making Queries

After your application discovers the metadata, it typically goes on to create queries for selecting, calculating, and otherwise manipulating the data. To work with data in these ways, you must get the Source objects from the MDM objects. These Source objects are referred to as primary Source objects. Source objects specify the data for querying.

This chapter focuses on the initial step of discovering the available metadata, but it also briefly mentions the step of getting a primary Source from a metadata object. Subsequent chapters of this guide explain how you work with primary Source objects and create queries based on them.

4.2 Creating an MdmMetadataProvider

An MdmMetadataProvider gives access to the metadata in a data store. It provides OLAP metadata objects, such as measures, dimensions, and measure folders, as corresponding MDM objects, such as MdmMeasure, MdmDimension, and MdmSchema objects.

4.3 Getting the Root MdmSchema

Getting the root MdmSchema is the first step in exploring the metadata in your data store.

4.3.1 Function of the Root MdmSchema

The metadata objects that are accessible through an MdmMetadataProvider are organized in a tree-like structure, with the root MdmSchema at the top. Under the root MdmSchema are MdmPrimaryDimension objects and one or more MdmSchema objects, which are referred to as subschemas. In addition, if an MdmMeasure object does not belong to any subschema, then it is included under the root.

Subschemas have their own MdmMeasure and MdmPrimaryDimension objects. Optionally, they can have their own subschemas as well.

The root MdmSchema contains all of the MdmPrimaryDimension objects that are in the subschemas. Therefore, an MdmPrimaryDimension typically appears twice in the tree. It appears once under the root MdmSchema and again under the subschema. If an MdmPrimaryDimension does not belong to a subschema, then it is listed only under the root.

The starting point for discovering the available metadata objects is the root MdmSchema, which is the top of the tree. The following diagram illustrates an MdmSchema that has two subschemas and four MdmPrimaryDimension objects.

In the OLAP Catalog, a database administrator arranges dimensions and measures under one or more top-level measure folders. When Oracle OLAP maps the measure folders to MdmSchema objects, it always creates the root MdmSchema over the MdmSchema objects for the top-level measure folders. Therefore, even if the database administrator creates only one measure folder, its corresponding MdmSchema is a subschema under the root.

4.3.2 Calling the getRootSchema Method

The following code gets the root MdmSchema for mp, which is an MdmMetadataProvider.

Example 4-2 Getting the Root MdmSchema

MdmSchema rootSchema = mp.getRootSchema();

4.4 Getting the Contents of the Root MdmSchema

The root MdmSchema contains MdmPrimaryDimension objects, MdmSchema objects, and possibly MdmMeasure objects. In addition, the root MdmSchema has an MdmMeasureDimension that has a List of all of the MdmMeasure objects.

4.4.1 Getting the MdmDimension Objects in an MdmSchema

The following code gets a List of the MdmPrimaryDimension objects that are in rootSchema, which is the root MdmSchema. The List does not include the MdmMeasureDimension.

Example 4-3 Getting MdmDimension Objects

List dims = rootSchema.getDimensions();

4.4.2 Getting the Subschemas in an MdmSchema

The following code gets a List of MdmSchema objects that are in rootSchema.

Example 4-4 Getting Subschemas

List subSchemas = rootSchema.getSubSchemas();

4.4.3 Getting the Contents of Subschemas

For each MdmSchema that is under the root MdmSchema, you can call its getMeasures, getDimensions, and getSubSchemas methods. The procedures are the same as those for getting the contents of the root MdmSchema.

4.4.4 Getting the MdmMeasureDimension and Its Contents

Example 4-5 gets the MdmMeasureDimension that is in the root MdmSchema. Use this method only on the root MdmSchema, because only the root MdmSchema has the MdmMeasureDimension. The example displays the names of the MdmMeasure objects that are contained by the MdmMeasureDimension.

4.5 Getting the Characteristics of Metadata Objects

Having discovered the list of MdmMeasure and MdmDimension objects, the next step in metadata discovery involves finding out the characteristics of those objects.

4.5.1 Getting the MdmDimension Objects for an MdmMeasure

A primary characteristic of an MdmMeasure is that it has related MdmPrimaryDimension objects. Example 4-6 gets a List of MdmPrimaryDimension objects for mdmUnits, which is an MdmMeasure.

Example 4-6 Getting the Dimensions of an MdmMeasure

List dimsOfUnits = mdmUnits.getDimensions();

The getMeasureInfo method, which is in the Example 4-9, shows one way to iterate through the MdmPrimaryDimension objects belonging to an MdmMeasure.

4.5.2 Getting the Related Objects for an MdmPrimaryDimension

An MdmPrimaryDimension has one or more component MdmHierarchy objects, which you can obtain by calling its getHierarchies method. That method returns a List of MdmHierarchy objects. If an MdmHierarchy is an MdmLevelHierarchy, then it has levels that you can obtain by calling its getLevels method.

Example 4-7 demonstrates how you can get the MdmHierarchy objects for an MdmPrimaryDimension. The example displays the OLAP Catalog names of the MdmHierarchy objects.

Example 4-7 Getting the MdmHierarchy Components of an MdmPrimaryDimenison

The getDimInfo method in Example 4-9 shows one way to get the following metadata objects for an MdmDimension.

Its concrete class.

Its MdmHierarchy objects.

Its default MdmHierarchy object.

The MdmAttribute objects returned by its getAttributes method.

Its parent, ancestors, level, and level depth attributes.

Methods are also available for obtaining other MdmPrimaryDimension characteristics. See the Oracle OLAP Java API Reference for descriptions of all of the methods of the MDM classes.

4.6 Getting the Source for a Metadata Object

A metadata object represents a set of data, but it does not provide the ability to create queries on that data. Its function is informational, recording the existence, structure, and characteristics of the data. It does not give access to the data values.

In order to access the data values for a metadata object, an application gets the Source object for that metadata object. A Source for a metadata object is called a primary Source.

To get the primary Source for a metadata object, an application calls the getSource method of that metadata object. For example, if an application needs to display the quantity of product units sold during the year 1999, then it must use the getSource method of the MdmMeasure for that data, which is mdmUnits in the following example.

4.7 Sample Code for Discovering Metadata

The sample code that follows is a simple Java program called SampleMetadataDiscoverer10g. The program discovers the metadata objects that are under the root MdmSchema of a data store. The output of the program lists the names and related objects for the MdmMeasure and MdmDimension objects in the root MdmSchema and the MdmSchema subschema for the Global relational schema.

After presenting the program code, this topic presents the output of the program when it is run against a data store that consists of the Global relational schema. In the OLAP metadata, the Global schema is represented as the GLOBAL_CAT measure folder. Through an OLAP API connection, the GLOBAL_CAT measure folder maps to an MdmSchema whose name is GLOBAL_CAT.

4.7.1 Code for the SampleMetadataDiscoverer10g Program

The program in Example 4-9 gets the OLAP Catalog metadata objects that map to the tables and views of the Global relational schema. It passes the command line arguments that specify the server on which the Oracle Database instance is running and a user name and password to the connectToDB method of a MyConnection10g object, which establishes a connection to the database.

The code for the MyConnection10g is not shown here, but the procedure for connecting is described in Chapter 3, " Connecting to a Data Store". The complete code for the MyConnection10g and the SampleMetadataDiscoverer10g classes is available from the Overview of the Oracle OLAP Java API Reference.