Creating Source Objects

Making queries using the OLAP API is a process that involves creating a number of different Source objects. This process is outlined below:

1. Create Source objects that correspond to metadata objects as described in "Getting Source Objects From Metadata Objects". These Source objects, sometimes called primary Source objects, have a structure that is similar to the metadata objects from which they are created.
2. Begin your querying by calling methods on the primary Source objects. The methods of the Source class and its subclasses return new Source objects sometimes called derived Source objects. Continue your analysis by deriving additional Source objects until you have the results you want to retrieve the data into your program. Derived Source object and the methods that create them are introduced in "Creating New Source Objects Using Source Methods" and documented in detail in the OLAP API Javadoc. Task-oriented discussions of how to use Source methods to make selections and perform typical analytic operations are provided in Chapter 6, "Making Queries Using Source Methods".

   As part of the query process, you might also create simple nondimensional Source object to use as operands when making selections and calculations and Source objects that represent OLAP API data types. How to create these types of Source objects is discussed in more detail in"Creating Simple Nondimensional Source Objects" and "Creating Source Objects that Represent OLAP API Data Types".

3. When you want to retrieve the data set represented by a Source object, create a Cursor for it as described in Chapter 9, "Retrieving Query Results".

Getting Source Objects From Metadata Objects

To get a Source object from a metadata object, 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.

Creating a Source from MdmDimension, MdmHierarchy, or MdmLevel Objects

A Source that you create by using the calling the getSource method on a MdmDimension, an MdmHierarchy, or an MdmLevel does not have any inputs or outputs. It is a specification for a simple list of values.

In "Level MdmHierarchy for Calendar Year" , we created an MdmHierarchy named mdmTimesDimCalHier. To create a Source named timesDimCalHier from mdmTimesDimCalHier, you use code shown in Example 5-1.

Example 5-1 Getting a Source for an MdmHierarchy

Source timesDimCalHier = mdmTimesDimCalHier.getSource;

The Source named timesDimCalHier consists of a simple non-indexed list of 1529 values: 4 values for year, 16 values for quarters, 48 values for months, and 1461 values for days.

timesDimCalHier values
1998
1998-Q1
1998-01
01-JAN-98
02-JAN-98
03-JAN-98
...
1998-Q2
1998-04
01-APR-98
. . .
1999
...

Creating a Source from MdmMeasure or MdmAttribute Objects

A Source that you create by calling the getSource method on a MdmMeasure or an MdmAttribute is a specification for a data set that has one or more inputs. Each of these inputs is a primary Source that was created from a MdmDimension. Thus, the specification for a set of data represented by a Source that you create from an MdmMeasure or an MdmAttribute is incomplete. Consequently, you cannot create a Cursor on these Source objects to retrieve their values into the application. To retrieve the values of a Source created from a MdmMeasure or an MdmAttribute, you must derive a new Source from it by specifying values for the values of the Source objects that act as its dimensions as described in "Selecting Based on Output Values".

In "MdmMeasure with two MdmDimension objects" , we created an MdmMeasure named mdmUnitCost. To create a Source named unitCost from mdmUnitCost, you use code shown in Example 5-2.

Example 5-2 Getting a Source for an MdmMeasure

Source unitCost = mdmUnitCost.getSource;

Since mdmUnitCost has mdmProductsDim and mdmTimesDim as its MdmDimension objects, unitCost has two inputs (productsDim and timesDim). In order to retrieve one or more values of unitCost, you must specify the values for its inputs (productsDim and for timesDim) that will uniquely identify the values of unitCost. For information on specifying values for inputs, see "Selecting Based on Output Values".

Creating New Source Objects Using Source Methods

Most OLAP queries derive new Source objects from existing Source objects using the methods in the Source class.

Table 5-1 outlines the most important Source methods in the OLAP API.

Table 5-3  The Major Source Methods

Method	Description
join	The single most important Source creation method in the OLAP API. The join method creates a new Source by combining the values of the base Source and another Source (called the joined Source) and filtering this set of data using a third Source (called the comparison Source) in the specified manner. Using an optional parameter, you can also use the join method to add the joined Source as n output to the new Source.
alias	Creates a new Source object that is the same as the base Source object, but that has the base Source as its type.
distinct	Creates a new Source object that is the same as the base Source object, but that has all duplicate rows (tuples) removed.
position	Creates a new Source object with the same structure as the base Source and whose values are the position of the values of the base Source.
value	Creates a new Source object that has the values of the base Source and that has the base Source as an input.

The OLAP API provides various other methods that you can use instead of the methods listed in Table 5-3, " The Major Source Methods". These methods include variations on the join method, as well as methods such as appendValue, at, cumulativeInterval, first, ge, interval, selectValues, and sortAscending. All of these methods are documented in the OLAP API Javadoc. For task-oriented discussions on using these methods to analyze your data, see Chapter 6, "Making Queries Using Source Methods".

Creating Simple Nondimensional Source Objects

You create simple nondimensional Source objects which are not based on metadata objects or other Source objects that you can use as operands by using the createConstantSource, createListSource, and createRangeSource methods on the DataProvider class. These Source objects are sometimes referred to as constant, list, and range Source objects.

Assume that you have an object named myDataProvider that represents the DataProvider used by your application and that, for computational purposes, you want a Source with a single value of 4. To create this Source you issue the code shown in Example 5-3

Example 5-3 Creating a Constant Source

NumberSource myConstantFour = myDataProvider.createConstantSource(4);

Creating Source Objects that Represent OLAP API Data Types

You can retrieve the objects that represent the OLAP API data types using methods on the FundamentalMetadataProvider. Each of these methods returns a FundamentalMetadataObject. The OLAP API data types and the methods you use to retrieve them are shown in Table 5-4.

Table 5-4 Methods that Retrieve Objects that Represent OLAP API Data Types

OLAP API Data Type	Method that Retrieves This Data Type
Value	getValueDataType
Boolean	getBooleanDataType
Date	getDateDataType
Number	getNumberDataType
Double	getDoubleDataType
Float	getFloatDataType
Int	getIntegerDataType
Short	getShortDataType
String	getStringDataType
Empty	getEmptyDataType To retrieve an empty Source, use the DataProvider.getEmptySource method.
Null	getVoidDataType To retrieve a null Source, use the DataProvider.getVoidSource method.

To create a Source object that represents an OLAP API data type, take the following steps:

1. Get the FundamentalMetadataProvider by using the getFundamentalMetadataProvider method on the DataProvider class.
2. Create the FundamentalMetadataObject object that represents the OLAP API data type by using the appropriate method on the FundamentalMetadataProvider class.
3. Create a Source from the objects returned in Step 1 by using the FundamentalMetadataObject.getSource method.

Example 5-4 creates a Source object called olapBooleanDataType that represents the OLAP API Boolean data type. You can use olapBooleanDataType to check to see if the OLAP API data type of any other Source is Boolean.

Example 5-4 Creating a Source for the OLAP API Boolean Data Type

FundamentalMetadataObject myFundamentalMetadataProvider =
    myDataProvider.getFundamentalMetadataProvider(); 
FundamentalMetadataObject olapBooleanFundObj =
    myFundamentalMetadataProvider.getBooleanType(); 
Source olapBooleanDataType = olapBooleanFundObj.getSource();