Creating Derived Source Objects

How to create derived Source objects

You can derive new Source objects from existing Source objects by using the methods in the Source class and its subclasses or by using the generateSource method in the Template class. Template objects are extensions to the OLAP API that represent end-user concepts such as cubes, edges, and selections. They form a bridge between the requirements of the user interface and the powerful, but abstract, OLAP API logical model. Unlike other OLAP API objects, Template objects have state. Consequently, they can be modified at any time, even after they have been incorporated into some larger Source. The Source defined by a Template can be said to be dynamic in the sense that it can be changed. For more information about Template objects and how to define and work with Source objects within them, see Chapter 11.

Introducing the OLAP API Source methods

The OALP API includes primitive methods and shortcut methods.

Primitive methods

The primitive join method is the single most important Source creation method in the OLAP API. The primitive join method combines the elements of this Source (sometimes called the base Source) and another Source (called the joined Source) and filters this result set using a third Source (called the comparison Source) in the specified manner. Using an optional parameter, you can also use the primitive join method to add the joined Source as a dimension (or key) to the new Source. The primitive join method is discussed in more detail in "Introducing the join method" and documented in detail the online reference documentation for the OLAP API.

The following table outlines the other primitive methods in the OLAP API.

Primitive Method	Description
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	Removes the duplicate rows (tuples) in this Source object.
extract	When the elements of the base Source are other Source objects, creates a new Source that has the base Source as an extraction input.
position	Creates a new Source object with the same structure as the base Source and whose elements are the position of the elements of the base Source.
value	Creates a new Source object that has the elements of the base Source and that has the base Source as an input.

These methods are documented in the online reference documentation provided for the OLAP API. For more information about using these methods to create derived Source objects, see Chapter 6 and Chapter 7.

Shortcut methods

The OLAP API provides various shortcut and convenience methods that you can use instead of the primitive join method. These methods include shortcuts for the primitive join method, as well as shortcut methods such as appendValue, at, cumulativeInterval, first, ge, interval, selectValues, and sortAscending.

These methods are documented in the online reference documentation provided for the OLAP API. For more information about deriving Source objects using these methods, see Chapter 6 and Chapter 7.

Introducing the join method

The most important primitive method in the OLAP API is the primitive join method.

Syntax: the primitive join method

The signature of the primitive join method is shown below:

Source join(Source joined,
            Source comparison,
            int comparisonRule,
            boolean visible)

The parameters are described below:

• joined is the Source that you want to join to this Source.

• comparison is the Source that you want to use as a filter for the join.

• comparisonRule is the rule that determines how the method uses the comparison Source to filter the result set. Specify a value for this parameter using one of the Source.COMPARISON_RULE fields.
  • COMPARISON_RULE_SELECT specifies that the new Source contains only those elements that appear in the comparison Source.

  • COMPARISON_RULE_ASCENDING, like COMPARISON_RULE_SELECT, specifies that the new Source contains only those elements that appear in the comparison Source, additionally, once the rows of the cross-product have been intersected by the comparison Source, the remaining rows are sorted by the value of the joined Source according to the position defined in the comparison Source.

  • COMPARISON_RULE_DESCENDING, like COMPARISON_RULE_SELECT, specifies that the new Source contains only those elements that appear in the comparison Source, additionally, once the rows of the cross-product have been intersected by the comparison Source, the remaining rows are sorted by the value of the joined Source according to the reverse position defined in the comparison Source.

  • COMPARISON_RULE_REMOVE specifies that the new Source created by a join contains only those elements that do not appear in the comparison Source.

• visible is a flag that specifies whether you want the joined Source object to be an output of the new Source. When true is specified, the joined Source becomes a dimension of the new Source and the values of the joined Source become the elements of that dimension.

The result of the primitive join method

The result of the join method is a new Source object. Depending on the complexity of the Source objects that you are joining, the resulting Source object may be simple or complex:

• When you join two nondimensional Source objects, the new Source is dimensioned by the joined Source and the new Source is simply the cross-product of the two Source objects.

• When you join dimensional Source objects, the new Source has the combined dimensionality of the base, joined, and comparison Source objects. Additionally, when you specify true for the value of the visible parameter, the joined Source becomes a dimension or key of the new Source. (For details on how the dimensions of the new Source are determined, see the online Help for the primitive join method.)

Example: Select option of join

Assume that you have a Source named myStates that does not have any inputs or outputs and whose elements are CA, MA, and NY and a Source named myProducts that does not have any inputs or outputs and whose elements are Dresses - Girls and Shirts - Girls. Now we issue the following code.

String[] values = new String[] {"NY", "CA"};
Source newSource = myProducts.join(myStates, values, 
    Source.COMPARISON_RULE_SELECT, true);

When processing this code, the OLAP service takes the cross-product of myProducts and myStates, and then selects from the result only those rows for which the value of region is in the set of values {"NY", "CA"}. Another way of describing this processing is to say that the states output (column) is intersected with the comparison set {"NY", "CA"}.

This yields the result set shown below. Notice that the rows containing "MA" have been removed.

Input	Elements
states	product
CA	Dresses - Girls
CA	Shirts - Girls
NY	Dresses - Girls
NY	Shirts - Girls