Most metadata objects have a name that you can get by calling the getName method of the object. For some objects, you can assign a name when you create the object. For example, an oracle.olapi.metadata.deployment.AW object represents an analytic workspace. When you create an AW by calling the findOrCreateAW method of an MdmDatabaseSchema, you use the publicName parameter of the method to specify a name for the AW object that the method returns.

For some objects, you can use the setName method to change the name of an existing object. For example, you can change the name of an MdmStandardDimension by calling the setName method of the dimension object. The new name does not take effect until you commit the root Transaction of the session. After you call setName, but before you commit the root Transaction, the getNewName method returns the new name while the getName method returns the existing name. For more information on getting objects by name, see "About Creating a Metadata Object or a Query in a Transaction"

You can get some objects by name from an MdmDatabaseSchema. For more information on getting objects by name, see "Representing Schemas".

For use in displaying names or descriptions in a user interface, or for any purpose you want, you can associate any number of names and descriptions with an MdmObject by using the MdmDescription class. For information on using that class, see "Using Descriptions".

Most metadata objects have a unique identifier (ID). The identifier has one of the following forms.

• objectName

• ownerName.objectName

• ownerName.containerName.objectName

For example, for the MdmDatabaseSchema that represents the schema for the user GLOBAL, the identifier returned by the getID method is GLOBAL. For an MdmPrimaryDimension named PRODUCT_AWJ, the getID method returns GLOBAL.PRODUCT_AWJ and for an MdmLevelHierarchy of that dimension named PRODUCT_PRIMARY, the method returns GLOBAL.PRODUCT_AWJ.PRODUCT_PRIMARY.

The ID of a metadata object is persistent. However, if the name or the owner of a metadata object changes, then the ID changes as well. For more information on getting objects by ID, see "Getting Metadata Objects by ID".

For a legacy 10g metadata object, the first part of the identifier is a namespace. The namespace is followed by the namespace delimiter, which is two periods. An example of the identifier of a 10g dimension is AWXML_DIMENSION..GLOBAL.PRODUCT_AW.

In Oracle Database, Release 11g, Oracle Database, Release 11g Oracle OLAP supports legacy 10g OLAP Java API applications. Namespaces identify 10g metadata objects and enable them to exist in the same session as 11g objects.

MdmStandardDimension mdmProdAWDim =
  mdmDBSchema.findOrCreateStandardDimension("PRODUCT_AW",
    MdmMetadataProvider.AWXML_DIMENSION_NAMESPACE);

Usually, you get or create metadata objects by calling findOrCreate methods on the owning object. For example, you can get or create an MdmCube by calling the findOrCreateCube method of an MdmDatabaseSchema object. However, you can also get an existing metadata object from an MdmMetadataProvider by specifying the ID of the object. The MdmMetadataProvider.getMetadataObject method takes a String that is the ID of an object and returns the object. The getMetadataObjects method takes a List of IDs and returns a List of objects.

You can store the ID of a metadata object from one session and then get the object by that ID in another session. Of course, getting an object by a stored ID assumes that the object still exists and that the ID of the object has not changed. For some metadata objects, you can change the name or the owner. If the name or owner of the object changes, then the ID of the object changes.

The MdmMetadataProvider class has many methods for exporting and importing metadata objects to and from XML definitions of those objects. The XML definition is a template from which Oracle OLAP can create the metadata objects defined.

You can use XML templates to transport metadata objects between Oracle Database instances. You can exchange XML templates between Analytic Workspace Manager and an OLAP Java API application; that is, in Analytic Workspace Manager you can import a template that you created with an MdmMetadataProvider export XML method, and you can use an importXML method to import an XML template created by Analytic Workspace Manager.

When exporting XML, you can rename objects or specify bind variables for the values of XML attributes. You can also supply an implementation of the XMLWriterCallback interface to manage some aspects of the export process. When importing XML, you can specify an MdmDatabaseSchema to own the imported objects, bind values to replace the bind variables in the exported XML, and an implementation of the XMLParserCallback interface to manage some aspects of the import process.

The following topics describe exporting and importing metadata objects through XML templates.

• Exporting XML Templates

• Importing XML Templates

• Describing Bind Variables in XML Templates

<!DOCTYPE Metadata [
<!ENTITY % BIND_VALUES PUBLIC "OLAP BIND VALUES" "OLAP METADATA">
%BIND_VALUES;
 ]>

The root schema is a container for database schema objects. This top-level schema is represented by the MdmRootSchema class. You get the MdmRootSchema with the getRootSchema method of the MdmMetadataProvider. From the MdmRootSchema you can get all of the MdmDatabaseSchema objects or you can get an individual MdmDatabaseSchema by name.

The MdmRootSchema class also contains all of the MdmCube, MdmMeasure, and MdmPrimaryDimension objects that are provided by the MdmMetadataProvider, and has methods for getting those objects. However, the List of objects returned by those methods contains only the cubes, measures, or dimensions that the user has permission to see.

Figure 2-4 shows the associations between an MdmMetadataProvider and the subclasses of MdmSchema.

The relational schema owned by a database user is represented by an MdmDatabaseSchema object.

The MdmRootSchema has one MdmDatabaseSchema object for each database user. An MdmDatabaseSchema has the same name as the database user. For example, the name of the MdmDatabaseSchema for the user GLOBAL is GLOBAL.

You can get one or all of the MdmDatabaseSchema objects with methods of the MdmRootSchema. However, access to the objects that are owned by an MdmDatabaseSchema is determined by the security privileges granted to the user of the session.

An MdmDatabaseSchema is the owner of top-level OLAP metadata objects and the objects created by them. You use an MdmDatabaseSchema to get existing metadata objects or to create new ones. The top-level objects are the following:

• AW

• MdmCube

• MdmNamedBuildProcess

• MdmOrganizationalSchema

• MdmPrimaryDimension

• MdmTable

Except for an MdmTable, you can create new top-level objects, or get existing ones, with the findOrCreate methods such as findOrCreateAW and findOrCreateStandardDimension. Creating objects is described in Discovering Metadata.

When you commit the Transaction in which you have created top-level OLAP metadata objects, those objects then exist in the Oracle data dictionary. They are available for use by ordinary SQL queries as well as for use by applications that use the Oracle OLAP Java API.

Because the metadata objects exist in the Oracle data dictionary, an Oracle Database DBA can restrict access to certain types of the metadata objects. In a client application, you can set such restrictions by using the JDBC API to send standard SQL GRANT and REVOKE commands through the JDBC connection for the user session.

You can get an MdmTable, or other top-level object, with the getTopLevelObject method. You can get all of the instances of a particular type of top-level object with methods such as getAWs, getDimensions, or getOrganizationalSchemas, or you can use the getSchemaObjects to get all of the objects owned by the MdmDatabaseSchema. You can add or remove top-level objects with methods like addAW and removeSchemaObject.

An OLAP measure folder organizes measures, cubes, and dimensions. A measure folder is represented by the MdmOrganizationalSchema class. Measure folders provide a way to differentiate among the similarly named measures. For example, a user may have access to several schemas with measures named SALES or COSTS. You could separate measures that have the same name into different MdmOrganizationalSchema objects. An MdmOrganizationalSchema has methods for adding or removing cubes, dimensions, and measures. You can nest organizational schemas, so the class also has methods for adding and removing other MdmOrganizationalSchema objects.

An OLAP cube is represented by the MdmCube class. An MdmCube is a container for MdmMeasure objects that are dimensioned by the same set of MdmPrimaryDimension objects. An application creates MdmBaseMeasure or MdmDerivedMeasure objects with the findOrCreateBaseMeasure and findOrCreateDerivedMeasure methods of an MdmCube. It associates each of the dimensions of the measures with the cube by using the addDimension method.

An MdmCube usually corresponds to a single fact table or view. To associate the table or view with the cube, you use Query and CubeMap objects. You get the Query for the table or view and then associate the Query with the CubeMap by using the setQuery method of the CubeMap.

The CubeMap contains MeasureMap and CubeDimensionalityMap objects that map the measures and dimensions of the cube to data sources. With the MeasureMap, you specify an MdmBaseMeasure and an Expression that identifies the column in the fact table or view that contains the base data for the measure.

To map the dimensions of the cube you get the MdmDimensionality objects of the cube. You create a CubeDimensionalityMap for each MdmDimensionality. You then specify an Expression for the CubeDimensionalityMap that identifies the foreign key column for the dimension in the fact table or view. If you want to specify a dimension column other than the column for the leaf-level dimension members, then you must specify a join Condition with the setJoinCondition method of the CubeDimensionalityMap.

An MdmCube has an associated CubeOrganization. The CubeOrganization deploys the cube in an analytic workspace or as a relational database object. To deploy a cube to an analytic workspace, you call the findOrCreateAWCubeOrganization method of the MdmCube. You use the AWCubeOrganization returned by that method to specify characteristics of the cube, such as how Oracle OLAP builds the cube, how the cube stores measure data, and whether the database creates materialized views for the cube. For information on the AWCubeOrganization class, see Oracle OLAP Java API Reference.

If the AWCubeOrganization has a materialized view option of REWRITE_MV_OPTION, then Oracle OLAP creates a materialized view for the cube that can be used by the database query rewrite system. If the materialized view option is REWRITE_WITH_ATTRIBUTES_MV_OPTION, then Oracle OLAP includes in the rewrite materialized view the dimension attributes for which the isPopulateLineage method returns true. You set the materialized view options with the setMVOption method of the AWCubeOrganization.

An MdmCube also has a ConsistentSolveSpecification object, which contains one or more ConsistentSolveCommand objects that specify how Oracle OLAP calculates (or solves) the values of the measures of the cube. For example, as the ConsistentSolveCommand, you could specify an AggregationCommand that represents the SUM or the MAX function. You specify the ConsistentSolveSpecification with the setConsistentSolveSpecification method of the cube.

A cube is consistent when the values of the measures match the specification, for example, when the values of the parents are equal to the SUM of the values of their children. A cube becomes consistent when the BuildProcess executes the ConsistentSolveCommand.

For examples of creating MdmCube and MdmMeasure objects and mapping them, and of the other operations described in this topic, see Example 4-7 and Example 4-8.

Figure 2-6 shows the associations between an MdmCube and the some of the classes mentioned in this topic. The figure shows an MdmCube as deployed in an analytic workspace.

An MdmMeasure is an abstract class that represents a set of data that is organized by one or more MdmPrimaryDimension objects. The structure of the data is similar to that of a multidimensional array. Like the dimensions of an array, which provide the indexes for identifying a specific cell in the array, the MdmPrimaryDimension objects that organize an MdmMeasure provide the indexes for identifying a specific value of the MdmMeasure.

For example, suppose you have an MdmMeasure that has data that records the number of product units sold to a customer during a time period and through a sales channel. The data of the measure is organized by dimensions for products, times, customers, and channels (with a channel representing the sales avenue, such as catalog or internet.). You can think of the data as occupying a four-dimensional array with the product, time, customer, and channel dimensions providing the organizational structure. The values of these four dimensions are indexes for identifying each particular cell in the array. Each cell contains a single data value for the number of units sold. You must specify a value for each dimension in order to identify a value in the array.

The values of an MdmMeasure are usually numeric, but a measure can have values of other data types. The concrete subclasses of MdmMeasure are MdmBaseMeasure and MdmDerivedMeasure.

An MdmBaseMeasure in an analytic workspace has associated physical storage structures. Typically an MdmCube gets the base data for an MdmBaseMeasure from a column in a fact table. Oracle OLAP then calculates the aggregate values of the measure and stores those values in an OLAP view for the cube.

When you create an MdmBaseMeasure, you can specify the SQL data type of the measure with the setSQLDataType method. If you do not specify it, then the MdmBaseMeasure has the data type of the source data to which you map it.

By specifying true with the setAllowAutoDataTypeChange method, you can allow Oracle OLAP to automatically set the SQL data type of the measure. This can be useful if the data type of a measure changes. If you allow the automatic changing of the SQL data type, then Oracle OLAP determines the appropriate SQL data type whether or not you have specified one with the setSQLDataType method.

An MdmDerivedMeasure has no associated physical storage. Oracle OLAP dynamically calculates the values for an MdmDerivedMeasure as needed.

The values of an MdmMeasure are determined by the structure of the MdmPrimaryDimension objects of the MdmMeasure. That is, each value of an MdmMeasure is identified by a tuple, which is a unique combination of members from the MdmPrimaryDimension objects.

The MdmPrimaryDimension objects of an MdmMeasure are MdmStandardDimension or MdmTimeDimension objects. They usually have at least one hierarchical structure. Those MdmPrimaryDimension objects include all of the members of their component MdmHierarchy objects. Because of this structure, the values of an MdmMeasure are of one or more of the following:

• Values from the fact table column, view, or calculation on which the MdmMeasure is based. These values are identified by a combination of the members at the leaf levels of the hierarchies of a dimension.

• Aggregated values that Oracle OLAP has provided. These measure values are identified by at least one member from an aggregate level of a hierarchy.

• Values specified by an Expression for a MdmDerivedMeasure or a custom dimension member.

As an example, imagine an MdmBaseMeasure that is dimensioned by an MdmTimeDimension and an MdmStandardDimension of products. The metadata objects for the measure and the dimensions are mdmUnitCost, mdmTimeDim, and mdmProdDim. Each of the mdmTimeDim and the mdmProdDim objects has all of the leaf members and aggregate members of the dimension it represents. A leaf member is one that has no children. An aggregate member has one or more children.

A unique combination of two members, one from mdmTimeDim and one from mdmProdDim, identifies each mdmUnitCost value, and every possible combination of dimension members is used to specify the entire set of mdmUnitCost values.

Some mdmUnitCost values are identified by a combination of leaf members (for example, a particular product item and a particular month). Other mdmUnitCost values are identified by a combination of aggregate members (for example, a particular product family and a particular quarter). Still other mdmUnitCost values are identified by a mixture of leaf and aggregate members.

The values of mdmUnitCost that are identified only by leaf members come directly from the column in the database fact table (or fact table calculation). They represent the lowest level of data. However, the values that are identified by at least one aggregate member are calculated by Oracle OLAP. These higher-level values represent aggregated, or rolled-up, data. Thus, the data represented by an MdmBaseMeasure is a mixture of fact table data from the data store and aggregated data that Oracle OLAP makes available for analytical manipulation.

Dimensions are represented by instances of the MdmPrimaryDimension class, which is an abstract subclass of MdmDimension. The concrete subclasses of the MdmPrimaryDimension class represent different types of data. The concrete subclasses of MdmPrimaryDimension are the following:

• MdmMeasureDimension, which has all of the MdmMeasure objects in the data store as the values of the dimension members. A data store has only one MdmMeasureDimension. You can obtain the MdmMeasureDimension by calling the getMeasureDimension method of the MdmRootSchema. You can get the measures of the data store by calling the getMeasures method of the MdmMeasureDimension.

• MdmStandardDimension, which has no special characteristics, and which typically represent dimensions of products, customers, distribution channels, and so on.

• MdmTimeDimension, which has time periods as the values of the members. Each time period has an end date and a time span. An MdmTimeDimension has methods for getting the attributes that record that information.

An MdmPrimaryDimension implements the following interfaces.

• Buildable, which is a marker interface for objects that you can specify in constructing a BuildItem.

• MdmMemberListMapOwner, which defines methods for finding or creating, or getting, a MemberListMap object.

• MdmViewColumnOwner, which is marker interface for objects that can have an associated MdmViewColumn.

• MetadataObject, which defines a method for getting a unique identifier.

• MdmQuery, which defines methods for getting the Query object associated with the implementing class and for getting information about the Query.

An MdmPrimaryDimension can have component MdmDimensionLevel objects that organize the dimension members into levels. It also can have MdmHierarchy objects, which organize the levels into the hierarchies. An MdmPrimaryDimension has all of the members of the component MdmHierarchy objects, while each of the MdmHierarchy objects has only the members in that hierarchy.

You can get all of the MdmPrimaryDimension objects that are contained by an MdmDatabaseSchema or an MdmOrganizationalSchema by calling the getDimensions method of the object. An MdmDatabaseSchema has methods for finding an MdmTimeDimension or an MdmStandardDimension by name or creating the object if it does not already exist.

MdmStandardDimension and MdmTimeDimension objects contain MdmAttribute objects. Some of the attributes are derived by Oracle OLAP, such as the parent attribute, and others you map to data in relational tables or to data that you specify by an Expression. For information on attributes, see "Representing Dimension Attributes".

An MdmPrimaryDimension can organize the dimension members into one or more levels. Each level is represented by an MdmDimensionLevel object. An MdmStandardDimension or an MdmTimeDimension can contain MdmHierarchy objects that organize the levels into hierarchical relationships. In an MdmLevelHierarchy the dimension levels are represented by MdmHierarchyLevel objects. The concrete MdmDimensionLevel and MdmHierarchyLevel classes, and the abstract MdmHierarchy class, are the direct subclasses of the abstract MdmSubDimension class.

An MdmDimensionLevel represents a set of dimension members that are at the same level. A dimension member can be in at most one dimension level. You get or create an MdmDimensionLevel with the findOrCreateDimensionLevel of an MdmPrimaryDimension. You can map an MdmDimensionLevel to a data source by using a MemberListMap.

An MdmPrimaryDimension has a method for getting a list of all of the MdmDimensionLevel objects that it contains. It also has a method for finding an MdmDimensionLevel by name or creating the object if it does not already exist.

MdmHierarchy is an abstract subclass of MdmSubDimension. The concrete subclasses of MdmHierarchy are MdmLevelHierarchy and MdmValueHierarchy.

An MdmHierarchy organizes the members of a dimension into a hierarchical structure. The parent-child hierarchical relationships of an MdmLevelHierarchy are based on the levels of the dimension. In an MdmValueHierarchy, the hierarchical relationships are based on dimension member values and not on levels. An MdmPrimaryDimension can have more than one of either or both kinds of hierarchies.

The parent of a hierarchy member is recorded in a parent MdmAttribute, which you can get by calling the getParentAttribute method of the MdmHierarchy. The ancestors of a hierarchy member are recorded in an ancestors MdmAttribute, which you can get by calling the getAncestorsAttribute method.

An MdmPrimaryDimension has a method for getting a list of all of the MdmHierarchy objects that it contains. It also has methods for finding an MdmLevelHierarchy or MdmValueHierarchy by name or creating the object if it does not already exist.

The following topics describe the objects that represent level-based and value-based hierarchies.

• Representing a Level-based Hierarchy

• Representing a Value-based Hierarchy

MdmHierarchyLevel is a subclass of MdmSubDimension. An MdmHierarchyLevel associates an MdmDimensionLevel with an MdmLevelHierarchy.

The order of the levels in the hierarchy is specified by the order in which you create the MdmHierarchyLevel objects for the MdmLevelHierarchy. The first MdmHierarchyLevel that you create is the highest level and the last one that you create is the lowest level. For an example of creating a hierarchy, see "Creating and Mapping an MdmLevelHierarchy".

The abstract MdmAttribute class has a subclass, which is the abstract class MdmSingleValuedAttribute. That class has two concrete subclasses: MdmBaseAttribute and MdmDerivedAttribute.

An MdmBaseAttribute has values that are stored in the OLAP views for the dimension that contains it and the hierarchy to which it applies. For information on OLAP views, see "Using OLAP Views".

You create an MdmBaseAttribute with the findOrCreateBaseAttribute method of an MdmPrimaryDimension. You map the MdmBaseAttribute to a column in a relational table or view. When you build the MdmPrimaryDimension that created the attribute, Oracle OLAP stores the values of the MdmBaseAttribute in an OLAP view. You can get the column for the MdmBaseAttribute in the OLAP view by using the getETAttributeColumn method. That method returns an MdmViewColumn object.

Examples of MdmBaseAttribute objects are the name attribute created and mapped in Example 4-5 and the long description attribute created in Example 4-6. The mapping for that long description attribute is in Example 4-3.

For regular OLAP queries, using Source objects, you only need to map an MdmBaseAttribute to MdmDimensionLevel objects by using MemberListMap objects. For SQL queries against OLAP views, you should map the attributes to MdmHierarchyLevel objects by using HierarchyLevelMap objects.

  mdmAttr.setPopulateLineage(true);

SELECT TOTAL_PRODUCT_SHORT_DESC || '*' || CLASS_SHORT_DESC || '*' ||
        FAMILY_SHORT_DESC || '*' || ITEM_SHORT_DESC
  FROM PRODUCT_AWJ_PRODUCT_PRIMA_VIEW
  ORDER BY TOTAL_PRODUCT nulls first, CLASS nulls first,
           FAMILY nulls first, ITEM nulls first;

TOTAL_PRODUCT_SHORT_DESC||'*'||CLASS_SHORT_DESC||'*'||FAMILY_SHORT_DESC||'*'||IT
--------------------------------------------------------------------------------
Total Product***
*Hardware**
**CD/DVD*
***External 48X CD-ROM
***External - DVD-RW - 8X
***Internal - DVD-RW - 8X
...
**Desktop PCs*
***Sentinel Financial
***Sentinel Multimedia
***Sentinel Standard
**Portable PCs*
***Envoy Ambassador
***Envoy Executive
***Envoy Standard
...

TOTAL_PRODUCT_SHORT_DESC||'*'||CLASS_SHORT_DESC||'*'||FAMILY_SHORT_DESC||'*'||IT
--------------------------------------------------------------------------------
Total Product***
Total Product*Hardware**
Total Product*Hardware*CD/DVD*
Total Product*Hardware*CD/DVD*External 48X CD-ROM
Total Product*Hardware*CD/DVD*External - DVD-RW - 8X
Total Product*Hardware*CD/DVD*Internal - DVD-RW - 8X
...
Total Product*Hardware*Desktop PCs*
Total Product*Hardware*Desktop PCs*Sentinel Financial
Total Product*Hardware*Desktop PCs*Sentinel Multimedia
Total Product*Hardware*Desktop PCs*Sentinel Standard
Total Product*Hardware*Portable PCs*
Total Product*Hardware*Portable PCs*Envoy Ambassador
Total Product*Hardware*Portable PCs*Envoy Executive
Total Product*Hardware*Portable PCs*Envoy Standard
...

An MdmDerivedAttribute has values that Oracle OLAP calculates on the fly as you need them. Oracle OLAP generates several MdmDerivedAttribute objects, such as the attributes returned by the getParentAttribute and the getAncestorsAttribute methods of an MdmPrimaryDimension.