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:

Create Source objects that correspond to metadata objects as described in "Getting Source Objects From Metadata Objects". These Source objects, sometimes called primarySource objects, have a structure that is similar to the metadata objects from which they are created.

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 derivedSource 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".

Getting Source Objects From Metadata Objects

To get a Source object from a metadata object, take the following steps:

Create the metadata data object for which you want to create a corresponding Source object as described in Chapter 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.

Example 5-1 Getting a Source for an MdmHierarchy

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".

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-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 rangeSource 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.

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:

Get the FundamentalMetadataProvider by using the getFundamentalMetadataProvider method on the DataProvider class.

Create the FundamentalMetadataObject object that represents the OLAP API data type by using the appropriate method on the FundamentalMetadataProvider class.

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.