Getting Primary Source Objects

How to get primary Source objects

To get a primary Source object you take the following steps:

1. Create the metadata data object for which you want to create a corresponding Source object as described in Chapter 2.

2. Use the getSource method to create a Source object from the metadata object.

Example: Getting the Source for an MdmDimension

Assume that you have browsed through the metadata of a schema, identified an MdmDimension that has time values for both the fiscal year and the calendar year, and created an object named mdmTimesDim to represent it. To get the Source for this union dimension, you use the following syntax.

Source timesDim = mdmTimesDim.getSource();

Structure of a Source created from an MdmDimension

A primary Source that you create from an MdmDimension is a specification for a simple list of elements. This kind of Source does not have any keys itself, but it usual acts as a key to other Source objects. A primary Source created from an MdmDimension is called a nondimensional Source. You can think of it as a table with only a single column that holds the values of its elements.

Example: Structure of a nondimensional Source

In "Example: Getting a primary Source for an MdmMeasure", we created a Source named timesDim from an MdmDimension named mdmTimesDim. The Source named timesDim has the same structure as mdmTimesDimCalHier that is illustrated in "Elements of a union MdmHierarchy". It consists of a simple non-indexed list of elements.

Example: Getting a primary Source for an MdmMeasure

Assume that there is an MdmMeasure for which you have created an object named mdmUnitCost. To create a primary Source named unitCost for mdmUnitCost, you use the following code:

Source unitCost = mdmUnitCost.getSource;

Structure of a Source created from a MdmMeasure or an MdmAttribute

A primary Source that you create from an MdmMeasure or an MdmAttribute is a specification for a data set that has one or more keys. Each of these keys is a primary Source that was created from a MdmDimension. In other words, this kind of Source represents a set of data that is organized by one or more primary Source objects that have been created from MdmDimension objects.

You can conceptualize a primary Source created from an MdmMeasure or an MdmAttribute as a multidimensional array. The Source objects that were created from MdmDimension objects and that act as its keys are the dimensions of the array. The values of its dimensions are indexes for identifying each particular cell in the array, which contains a single value. You must specify a value for each dimension in order to identify a value in the array. Thus, the set of elements that are in a dimensional Source is determined by the structure of the Source objects that act as its keys.

In relational terms, you can also conceptualize a Source that you create from an MdmMeasure or an MdmAttribute as a table that has one column for its elements and one column for the elements of each of the Source objects that act as its keys. A Source object that is a key to another Source is often a primary key in a table in the underlying database. Consequently, when one Source is a key to another Source, you can think of the Source that is the key as a foreign key. When a Source has foreign keys, the primary key of the Source is a composite key (or multisegmented key) that consists of its foreign keys. Each element of one Source is identified by a set of elements of the Source objects that are its foreign keys.

The Source objects that act as the keys of a dimensional primary Source are known as inputs. An input is a foreign key to a Source object for which values have not yet been specified. A Source object that has an input knows the identity and characteristics of the input Source but does not know the values of the elements of the input. As a result, when a Source has inputs, the primary keys to its elements are not fully specified and the OLAP service cannot identify the elements of the Source. Thus, the query specification represented by a Source that has an input is incomplete. Consequently, you cannot create a Cursor on a primary Source and, therefore, you cannot retrieve its values into the application. To retrieve the values represented by a dimensional primary Source, you must derive a new Source from it by specifying elements for the values of the Source objects that act as its keys as described in "Selecting Elements Based on Key Values".

Example: Structure of a dimensional Source

In "Example: Getting a primary Source for an MdmMeasure", we created a primary Source named unitCost from the MdmMeasure named mdmUnitCost. The Source named unitCost has a structure that is similar to the structure of the MdmMeasure named mdmUnitCost illustrated in "Elements of an MdmMeasure". It consists of elements that are indexed by the elements of productsDim and timesDim. The specification for the primary Source named unitCost does not include values for the Source objects that act as its keys (that is, productsDim and timesDim). In order to retrieve one or more elements of unitCost, you must specify the key values for productsDim and for timesDim that will uniquely identify the desired elements. For information on selecting key values, see "Selecting Elements Based on Key Values".