Oracle® OLAP Developer's Guide to the OLAP API 10g Release 2 (10.2) Part Number B14347-02 |
|
|
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 information on how to get the complete code for the examples in this chapter, see the topic "Sample Schema for OLAP API Examples" in Chapter 1.
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 that 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 or the Oracle OLAP Analytic Workspace Java API Reference.
An application can create custom dimension members, which are transient metadata objects, with methods of an OLAP API MdmCustomObjectFactory
or with subclasses of MdmPrimaryDimension
. An application can create transient or permanent custom dimension members with classes in the Oracle OLAP Analytic Workspace Java API.
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 with Analytic Workspace manager or the Oracle OLAP Analytic Workspace Java API. Oracle OLAP maps those objects to MDM metadata objects in the OLAP API. 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 can 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 the Oracle OLAP Application Developer's Guide or the Oracle OLAP Analytic Workspace Java API Reference.
An application developer can create transient custom dimension member, which is a metadata object that is based on permanent metadata objects. A transient object 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 the measure 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 the members of the dimension are drawn.
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 a defining feature.
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 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 the dimensions associated with it. MdmModel
, MdmSchema
and MdmSource
are the subclasses of MdmObject
.
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".
The MdmModel
class and subclasses of it 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 5, "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 the getModel
method of the MdmDimensionedObject
. 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 is defined by the dynamic analytic workspace. 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 5, "Understanding Source Objects" and Chapter 8, "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 the 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 the dimension 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 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
has one or more component MdmHierarchy
objects, which represent the hierarchies of the dimension. 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.
An MdmPrimaryDimension
that represents a nonhierarchical list of members has only one MdmLevelHierarchy
, which has all of the 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
, the MdmLevelHierarchy
, and the 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 parent-child relationships that are 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 the 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 the 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.
The set of elements that are in an MdmMeasure
is determined by the structure of the MdmDimension
objects of the MdmMeasure
. That is, each element of an MdmMeasure
is identified by a unique combination of members from the 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 the MdmDimension
associated with it. Sometimes an MdmAttribute
does not have a value for every member of the 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 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 the set of MdmHierarchy
members that are its ancestors.
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 an attribute that relates a package to the values of some of the members at the lowest level of the hierarchy. The values of the package MdmAttribute
are null
for the aggregate Total Product, Class, and Family levels and for unassigned Item level values. In the table, null
values appear as NA
. In the first column of the table, the value does not include the PRODUCT_PRIMARY_AW
hierarchy component of the unique dimension member value.
Product Values | Related Short Descriptions | Related Package |
---|---|---|
TOTAL_PRODUCT_AW::1 |
Total Product |
NA |
CLASS_AW::2 |
Hardware |
NA |
FAMILY_AW::4 |
Portable PCs |
NA |
ITEM_AW::13 |
Envoy Standard |
Laptop Value Pack |
ITEM_AW::14 |
Envoy Executive |
Executive |
ITEM_AW::15 |
Envoy Ambassador |
NA |
FAMILY_AW::5 |
Desktop PCs |
NA |
ITEM_AW::16 |
Sentinel Standard |
NA |
ITEM_AW::17 |
Sentinel Financial |
NA |
ITEM_AW::18 |
Sentinel Multimedia |
Multimedia |
... | ... | ... |
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 the Classes That Implement It
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. The prodHier
object is the Source
for a hierarchy of the Product Dimension.
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_PRIMARY_AW::ITEM_AW::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 Year 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_YEAR_AW::MONTH_AW::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(prodHier, "PRODUCT_PRIMARY_AW::ITEM_AW::14"))) .plus( (NumberSource) (ph.join(prodHier, "PRODUCT_PRIMARY_AW::ITEM_AW::15"))); MdmStandardMember mdmItem60 = mdmProdStdDim.createCustomMember( "60", // member local value mdmItemLevel, // member level "4", // parent local value calc, // calculation Source 10); // precedence value StringSource prodSel = prodHier.selectValues( new String[]{"PRODUCT_PRIMARY_AW::ITEM_AW::14", "PRODUCT_PRIMARY_AW::ITEM_AW::15", "PRODUCT_PRIMARY_AW::ITEM_AW::60"}); Source result = unitPrice.join(unitCost) .join(prodSel) .join(calendar, "CALENDAR_YEAR_AW::MONTH_AW::47");
A Cursor
for result
has the following values, with column headings and formatting added:
Product Item Cost Price ------------------------ ------- ------- PRODUCT_PRIMARY_AW::ITEM_AW::14 3238.36 3442.86 PRODUCT_PRIMARY_AW::ITEM_AW::15 2847.47 2962.14 PRODUCT_PRIMARY_AW::ITEM_AW::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 7, "Using a TransactionProvider" and Chapter 10, "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 the elements of it 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 the getDataType
method of it. 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. The type of the object (as opposed to its data type) is another metadata object from which the metadata object draws elements. In other words, the elements of a metadata object correspond to a subset of the elements of the type object. There can be no element in the metadata object that does not match an element of the 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 mdmShipments
, 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 mdmShipments mdmTotalCust mdmRegion mdmWarehouse mdmShipTo
Because of the hierarchical structure, mdmWarehouse
(for example) derives members from the members of mdmShipments
. That is, the set of members for mdmWarehouse
corresponds to a subset of members from mdmShipments
, and mdmShipments
is the type of mdmWarehouse
.
Similarly, mdmShipments
is a component hierarchy of mdmCustDim
. Therefore, mdmShipments
derives members from mdmCustDim
, which is the type.
However, mdmCustDim
is not a component of any other object. It represents the entire dimension. The pool of elements from which mdmCustDim
derives 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 the OLAP API data type of the MdmPrimaryDimension
. Typically, this is the String data type.
The type of an MdmMeasure
is the FundamentalMetadataObject
that represents the OLAP API data type of the MdmMeasure
. 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 the getType
method of the MdmSource
. 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
. 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 prodHier
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 prodHier
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 5, "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_AW", 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 = prodHier.selectValue("PRODUCT_PRIMARY_AW::ITEM_AW::13"); StringSource timeSel = calendar.selectValues(new String[] {"CALENDAR_YEAR_AW::MONTH_AW::43", "CALENDAR_YEAR_AW::MONTH_AW::44", "CALENDAR_YEAR_AW::MONTH_AW::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_PRIMARY_AW::ITEM_AW::13, Envoy Standard, CALENDAR_YEAR_AW::MONTH_AW::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