| Oracle® OLAP Developer's Guide to the OLAP API 10g Release 2 (10.2) Part Number B14347-01 |
|
|
View PDF |
| Oracle® OLAP Developer's Guide to the OLAP API 10g Release 2 (10.2) Part Number B14347-01 |
|
|
View PDF |
This chapter describes the metadata objects that the OLAP API provides, and explains how these objects relate to the permanent OLAP metadata objects that a database administrator specifies. The chapter also describes how an application can create transient custom metadata objects.
This chapter includes the following topics:
For the complete code of the examples in this chapter, see the example programs available from the Overview of the Oracle OLAP Java API Reference.
The OLAP API provides a Java application with access to a multidimensional view of data in an Oracle database. The OLAP API design includes objects that are consistent with that view and are familiar to data warehousing and OLAP developers. For example, it has objects for measures, dimensions, hierarchies, levels, and attributes. The OLAP API design incorporates an object-oriented model called MDM (multidimensional metadata).
To make the data in an Oracle database accessible to an OLAP API application as permanent MDM objects, a database administrator must map the relational data to OLAP metadata as described in Oracle OLAP Application Developer's Guide. An application can create transient custom metadata objects.
A database administrator starts with a data warehouse that is organized according to certain specifications. For example, it might conform to a star schema. The requirements are described in Oracle OLAP Application Developer's Guide.
The administrator creates OLAP metadata objects that Oracle OLAP maps to MDM metadata objects in the OLAP API. An application developer can discover the mapping of the MDM metadata objects to the relational tables and views, or create some custom MDM metadata objects, by using MTM (metadata mapping) objects. See Chapter 5, "Working with Metadata Mapping Objects", for more information on MTM objects.
The topic "OLAP Metadata Objects" briefly describes the OLAP metadata objects that a database administrator prepares for use with Oracle OLAP.
A database administrator creates Oracle OLAP metadata objects and can create one or more measure folders that contain one or more measures. The measures have dimensions and the dimensions have hierarchies, levels, and attributes. Each of these OLAP metadata objects maps directly to an MDM object in the OLAP API. For detailed information about creating OLAP metadata or about creating an analytic workspace, see Oracle OLAP Application Developer's Guide.
An application developer can create transient custom metadata objects that are based on the permanent metadata objects. The transient objects exist only in the context of an MdmMetadataProvider during a connection to the database.
Note that the OLAP metadata includes a cube object, which does not map directly to any MDM object. Database administrators create OLAP metadata cubes to specify the dimensions of each measure. Once the dimensions are specified, they are firmly associated with their measures in the metadata, so this type of cube object is not needed in the MDM model.
The rest of this topic briefly describes the OLAP metadata objects that map directly to MDM objects in the OLAP API.
The following are some of the characteristics that a database administrator can specify for dimensions:
General characteristics, such as the name of the dimension and the database schema from which its elements are drawn. The elements of a dimension are also known as the members of the dimension.
Hierarchies, which organize the members of the dimension into parent-child relationships. A hierarchy can be level-based or value-based. In a level-based hierarchy, the parent and child members are in different levels. A level-based hierarchy can have up to 31 levels. In a value-based hierarchy, the database administrator has defined the parent and child relationships by values rather than levels. A simple, nonhierarchical list of members is represented by a hierarchy that has only one level and that has no parent-child relationships defined for the members.
Levels, which organize the members of a hierarchy into groups defined by the parent-child relationships for the hierarchy.
Attributes, which record characteristics of the members for the dimension. For example, attributes record the level of each member of a level-based hierarchy and the depth of that level in the hierarchy.
Typically, a database administrator specifies one or more columns in a database table to serve as the basis for each OLAP level, hierarchy, and attribute.
A database administrator creates cubes after creating dimensions. An OLAP metadata cube identifies a set of measures that are dimensioned by the same set of dimensions.
A database administrator specifies that a measure belongs to an OLAP metadata cube, which also specifies the set of dimensions for the measure. This is essential information for the OLAP API, where the dimensionality of a measure is one of its most important features.
To identify the data for a measure, the database administrator typically specifies a column in a fact table where the data for the measure resides. As an alternative, the database administrator can specify a calculation or transformation that produces the data.
Once a database administrator has created measures (after first creating dimensions and cubes), the next step is to create one or more groups of measures called measure folders. Typically, the measures in a given folder are related by subject matter. That is, they all pertain to the same business area. For example, there might be separate folders for financials, sales, and human resources data.
The measures in a measure folder can belong to different cubes and they can be from more than one relational schema. Measure folders can be nested, which means that a measure folder can have subfolders that have their own measures, and even their own subfolders. Thus, a database administrator can arrange measures in a hierarchy of folders, and an OLAP API MdmMetadataProvider can give access to all of the measure folders and their subfolders.
The OLAP API implementation of the MDM model is represented by classes in the oracle.olapi.metadata.mdm package. Most of the classes in this package implement metadata objects, such as dimensions and measures. Figure 2-1 introduces the subclasses of the MdmObject class.
Figure 2-1 MdmObject Class and Its Subclasses
An application gains access to metadata objects by creating an OLAP API MdmMetadataProvider and using it to discover the available metadata objects in the data store.
The Oracle OLAP metadata objects that a database administrator specifies map directly to MDM metadata objects that are accessible through the MdmMetadataProvider. The following table presents a typical mapping.
| Oracle OLAP Metadata Objects | MDM Metadata Objects |
|---|---|
| Dimension | MdmPrimaryDimension |
| Hierarchy | MdmLevelHierarchy or MdmValueHierarchy |
| Level | MdmLevel |
| Measure | MdmMeasure |
| Attribute | MdmAttribute |
| Measure folder | MdmSchema |
Some MDM metadata objects do not relate directly to OLAP metadata objects. For example, an MdmCustomObjectFactory object creates custom metadata objects, an MdmMember object represents a custom member of a dimension, or an MdmMeasure, and an MdmModel object assigns values to an MdmDimensionedObject for one or more sets of members of its dimensions.
This chapter describes the MDM metadata objects. For information about how an application discovers the available MDM metadata objects in the data store, see Chapter 4, "Discovering the Available Metadata". MTM objects record the mapping of MDM objects to relational tables or views. For information on MTM objects, see Chapter 5, "Working with Metadata Mapping Objects".
MdmModel, MdmSchema and MdmSource are the subclasses of MdmObject.
The MdmModel class and its subclasses implement the Model interface for MdmSource objects. Because a Model is closely is associated with a Source, the Model interface is in the oracle.olapi.data.source package. The Model interface is discussed in the topic "Model Objects and Source Objects" in Chapter 6, "Understanding Source Objects".
The MdmModel classes are an advanced feature of the OLAP API. When an application creates an MdmMember object, Oracle OLAP automatically creates an MdmModel for the MdmMember or adds information to an existing MdmModel object.
You can get an MdmModel for an MdmPrimaryDimension or an MdmDimensionedObject and use the MdmModel to specify the calculation of a value for a dimension member and the assignment of that value to the Source for a measure or attribute that is dimensioned by the dimension. For more information on MdmMember classes and examples of creating custom dimension members and using MdmModel objects, see "MdmMember Classes" and "Creating Custom Metadata Objects".
The subclasses of MdmModel are MdmDimensionCalculationModel and MdmDimensionedObjectModel. An MdmDimensionedObject object has an associated MdmDimensionedObjectModel that represents the assignment of zero or more values for the Source for the MdmDimensionedObject. You can get the MdmDimensionedObjectModel for an MdmDimensionedObject by calling its getModel method. The concrete subclasses of MdmDimensionedObjectModel are MdmAttributeModel and MdmMeasureModel.
An MdmDimensionCalculationModel assigns values for a measure of a particular data type. An MdmPrimaryDimension object has MdmDimensionCalculationModel objects for the OLAP API data types Boolean, Date, Number, and String. The MdmMeasureDimension subclass of MdmPrimaryDimension has a MdmDimensionCalculationModel for the Value data type, as well. You get an MdmDimensionCalculationModel for a specific data type by calling a method of an MdmPrimaryDimension, such as the getStringCalcModel method. Calling the getModel method of an MdmPrimaryDimension returns null.
The subclasses of MdmSubDimension, and the MdmStandardMember and MdmTimeMember classes, do not have associated MdmModel objects. Calling the getModel method of an MdmSubDimension, MdmStandardMember, or MdmTimeMember returns null.
An MdmSchema represents a set of data that is used for navigational purposes. It is a container for MdmMeasure, MdmPrimaryDimension, and other MdmSchema objects. An MdmSchema is equivalent to a folder or directory that contains associated items. It does not correspond to a relational schema in the Oracle database. Instead, it corresponds to an Oracle OLAP measure folder, which can include data from several relational schemas and which was created by a database administrator. You can create a custom MdmSchema with the createSchema method of an MdmCustomObjectFactory.
Data that is accessible through the OLAP API is arranged under a top-level MdmSchema, which is referred to as the root MdmSchema. Under the root schema, there can be one or more subschemas. To begin navigating the metadata, an application calls the getRootSchema method of the MdmMetadataProvider, as explained in Chapter 4, "Discovering the Available Metadata".
The root MdmSchema contains all of the MdmDimension objects that are in the data store. Most MdmPrimaryDimension objects are also contained in subschemas under the root MdmSchema. However, a data store can contain a dimension that is not included in a subschema. The root MdmSchema contains all of the available dimension objects, including those that are in subschemas as well as any dimension objects that are not.
The root MdmSchema contains MdmMeasure objects only if they are not contained in a subschema. Because most MdmMeasure objects belong to a subschema, the root MdmSchema typically has no MdmMeasure objects. Therefore, the getMeasures method of the root MdmSchema typically returns an empty List object.
An MdmSchema has methods for getting all of the MdmMeasure, MdmPrimaryDimension, and MdmSchema objects that it contains. The root MdmSchema also has a method for getting the MdmMeasureDimension, whose members are all of the MdmMeasure objects in the data store regardless of whether they belong to a subschema.
MdmSource objects represent data that is available to an application. With the getSource method of an MdmSource, an application gets a Source object that it can use to create a query. The following line of code gets the Source for an MdmStandardDimension called mdmProductDim.
Source productDim = mdmProductDim.getSource();
A Source that is the result of the getSource method of an MdmSource is called a primary Source. An application derives new Source objects from this primary Source as it selects, calculates, and otherwise manipulates the data. When the application derives a Source that represents the query that it wants to make, it creates a Cursor for the Source. The Cursor retrieves the data.
For more information about working with Source and Cursor objects, see Chapter 6, "Understanding Source Objects" and Chapter 9, "Understanding Cursor Classes and Concepts". The rest of this chapter describes the subclasses of MdmSource.
MdmDimension is an abstract subclass of MdmSource that represents the general concept of a list of members that can organize a set of data. For example, if you have a set of figures that are the prices of product items during month time periods, then the unit price data is represented by an MdmMeasure that is dimensioned by dimensions for time and product values. The time dimension includes the month values and the product dimension includes item values. The month and item values act as indexes for identifying each particular value in the set of unit price data.
An MdmDimension can have one or more MdmAttribute objects. An MdmAttribute maps the value of each member of the MdmDimension to a value representing some characteristic of the member value. To obtain the MdmAttribute objects for an MdmDimension, call its getAttributes method or the methods that return specific attributes, such as the getHierarchyAttribute or the getParentAttribute method.
MdmDimension has the abstract subclasses MdmPrimaryDimension and MdmSubDimension.
MdmPrimaryDimension 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 its members. A data store has only one MdmMeasureDimension. You can obtain the MdmMeasureDimension by calling the getMeasureDimension method of the root MdmSchema and casting the result to an MdmMeasureDimension. 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 its 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 has one or more component MdmHierarchy objects, which represent the hierarchies of the dimension. An MdmPrimaryDimension has all of the members of its component MdmHierarchy objects, while each of its MdmHierarchy objects has only the members in that hierarchy.
An MdmPrimaryDimension that represents a nonhierarchical list of members has only one MdmLevelHierarchy, which has all of its members at one level with no hierarchical relationships defined for them. For example, the MdmMeasureDimension represents a dimension that is simple list of the MdmMeasure objects in the data store. The MdmMeasureDimension has one MdmLevelHierarchy, which has one MdmLevel. The MdmMeasureDimension, its MdmLevelHierarchy, and its MdmLevel all have the same dimension members, the values of which are the MdmMeasure objects.
MdmSubDimension is an abstract subclass of MdmDimension. The subclasses of MdmSubDimension are MdmHierarchy and MdmLevel.
MdmHierarchy is an abstract subclass of MdmSubDimension. An MdmHierarchy represents an organization of the members of an MdmPrimaryDimension, which can have more than one hierarchy defined for it. For example, an MdmTimeDimension dimension might have two hierarchies, one organized by calendar year time periods and the other organized by fiscal year time periods. The members of both hierarchies are drawn from the members of the MdmTimeDimension, but the number of members in each hierarchy and the parent-child relationships of the values of the members can be different.
The parent-child relationships of an MdmHierarchy are recorded in a parent MdmAttribute, which you can get by calling the getParentAttribute method of the MdmHierarchy. The ancestor-descendent relationships are specified in an ancestors MdmAttribute, which you can get by calling the getAncestorsAttribute method.
MdmLevelHierarchy is a concrete subclass of MdmHierarchy. An MdmLevelHierarchy has its parent-child relationships defined between the values of the members at different levels. The different levels of an MdmLevelHierarchy are represented by MdmLevel objects. An MdmLevelHierarchy can have up to 31 component MdmLevel objects. An MdmLevelHierarchy has a tree-like structure. The members at the lowest level of the hierarchy are the leaves, and the members at higher levels are nodes. Nodes have children; leaves do not.
The MdmLevelHierarchy has all of the members of the hierarchy, and each of its component MdmLevel objects has only the members at the level it represents. Each member, except those at the highest level, can have a parent, and each member, except those at the lowest level, can have one or more children. The parent and children of a member of an MdmLevel are in other MdmLevel objects. An MdmLevelHierarchy can also represent a nonhierarchical list of members, in which case the MdmLevelHierarchy has one MdmLevel, and both objects have the same members. You get the levels of an MdmLevelHierarchy by calling its getLevels method.
MdmValueHierarchy is the other concrete subclass of MdmHierarchy. An MdmValueHierarchy has parent-child relationships defined between the values of the dimension members, and does not have the parent and child members at different levels. An example of a value hierarchy is the employee reporting structure of a company, which can be represented with parent-child relationships but without levels. A database administrator defines a dimension as a value hierarchy in the Oracle OLAP metadata. An application developer can define a value hierarchy with the createValueHierarchy method of an MdmCustomObjectFactory or an MdmPrimaryDimension.
MdmLevel is a concrete subclass of MdmSubDimension. An MdmLevel represents a set of members that supply one level of the hierarchical structure of an MdmLevelHierarchy.
An MdmLevel represents a level that was specified by a database administrator in the OLAP metadata or that is a custom MdmLevel. Typically, a database administrator specifies a column in a relational database table or view to provide the values of the level, or an application specifies a column in an MtmExpression. The values of the members of an MdmLevel must be unique. If the column in the database has values that are not unique, then the database administrator can define the members of a level using two or more columns of the table, thus ensuring that the members of the MdmLevel have unique values. For example, if a dimension of geographical locations has a level for cities and more than one city has the same name, then a database administrator can specify as the value of the city level both the city column and the state column in the relational database. The values of the members in the MdmLevel for cities are then combinations of the two column values, such as IL:Springfield for Springfield, Illinois and MA:Springfield for Springfield, Massachusetts.
An MdmLevelHierarchy has one MdmLevel for each level of members in the hierarchy of dimension members that it represents. Each member of an MdmLevel, except the highest level, can have a parent, and each member, except those of the lowest level, can have one or more children. The parent and children of members of one MdmLevel are members from other MdmLevel objects.
The parent-child relationships among the members are recorded in the parent and ancestors attributes, which you can obtain by calling the getParentAttribute and getAncestorsAttribute methods of the MdmLevelHierarchy of which the MdmLevel is a component. You can get the MdmLevelHierarchy for the MdmLevel by calling the getLevelHierarchy method of the MdmLevel.
MdmDimensionedObject is an abstract subclass of MdmSource that represents objects the values of which are specified by members of one or more dimensions. The subclasses of MdmDimensionedObject are MdmMeasure and MdmAttribute.
An MdmMeasure represents a set of data that is organized by one or more MdmDimension 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 MdmDimension objects that organize an MdmMeasure provide the indexes for identifying a specific value of an element 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 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, which contains a single units sold data value. You must specify a value for each dimension in order to identify a value in the array. In relational terms, the MdmDimension objects constitute a compound (that is, composite) primary key for the MdmMeasure.
The values of an MdmMeasure are usually numeric, but a measure can have values of other data types.
A persistent MdmMeasure is based on an OLAP metadata measure that was created by a database administrator. In most cases, the MdmMeasure maps to a column in a fact table or to an expression that specifies a mathematical calculation or a data transformation. In many but not all cases, the MdmMeasure also maps to at least one hierarchy for each OLAP dimension of the measure, as well as an aggregation method. Oracle OLAP uses all of this information to identify the number of elements in the MdmMeasure and the value of each element.
An application can create a transient custom MdmMeasure, and make it a member of the MdmMeasureDimension, by calling a createCustomMeasure method of the MdmMeasureDimension or a method of MdmCustomObjectFactory.
The set of elements that are in an MdmMeasure is determined by the structure of its MdmDimension objects. That is, each element of an MdmMeasure is identified by a unique combination of members from its MdmDimension objects. That combination of dimension members is called a tuple.
The MdmDimension 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 the elements 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 belong to MdmMeasure elements that are identified by a combination of values from the members at the leaf level of an MdmHierarchy.
Aggregated values that Oracle OLAP has provided. These values belong to MdmMeasure elements that are identified by the value of at least one member from a node level of an MdmHierarchy.
Values assigned by an MdmModel for a custom dimension member.
As an example, imagine an MdmMeasure called mdmUnitCost that is dimensioned by an MdmTimeDimension called mdmTimeDim and an MdmStandardDimension of products called mdmProdDim. Each of the mdmTimeDim and the mdmProdDim objects has all of the leaf members and node members of the dimension it represents.
A unique combination of two members, one from mdmTimeDim and one from mdmProdDim, identifies each mdmUnitCost element, and every possible combination is used to specify the entire mdmUnitCost element set.
Some mdmUnitCost elements are identified by a combination of leaf members (for example, a particular product item and a particular month). Other mdmUnitCost elements are identified by a combination of node members (for example, a particular product family and a particular quarter). Still other mdmUnitCost elements are identified by a mixture of leaf and node members. The values of the mdmUnitCost elements 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, for the elements that are identified by at least one node member, Oracle OLAP provides the values. These higher-level values represent aggregated, or rolled-up, data.
Thus, the data represented by an MdmMeasure is a mixture of fact table data from the data store, aggregated data that Oracle OLAP makes available for analytical manipulation, and possibly values that Oracle OLAP assigns as specified by an MdmModel.
MdmAttribute is a concrete subclass of MdmDimensionedObject that represents a particular characteristic of the members of an MdmDimension. An MdmAttribute maps a member of the MdmDimension to a particular value.
For example, mdmCustDim is the MdmPrimaryDimension for the Customer dimension. The MdmPrimaryDimension has a hierarchy that has levels that are based on shipment origination and destination values. The MdmAttribute returned by the getShortValueDescriptionAttribute method of mdmCustDim relates a short description to each the member of the dimension. The elements of the MdmAttribute have String values such as Europe, Italy, or Computer Services Athens.
The elements of an MdmAttribute might have String values (such as Italy), numeric values (such as 45), or objects (such as MdmLevel objects).
Like an MdmMeasure, an MdmAttribute has elements that are organized by its MdmDimension. Sometimes an MdmAttribute does not have a value for every member of its MdmDimension. For example, an MdmAttribute that records the name of a contact person might have values only for the Ship To and Warehouse levels of the Shipments Rollup hierarchy of the mdmCustDim dimension, because contact information does not apply to the higher Region and All Customers levels. If an MdmAttribute does not apply to a member of an MdmDimension, then the MdmAttribute element value for that member is null.
An MdmAttribute object can provide a mapping that is one-to-many, rather than one-to-one. Therefore, a member in an MdmDimension might map to a whole set of MdmAttribute elements. For example, the MdmAttribute that serves as the ancestors attribute for an MdmHierarchy maps each MdmHierarchy member to its set of ancestor MdmHierarchy members.
An MdmAttribute is based on an OLAP attribute that was specified for a dimension, hierarchy, or level by a database administrator or that was specified by an MtmValueExpression for a custom MdmAttribute created by an application.
The following table lists the values of elements of a Source object that represents the members of a hierarchy of an MdmPrimaryDimension of products. The table also lists the values of the Source objects for two MdmAttribute objects that are dimensioned by the MdmPrimaryDimension. One attribute is the short description attribute for the dimension. Each member of the dimension has a related short description. The other is a custom attribute that relates a color to the values of members at the Item level, which is the lowest level of the hierarchy. The values of the color MdmAttribute are null for the aggregate Total Product, Class, and Family levels. In the table, null values appear as NA.
| Product Values | Related Short Descriptions | Related Colors |
|---|---|---|
PRODUCT_ROLLUP::TOTAL_PRODUCT::1 |
Total Product |
NA |
PRODUCT_ROLLUP::CLASS::2 |
Hardware |
NA |
PRODUCT_ROLLUP::FAMILY::4 |
Portable PCs |
NA |
PRODUCT_ROLLUP::ITEM::13 |
Envoy Standard |
Black |
PRODUCT_ROLLUP::ITEM::14 |
Envoy Executive |
Black |
PRODUCT_ROLLUP::ITEM::15 |
Envoy Ambassador |
Black |
PRODUCT_ROLLUP::FAMILY::5 |
Desktop PCs |
NA |
PRODUCT_ROLLUP::ITEM::16 |
Sentinel Standard |
Beige |
PRODUCT_ROLLUP::ITEM::17 |
Sentinel Financial |
Beige |
PRODUCT_ROLLUP::ITEM::18 |
Sentinel Multimedia |
Beige |
| ... | ... | ... |
MdmMember is an interface that specifies characteristics of a custom dimension member. Figure 2-2 shows the classes that implement the interface.
Figure 2-2 MdmMember Interface and Its Implementations
You can add a custom member to an MdmStandardDimension or an MdmTimeDimension by calling a createStandardCustomMember method or a createTimeCustomMember method of an MdmCustomObjectFactory. You can also use one of the addCustomMember convenience methods of the MdmStandardDimension or the MdmTimeDimension.
You can create an MdmMeasure and add it as a custom member of the MdmMeasureDimension by calling a createCustomMeasure method of an MdmCustomObjectFactory. You can also use one of the createCustomMeasure convenience methods of the MdmMeasureDimension.
When you create a custom member, you specify a Source that provides the value that Oracle OLAP assigns as the measure or attribute value for the custom member. That Source can specify a constant value or it can specify a calculation to perform. Custom dimension members are therefore Source-based dimension members, in that the measure or attribute value that Oracle OLAP assigns for the custom member is provided by the Source that the application supplies. The measure or attribute values specified by other members of a dimension, which are not instances of MdmMember, are not based on a Source but instead are mapped to data derived from columns in tables or views in the database.
Example 2-1 creates a custom member of the Product dimension. The measure value specified for the custom member is the result of a calculation.
In the example, dp is the DataProvider. The example gets the placeholder Source, ph, for the Number data type from the DataProvider. If a query specifies the values for more than one measure that is dimensioned by the Product dimension, then the placeholder Source represents the current measure in the query.
The example uses the placeholder in defining the calculation object, calc. The calculation object defines the value assigned for the custom member as the value specified by product item 14 plus the value specified by item 15.
In the createCustomMember method call, the local value of the custom dimension member is 60. In creating the custom member, Oracle OLAP supplies the other parts of the unique value. The unique value for the member is PRODUCT_ROLLUP::ITEM::60. The itemLevel object is the MdmLevel for the custom member. The local value of the parent of the custom member is 4. The calc object is the value that Oracle OLAP assigns for the member as the measure value for a measure dimensioned by the Product dimension, and 10 is the precedence value for the custom member.
The prodSel object specifies the dimension members for items 14 and 15 and the custom member, item 60. The unitCost and unitPrice objects are Source objects for the Unit Cost and Unit Price measures, and the calendar object is the Source for the Calendar hierarchy of the Time dimension.
The result object is the query produced by joining the Source objects for the Unit Cost and Unit Price price measures to the Source objects for the selected members of the dimensions of the measures. The join method used to join the Time dimension value, CALENDAR::MONTH::47, to the result of the previous join operations causes the Time value to not appear in the result object.
Example 2-1 Creating a Custom Member of a Dimension
Source ph = dp.getFundamentalMetadataProvider()
.getNumberPlaceholder()
.getSource();
Source calc = ((NumberSource)
(ph.join(prodRollup, "PRODUCT_ROLLUP::ITEM::14")))
.plus(
(NumberSource)
(ph.join(prodRollup, "PRODUCT_ROLLUP::ITEM::15")));
MdmStandardMember mdmItem60 = mdmProdStdDim.createCustomMember(
"60", // member local value
mdmItemLevel, // member level
"4", // parent local value
calc, // calculation Source
10); // precedence value
StringSource prodSel = prodRollup.selectValues(
new String[]{"PRODUCT_ROLLUP::ITEM::14",
"PRODUCT_ROLLUP::ITEM::15",
"PRODUCT_ROLLUP::ITEM::60"});
Source result = unitPrice.join(unitCost)
.join(prodSel)
.join(calendar, "CALENDAR::MONTH::47");
A Cursor for result has the following values, with column headings and formatting added:
Product Item Cost Price ------------------------ ------- ------- PRODUCT_ROLLUP::ITEM::14 3238.36 3442.86 PRODUCT_ROLLUP::ITEM::15 2847.47 2962.14 PRODUCT_ROLLUP::ITEM::60 6085.83 6405.00
For an example of creating a custom MdmMeasure as a member of an MdmMeasureDimension, see Example 2-4.
Like Template objects, custom dimension members exist in the context of a Transaction. Also, custom members are not persistent; they are not stored in the database after the application closes the DataProvider. For information on the Transaction and Template classes, see Chapter 8, "Using a TransactionProvider" and Chapter 11, "Creating Dynamic Queries".
Custom members can only be used by the OLAP API application. They are not available to an OLAP DML or SQL application.
All MdmSource objects have the following two basic characteristics:
Data type
Type
MdmDimensionCalculationModel objects also have a data type and a type. MdmDimensionedObjectModel objects have a type but not a data type.
The concept of data type is a familiar one in computer languages and database technology. It is common to categorize data into types such as integer, Boolean, and String.
The OLAP API implements the concept of data type through the FundamentalMetadataObject and FundamentalMetadataProvider classes. Every data type recognized by the OLAP API is represented by a FundamentalMetadataObject, and you obtain this object by calling a method of a FundamentalMetadataProvider.
The following table lists the most familiar OLAP API data types. For each data type, the table presents a description of the FundamentalMetadataObject that represents the data type and the name of the method of FundamentalMetadataProvider that returns the object. The OLAP API data types appear in regular typeface, instead of monospace typeface, to distinguish them from java.lang data type classes.
In addition to these familiar data types, the OLAP API includes two generalized data types (which represent groups of the familiar data types) and two data types that represent the absence of values. The following table lists these additional data types.
When an MDM metadata object, such as an MdmMeasure, has a given data type, this means that each of its elements conforms to that data type. If the data type is numeric, then the elements also conform to the generalized Number data type, as well as to the specific data type (Double, Float, Integer, or Short). The elements of any MDM metadata object conform to the Value data type, as well as to their more specific data type, such as Integer or String.
If the elements of an object represent a mixture of several numeric and non-numeric data types, then the data type is only Value. The object has no data type that is more specific than that.
The MDM metadata objects for which data type is relevant are MdmDimensionCalculationModel objects and MdmSource objects, such as MdmMeasure, MdmLevelHierarchy, and MdmLevel. The typical data type of an MdmMeasure is one of the numeric data types; the data type of an MdmLevelHierarchy or MdmLevel is always String.
An MdmPrimaryDimension has a set of MdmDimensionCalculationModel objects, each of which has a different data type. If an MdmDimensionCalculationModel has an Assignment, then Oracle OLAP assigns the specified value to measures that have the same data type as the MdmDimensionCalculationModel. For example, the data type of the MdmDimensionCalculationModel returned by the getNumberCalcModel method of an MdmStandardDimension is the FundamentalMetadataObject for the Number data type. An Assignment specified by that MdmDimensionCalculationModel applies only to a measure that has a Number data type and that is dimensioned by the MdmStandardDimension.
To find the data type of an MdmSource or MdmDimensionCalculationModel, call its getDataType method. That method returns a FundamentalMetadataObject.
To find the OLAP API data type that is represented by the returned FundamentalMetadataObject, you could compare it to the FundamentalMetadataObject for each OLAP API data type. That is, you compare it to the return value of each of the data type methods in FundamentalMetadataProvider.
The following sample method returns a String that indicates the data type of an MdmSource. Note that this code gets the FundamentalMetadataProvider by calling a method of a DataProvider. Getting a DataProvider is described in Chapter 4, "Discovering the Available Metadata".
Example 2-2 Getting the Data Type of an MdmSource
public String getDataType(DataProvider dp, MdmSource metaSource)
{
String theDataType = null;
FundamentalMetadataProvider fmp =
dp.getFundamentalMetadataProvider();
if (fmp.getBooleanDataType() == metaSource.getDataType())
theDataType = "Boolean";
else if (fmp.getDateDataType() == metaSource.getDataType())
theDataType = "Date";
else if (fmp.getDoubleDataType() == metaSource.getDataType())
theDataType = "Double";
else if (fmp.getFloatDataType() == metaSource.getDataType())
theDataType = "Float";
else if (fmp.getIntegerDataType() == metaSource.getDataType())
theDataType = "Integer";
else if (fmp.getShortDataType() == metaSource.getDataType())
theDataType = "Short";
else if (fmp.getStringDataType() == metaSource.getDataType())
theDataType = "String";
else if (fmp.getNumberDataType() == metaSource.getDataType())
theDataType = "Number";
else if (fmp.getValueDataType() == metaSource.getDataType())
theDataType = "Value";
return theDataType;
}
An MDM metadata object, such as an MdmSource, is a collection of elements. Its type (as opposed to its data type) is another metadata object from which the metadata object draws its elements. In other words, the elements of a metadata object correspond to a subset of the elements in its type. There can be no element in the metadata object that does not match an element of its type.
Consider the following example of a MdmPrimaryDimension called mdmCustDim, which has the OLAP API data type of String. The mdmCustDim dimension has a hierarchy, which is an MdmLevelHierarchy object called mdmShipmentsRollup, which in turn has levels, which are MdmLevel objects. The MdmLevelHierarchy and the MdmLevel objects represent subsets of the members of the MdmPrimaryDimension. In the following list, the hierarchy and the levels are indented under the MdmPrimaryDimension to which they belong.
mdmCustDim
mdmShipmentsRollup
mdmTotalCust
mdmRegion
mdmWarehouse
mdmShipTo
Because of the hierarchical structure, mdmWarehouse (for example) draws its members from the members of mdmShipmentsRollup. That is, the set of members for mdmWarehouse corresponds to a subset of members from mdmShipmentsRollup, and mdmShipmentsRollup is the type of mdmWarehouse.
Similarly, mdmShipmentsRollup is a component hierarchy of mdmCustDim. Therefore, mdmShipmentsRollup draws its members from mdmCustDim, which is its type.
However, mdmCustDim is not a component of any other object. It represents the entire dimension. The pool of elements from which mdmCustDim draws its members is the entire set of possible String values. Therefore, the type of mdmCustDim is the FundamentalMetadataObject that represents the OLAP API String data type. In the case of mdmCustDim, the type and the data type are the same.
The following list presents the types that are typical for the most common MdmSource objects:
The type of an MdmLevel is the MdmLevelHierarchy to which it belongs.
The type of a MdmHierarchy is the MdmPrimaryDimension to which it belongs.
The type of an MdmPrimaryDimension is the FundamentalMetadataObject that represents its OLAP API data type. Typically, this is the String data type.
The type of an MdmMeasure is the FundamentalMetadataObject that represents its OLAP API data type. Typically, this is one of the OLAP API numeric data types.
An MdmModel also has a type, which is the Source from which Oracle OLAP draws the values that the MdmModel assigns. For example, the type of the MdmDimensionedObjectModel for the MdmAttribute for the short value description attribute of the Product dimension is the Source for the FundamentalMetadataObject for the String data type because the values of that attribute are String objects.
To find the type of an MdmSource that you have obtained from the data store, call its getType method. That method returns the object that is the type of the MdmSource object.
For example, the following Java statement obtains the type of the MdmLevel named mdmWarehouse.
An application developer can create transient custom metadata objects with methods of an MdmCustomObjectFactory or with convenience methods of the subclasses of MdmPrimaryDimension, or with methods of an MdmLevelHierarchy or an MtmPartitionedCube. The custom metadata objects exist in the context of a Transaction.
Example 2-4 demonstrates the creation of a custom MdmMeasure as a member of the MdmMeasureDimension of the root MdmSchema. The example gets the root MdmSchema from the MdmMetadataProvider, gets the top-level MdmMeasureDimension from root MdmSchema, and then gets the Source for the MdmMeasureDimension, cast as a StringSource.
Next, the example creates a Source, calculation, that specifies the values for the custom measure. The values are the result of the calculation unit price minus unit cost. The unitPrice and unitCost objects are the Source objects for the Unit Price and Unit Cost measures.
The createCustomMeasure method of the MdmMeasureDimension returns an MdmMeasure that has the name MARKUP, is a member of the root MdmSchema, has the calculation specified, and has the precedence value of 10.
The selectValues method of the Source for the MdmMeasureDimension returns a Source that specifies the identification String objects for each measure. For example, the ID of the custom measure is Hidden..CUSTOM_MEASURES.MARKUP. The example gets the short value description attributes for the Time and Product dimensions, and then gets the Source objects for those attributes.
The prodRollup object is the Source for a hierarchy of the MdmPrimaryDimension for the Product dimension, and calendar is a hierarchy of the MdmPrimaryDimension for the Time dimension. The selectValue method of prodRollup returns a Source that specifies one member of the Product hierarchy, and the selectValues method of calendar returns a Source that specifies three members of the Time hierarchy.
The extract method of measDim produces a Source that specifies the values of the Source objects that are the element values of measDim. The first join method provides Source objects that match the inputs of the Source produced by the extract method. The next two join methods add the short value description attribute for the Time dimension members and provide the input required by the attribute. The final two join methods do the same for the Product dimension members. For more information about Source objects and the inputs of a Source, see Chapter 6, "Understanding Source Objects".
Example 2-4 Creating a Custom Member of the MdmMeasureDimension
MdmSchema rootSchema = mdmMetadataProvider.getRootSchema();
MdmMeasureDimension mdmMeasDim = rootSchema.getMeasureDimension();
StringSource measDim = (StringSource) mdmMeasDim.getSource();
Source calculation = unitPrice.minus(unitCost);
MdmMeasure mdmMarkup = mdmMeasDim.createCustomMeasure("MARKUP",
rootSchema,
calculation,
10);
Source measDimSel = measDim.selectValues(new String[]
{mdmMarkup.getValue(),
mdmUnitPrice.getValue(),
mdmUnitCost.getValue()});
Source timeShortDesc =
mdmTimeDim.getShortValueDescriptionAttribute().getSource();
Source prodShortDesc =
mdmProdDim.getShortValueDescriptionAttribute().getSource();
StringSource prodSel = prodRollup.selectValue("PRODUCT_ROLLUP::ITEM::13");
StringSource timeSel = calendar.selectValues(new String[]
{"CALENDAR::MONTH::43",
"CALENDAR::MONTH::44",
"CALENDAR::MONTH::45"});
Source result = measDim.extract()
.join(measDimSel)
.join(timeShortDesc.join(timeSel))
.join(prodShortDesc.join(prodSel));
A Cursor for the result object has nine sets of values. Each set has the product member value and short value description, the time member value and short value description, the ID of the measure, and the measure value specified by the product and time members. The first set of values is the following:
PRODUCT_ROLLUP::ITEM::13, Envoy Standard, CALENDAR::MONTH::43, Jan-00, Hidden..CUSTOM_MEASURES.MARKUP, 134.24
The following is a display of the values of a Cursor for result in a crosstab format that has only the description and measure values and that has column headings added.
Product: Envoy Standard Month Unit Cost Unit Price Markup ------ --------- ---------- ------ Jan-00 2865.87 3000.11 134.24 Feb-00 2862.51 3008.91 146.40 Mar-00 2926.79 3142.99 216.20
